Enable prod CRDT + Railway realtime after audit (Notion-like multi-tab sync)

[chasehuh]

Summary

Audit the already-merged Yjs CRDT + Railway Hocuspocus realtime path (#59 / #60–#63). If the implementation is sound for production multi-tab use (Chase’s default: many agentnote.dev tabs open), enable the feature flags on Vercel production and fix Railway origin allowlist for www.agentnote.dev. If the audit finds blockers, do not enable — report and stop.

Why This Matters

Chase keeps multiple agentnote.dev tabs open by default. #73/#74 hardened the legacy whole-document PUT path against silent clobber, but the product goal is Notion-like streaming sync: edits on one tab appear on the other without LWW races. That stack is already built and the collab service is healthy; production simply never flipped the flags. Enabling without a proper audit risks body duplication, origin rejection, or one-way CRDT seeding surprises.

Conversation Context

• 2026-08-04: body wipe on 0804.md (dsb-wbhi-aqa) — fix: stop 409-rebased stale buffers from silently clobbering newer note bodies (0804 wipe RCA) #73 fixed 409 token laundry; fix: stop row-stamped peer drafts from laundering stale buffers into a valid save token (post-#73 multi-tab clobber) #74 fixed post-fix: stop 409-rebased stale buffers from silently clobbering newer note bodies (0804 wipe RCA) #73 multi-tab draft laundering (broadcastDraft stamped list-row updated_at).
• Chase: multi-tab is the default; asked whether Notion-style streaming sync is possible on Railway.
• Answer: yes — Phase 1 CRDT (feat(crdt): Yjs note body behind NEXT_PUBLIC_AGENTNOTE_CRDT (Phase 1) #60) + Phase 2 Hocuspocus on Railway (feat(crdt): Hocuspocus realtime transport on Railway (Phase 2) #63) already merged; GET https://agentnote-collab-production.up.railway.app/health → {"ok":true,"service":"agentnote-collab"}.
• Vercel production currently has no NEXT_PUBLIC_AGENTNOTE_CRDT / NEXT_PUBLIC_AGENTNOTE_COLLAB_URL (verified via vercel env ls on linked cwhuh/memo project).
• Chase lock (2026-08-05): audit → if OK enable flags. Hand to Opus. Prefer Notion-like realtime over staying on legacy forever. CRDT was previously deferred as follow-up; now authorized to turn on if audit passes.
• Domain today: https://www.agentnote.dev (and memo.chasehuh.com → redirect). README still says collab allowlist is pinned to https://memo.chasehuh.com — must include agentnote.dev origins before enable, or WebSocket auth will fail closed.

Current Behavior

• Prod app uses legacy body path: optimistic concurrency + fix: stop 409-rebased stale buffers from silently clobbering newer note bodies (0804 wipe RCA) #73/fix: stop row-stamped peer drafts from laundering stale buffers into a valid save token (post-#73 multi-tab clobber) #74 guards (baseUpdatedAtRef, base_fingerprint, conflict Overwrite/Use server).
• CRDT client gate in components/agentnote-app.tsx:
  • CRDT_ENABLED = process.env.NEXT_PUBLIC_AGENTNOTE_CRDT === "1"
  • COLLAB_URL = process.env.NEXT_PUBLIC_AGENTNOTE_COLLAB_URL?.trim() || null
  • When enabled: useNoteDoc({ noteId: activeId, collabUrl: COLLAB_URL, … }); editor binds ytext; legacy dirty/409 path short-circuits.
• HTTP CRDT: GET/POST /api/notes/:id/doc (+ sync); tables note_doc_updates, note_doc_snapshots via ensureSchema().
• Realtime: services/collab Hocuspocus; room = canonical note id; Clerk JWT + ownership; shared lib/crdt/note-doc-store.ts with HTTP path.
• Flag is effectively one-way per note: once a snapshot exists, legacy PUT body returns 409 { reason: "crdt_managed_body" }. Turning the flag off leaves those notes non-body-editable until doc rows are deleted (projected notes.body remains).

Desired Behavior

1. Audit report (issue comment or PR body) covering correctness, security, ops readiness, and explicit go/no-go.
2. If go: production flags set and a deploy that picks them up; Railway allowlist includes agentnote.dev; smoke proves two tabs stream the same note.
3. If no-go: flags remain unset; blockers listed with severity and suggested fix PRs.

Target production env (Vercel project memo / cwhuh/memo, Production)

NEXT_PUBLIC_AGENTNOTE_CRDT=1
NEXT_PUBLIC_AGENTNOTE_COLLAB_URL=wss://agentnote-collab-production.up.railway.app

Target Railway collab env

# Must include the live site origin(s). Prefer explicit list:
AGENTNOTE_ALLOWED_ORIGINS=https://www.agentnote.dev,https://agentnote.dev,https://memo.chasehuh.com

DATABASE_URL + CLERK_SECRET_KEY must already match production Clerk (do not print secrets). Confirm they are set; do not rotate unless broken.

Source Of Truth

Internal

• README.md — CRDT + Realtime sections (ops, one-way flag, compaction, IME, undo)
• components/agentnote-app.tsx — flag gates, useNoteDoc wiring
• lib/crdt/* — doc store, transports, composition gate, local IndexedDB
• services/collab/src/{index,env,room-auth}.ts — Hocuspocus auth/persist
• app/api/notes/[id]/route.ts — crdt_managed_body 409
• Closed issue Realtime sync: replace whole-document LWW note body with a Yjs CRDT (y-codemirror.next + Postgres update log), collab-ready #59; PRs feat(crdt): Yjs note body behind NEXT_PUBLIC_AGENTNOTE_CRDT (Phase 1) #60 (CRDT core), feat(crdt): nightly compaction of the note document update log #61/feat(crdt): local-first note documents with IndexedDB and reconnect flush #62 (compaction/offline if present), feat(crdt): Hocuspocus realtime transport on Railway (Phase 2) #63 (Railway realtime)
• Related hardening (legacy path, still relevant during mixed rollout): fix: stop 409-rebased stale buffers from silently clobbering newer note bodies (0804 wipe RCA) #73, fix: stop row-stamped peer drafts from laundering stale buffers into a valid save token (post-#73 multi-tab clobber) #74

External / live checks

• Collab health: https://agentnote-collab-production.up.railway.app/health
• App: https://www.agentnote.dev
• Vercel: project linked from /Users/huhchaewon/chase/memo/.vercel → prj_5vnO1SA0hDdvACA2Rn5vq8jTH0Ah (memo)
• Railway project: chasehuh (workspace chasehuh), service agentnote-collab

Audit Checklist (must complete before enable)

A. Correctness

• Seeding is exactly-once / advisory-locked; double-seed cannot duplicate body (tests + code path).
• HTTP sync and Hocuspocus store merge into one history (no second document lineage).
• Projection to notes.body stays coherent for publish//p/…, titles, sidebar, revisions.
• IME composition gate holds remote applies during Hangul composition.
• Peer-tab BroadcastChannel doc-update + WS path do not fight (origins: remote/broadcast/network).
• Legacy PUT correctly 409s once CRDT-managed; intentional Overwrite/Use server N/A on CRDT path (merge instead).
• Existing notes (e.g. 0804.md / dsb-wbhi-aqa) seed from current notes.body without truncation.

B. Security / tenancy

• Room auth: bad token / wrong user / alias id / missing note → fail closed before DB where designed.
• Origin allowlist behavior understood; production origins for agentnote.dev included.
• Clerk secret on collab matches production app Clerk instance.

C. Ops

• Collab /health green; recent Railway deploy not crash-looping.
• Compaction cron still configured (CRON_SECRET present on Vercel per earlier env ls).
• README allowlist note updated if origins change.
• Rollback: unsetting NEXT_PUBLIC_AGENTNOTE_COLLAB_URL falls back to HTTP CRDT poll; unsetting CRDT leaves already-seeded notes read-only for body — document this in the enable comment.

D. Tests

• pnpm vitest run (or project test script) green on main after any fix commits.
• Room-auth + persist merge tests still meaningful vs current code.

Implementation Notes (enable path)

Likely files (only if audit finds gaps)

• README.md — update allowlisted production origins to agentnote.dev
• services/collab/** — only if auth/origin/health bugs found
• lib/crdt/** / components/agentnote-app.tsx — only if audit finds real bugs blocking enable

Ops steps (authorized for production)

1. Fresh clone of chasehuh/agentnote (not Cursor worktree under shared checkout if using gt; for this repo historical path is worktree/clone + gh pr — prefer gh here; not sumelabs/sume-com).
2. Run audit locally against main; write findings as issue comment.
3. If no-go: stop. Do not set Vercel flags.
4. If go:
   • Set Railway AGENTNOTE_ALLOWED_ORIGINS (redeploy collab if needed).
   • vercel env add / update Production:
     • NEXT_PUBLIC_AGENTNOTE_CRDT=1
     • NEXT_PUBLIC_AGENTNOTE_COLLAB_URL=wss://agentnote-collab-production.up.railway.app
   • Trigger Vercel production redeploy so Next inlines the public env at build time (NEXT_PUBLIC_* require rebuild).
   • Smoke: two browser contexts / tabs on same note — type in A, see stream in B within ~100ms on WS path; confirm header not stuck Offline; confirm no legacy 409 clobber.
5. If small code/docs fixes are required for go: one PR, then enable after merge+deploy of that PR (order: fix → merge → flags → redeploy).

Authorization

• Authorized: read production env names (not values dumps of secrets), set the two Vercel public flags, update Railway AGENTNOTE_ALLOWED_ORIGINS, trigger redeploy, read Railway health/logs (no secret printing).
• Not authorized: DB destructive SQL on production notes, deleting note_doc_* rows, Clerk key rotation, changing DATABASE_URL, CRDT Phase 3 remote cursors/presence.

Edge Cases And Risks

• One-way per note: once opened under CRDT, legacy PUT is refused. Rolling the flag back is not a clean undo for seeded notes.
• Mixed-bundle window: old tabs without the flag still on legacy path; hard-refresh all agentnote.dev tabs after deploy (same operator instruction as fix: stop 409-rebased stale buffers from silently clobbering newer note bodies (0804 wipe RCA) #73/fix: stop row-stamped peer drafts from laundering stale buffers into a valid save token (post-#73 multi-tab clobber) #74).
• Offline IndexedDB: clearing site data drops unsynced offline edits.
• Preview deployments: may need allowlist entries or unset allowlist; out of scope unless needed for smoke.
• Remote cursors: intentionally off (Phase 3) — do not build them here.

Non-Goals

• Building CRDT from scratch (already shipped).
• Remote presence / cursors (Phase 3).
• Migrating every historical note eagerly (lazy seed on open is correct).
• Replacing fix: stop 409-rebased stale buffers from silently clobbering newer note bodies (0804 wipe RCA) #73/fix: stop row-stamped peer drafts from laundering stale buffers into a valid save token (post-#73 multi-tab clobber) #74 legacy guards while flag is off (keep them for rollback/mixed clients).
• Changing publish URL scheme, Clerk app, or note id format.

Acceptance Criteria

• Written audit with go/no-go and evidence (file paths, test results, health checks).
• If go: Production has NEXT_PUBLIC_AGENTNOTE_CRDT=1 and collab WSS URL; Vercel redeploy completed.
• If go: Railway allowlist includes https://www.agentnote.dev (and apex if used).
• If go: two-tab smoke on a real note shows streaming sync (not 1.5s-only poll feel when WS connected).
• If no-go: flags unset; blockers filed or listed with next PR suggestion.
• Operator note: hard-refresh all open agentnote.dev tabs after enable.
• Issue updated with enable commit/redeploy links; leave open if residuals, else close.

QA Plan

1. pnpm vitest run (full or at least lib/crdt + collab unit tests).
2. curl -sS https://agentnote-collab-production.up.railway.app/health
3. After enable: signed-in two tabs on https://www.agentnote.dev, same note — concurrent type, Hangul IME composition while other tab types, reload mid-edit, offline→online flush if easy.
4. Confirm publish page still shows projected body for a CRDT-touched note.
5. Confirm legacy PUT against a seeded note returns crdt_managed_body (optional API check with session).

Suggested PR Scope

• S if audit-only + env ops (maybe tiny README origin fix PR).
• M if audit finds a real bug that must land before enable — fix PR first, then ops enable in the same Opus session after merge.

Stage boundary: Opus owns audit + (on go) flag enable + any required fix PR through merge for this agentnote task (Chase asked to turn the flag on). Report done with evidence; hard-refresh reminder for Chase.

[chasehuh]

Audit verdict: GO — enabled in production

Audited main at 57be44e in a fresh clone (/tmp/agentnote-crdt-enable), then executed the enable path. One docs-only PR landed first (#76). Ops steps below are done; the signed-in two-tab smoke is the one residual (see bottom).

---

A. Correctness

Seeding is exactly-once. seedNoteDoc runs inside withNoteDocLock (pg_advisory_xact_lock(hashtext(note_id)), one transaction per note) and inserts with ON CONFLICT (note_id) DO NOTHING; loadOrSeedNoteDoc re-reads afterwards, so a lost race adopts the winner's state instead of starting a second lineage (lib/crdt/note-doc-store.ts:119-172). The client never seeds: useNoteDoc creates an empty Y.Doc and the editor is gated on docSession.ytext !== null (components/agentnote-app.tsx:1536-1554), so no plaintext-derived document can merge into a duplicated body.

One history, not two. The Hocuspocus Database extension calls the same getNoteDocState / persistNoteDocState helpers the HTTP route uses (services/collab/src/index.ts:63-93). store merges the room state into the loaded doc rather than replacing it, then snapshots, folds the tail, and re-projects — an HTTP append during a live room cannot be clobbered (note-doc-store.ts:522-587). through_seq <= $4 keeps the snapshot cursor monotonic in both persistNoteDocState and compactNoteDoc.

Projection stays coherent. projectNoteBody writes notes.body + deriveNoteTitle(body) under the same lock and records the prior body into note_revisions, so publish / /p/…, sidebar, titles, and archive keep reading exactly what they read before. On the realtime path the projection lands on the store debounce (2 s min, 10 s max), not per keystroke — documented behaviour, and the sidebar row refreshes from the notes-list poll.

IME. createCompositionGate holds inbound updates between compositionstart/compositionend and replays them (lib/crdt/composition-gate.ts). This survives the realtime path only because the provider gets its own Y.Doc bridged to the editor's (websocket-transport.ts:41-71) — otherwise y-codemirror.next would dispatch remote deltas into CodeMirror mid-Hangul-composition.

Peer tabs vs. socket don't fight. mirrorToPeerTabs drops remote / broadcast / network origins and the IndexedDB replay origin; bridgeDocuments drops EDITOR_ORIGIN inbound and NETWORK_ORIGIN outbound. Duplicates and re-orderings are correct CRDT inputs anyway.

Legacy PUT. The isCrdtManagedNote check in app/api/notes/[id]/route.ts:71-80 runs before the optimistic-concurrency check, so even an explicit "Overwrite" from a stale pre-flag tab returns 409 crdt_managed_body and cannot LWW-clobber the projection.

Existing notes. Production note_doc_snapshots and note_doc_updates both exist (created by ensureSchema) and are empty — 0 rows. dsb-wbhi-aqa (0804.md) is intact at 3821 chars, updated_at 2026-08-04T17:14:23Z. Nothing needs deleting; every note lazy-seeds from notes.body on first open. (34 live notes, 3 users — one Hocuspocus replica is amply sized.)

B. Security / tenancy

authorizeNoteRoom fails closed in order: origin → non-empty token → verifyToken → sub → per-documentName ownership re-check → canonical-id equality, so a valid token for user A cannot open user B's room and an alias is refused (not_canonical_id) rather than opening a second in-memory document (services/collab/src/room-auth.ts). Rejections never disclose "missing" vs. "not yours". The room key is always canonical in practice — activeId only ever comes from a Note returned by the API. loadOrSeedNoteDoc re-checks notes.user_id even for callers that already resolved the id.

Clerk: Railway CLERK_SECRET_KEY is byte-identical to Vercel Production's, both sk_live_ (verified by SHA-256 comparison; no values printed). DATABASE_URL differs only by host — Vercel via the public proxy, collab via postgres.railway.internal — same railway database.

Origin allowlist was the one real blocker: it was still https://memo.chasehuh.com only, while the app is served from https://www.agentnote.dev (apex and memo.chasehuh.com both 30x there). The Railway log had already recorded the symptom: collab auth rejected { reason: 'origin_not_allowed' }. Fixed in ops below.

C. Ops

• /health → {"ok":true,"service":"agentnote-collab"}; service Online, no restart loop.
• Graceful shutdown is safe: Hocuspocus registers SIGINT/SIGQUIT/SIGTERM → destroy(), and on last-connection close unloadImmediately: true forces a pending debounced store to executeNow — so a tab close or a Railway redeploy does not drop the last 2 s of edits. Anything still un-acked survives in IndexedDB and re-syncs by state vector on reconnect.
• Build is reproducible: Railway builds with pnpm 9.15.9, so the local pnpm-11 allowBuilds prompt does not affect it.
• Compaction cron intact: vercel.json /api/cron/compact-note-docs at 30 9 * * *, CRON_SECRET present in Production.
• README allowlist updated (docs: point the collab origin allowlist at agentnote.dev #76).

D. Tests

• pnpm vitest run → 24 files, 239 tests, all passing (includes room-auth, realtime-persistence, convergence, compaction, offline-sync, doc-routes, editor-binding.dom).
• pnpm exec tsc --noEmit → clean.
• pnpm exec eslint → 9 errors, all pre-existing react-hooks compiler rules in account-menu.tsx / agentnote-app.tsx / codemirror-editor.tsx / publish-panel.tsx, unrelated to CRDT. The repo has no .github/workflows, so there is no CI gate to be green.

---

Ops executed

Step	Result
PR	#76 — docs: point the collab origin allowlist at agentnote.dev → merged as ce21f03
Railway AGENTNOTE_ALLOWED_ORIGINS	https://www.agentnote.dev,https://agentnote.dev,https://memo.chasehuh.com — set, service rebuilt and Online
Vercel Production NEXT_PUBLIC_AGENTNOTE_CRDT	1
Vercel Production NEXT_PUBLIC_AGENTNOTE_COLLAB_URL	wss://agentnote-collab-production.up.railway.app
Production redeploy	memo-kqy2wj3t5-cwhuh.vercel.app (dpl inspect: https://vercel.com/cwhuh/memo/4jjQiQUjaNZXRi6qgAXDmSQiEzAL) — Ready, aliased to https://www.agentnote.dev

Origin fix verified end-to-end

Connected a real HocuspocusProvider to production with a deliberately bogus token and a forced Origin header, and read the server's own log line:

Origin sent	Server verdict
https://www.agentnote.dev	unauthenticated / invalid_token — origin gate passed, rejected at the token as designed
https://evil.example.com	forbidden / origin_not_allowed — allowlist still enforced

Env inlining verified

NEXT_PUBLIC_* are build-time. A local pnpm build with exactly the two production values inlines wss://agentnote-collab-production.up.railway.app into the client chunk, and the production redeploy was created after both variables existed in the Production scope.

---

Residuals (issue stays open)

1. Signed-in two-tab smoke is not done. I cannot authenticate as you against production Clerk. Everything up to the handshake is proven (origin accepted, token gate reached, flags inlined, both services healthy) — the last mile needs your session. Open the same note in two tabs on https://www.agentnote.dev and type in one; the other should stream within ~100 ms, and the header must not sit on "Offline".
2. A note this device has never opened is read-only until the socket connects. On the realtime transport the editor mounts on the CRDT document, and unlike the HTTP transport that document has no request/response fallback. Notes already in IndexedDB stay fully editable offline. Worse, the header reads "Saved" in that state because onStatus reports loading, not offline, before the first sync. Documented in docs: point the collab origin allowlist at agentnote.dev #76; a small follow-up could surface it honestly (and/or fall back to HTTP after N failed connects). Not a data-loss path.
3. Latent, unreachable in this config: syncNoteDoc's pull-only fast path (since === head.seq) cannot see a Hocuspocus store that folded the tail without appending a new note_doc_updates row. An idle HTTP-CRDT client would not pull WS-originated edits until it edits or reloads. Only reachable if some clients run CRDT-on without COLLAB_URL while others run realtime — not the case now, but relevant if you ever roll realtime back by unsetting only the collab URL.
4. ASCII-arrow migration (-> → →) no longer persists on the CRDT path: the autosave effect that used to write it back is short-circuited by CRDT_ENABLED. Cosmetic.
5. Rollback is not clean per note. Once a note is opened under the flag a snapshot row exists and legacy PUT is refused. Unsetting NEXT_PUBLIC_AGENTNOTE_COLLAB_URL alone is safe (falls back to HTTP CRDT + 1.5 s poll). Unsetting NEXT_PUBLIC_AGENTNOTE_CRDT leaves seeded notes readable and publishable but not body-editable until their note_doc_* rows are dropped (notes.body already holds the current text, so nothing is lost).

Operator note

Hard-refresh every open agentnote.dev tab. Tabs still running the pre-flag bundle keep using the legacy whole-document PUT; once another tab seeds a note, those writes come back as 409 crdt_managed_body and show the conflict banner. They cannot clobber anything — the CRDT check runs before the concurrency check — but they will look stuck until reloaded.