PostgreSQL PG-C1: Full PostgreSQL E2E leg #640

Goal

Deliver slice PG-C1 — Full PostgreSQL E2E leg of the approved PostgreSQL design (docs/postgresql-architecture.md §15.3, merged in PR #619 as 128e05f).

Context / why

The PostgreSQL design gate (#613) was approved and merged in #619. §15.3 splits the migration into slices with explicit dependencies and file ownership so they can be implemented and reviewed one at a time. Sequential: after every Stage 2 lane except L-S-2. PG-C1 must finish before PG-C2 starts.

Files for Processing is now a managed upload queue (maintainer decision 12, 2026-10-30; #1006, §11.5). Its frontend targets PostgreSQL server mode only and lands here, so the PostgreSQL server never shows the legacy Files for Processing page against an API it does not have.

Scope

• Run the full E2E gate with the facade as the backend in CI (not yet default); the combined restore and browser scenario
• The Processing queue frontend ([Roadmap] Files for Processing V2: managed upload queue #40) on the final PostgreSQL API, replacing the legacy page in PostgreSQL server mode; no SQLite implementation or compatibility layer

Release ownership (2026-10-31)

#40 is the feature epic, this PG-C1 issue is the v0.8 delivery gate for the PostgreSQL-only queue frontend. Implement the UI in scoped reviewable PR(s) before attempting the full PostgreSQL E2E gate; do not push the feature to #615. #615's v0.9 checklist is subsequent full-browser-workflow acceptance only. No independent replacement frontend issue is needed unless a verified new scope boundary requires one.

Acceptance criteria

• Full E2E Gate green on PostgreSQL
• facade method registry reports 100 % ported or retired, where retired is allowed only for the legacy processing inbox methods that §11.5 replaces
• E2E: a real restore to an older snapshot while the browser holds a pending edit, the edit is not applied and its text is offered in review-only recovery
• E2E (Processing queue): upload by file picker and by drag-and-drop with progress, read-only preview in the PRKS viewer, draft edit with save status, single and batch import, and remove; a failed upload never shows an item
• E2E (Research-ACK fence, transferred from PostgreSQL L-R-1: Research #634): on the actual PostgreSQL facade and sync protocol, a browser Research Note edit is acknowledged with research_refs.pending=true until research.reindex_work completes; afterward pending=false and the references reflect the edit. This browser test must pass in the PostgreSQL Full E2E Gate before closing PostgreSQL PG-C1: Full PostgreSQL E2E leg #640.

Research-ACK fence handoff from #634 (required before closure)

L-R-1 (#634) delivered the Research indexing, research_refs.pending and PostgreSQL domain/HTTP fence tests (#940, #946, #953). The remaining PostgreSQL browser E2E acceptance belongs here because PG-C1 owns actual backend cutover, sync route wiring and the Full E2E Gate.

• Use the PostgreSQL facade for Work/Research data and backend.sync.protocol.process_operation for POST /api/sync/operations, not only PostgreSQL sessions with SQLite application data (the test(e2e): run every E2E server on a disposable PostgreSQL Library (#629 PR 1/3) #1021 harness alone is insufficient).
• Drive a browser Research Note save through the durable sync path; verify its ACK includes research_refs.pending=true while the research.reindex_work job is deliberately held.
• Release indexing through deterministic test control, not timing sleeps. Verify pending=false, updated Concept/Argument references and the browser's Research-ACK fence/refresh behavior.
• Run this in CI's PostgreSQL Full E2E Gate. Do not close PostgreSQL PG-C1: Full PostgreSQL E2E leg #640 before that test passes.

Related: #634 (implementation-complete), #940, #946, #953, #1021.

Validation

• Targeted unit, integration and API-contract tests for the changed modules, plus lint, typecheck and structural checks, run locally (PostgreSQL tests through scripts/test-postgres).
• Browser E2E only where the acceptance criteria name browser behavior; GitHub Actions runs the authoritative Test Gate and Full E2E Gate.
• Local targeted results and GitHub CI results reported separately in the PR.

Non-goals / boundaries

• Anything outside the slice above; later slices own their families.
• The legacy SQLite inbox (scan, PRKS_FOR_PROCESSING_DIR, legacy page and API, relocation inbox rules) is removed in PG-C2 with SQLite, per §13.4.
• Starts only on the maintainer's explicit go; the PR stops for maintainer review and is never self-merged.

Related work

Dependencies (recorded as native Blocked by relationships):

• Blocked by PostgreSQL L-ID-1: Identity, bootstrap and sessions #626 (L-ID-1)

• Blocked by PostgreSQL L-J-1: Jobs runtime #627 (L-J-1)

• Blocked by PostgreSQL L-W-1: Works core #628 (L-W-1)

• Blocked by PostgreSQL L-W-2: Bulk, BibTeX, wiki links, Work merge scaffolding #631 (L-W-2)

• Blocked by PostgreSQL L-P-1: People #632 (L-P-1)

• Blocked by PostgreSQL L-O-1: Organization #633 (L-O-1)

• Blocked by PostgreSQL L-R-1: Research #634 (L-R-1)

• Blocked by PostgreSQL L-A-1: Objects and annotations #635 (L-A-1)

• Blocked by PostgreSQL L-PR-1: Processing queue (managed uploads) #636 (L-PR-1)

• Blocked by PostgreSQL L-S-1: Search #637 (L-S-1)

• Blocked by PostgreSQL L-B-1: Backup and restore format 2 #639 (L-B-1)

• Blocked by PostgreSQL L-D-1: Compose and health #630 (L-D-1)

• Blocked by PostgreSQL L-F-1: Browser store scoping, auth hold and restore epoch #629 (L-F-1)

• Blocks PostgreSQL PG-C2: Switch and delete #641 (PG-C2)

• Refs PostgreSQL design gate: canonical backend, schema reset, and pre-1.0 SQLite retirement #613 (design gate)

• Refs [Roadmap] Server, Multi-User & Storage Architecture #310 (roadmap)

• Refs PRKS v0.8 — Backend foundation release tracker #614 (v0.8 tracker)

• Refs [Roadmap] Files for Processing V2: managed upload queue #40 (Processing queue frontend), Specify Files for Processing as a managed upload queue #1006 (design)

Implementation notes

• Owns: cutover: CI workflows, facade wiring, retirement checklist §13.4, the Processing queue frontend
• Design reference: docs/postgresql-architecture.md (§15.2 ownership, §15.3 slice table). Shared files such as server.py are edited by at most one open PR at a time.