feat(server): attachment object storage, quotas, and reference lifecycle

[liuchao-001]

Closes #1664.

Implements the full governance scope pinned in the issue's binding "GoF Competition scope & acceptance" comment: attachment binary payloads move to S3-compatible object storage (PostgreSQL keeps metadata only), with hard-reject quotas, a reference lifecycle with orphan cleanup, streaming on both transfer paths, bounded upload concurrency, and an idempotent data-migration command for existing bytea payloads.

Storage boundary

• Object storage (any S3-compatible backend — AWS S3, R2, MinIO): every attachment payload at the deterministic key attachments/<id>, and agent avatars at avatars/<uuid> (overwritten in place). Config is the optional FIRST_TREE_S3_* env group; without it the server boots and serves pre-migration rows, but uploads answer 503 until storage is configured (no silent bytea fallback — that would keep the unbounded-growth path alive).
• PostgreSQL: metadata + lifecycle state only. attachments gains organization_id (quota accounting unit), object_key, and a three-state state column (pending → stored → deleting); the legacy data bytea turns nullable and is cleared by the migration command. Dropping the column entirely is a small follow-up PR once deployments have migrated (the scope comment explicitly allows null-then-drop).

Acceptance checklist → implementation

1. New uploads land in object storage; the row holds metadata + key only.
   Upload is reservation-first: a pending row (the durable quota reservation) is inserted under a per-org advisory xact lock, the body then streams straight into the object-storage PUT, and a pending → stored CAS finalizes. .returning() payload exposure is gone with the write path itself. — attachments-route.test.ts
2. Migration command moves existing payloads; pre-migration attachments keep downloading.
   pnpm --filter @first-tree/server migrate:attachments — five idempotent phases: org backfill from uploader rows, reference-ledger backfill from message content/metadata, attachment payload move (atomic key+NULL swap per row), avatar payload move, verify (non-zero exit while any payload remains inline). Runs against a live server; the download path serves remaining bytea rows directly and falls through to the deterministic key when a row migrates between its metadata and payload reads. A 0-row swap is adjudicated by re-reading the row — the object is deleted only when genuinely ownerless (row destroyed/tombstoned), never when a rival run or a concurrent online avatar upload won the swap; test hooks expose the between-PUT-and-UPDATE window for deterministic race coverage. — attachment-migration.test.ts (byte-identical round-trip, org/edge backfill, dangling-id filtering, idempotent rerun, rival-run/sweep/online-upload races)
3. Quotas, hard reject. Single file 10 MiB → 413 (ATTACHMENT_TOO_LARGE); org totals 2 GB / 1000 objects → 422 with stable ATTACHMENT_QUOTA_EXCEEDED, rejected before the body is read. Quota checks run under pg_advisory_xact_lock(hashtext('attachment_quota'), hashtext(orgId)) (the repo's existing two-int lock idiom), so concurrent uploads cannot jointly overshoot — covered by a race test asserting exactly one of two jointly-over-quota uploads is admitted. The governed "2 GB" is implemented as 2 GiB (2^31), consistent with the binary units of MAX_ATTACHMENT_BYTES (and slightly generous rather than strict); both limits are env-tunable with the governed values as defaults, and the reject semantics never soften. — attachment-quota.test.ts
4. Reference lifecycle & orphan cleanup.
   • Discovery has one source of truth: collectAttachmentIds covers the single-image content.imageId, the batch content.attachments[].imageId, and metadata.attachments[].attachmentId shapes. Agent avatars are deliberately not attachment references in this codebase — they are a separate 1:1, size-capped, overwrite-in-place surface (agents.avatar_*), migrated and served through the same storage but exempt from reference counting and org quotas (bounded by 512 KiB × agent count; nothing accumulates).
   • An attachment_references (attachment_id, message_id) ledger is maintained inside the message write transaction (send and edit), with RESTRICT FKs — a cascade could only ever fire on a bug deleting a still-referenced attachment, and would destroy the evidence.
   • Delete on last reference removed: message edit — the one live event that can drop a reference today, since messages/chats/orgs have no delete paths — reconciles the ledger and tombstones + destroys attachments whose last edge disappeared. editMessage now runs in a transaction (it was bare sequential statements).
   • 24 h orphan sweep: a background pass (SKIP LOCKED claims, concurrent-replica safe, no leader election — same claim shape as the cron scheduler) reclaims expired pending reservations, deletes aged zero-edge stored rows, and retries leftover deleting tombstones. — attachment-references.test.ts, attachment-sweep.test.ts
   • Deploy-window safety: between deploying this PR and running the backfill, every pre-existing attachment has zero edges. The orphan pass therefore carries a verify scan: candidates are matched as literal text against messages.content/metadata (one scan per batch) and any hit is vetoed and logged. Text matching can only err toward keeping; the pre-backfill window is a performance note, not a data-loss window.
5. Streaming, no full buffering. Upload: a plugin-scoped content-type parser hands the raw request stream through a byte-exact limit stream into the PUT (Content-Length is now required → 411; the declared size is what quota reservation is based on). Download: proxy mode (default) pipes the object stream through the server; redirect mode answers 302 to a ≤300 s presigned URL with pinned response-content headers. Default is proxy because the web app consumes attachments with authenticated fetch — redirect-by-default would require every existing deployment to configure browser-reachable buckets + CORS before images render again. Avatars always proxy regardless of mode: a per-request presigned redirect varies the URL every time and would defeat the immutable browser cache that surface depends on.
6. Bounded concurrency. A per-uploader in-process gate (keyed by humanAgentId, default 4 parallel streams, env-tunable) answers 429 ATTACHMENT_CONCURRENCY_EXCEEDED; the global rate limiter still applies. Per-instance scoping matches the repo's in-memory rate-limit precedent (PostgreSQL stays the only shared backend).

Wire-contract changes

• POST /orgs/:orgId/attachments: requires Content-Length (411 on chunked/absent), 413 + code for oversize (previously 400/413 split), 422 + code for org quotas, 429 + code for concurrency, 409 if an upload outlives its reservation window, 503 when storage is unconfigured. Success responses are unchanged.
• Message writes now validate content.imageId references (existence, stored state, same-org-or-legacy) — previously shape-checked only. Fabricated/foreign ids get 400; legitimate upload-then-send flows are unaffected. Legacy NULL-org attachments stay referenceable.
• GET /attachments/:id: unchanged for live rows (ETag/304 intact; Content-Disposition gains an RFC 5987 filename*); pending/deleting rows are 404.
• Avatar upload requires Content-Length (411); other avatar semantics (400 on oversize/empty/bad mime) are unchanged.
• Error bodies carry the stable code field via the existing attrs.code serialization; new codes are exported from @first-tree/shared (ATTACHMENT_ERROR_CODES), including ATTACHMENT_LENGTH_REQUIRED on the 411s.

Two reviewer-accepted implementation deviations from the design doc: quota rejections reuse UnprocessableError with attrs.code instead of introducing a dedicated error class (the handler only reads attrs.code), and the migration verifies payload length from the local buffer + column normalization instead of a HeadObject round-trip (equivalent under the SDK's enforced ContentLength).

Deployment runbook

1. Deploy. Schema migration 0083 applies on boot (adds columns/tables only; existing rows become valid stored rows). Uploads answer 503 until storage is configured; existing attachments keep downloading from PG.
2. Configure FIRST_TREE_S3_* (see .env.example; MinIO ships in docker-compose for dev) and restart. The server ensures the bucket on boot (or pre-provision it under least-privilege credentials). Uploads now stream to object storage.
3. Run pnpm --filter @first-tree/server migrate:attachments (idempotent, resumable, live-safe). Rerun after a crash or to converge references recorded while it ran; it exits non-zero while any payload remains inline.
4. Optional scale-out: set FIRST_TREE_ATTACHMENT_DOWNLOAD_MODE=redirect once the bucket is browser-reachable and carries CORS for the web origin (FIRST_TREE_S3_PUBLIC_ENDPOINT supports split-horizon presigning).
5. Follow-up PR (after fleet migration): drop attachments.data + agents.avatar_image_data.

CI / test infrastructure

Server tests provision a pinned MinIO via testcontainers in global setup (started concurrently with the PostgreSQL container), with one bucket per vitest worker mirroring the per-worker databases. No workflow changes: this works identically on ubuntu-latest for both ci.yml and publish-npm-package.yml (a sidecar approach would have had to edit both). It is the first time CI actually exercises the testcontainers path (locally it always did); if that ever proves flaky, the CI_S3_ENDPOINT / CI_S3_ACCESS_KEY_ID / CI_S3_SECRET_ACCESS_KEY escape hatch mirrors CI_DATABASE_URL — a one-line workflow edit switches to a sidecar with zero code changes. Tests require no real cloud credentials anywhere.

New suites: attachment-references.test.ts (9 — incl. the wire-400 pin for invalid content refs), attachment-sweep.test.ts (5), attachment-migration.test.ts (4 — the end-to-end plus three hook-driven races), attachment-quota.test.ts (5 — incl. the concurrency race with a SUM-≤-quota invariant and a held-slot 429 over the wire), stream-limit.test.ts (7 — byte-limit semantics and the settleStreamingUpload cross-cancel matrix under an unhandled-rejection probe); attachments-route.test.ts grown to 17 (streaming, 411/413/503 with stable codes, undershot-Content-Length cleanup with a bucket-count leak check, redirect + presigned URL followed end-to-end). Existing suites adapted where contracts intentionally changed. Local gate: pnpm check + pnpm typecheck green; server 2664/2664 across 248 files (zero unhandled rejections), shared 694/694, client/web/qa green. Two machine-local false failures observed and verified unrelated: the known agent-env leak into client-switch-transaction process scans (pre-existing; 21/21 under a sanitized env) and git-fixture timeouts in skill-evals under parallel load (green rerun in isolation).

Out of scope (per the binding comment)

CDN/edge caching, thumbnails, virus scanning, resumable-upload UI, cross-region replication, storage-class tiering, per-user quotas. Also intentionally not introduced: message/chat/org delete APIs (the reference machinery is generic set-diff, so future removal events plug into the same helper).