ui-server: admit generic chat files and retain specialized content routing #3153

Out of scope

No picker implementation, PDF extractor/reader selection, general plugin registry, relaxed track parser, uploaded-code execution, automatic operational inbox work, automatic canonical filing or implied Undo feature. Content-reading strategy belongs to #3154 and interaction design to #3155; #3151 supplies the concrete reconciled design.

Context

Part of #3150.

Blocked by #3151

stageShareAt (packages/ui-server/src/share/staging.ts:298-424) already retains arbitrary file bytes and validates tracks. resolveChatFiles (packages/ui-server/src/tracks/read.ts:58-63) still requires every chat file to parse as a track; withTrackFiles at lines 69-72 emits track-specific context. createShareRoutes (packages/ui-server/src/routes/share.ts:108-222) gives /share operational intake side effects while /track-upload is track-specific. Current dispatch combines file/image limits at packages/ui-server/src/ws/dispatch.ts:133-149. Image model content alone is not proof that an original filesystem file is retained.

The maintainer's November 2 review selects the neutral route, filesystem originals, durable draft/chat lifetime, aligned byte/count envelope, protected-reference cleanup and configurable total attachment pool below. These supersede the October 29 deferral for those policy questions. #3151 remains an actual design dependency, not an unanswered choice between those branches.

Scope

Implement a separate neutral composer-upload endpoint with concrete type routing, reusing staging/validation internals. Bind references against authenticated server-owned original files and recorded ownership; keep images and validated tracks specialized without forcing every other file through track parsing. Implement the selected durable ownership, admission and cleanup semantics and preserve existing share/track callers or document an explicitly compatible migration.

Acceptance criteria

• Implement the G1 A snapshot list below: the draft's outgoing is a list of up to 10 { snapshotId, requestId, text, fileIds, state, createdAt } items per chat; the creating save counts every live snapshot for the chat across tabs and devices in the same transaction and returns 409 DRAFT_OUTGOING_FULL before any send effect; Cancel, upload failure, dispatch and non-acceptance transitions edit in place without a free slot; release only on confirmed acceptance, Edit or confirmed Delete…; every live snapshot is in aggregate accounting. Tests prove ten combined slots, eleventh refused with no chat_message effect, Cancel at 10 of 10, two devices at 9 each racing and exactly one admitted, and a mutation counting only one tab's snapshots failing. The single-outgoing-slot implementation does not satisfy this criterion; a shipped single-slot field needs additive compatibility treatment.

• Generic PDF, text, ordinary JSON and unknown binary originals within the selected envelope can upload and bind to a draft/chat without unsupported-track rejection. Unknown type alone is not an admission failure, and upload never claims successful extraction.

• Every attachment including images has real original filesystem bytes and an authorized stable read/reference path inside the agent environment. Prove actual reads/digests with image, PDF/text and track fixtures; metadata-only/inline-only assertions do not qualify. Retained originals remain available to later conversation turns.

• Server-owned reference resolution rejects missing/stale/altered/cross-owner/symlink/outside-authorized-store references and client authority overrides. Revalidate recipient/taint and filesystem access constraints; attaching a file is no arbitrary-path or execution grant.

• Content-valid GPX/KML/GeoJSON preserve the existing shared parser's metrics, partial/omission evidence and rendering metadata. Wrong extensions/MIME cannot forge track evidence; ordinary JSON remains generic. Original preservation does not remove separate specialized processing bounds.

• Enforce 10 attachments, 25,000,000 original bytes each and 50,000,000 combined original bytes per draft/message, including images. Preserve the 65,536-byte text allowance separately and update the old draft combined-byte accounting/advertised limits consistently. Streamed and actual sizes, not client claims, enforce admission.

• Implement the configurable default 1 GiB total attachment pool across draft/sent/pending/grace storage with durable cross-operation accounting/reservations. Preserve the 100-draft/256-MiB draft defaults as sub-limits. Pending and derived objects cannot escape accounting. At capacity refuse explicitly, preserving existing referenced/in-grace content; concurrent admissions cannot multiply the cap.

• Exact acknowledged draft revisions and filesystem bindings survive reload/tab close/normal restart. An accepted send retains conversation references before consuming its submitted draft revision; newer edits, other drafts and unresolved sends remain intact. Recovery/idempotency prevents duplicate files, cross-draft binding and premature cleanup; no automatic resend or falsely saved state.

• Cleanup uses one hour for never-bound uploads and seven days from authoritative last-reference removal for formerly referenced originals, with clocks/eligibility retained across restart. Recheck every reference, live operation and file identity at deletion under race-safe coordination. Uncertain sends/ownership/state protect files. Rebinding cancels collection; no mtime reset, early quota-driven purge or implied Undo.

• The new route creates no operational inbox/queue/triage job. Preserve existing share/track intake behavior and the settled mobile source shortcuts. Concrete schemas, capability negotiation and bounded detection/resource implementation must match ui-server: design generic attachment intake, routing and content access #3151's design under the selected policies, without introducing a public registry.

• Update runtime schemas and authoritative HTTP/WS/package/draft/storage contract documentation, API reports where relevant and minor changesets. Record the D52 lifetime/envelope amendment, pool and cleanup policies and rejected alternatives in the relevant decision records in this implementation. Preserve legacy/unavailable-host honesty and existing unrelated draft behavior; no retrospective saved claims.

Verification

Extend share-routes, track-intake, ws-track-files and draft/reference/storage tests with real chat dispatch and filesystem reads. Cover mixed files, tampered authority/metadata, misleading MIME, generic versus valid-track routing, original/derived limits, concurrent quota admission, ownership, acknowledged save/reload/restart, accepted/uncertain send, version edits, reference transfer, last-reference cleanup and rebind/unlink races. Use keyless offline fixtures and actual retained bytes; no paid service.

Run bun run test packages/ui-server/tests/share-routes.test.ts packages/ui-server/tests/track-intake.test.ts packages/ui-server/tests/ws-track-files.test.ts plus focused new ownership/quota/draft suites, typecheck and bun run check:pr --base origin/main. Retain a failing-first generic/PDF admission witness and restored mutations for authorization, original-file presence, quota and cleanup protections on their intended assertions. Tests of turn-path/provider context changes run the append-only history guard; do not mutate previous provider tools/system/messages.

Contract impact

A new composer endpoint, server-owned references, generic durable-draft capability, advertised limits and configurable attachment-pool input need contract labeling, CONTRACT-prefixed implementation commits, authoritative same-commit docs and appropriate minor changesets. Preserve old supported share/track shapes and existing client behavior through additive negotiated evolution where possible. Under G1 A this includes the draft outgoing snapshot list and the new 409 DRAFT_OUTGOING_FULL refusal in the draft-save HTTP contract; if a single-slot outgoing field has already shipped on main, the list needs additive compatibility treatment or its own breaking ruling. The explicit lifetime and limit rulings authorize their named amendments; any additional breaking retype/removal or changed existing-source meaning needs its own ruling before implementation. No new provider transfer or release milestone is approved.

Approved decisions

Approved shared constraints (maintainer, 2026-11-02; #3153)

• Admission: separate neutral composer-upload endpoint reusing concrete staging internals, with no operational inbox/queue/triage side effects. Existing share/track callers retain their documented behavior; preserve the settled phone Photo library/Camera/unrestricted Files entry points and common processing pipeline.
• Actual files: every attachment, including images, has a byte-identical uploaded-original filesystem file and authorized stable reference readable from the agent's execution environment. Inline/base64 context, previews or extracted text alone are insufficient. Preserve specialized processing, taint/recipient/permission rules and honest content-access outcomes; a stored binary is not automatically semantically readable.
• Ownership/lifetime: originals belong to the exact acknowledged draft revision and, after accepted send, the retained conversation. A saved draft including its file bindings survives reload/tab close and normal host restart. Sending retains originals for later agent reads without consuming newer edits or another draft. No automatic filing into canonical brain content. Unacknowledged/legacy data never falsely reads as saved; unresolved sends protect their files. This explicitly amends D52's tab-only staged-track exception for the new generic path.
• Per-draft/message envelope: 10 attachments total, 25,000,000 original bytes per file and 50,000,000 original bytes combined, including images. Preserve the 65,536-byte text allowance separately and reconcile the old 8,388,608-byte draft ceiling so an eligible original batch can be saved subject to aggregate admission. Original-byte limits do not relax separate image/provider-frame/track-parser bounds or authorize silent omission.
• Aggregate storage: a configurable host attachment-pool cap, default 1,073,741,824 bytes (1 GiB), covers draft, sent, pending and grace-period attachments. Account materialized originals/derived attachment storage and in-flight reservations under bounded accounting; do not leave an uncharged derivative or pending-file escape. Preserve the 100-live-draft default and 268,435,456-byte host draft sub-limit. Draft storage is a subset of the attachment pool, not an additional 256 MiB on top. Shared physical storage/reference accounting must be explicit. At capacity refuse new work honestly and preserve existing references; no early purge to make room.
• Cleanup: never-bound uploads have a one-hour window; formerly referenced originals have seven days from authoritative last-reference removal. Saved draft/chat references, active work and unresolved sends protect files. Revalidate ownership, identity and all references immediately before deletion, coordinating rebinding against unlink. Unknown reference state fails closed. Rebinding cancels collection; a later last-reference removal starts a new seven-day interval. Incidental access/mtime does not reset it. Grace-period storage remains charged. No implied Undo feature or permission to delete unrelated canonical/share data.
• Design/compatibility: ui-server: design generic attachment intake, routing and content access #3151 must turn these settled constraints into exact reference/route/capability schemas, durable ownership/admission accounting, detection/resource bounds and executable proof briefs. Record choices and rejected alternatives in D52/attachment decision guidance and authoritative contract docs. Concrete names and internal implementation details may be chosen within these constraints; a proposal exceeding them requires a new ruling. No release commitment is made.

Readiness and design dependency

The maintainer policy questions on this admission issue are answered. Remove needs: decision and add agent-ready because no other needs label remains. Retain blocked on #3151: implementation must consume its concrete route/reference/resource/compatibility design rather than inventing or bypassing that deliverable. Reader and UI decisions remain on #3154/#3155; this readiness does not complete those issues or approve their unreviewed choices.

2026-11-02 decision review: consolidated the selected admission/original/lifetime/limit/cleanup/pool policies into checkable criteria and replaced the original deferred alternatives. No implementation, live upload/deletion, proof completion or release commitment is claimed.

Blocked by #3291

Later recovery-capacity amendment — maintainer, 2026-11-02 (#3155)

The subsequent interactive #3155 review selects multiple separate recovery cards, with up to 10 pending/recoverable snapshots combined per chat, rather than a single outgoing slot. Count held, returned and dispatched-but-unconfirmed snapshots together across tabs/devices; each keeps its own exact text/file bindings and identity. Confirmed accepted sends leave the queue, retaining their conversation references. This supersedes only the earlier single-slot restriction (including #3151's approval of §13 item 6); the other five approved recommendations and existing ownership/lifetime/security policies remain in force.

Admit/reserve capacity before a new send creates effects. At capacity explain why new sends wait, while drafting, checking/recovery and cancellation remain available. Cancelling admitted work must preserve that same snapshot without requiring another slot. Do not merge/overwrite/evict unresolved snapshots, automatically replay uncertain sends or authorize parallel provider turns. Keep per-message envelopes and aggregate 256-MiB draft/1-GiB attachment-pool defaults unchanged; the count does not guarantee byte capacity or multiply those allowances.

Reconcile the design's single outgoing representation, contracts and reference transfer/accounting with multiple independently identified snapshots before claiming the affected scope complete. Preserve each snapshot across newer edits, acknowledgement loss, reload, auth/session changes and uncertain sends; release/collect only after the matching authoritative ownership transition. The durable records remain app-owned internal state, outside provider history. Concrete API names/representation and compatibility treatment remain the design/delivery owners' responsibility; no new public persistence seam is approved.

G1 A — snapshot list (maintainer, 2026-11-03; #3155). The draft's single outgoing? field (docs/plans/chat-attachments.md §6.4) becomes a list of up to 10 snapshots per chat, each { snapshotId, requestId, text, fileIds, state: held | returned | dispatched, createdAt }, keyed for ownership by the existing §6.3 draftId:requestId refs (no new table). The save that creates a snapshot counts every live snapshot for that chat across tabs and devices in the same transaction and refuses the eleventh with 409 DRAFT_OUTGOING_FULL before any send effect; that save is the reservation. Cancel (held → returned), upload failure (held → returned), dispatch (held → dispatched) and a recovery read showing non-acceptance (dispatched → returned) edit a snapshot in place and never need a free slot. A slot is released only on confirmed acceptance (refs move to the message), Edit into an empty composer revision or confirmed Delete…; nothing is evicted, merged or overwritten. An ordinary all-ready send also creates a dispatched snapshot until acceptance. Source: #3155 design brief rev 5 §2. Rejected: a separate send-intent table.

Add explicit proof for ten combined slots, eleventh-send refusal before effects, cancellation while full, independent per-card recovery across reload and concurrent devices, older acknowledgements not consuming newer drafts, no duplicate resend and no early file cleanup. Reconcile the final UI matrix under #3155's remaining needs: design; the selected product behavior itself needs no repeat interview.

2026-11-02 decision propagation: recorded the later #3155 E2 B / capacity B / E1 A rulings in the current brief. Initial single-slot design delivery is not evidence this amendment is implemented or verified. Preserve assignments, existing blockers and release commitments; no PR/runtime completion is claimed.

Triage 2026-11-03: folded the maintainer ruling (#3155 G1 A, snapshot list with 409 DRAFT_OUTGOING_FULL in the save transaction) into the first acceptance criterion, the recovery-capacity amendment and contract impact.