[Epic] Sources of truth: stop synchronizing duplicated state — collapse it

[2witstudios]

The pattern

Wherever this codebase stores one fact in two representations, the two drift — reliably, provably, across every layer. The response so far has been to patch individual desyncs: an isPaused guard here, a Math.max limit reconciliation there, a dated repair script, a "keep in sync with X" comment, a version counter, a dual-write helper with a deletion covenant. Every duplicated fact requires a sync protocol; every hand-rolled sync protocol is a standing bug factory. The durable fix is almost never better synchronization — it's collapsing the duplication: one source of truth per fact, everything else derived at read time or generated at build time.

The evidence that drift is systemic, not incidental: the repo carries at least nine repair/backfill scripts that exist only because two representations diverged (repair-orphaned-trashed-pages, sync-legacy-subscriptions, backfill-gifted-subscriptions, backfill-credit-ledger with dated adjustment rows, reenqueue-unprocessed-uploads, backfill-file-storage, calculate-initial-storage, normalize-dead-ai-models, migrate-ai-models-to-openrouter) — plus an entire client store (useEditingStore) whose only job is arbitrating between two cache layers.

Findings (this audit)

Client state

• state: SWR and Zustand both hold the same server state — useEditingStore + 17 isPaused guards are arbitration for duplication that should be collapsed #2146 SWR + Zustand both hold server state; 17 copy-pasted isPaused guards, 4-way manual cache fan-outs, stale-forever tab titles
• state: delete useOpenTabsStore — a second persisted tab store with zero production readers #2142 Two persisted tab stores; one has zero production readers
• ai/state: finish the transport demotion — 7+ dual-write sites between the useChat array and the conversation cache #2145 AI chat: 7+ dual-write sites between the useChat transport array and the conversation cache ("rail 11" transitional covenants, 13 TRANSITIONAL markers)
• ai: useAnswerAskUser re-seeds the transport from a render-time snapshot — three distinct stale-write bugs #2144 useAnswerAskUser re-seeds the transport from a render-time snapshot — three stale-write bugs (fix pattern already exists in useCacheMessageActions)

Schema / server

• tasks: taskItems.position is a dead ordering rail — users order by pages.position, AI tools order by taskItems.position, and they diverge #2143 taskItems.position vs pages.position — dead rail with a live consequence: AI agents see a different task order than users
• tasks: legacy assignee columns vs task_assignees junction — dual-write reimplemented in two writers, onboarding writes only the legacy side #2152 Task assignees: legacy columns vs junction table, dual-write reimplemented twice, onboarding writes only one side
• chat: denormalized message metadata has one-sided writers — DM previews survive deletion, lastReplyAt points at deleted replies, interrupted-stream recovery skips lastMessageAt #2153 Chat denormalizations with one-sided writers (DM previews survive deletion, lastReplyAt points at deleted replies, mirror edits don't propagate, interrupted-stream recovery skips lastMessageAt)
• pages: trash cascade implemented twice, plus raw non-cascading writers — the class of bug repair-orphaned-trashed-pages.ts fixes can recur #2157 Trash cascade implemented twice + raw non-cascading writers (repair script proves the drift class)
• machines: machine JSONB refs are scrubbed on exactly one deletion path — trash, cascade, and purge leave dangling refs in agent configs #2156 Machine JSONB refs scrubbed on one deletion path only — dangling refs from trash/cascade/purge
• db: drop the dormant legacy permissions table — zero readers/writers, frozen misinformation next to page_permissions #2160 Dormant legacy permissions table next to page_permissions

Billing / limits

• billing: the concurrency view counts credit holds, the gate counts per-process slots — the number users see is never the number that blocks them #2147 Concurrency view counts credit holds; the gate counts per-process slots; displayed limit ≠ enforced limit; payer ≠ actor
• billing: tier vocabulary hand-declared ~15× (control-plane uses a different list entirely) and plan limits triplicated across lib/web/marketing #2148 Tier vocabulary declared ~15×; control-plane validates a different tier list (founder fails, enterprise orphaned); plan limits triplicated and previously diverged
• billing: users.subscriptionTier vs subscriptions rows — webhook-only sync, no reconciler, two repair scripts prove drift #2149 users.subscriptionTier vs subscriptions rows — webhook-only sync, no reconciler
• storage: users.activeUploads leaks permanently on process restart — DB counter reconciled only by a per-process in-memory sweep #2154 users.activeUploads counter leaks permanently on process restart — bricks uploads
• storage: three representations of storage use — running counter, files.sizeBytes, pages.fileSize — and two surfaces report different totals by construction #2155 Storage use has three representations and two user-facing surfaces report different totals by construction

Cross-service / constants

• types: PageType re-declared by hand — glob search and the AI search tool silently drop FILE and MACHINE pages #2150 PageType re-declared by hand — FILE and MACHINE silently dropped from glob search and the AI search tool (live bug)
• admin: apps/admin is a hand-copied, already-diverged fork of apps/web modules (Stripe price IDs ×2, auth ×2, onboarding seeds ×2) #2151 apps/admin is a hand-copied, already-diverged fork of apps/web modules (Stripe price IDs ×2, auth ×2, onboarding seeds ×2)
• realtime: socket room membership vs DB permissions — three sync mechanisms for one fact, and broadcast-audience's hand-maintained room grammar is already stale #2158 Realtime room membership vs DB permissions: three sync mechanisms; broadcast-audience's hand-maintained room grammar cites line numbers ~300 lines stale
• processor: pages.processingStatus vs queue state — fire-and-forget enqueue, stuck-'pending' proven in production, no reconciler #2159 pages.processingStatus vs queue state: fire-and-forget enqueue, stuck-pending proven in production, no reconciler

Known duplications deliberately NOT filed (managed or accepted)

• credit_balances vs credit_ledger — genuinely dual by design, but it's the one place drift is engineered for: computeBalanceDrift + getBalanceDriftAlerts monitor continuously, holds are swept by cron. This is the model the unmonitored denormalizations above should follow if they can't be collapsed.
• AI model catalog/pricing maps + persisted model ids — has a drift-report script (sync-openrouter-models.mjs), runtime default-substitution self-heals, and two generations of normalize scripts; bounded, though a merged catalog+pricing table would still be better.
• SDK hand-mirrored constants — the done-right pattern: every copy has a compile-time or source-parsing drift-guard test (roles-pageperm-drift-guard.test.ts, edge-logger.test.ts). When a copy must exist (bundle isolation), this is the standard to hold it to.
• Smaller comment-synced mirrors worth folding into the above work as touched: duplicated MIME lists (file-security.ts ↔ processor security.ts, content-detector's "keep in sync with" triple), credit-balance.ts/credit-gate.ts mirrored date arithmetic and STRIPE_REF_ARBITER, tenant-export.ts hand-listed column arrays ("A mismatch will cause data loss"), client vs server deployment-mode env vars, WorkspaceLayoutScopeDTO mirror, form-target field mappings (drift documented in-schema as a v1 limitation).

Decision rule going forward

For any fact about to be stored twice, in order of preference:

1. Don't. Derive at read time (dead COALESCE fallbacks, tab titles, trash-state-from-ancestor) or import from the one module that owns it (tiers, page types, prices).
2. If a copy is forced by a boundary (client bundle, separate process, external system): add a drift-guard test (the SDK pattern) or a reconciler with alerting (the credit-balance pattern). Comments are not a sync mechanism.
3. If both sides must be writable: one shared writer owning the dual-write (task assignees, chat derived fields), never per-call-site reimplementation.

Prior art showing the payoff: #1055 (tool registry), #1452 (builtin provider config), #1052 (env var drift) — each was this same disease in miniature, and each fix was collapse, not sync.