@elytracms/studio 0.0.91 → 0.0.93

package/convex/contract-parity.test.ts

@@ -2,10 +2,15 @@ import { describe, expect, it } from 'vitest'
 import { convexTest } from 'convex-test'
 import type { ConvexHttpClient } from 'convex/browser'
 import type { FunctionReference } from 'convex/server'
-import { measureMaxDepth } from '@elytracms/core/cms-core'
-import { PERSISTENCE_CONTRACT_SCENARIOS } from '@elytracms/core/persistence'
+import { fieldPath, measureMaxDepth, nodePropPath } from '@elytracms/core/cms-core'
+import {
+  PERSISTENCE_CONTRACT_SCENARIOS,
+  publishCurrentDraft,
+  replaceAtCurrentRevision,
+} from '@elytracms/core/persistence'
 import type { ContractContext } from '@elytracms/core/persistence'
 import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import type { ReactiveDocumentClient } from '../src/lib/persistence/convex-client'
 import schema from './schema'
 
 /**
@@ -49,17 +54,55 @@ interface AdapterBackend {
   mutation: (ref: FunctionReference<'mutation'>, args: Record<string, unknown>) => Promise<unknown>
 }
 
+/**
+ * EC-595 — the reactive-client DOUBLE a document subscription runs on: `onUpdate` runs
+ * the query now and RE-RUNS every active subscription after each mutation through the
+ * client double (convex-test has no push transport; this models Convex's reactive
+ * re-execution deterministically). The live two-tab push is owner-run.
+ */
+function reactiveDouble(backend: AdapterBackend) {
+  interface Subscription {
+    ref: FunctionReference<'query'>
+    args: Record<string, unknown>
+    onResult: (value: unknown) => void
+    onError: (error: Error) => void
+  }
+  const active = new Set<Subscription>()
+  const run = async (subscription: Subscription) => {
+    try {
+      subscription.onResult(await backend.query(subscription.ref, subscription.args))
+    } catch (error) {
+      subscription.onError(error as Error)
+    }
+  }
+  const reactive: ReactiveDocumentClient = {
+    onUpdate: (ref, args, onResult, onError) => {
+      const subscription = { ref, args, onResult, onError }
+      active.add(subscription)
+      void run(subscription)
+      return () => {
+        active.delete(subscription)
+      }
+    },
+    onAuthLost: () => () => {},
+  }
+  return { reactive, rerun: async () => Promise.all([...active].map(run)) }
+}
+
 /**
  * Adapt a convex-test accessor onto the `ConvexHttpClient` call surface the
  * adapter uses (`client.query(ref, args)` / `client.mutation(ref, args)` with
  * `makeFunctionReference` refs — which convex-test resolves natively).
  */
-function asAdapterClient(backend: AdapterBackend): ConvexHttpClient {
+function asAdapterClient(backend: AdapterBackend, afterMutation?: () => Promise<unknown>): ConvexHttpClient {
   return {
     query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) =>
       backend.query(ref, args ?? {}),
-    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) =>
-      backend.mutation(ref, args ?? {}),
+    mutation: async (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => {
+      const result = await backend.mutation(ref, args ?? {})
+      await afterMutation?.()
+      return result
+    },
   } as unknown as ConvexHttpClient
 }
 
@@ -90,15 +133,15 @@ async function freshBackend() {
 async function convexHarness(): Promise<ContractContext> {
   const t = await freshBackend()
   const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
-  const adapter = new ConvexPersistenceAdapter(asAdapterClient(asAdmin), PROJECT_ID, [])
+  const push = reactiveDouble(asAdmin)
+  const adapter = new ConvexPersistenceAdapter(asAdapterClient(asAdmin, push.rerun), PROJECT_ID, {
+    reactive: () => push.reactive,
+  })
   return {
     adapter,
     projectId: PROJECT_ID,
     emptyProjectId: EMPTY_PROJECT_ID,
     sessionUserId: SESSION_USER_ID,
-    // EC-183 (AD-11): the Convex adapter's CMS schema is config-owned (injected
-    // at construction, no `cmsSchemas` table) — seeding it is a no-op here.
-    async seedSchema() {},
   }
 }
 
@@ -140,7 +183,7 @@ describe('EC-286 write-chokepoint triggers (Convex-only: in-transaction referenc
 
     // A draft write derives draft rows in the same transaction — no published
     // rows until a live version is pinned.
-    await adapter.cms.upsertDocument(projectId, doc)
+    await replaceAtCurrentRevision(adapter.cms, projectId, doc)
     const draft = await adapter.references.outbound(projectId, source, { variant: 'draft' })
     expect(draft.map((r) => `${r.target.type}:${r.target.id}:${r.kind}`).sort()).toEqual([
       'asset:asset_cover:asset-field',
@@ -151,14 +194,13 @@ describe('EC-286 write-chokepoint triggers (Convex-only: in-transaction referenc
     )
 
     // Pinning a version re-runs maintenance: published rows mirror the draft rows.
-    const v = await adapter.cms.saveDocumentVersion(projectId, doc, { label: 'published' })
-    await adapter.cms.publishDocumentVersion(projectId, ref, v.version)
+    await publishCurrentDraft(adapter.cms, projectId, ref)
     expect(
       (await adapter.references.outbound(projectId, source, { variant: 'published' })).length,
     ).toBe(2)
 
     // A retargeting save REPLACES the rows (replace-all-for-source, never appends).
-    await adapter.cms.upsertDocument(projectId, {
+    await replaceAtCurrentRevision(adapter.cms, projectId, {
       ...doc,
       values: { author: { type: 'reference', collection: 'author', id: 'grace' } },
     })
@@ -169,6 +211,35 @@ describe('EC-286 write-chokepoint triggers (Convex-only: in-transaction referenc
     await adapter.cms.deleteDocument(projectId, ref)
     expect(await adapter.references.outbound(projectId, source)).toEqual([])
   })
+
+  it('EC-589 (Codex P01): the published rows are the PINNED SNAPSHOT’s — a draft-only edit does not move them', async () => {
+    const { adapter, projectId } = await convexHarness()
+    const doc = {
+      collection: 'post',
+      id: 'p01-probe',
+      values: { author: { type: 'reference', collection: 'author', id: 'A' } },
+    }
+    const ref = { collection: doc.collection, id: doc.id }
+    const source = { type: 'document' as const, id: 'post:p01-probe' }
+    const targets = async (variant: 'draft' | 'published') =>
+      (await adapter.references.outbound(projectId, source, { variant })).map((r) => r.target.id)
+
+    const created = await replaceAtCurrentRevision(adapter.cms, projectId, doc)
+    // The one-step publish (EC-595): version row + pin in one transaction; the trigger
+    // reads that row by `by_doc_version`.
+    const published = await adapter.cms.publishDocument(projectId, ref, created.revision)
+    expect(published.status).toBe('ok')
+    expect(await targets('published')).toEqual(['author:A']) // control: the publish is indexed
+
+    // A draft-only save to B: the draft rows move, the published rows stay on A — what
+    // delivery serves. (Before EC-589 both variants were extracted from the draft.)
+    await replaceAtCurrentRevision(adapter.cms, projectId, {
+      ...doc,
+      values: { author: { type: 'reference', collection: 'author', id: 'B' } },
+    })
+    expect(await targets('draft')).toEqual(['author:B'])
+    expect(await targets('published')).toEqual(['author:A'])
+  })
 })
 
 describe('EC-260 fold-at-rest (Convex-only: the stored form respects the depth cap)', () => {
@@ -179,25 +250,37 @@ describe('EC-260 fold-at-rest (Convex-only: the stored form respects the depth c
   it('stores an over-budget document folded to within 16 levels; the wire stays structured', async () => {
     const t = await freshBackend()
     const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
-    const adapter = new ConvexPersistenceAdapter(asAdapterClient(asAdmin), PROJECT_ID, [])
+    const adapter = new ConvexPersistenceAdapter(asAdapterClient(asAdmin), PROJECT_ID)
 
     let deep: unknown = { type: 'leaf', text: 'bottom' }
     for (let i = 0; i < 24; i++) deep = { type: 'level', index: i, child: deep }
     const doc = { collection: 'post', id: 'ec260-at-rest', values: { title: 'Deep', body: deep } }
     expect(measureMaxDepth(doc).depth).toBeGreaterThan(16) // the premise: over-budget on the wire
 
-    const stored = await adapter.cms.upsertDocument(PROJECT_ID, doc)
+    const stored = await replaceAtCurrentRevision(adapter.cms, PROJECT_ID, doc)
     expect(stored.document.values).toEqual(doc.values) // the wire never carries an envelope
 
     const atRest = await t.run(async (ctx) => {
       const row = await ctx.db
         .query('cmsDocuments')
-        .withIndex('by_doc', (q) => q.eq('collection', doc.collection).eq('docId', doc.id))
+        .withIndex('by_doc', (q) => q.eq('collection', doc.collection).eq('docId', doc.id).eq('variant', 'draft'))
         .unique()
       return row?.document as unknown
     })
     expect(atRest).toBeDefined()
     expect(measureMaxDepth(atRest).depth).toBeLessThanOrEqual(16) // folded at rest
+
+    // EC-585: the publish step's version row now carries `kind` — a top-level scalar
+    // beside the folded snapshot, so the WHOLE stored row stays within the cap.
+    await publishCurrentDraft(adapter.cms, PROJECT_ID, { collection: doc.collection, id: doc.id })
+    const versionRow = await t.run(async (ctx) =>
+      ctx.db
+        .query('documentVersions')
+        .withIndex('by_doc_version', (q) => q.eq('collection', doc.collection).eq('docId', doc.id).eq('version', 1))
+        .unique(),
+    )
+    expect(versionRow?.kind).toBe('publish')
+    expect(measureMaxDepth(versionRow).depth).toBeLessThanOrEqual(16)
   })
 })
 
@@ -217,14 +300,20 @@ describe('guard capability gates through the real functions (EC-150/EC-240c, Con
       new ConvexPersistenceAdapter(
         asAdapterClient(t.withIdentity({ subject, issuer: 'https://convex.test' })),
         PROJECT_ID,
-        [],
       )
 
     const viewer = forSubject('user_viewer')
     expect(await viewer.cms.listDocuments(PROJECT_ID)).toEqual([]) // content.read granted
     await expect(
-      viewer.cms.upsertDocument(PROJECT_ID, { collection: 'post', id: 'x', values: {} }),
+      viewer.cms.replaceDocument(PROJECT_ID, { collection: 'post', id: 'x', values: {} }, { ifAbsent: true }),
     ).rejects.toThrow(/unauthorized/) // content.write denied
+    await expect(
+      viewer.cms.patchDocument(PROJECT_ID, { collection: 'post', id: 'x' }, [{ op: 'unset', path: fieldPath('t') }], 1),
+    ).rejects.toThrow(/unauthorized/) // the patch verb is content.write too
+    // …but presence is content.read: a viewer is present on a document too.
+    await expect(
+      viewer.cms.reportPresence(PROJECT_ID, { collection: 'post', id: 'x' }, { sessionId: 'v' }),
+    ).resolves.toBeUndefined()
     await expect(viewer.users.listUsers(PROJECT_ID)).rejects.toThrow(/unauthorized/) // project.administer denied
 
     // An authenticated NON-member is rejected even on reads …
@@ -232,7 +321,72 @@ describe('guard capability gates through the real functions (EC-150/EC-240c, Con
       /unauthorized/,
     )
     // … and so is an anonymous caller.
-    const anonymous = new ConvexPersistenceAdapter(asAdapterClient(t), PROJECT_ID, [])
+    const anonymous = new ConvexPersistenceAdapter(asAdapterClient(t), PROJECT_ID)
     await expect(anonymous.cms.listDocuments(PROJECT_ID)).rejects.toThrow(/unauthorized/)
   })
 })
+
+describe('EC-595 — the aggregate at the Convex store (Convex-only)', () => {
+  it('(c) the variant key and the revision are REQUIRED: a pre-EC-595 row is refused by the schema', async () => {
+    const t = await freshBackend()
+    await expect(
+      t.run(async (ctx) => {
+        await ctx.db.insert('cmsDocuments', {
+          collection: 'post',
+          docId: 'legacy',
+          document: { collection: 'post', id: 'legacy', values: {} },
+          createdAt: 'x',
+          updatedAt: 'x',
+        } as never)
+      }),
+    ).rejects.toThrow()
+  })
+
+  it('(d) hot-row OCC: two patches in quick succession both commit, serialised — revision +2, two log rows', async () => {
+    const { adapter, projectId } = await convexHarness()
+    const ref = { collection: 'post', id: 'hot' }
+    await adapter.cms.replaceDocument(projectId, { ...ref, values: { a: 0, b: 0 } }, { ifAbsent: true })
+    const [first, second] = await Promise.all([
+      adapter.cms.patchDocument(projectId, ref, [{ op: 'set', path: fieldPath('a'), value: 1 }], 1),
+      adapter.cms.patchDocument(projectId, ref, [{ op: 'set', path: fieldPath('b'), value: 1 }], 1),
+    ])
+    expect(first.status).toBe('ok')
+    expect(second.status).toBe('ok')
+    const record = await adapter.cms.getDocument(projectId, ref)
+    expect(record.revision).toBe(3)
+    expect(record.document.values).toEqual({ a: 1, b: 1 })
+    const log = await adapter.cms.listDocumentPatches(projectId, ref, 1)
+    expect(log.map((row) => row.kind)).toEqual(['patch', 'patch'])
+  })
+
+  it('critic 7: a patch-log row carrying a 24-level value is stored within 16 levels (folded like a document)', async () => {
+    const t = await freshBackend()
+    const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+    const adapter = new ConvexPersistenceAdapter(asAdapterClient(asAdmin), PROJECT_ID)
+    let deep: unknown = { type: 'leaf', text: 'bottom' }
+    for (let i = 0; i < 24; i++) deep = { type: 'level', index: i, child: deep }
+    const ref = { collection: 'page', id: 'deep-log' }
+    const body = {
+      version: 2,
+      content: [{ type: 'elytra/component', id: 'n1', componentId: 'Text', props: { text: { value: 'x' } } }],
+    }
+    await adapter.cms.replaceDocument(PROJECT_ID, { ...ref, values: { body } }, { ifAbsent: true })
+    const patched = await adapter.cms.patchDocument(
+      PROJECT_ID,
+      ref,
+      [{ op: 'set', path: nodePropPath('body', undefined, 'n1', 'data'), value: deep }],
+      1,
+    )
+    expect(patched.status).toBe('ok')
+    const rows = await t.run(async (ctx) => ctx.db.query('documentPatches').collect())
+    const patchRow = rows.find((row) => row.kind === 'patch')
+    expect(patchRow).toBeDefined()
+    // The premise: unfolded, the row would nest row → patches → patch → value (24 levels) far past 16.
+    expect(measureMaxDepth({ ...patchRow, patches: patched.status === 'ok' ? [{ value: deep }] : [] }).depth).toBeGreaterThan(16)
+    const { _id: _ignoredId, _creationTime: _ignoredTime, ...stored } = patchRow!
+    expect(measureMaxDepth(stored).depth).toBeLessThanOrEqual(16)
+    const doc = await t.run(async (ctx) => ctx.db.query('cmsDocuments').collect())
+    const { _id: _docId, _creationTime: _docTime, ...docRow } = doc[0]!
+    expect(measureMaxDepth(docRow).depth).toBeLessThanOrEqual(16) // the document folded at rest after the merge
+  })
+})

package/convex/delivery.ts

@@ -1,5 +1,6 @@
 import { v } from 'convex/values'
-import { unfoldValue } from '@elytracms/core/cms-core'
+import { DRAFT_PERSPECTIVE, DRAFT_VARIANT, unfoldValue, variantOf } from '@elytracms/core/cms-core'
+import type { Perspective } from '@elytracms/core/cms-core'
 import { assetRecordFromRow, deliveryAssetRecord } from '@elytracms/core/persistence'
 import type { AssetRecord } from '@elytracms/core/persistence'
 import studioPackage from '../package.json'
@@ -46,8 +47,9 @@ import { requireCapability } from './guard'
  * (unpinned, so never on the public snapshot; on the draft snapshot as a plain
  * document the host's content client reports as `unknown-collection`).
  *
- * `draftSnapshot` is the draft-perspective equivalent (all stored document rows
- * including drafts) and is gated by the deployment env var `DRAFT_PREVIEW_TOKEN`
+ * `draftSnapshot` is the draft-perspective equivalent (every stored row of the
+ * draft VARIANT — the working drafts — EC-595) and is gated by the deployment env var
+ * `DRAFT_PREVIEW_TOKEN`
  * — set via `npx convex env set`. A missing or
  * mismatching token throws `unauthorized`; an unset env var closes the
  * endpoint entirely. The host server passes the token from its own env when
@@ -56,8 +58,12 @@ import { requireCapability } from './guard'
 
 interface DeliverySnapshot {
   projectId: string
-  perspective: 'published' | 'draft'
-  /** Stored document rows visible in the perspective (published: pinned versions only). */
+  /** The perspective served — `'published'` or the variant (`{ variant: 'draft' }`), EC-595. */
+  perspective: Perspective
+  /**
+   * Stored document rows visible in the perspective: published — pinned versions only;
+   * a variant — that variant's rows only.
+   */
   documents: unknown[]
   /** Asset metadata in the delivery `AssetRecord` shape (with serve URLs). */
   assets: unknown[]
@@ -102,7 +108,7 @@ export async function loadDeliveryAssets(ctx: QueryCtx, projectId: string): Prom
 export async function loadSnapshot(
   ctx: QueryCtx,
   args: { projectId: string },
-  perspective: 'published' | 'draft',
+  perspective: Perspective,
 ): Promise<DeliverySnapshot> {
   const { projectId } = args
 
@@ -117,13 +123,20 @@ export async function loadSnapshot(
   // the continuously-edited draft); a row with no pin never leaves the
   // deployment. Publish-ness is the pointer, full stop — there is no flat-state
   // fallback (the `state` field is gone).
+  //
+  // EC-595 (binding point 1): the aggregate holds one row per (document, VARIANT), so
+  // both branches select rows by variant. A variant perspective serves the rows of
+  // exactly that variant (only `draft` exists in v1); the publish pointer lives on the
+  // draft variant's row — `cms.ts` `listPublishedDocuments` reads it the same way — so a
+  // variant row copied with its pin can never serve the pinned snapshot twice.
+  const variant = variantOf(perspective)
   let documents: unknown[]
-  if (perspective === 'draft') {
-    documents = documentRows.map(unfoldDraft)
+  if (variant !== undefined) {
+    documents = documentRows.filter((row) => row.variant === variant).map(unfoldDraft)
   } else {
     documents = []
     for (const row of documentRows) {
-      if (row.publishedVersion === undefined) continue
+      if (row.variant !== DRAFT_VARIANT || row.publishedVersion === undefined) continue
       // EC-308: read THIS document's pinned version directly via `by_doc_version`
       // (EC-307) instead of collecting the entire append-only `documentVersions`
       // table and joining in memory — the published snapshot now scales with the
@@ -190,9 +203,9 @@ export const snapshot = query({
 })
 
 /**
- * Draft-perspective snapshot for token-holding preview hosts: all stored
- * document rows (drafts included). Gated by the `DRAFT_PREVIEW_TOKEN` deployment
- * env var.
+ * Draft-perspective snapshot for token-holding preview hosts: every stored row of
+ * the draft variant (the working drafts, EC-595). Gated by the `DRAFT_PREVIEW_TOKEN`
+ * deployment env var.
  */
 export const draftSnapshot = query({
   args: { projectId: v.string(), token: v.string() },
@@ -204,7 +217,7 @@ export const draftSnapshot = query({
     if (args.token !== expected) {
       throw new Error('unauthorized: invalid draft preview token')
     }
-    return loadSnapshot(ctx, { projectId: args.projectId }, 'draft')
+    return loadSnapshot(ctx, { projectId: args.projectId }, DRAFT_PERSPECTIVE)
   },
 })
 

package/convex/document-revalidate.test.ts

@@ -37,9 +37,9 @@ const modules = {
   './_generated/api.ts': async () => ({}),
 }
 
-const upsertDocument = makeFunctionReference<'mutation'>('cms:upsertDocument')
-const saveVersion = makeFunctionReference<'mutation'>('cms:saveDocumentVersion')
-const publishVersion = makeFunctionReference<'mutation'>('cms:publishDocumentVersion')
+const replaceDocument = makeFunctionReference<'mutation'>('cms:replaceDocument')
+const getDocument = makeFunctionReference<'query'>('cms:getDocument')
+const publishDocument = makeFunctionReference<'mutation'>('cms:publishDocument')
 const unpublishDocument = makeFunctionReference<'mutation'>('cms:unpublishDocument')
 const deleteDocument = makeFunctionReference<'mutation'>('cms:deleteDocument')
 const deliverySnapshot = makeFunctionReference<'query'>('delivery:snapshot')
@@ -92,28 +92,29 @@ function doc(collection: string, id: string, values: Record<string, unknown>) {
 }
 
 async function saveDraft({ asAdmin }: Backend, collection: string, id: string, values: Record<string, unknown>) {
-  await asAdmin.mutation(upsertDocument, {
+  // EC-595: a whole-document write carries its precondition (the revision it read, or create).
+  const current = (await asAdmin.query(getDocument, { collection, docId: id })) as { revision: number } | null
+  await asAdmin.mutation(replaceDocument, {
     collection,
     docId: id,
     document: doc(collection, id, values),
-    createdAt: STAMP,
-    updatedAt: STAMP,
+    precondition: current ? { revision: current.revision } : { ifAbsent: true },
+    at: STAMP,
   })
 }
 
+/**
+ * Publish `values` the way the one publish operation does (EC-585): the draft holds them,
+ * then the one-step `publishDocument` records a publish-kind version and pins it.
+ */
 async function publish(backend: Backend, collection: string, id: string, values: Record<string, unknown>) {
-  const version = (await backend.asAdmin.mutation(saveVersion, {
-    collection,
-    docId: id,
-    snapshot: doc(collection, id, values),
-    createdAt: STAMP,
-  })) as { version: number }
-  await backend.asAdmin.mutation(publishVersion, {
+  await saveDraft(backend, collection, id, values)
+  const current = (await backend.asAdmin.query(getDocument, { collection, docId: id })) as { revision: number }
+  await backend.asAdmin.mutation(publishDocument, {
     collection,
     docId: id,
-    version: version.version,
-    updatedAt: STAMP,
-    publishedAt: STAMP,
+    expectedRevision: current.revision,
+    at: STAMP,
   })
 }
 

package/convex/orphan-hydration.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import type { FunctionReference } from 'convex/server'
+import type { CollectionDef } from '@elytracms/core/cms-core'
+import { createSequentialIdFactory } from '@elytracms/core/determinism'
+import { createOperations } from '@elytracms/core/operations'
+import { replaceAtCurrentRevision } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import { loadHydratedCms } from '../src/lib/operations/session-hydration'
+import schema from './schema'
+
+/**
+ * EC-606 close-out — the orphan count on the CONNECTED path, short of a signed-in
+ * connected studio (owner-run).
+ *
+ * The count itself is mode-independent: `loadHydratedCms` runs over whatever
+ * operations client the session has, and `project-session.test.tsx` already proves
+ * the content session carries its `orphans` to the rail foot. What only the connected
+ * mode adds is the backend between them — the real `cms:listDocuments` handler and the
+ * production `ConvexPersistenceAdapter`. This runs exactly that path on convex-test's
+ * in-memory backend (the harness of `contract-parity.test.ts`: the adapter's HTTP client
+ * is a call-through double onto `t.query` / `t.mutation`): a row of a collection the
+ * config does not declare must reach the session's orphan list, with its published
+ * count, and must not reach its documents.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const PROJECT_ID = 'orphan-hydration'
+const SESSION_USER_ID = 'user_admin'
+
+const DECLARED: CollectionDef[] = [{ id: 'post', kind: 'document', fields: [{ name: 'title', type: 'text' }] }]
+
+interface AdapterBackend {
+  query: (ref: FunctionReference<'query'>, args: Record<string, unknown>) => Promise<unknown>
+  mutation: (ref: FunctionReference<'mutation'>, args: Record<string, unknown>) => Promise<unknown>
+}
+
+function asAdapterClient(backend: AdapterBackend): ConvexHttpClient {
+  return {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => backend.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => backend.mutation(ref, args ?? {}),
+  } as unknown as ConvexHttpClient
+}
+
+/** The production adapter over a fresh in-memory Convex backend, as the session admin. */
+async function connectedAdapter() {
+  const t = convexTest(schema, modules)
+  const now = '2026-10-26T00:00:00.000Z'
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: SESSION_USER_ID, role: 'admin', createdAt: now, updatedAt: now })
+  })
+  const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+  return new ConvexPersistenceAdapter(asAdapterClient(asAdmin), PROJECT_ID)
+}
+
+/** The operations client a headless embedder (or the session) builds over that adapter. */
+function operationsOver(adapter: ConvexPersistenceAdapter) {
+  return createOperations({
+    adapter,
+    collections: () => DECLARED,
+    validateDocument: () => [],
+    idFactory: createSequentialIdFactory('doc'),
+  })
+}
+
+describe('EC-606 — orphans reach a connected session through the Convex functions', () => {
+  it('a stored row of an undeclared collection is counted (published too), and kept out of the documents', async () => {
+    const adapter = await connectedAdapter()
+    await replaceAtCurrentRevision(adapter.cms, PROJECT_ID, {
+      collection: 'post',
+      id: 'kept',
+      values: { title: 'Kept' },
+    })
+    await replaceAtCurrentRevision(adapter.cms, PROJECT_ID, {
+      collection: 'cms-data-sources',
+      id: 'legacy-draft',
+      values: { name: 'left behind by the data-binding subsystem' },
+    })
+    const published = await replaceAtCurrentRevision(adapter.cms, PROJECT_ID, {
+      collection: 'cms-data-sources',
+      id: 'legacy-live',
+      values: { name: 'and published' },
+    })
+    const pinned = await adapter.cms.publishDocument(
+      PROJECT_ID,
+      { collection: 'cms-data-sources', id: 'legacy-live' },
+      published.revision,
+    )
+    expect(pinned.status).toBe('ok')
+
+    const result = await loadHydratedCms(operationsOver(adapter), PROJECT_ID, DECLARED)
+    expect(result.ok).toBe(true)
+    if (!result.ok || !result.value) throw new Error('hydration must answer')
+    expect(result.value.orphans).toEqual([{ collection: 'cms-data-sources', count: 2, published: 1 }])
+    expect(result.value.documents.map((document) => `${document.collection}:${document.id}`)).toEqual(['post:kept'])
+  })
+
+  it('CONTROL: declared rows only → no orphans (the count is not a constant)', async () => {
+    const adapter = await connectedAdapter()
+    await replaceAtCurrentRevision(adapter.cms, PROJECT_ID, {
+      collection: 'post',
+      id: 'kept',
+      values: { title: 'Kept' },
+    })
+
+    const result = await loadHydratedCms(operationsOver(adapter), PROJECT_ID, DECLARED)
+    if (!result.ok || !result.value) throw new Error('hydration must answer')
+    expect(result.value.orphans).toEqual([])
+    expect(result.value.documents).toHaveLength(1)
+  })
+})

package/convex/presence-cost.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { PRESENCE_TTL_MS } from '@elytracms/core/persistence'
+import schema from './schema'
+
+/**
+ * EC-595 A2 — the thin presence's COST (critic, operator-read). A heartbeat writes a
+ * `documentPresence` row; every reactive query whose read set holds that row re-runs and
+ * pushes its WHOLE result to every subscriber. Measured here: the bytes one re-run of the
+ * document subscription pushes, for a ~20 KB document with two editors present — the
+ * payload a heartbeat costs per subscriber.
+ *
+ * Reported (EC-595 Done, part A2): when the row and the presence rode ONE query
+ * (`watchDocument` returned `{ row, presence }`), every heartbeat re-pushed the 20 KB row
+ * to both editors. The split (`watchDocument` = the row, `watchPresence` = the presence,
+ * merged by the adapter behind the same `subscribeDocument`) makes a heartbeat re-run
+ * only the presence query: its read set no longer includes the row, and the row query's
+ * read set no longer includes presence (Convex re-runs a query only when data it read
+ * changed — https://docs.convex.dev/realtime).
+ */
+
+// The same module map contract-parity.test.ts uses (no `_generated` dir; a stub key
+// satisfies convex-test's root lookup).
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const SESSION_USER_ID = 'user_admin'
+const watchDocument = makeFunctionReference<'query'>('cms:watchDocument')
+const watchPresence = makeFunctionReference<'query'>('cms:watchPresence')
+const replaceDocument = makeFunctionReference<'mutation'>('cms:replaceDocument')
+const reportPresence = makeFunctionReference<'mutation'>('cms:reportPresence')
+
+/** A body of roughly `bytes` bytes of prose (a long rich-text-ish field). */
+function prose(bytes: number): string {
+  const sentence = 'The analytical engine weaves algebraic patterns as the Jacquard loom weaves flowers. '
+  return sentence.repeat(Math.ceil(bytes / sentence.length)).slice(0, bytes)
+}
+
+async function backend() {
+  const t = convexTest(schema, modules)
+  const now = new Date().toISOString()
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: SESSION_USER_ID, role: 'admin', createdAt: now, updatedAt: now })
+  })
+  return t.withIdentity({ subject: SESSION_USER_ID })
+}
+
+describe('the presence heartbeat’s cost (EC-595 A2)', () => {
+  it('a heartbeat re-pushes only the presence — never the 20 KB document', async () => {
+    const t = await backend()
+    const document = { collection: 'post', id: 'p1', values: { title: 'Ada', body: prose(20_000) } }
+    await t.mutation(replaceDocument, {
+      collection: 'post',
+      docId: 'p1',
+      document,
+      precondition: { ifAbsent: true },
+      at: new Date().toISOString(),
+    })
+    const at = new Date().toISOString()
+    for (const [sessionId, actorName] of [
+      ['tab-a', 'Ada'],
+      ['tab-b', 'Grace'],
+    ] as const) {
+      await t.mutation(reportPresence, {
+        collection: 'post',
+        docId: 'p1',
+        sessionId,
+        actorName,
+        path: [{ kind: 'field', name: 'title' }],
+        at,
+        ttlMs: PRESENCE_TTL_MS,
+      })
+    }
+    const args = { collection: 'post', docId: 'p1' }
+    const rowBytes = JSON.stringify(await t.query(watchDocument, args)).length
+    const presenceBytes = JSON.stringify(await t.query(watchPresence, args)).length
+    // Recorded for the Done section (bytes per push per subscriber).
+    console.info(`[presence-cost] row query ${rowBytes} B · presence query ${presenceBytes} B`)
+    // The document query carries the row and NOTHING of presence…
+    expect(rowBytes).toBeGreaterThan(20_000)
+    expect(JSON.stringify(await t.query(watchDocument, args))).not.toContain('tab-a')
+    // …the presence query carries the heartbeats and nothing of the row.
+    expect(presenceBytes).toBeLessThan(1_000)
+    expect(JSON.stringify(await t.query(watchPresence, args))).not.toContain('analytical engine')
+  })
+})