@elytracms/studio 0.0.91 → 0.0.93

package/convex/cms.ts

@@ -1,28 +1,57 @@
 import { v } from 'convex/values'
-import { documentsSemanticEqual, foldDocument, unfoldDocument } from '@elytracms/core/cms-core'
-import type { CmsDocument } from '@elytracms/core/cms-core'
+import {
+  DRAFT_VARIANT,
+  applyDocumentPatches,
+  documentsSemanticEqual,
+  foldDocument,
+  foldPatchesForStorage,
+  replacePreconditionHolds,
+  unfoldDocument,
+  unfoldValue,
+} from '@elytracms/core/cms-core'
+import type { CmsDocument, DocumentPatch, PatchLogKind, ReplacePrecondition } from '@elytracms/core/cms-core'
+import { isPinnableVersion } from '@elytracms/core/persistence'
+import type { DocumentVersionKind } from '@elytracms/core/persistence'
 import { mutation, query } from './functions'
+import type { MutationCtx, QueryCtx } from './functions'
 import { requireCapability } from './guard'
 import { assertWithinWriteLimits } from './write-limits'
 
 /**
- * CMS document persistence (EC-043). The backend stores **documents only**
- * (AD-11, EC-183): CMS collection schemas are config-owned — they live in
- * `elytra.config.ts`, read by the studio + host — so there is no `cmsSchemas`
- * table and no schema read/write function here. Collection-membership
- * validation lives in `@elytracms/core/cms-core` `validateDocument` (the studio runs it
- * pre-dispatch); this layer is a pure document store.
+ * CMS document persistence (EC-043) — the revisioned document AGGREGATE (EC-595,
+ * ratified 2026-10-24). The backend stores **documents only** (AD-11, EC-183): there is
+ * no `cmsSchemas` table and no schema function here.
+ *
+ * ## Server-side trust (EC-565 1e — the boundary EC-304 Phase B inherits)
+ *
+ * Owner, verbatim: "yes keep validation client-side. server-side validation enforces
+ * migrations or could lead to invalid/lost data (the payload-sql-approach). schema should
+ * be the lens and the mask to put on the data." So these handlers enforce exactly three
+ * things, all data-only: **the revision** (every write and publish carries the one it was
+ * made against; a moved document refuses with `conflict`), **pin integrity** (a pinned
+ * version exists and belongs to this document) and **authority** (`requireCapability`).
+ * They never validate a document against a schema and never canonicalise a value — the
+ * client gate does both (a `content.write` member bypassing the studio can publish an
+ * invalid document; delivery parse raises it visibly, AD-14).
+ *
+ * ## Two write verbs, both revision-aware
+ *
+ * `replaceDocument` (whole document under a precondition: `{ revision }`, `{ ifAbsent }`,
+ * `{ ifCollectionEmpty }`) and `patchDocument` (path-level patches against a base
+ * revision, merged per path IN the transaction by THE merge, `applyDocumentPatches` from
+ * cms-core — the same function the in-memory store calls). Convex OCC makes the
+ * check-and-write atomic; the check itself is the revision argument. A refusal is a
+ * returned `conflict` outcome carrying the current row — never a throw. Every write
+ * appends ONE `documentPatches` row (the patch log) and bumps `revision`.
  *
  * ## EC-260 depth-budget codec (the storage boundary)
  *
  * Convex caps STORED documents at 16 nesting levels but allows 64 in function
- * args/returns. Ordinary content (deep rich text, nested compositions) trips 16 at
- * rest, so every write here FOLDS over-budget field values into self-describing
- * leaf envelopes immediately before `ctx.db`, and every read UNFOLDS before the
- * value leaves the function. Mutations receive the UNFOLDED value over the wire, so
- * the AD-15 reference walker (in the write-chokepoint trigger, which unfolds first)
- * always sees structured content. The wire never carries an envelope; only raw
- * `ctx.db` reads / the dashboard see the folded storage form.
+ * args/returns. Every write FOLDS over-budget field values into self-describing leaf
+ * envelopes immediately before `ctx.db`, and every read UNFOLDS before the value leaves
+ * the function. A patch merge unfolds the stored draft, applies, and re-folds; the patch
+ * log folds the values it carries the same way (`foldPatchesForStorage`). The wire never
+ * carries an envelope.
  */
 
 /** Unfold the `document` blob of a stored row before it leaves the function. */
@@ -35,74 +64,228 @@ function withUnfoldedSnapshot<R extends { snapshot: unknown }>(row: R): R {
   return { ...row, snapshot: unfoldDocument(row.snapshot as CmsDocument) }
 }
 
-export const upsertDocument = mutation({
+type Ctx = QueryCtx | MutationCtx
+
+function draftRow(ctx: Ctx, collection: string, docId: string) {
+  return ctx.db
+    .query('cmsDocuments')
+    .withIndex('by_doc', (q) => q.eq('collection', collection).eq('docId', docId).eq('variant', DRAFT_VARIANT))
+    .first()
+}
+
+async function versionRow(ctx: Ctx, collection: string, docId: string, version: number) {
+  return ctx.db
+    .query('documentVersions')
+    .withIndex('by_doc_version', (q) =>
+      q.eq('collection', collection).eq('docId', docId).eq('version', version),
+    )
+    .unique()
+}
+
+/**
+ * EC-449 / EC-595 binding point 6: the changed flag DERIVED in the transaction — ONE
+ * semantic compare of the draft against the snapshot the pin selects. Unpublished → no
+ * flag; a damaged pin (no version row) keeps the previous verdict.
+ */
+async function changedFlag(
+  ctx: Ctx,
+  collection: string,
+  docId: string,
+  publishedVersion: number | undefined,
+  draft: CmsDocument,
+  previous: boolean | undefined,
+): Promise<{ hasUnpublishedChanges?: boolean }> {
+  if (publishedVersion === undefined) return {}
+  const pinned = await versionRow(ctx, collection, docId, publishedVersion)
+  if (!pinned) return previous === undefined ? {} : { hasUnpublishedChanges: previous }
+  return {
+    hasUnpublishedChanges: !documentsSemanticEqual(unfoldDocument(pinned.snapshot as CmsDocument), draft),
+  }
+}
+
+/** Append one patch-log row (values folded, EC-260). */
+async function appendLog(
+  ctx: MutationCtx,
+  entry: { collection: string; docId: string; revision: number; kind: PatchLogKind; actor: string; at: string },
+  patches: readonly DocumentPatch[] = [],
+): Promise<void> {
+  await ctx.db.insert('documentPatches', {
+    collection: entry.collection,
+    docId: entry.docId,
+    variant: DRAFT_VARIANT,
+    revision: entry.revision,
+    kind: entry.kind,
+    actor: entry.actor,
+    at: entry.at,
+    patches: foldPatchesForStorage(patches),
+  })
+}
+
+/** The log rows above `afterRevision`, ascending (patch values unfolded). */
+async function logAfter(ctx: Ctx, collection: string, docId: string, afterRevision: number) {
+  const rows = await ctx.db
+    .query('documentPatches')
+    .withIndex('by_doc_revision', (q) =>
+      q.eq('collection', collection).eq('docId', docId).eq('variant', DRAFT_VARIANT).gt('revision', afterRevision),
+    )
+    .collect()
+  return rows.map((row) => ({
+    ...row,
+    kind: row.kind as PatchLogKind,
+    patches: unfoldValue(row.patches) as DocumentPatch[],
+  }))
+}
+
+/** Delete every row of a document's patch log and presence (delete / clear cascade). */
+async function deleteBookkeeping(ctx: MutationCtx, collection: string, docId: string): Promise<void> {
+  const log = await ctx.db
+    .query('documentPatches')
+    .withIndex('by_doc_revision', (q) => q.eq('collection', collection).eq('docId', docId).eq('variant', DRAFT_VARIANT))
+    .collect()
+  for (const row of log) await ctx.db.delete(row._id)
+  const presence = await ctx.db
+    .query('documentPresence')
+    .withIndex('by_doc', (q) => q.eq('collection', collection).eq('docId', docId).eq('variant', DRAFT_VARIANT))
+    .collect()
+  for (const row of presence) await ctx.db.delete(row._id)
+}
+
+const preconditionValidator = v.union(
+  v.object({ revision: v.number() }),
+  v.object({ ifAbsent: v.literal(true) }),
+  v.object({ ifCollectionEmpty: v.literal(true) }),
+)
+
+/**
+ * The whole-document write (EC-595 binding point 2, EC-578): create (`ifAbsent`), a
+ * singleton's first document (`ifCollectionEmpty`), or a replace at an exact revision —
+ * never an unconditional overwrite. Returns `{ status: 'conflict', current, existing? }`
+ * when the precondition does not hold.
+ */
+export const replaceDocument = mutation({
   args: {
     collection: v.string(),
     docId: v.string(),
     document: v.any(),
-    createdAt: v.string(),
-    updatedAt: v.string(),
+    precondition: preconditionValidator,
+    at: v.string(),
   },
   handler: async (ctx, args) => {
-    await requireCapability(ctx, 'content.write') // EC-150
-    // EC-304 B-4: defensive server-side depth/byte clamp at the `v.any()` chokepoint,
-    // BEFORE fold/write. Rejects abusive structurally-deep / oversized payloads that a
-    // direct Convex call (bypassing the client-side lens) could otherwise land. Limits
-    // are generous — legitimate content never trips them (see write-limits.ts).
+    const actor = await requireCapability(ctx, 'content.write') // EC-150
+    // EC-304 B-4: defensive server-side depth/byte clamp at the `v.any()` chokepoint.
     assertWithinWriteLimits(args.document, 'document')
-    // EC-260: fold for storage. `args.document` arrives UNFOLDED over the 64-level
-    // arg wire; the trigger unfolds before extracting references, so folding here
-    // (strictly before the `ctx.db` write) never hides a reference from the walker.
-    const stored = { ...args, document: foldDocument(args.document as CmsDocument) }
-    const existing = await ctx.db
-      .query('cmsDocuments')
-      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
-      .first()
+    const precondition = args.precondition as ReplacePrecondition
+    const existing = await draftRow(ctx, args.collection, args.docId)
+    const inCollection =
+      'ifCollectionEmpty' in precondition
+        ? await ctx.db
+            .query('cmsDocuments')
+            .withIndex('by_collection', (q) => q.eq('collection', args.collection))
+            .first()
+        : null
+    if (!replacePreconditionHolds(precondition, existing ?? undefined, inCollection !== null)) {
+      return {
+        status: 'conflict' as const,
+        current: existing ? withUnfoldedDocument(existing) : null,
+        ...(inCollection ? { existing: withUnfoldedDocument(inCollection) } : {}),
+      }
+    }
+    const draft = args.document as CmsDocument
+    const revision = (existing?.revision ?? 0) + 1
+    // EC-260: fold for storage, strictly before `ctx.db` (the trigger unfolds before
+    // extracting references, so folding never hides one from the walker).
+    const stored = foldDocument(draft)
     if (existing) {
-      // EC-449: a draft save while PUBLISHED re-materializes `hasUnpublishedChanges`
-      // by comparing the incoming draft (unfolded, off the arg wire) against the
-      // pinned published snapshot — the mutation has both sides, so the compare runs
-      // ONCE here, in-transaction (never per list render). A no-op save compares
-      // equal → `false` (never flips to true); a revert back to the published
-      // content clears a previously-true flag the same way. Schema-free (AD-11 — the
-      // deployment stores documents only); the compare is the editor's exact
-      // `documentsSemanticEqual`, the ONE def-less verdict over canonical forms (EC-586). Unpublished doc / missing pinned row →
-      // absent-key patch preserves the row as-is (the flag doesn't apply).
-      let changedFlag = {}
-      if (existing.publishedVersion !== undefined) {
-        const pinned = await ctx.db
-          .query('documentVersions')
-          .withIndex('by_doc_version', (q) =>
-            q
-              .eq('collection', args.collection)
-              .eq('docId', args.docId)
-              .eq('version', existing.publishedVersion as number),
-          )
-          .unique()
-        if (pinned) {
-          changedFlag = {
-            hasUnpublishedChanges: !documentsSemanticEqual(
-              unfoldDocument(pinned.snapshot as CmsDocument),
-              args.document as CmsDocument,
-            ),
-          }
-        }
+      const patch = {
+        document: stored,
+        revision,
+        updatedAt: args.at,
+        ...(await changedFlag(
+          ctx,
+          args.collection,
+          args.docId,
+          existing.publishedVersion,
+          draft,
+          existing.hasUnpublishedChanges,
+        )),
       }
-      // EC-153 parity: updates preserve `createdAt`, exactly like in-memory.
-      // EC-286: the write-chokepoint trigger reindexes references in-transaction.
-      const patch = { ...stored, createdAt: existing.createdAt, ...changedFlag }
       await ctx.db.patch(existing._id, patch)
-      // EC-322: return the merged row directly instead of re-reading the full
-      // (up-to-~20 KB) document body via `ctx.db.get`. `patch` only overwrites the
-      // supplied fields, so `{ ...existing, ...patch }` is byte-identical to the
-      // stored row (system fields + untouched `publishedVersion` carried from
-      // `existing`) — cutting one full-document read off the hottest write path.
-      // EC-260: unfold the folded body back to structured form for the return.
-      return withUnfoldedDocument({ ...existing, ...patch })
+      await appendLog(ctx, { collection: args.collection, docId: args.docId, revision, kind: 'replace', actor, at: args.at })
+      return { status: 'ok' as const, row: withUnfoldedDocument({ ...existing, ...patch }) }
     }
-    const id = await ctx.db.insert('cmsDocuments', stored)
+    const id = await ctx.db.insert('cmsDocuments', {
+      collection: args.collection,
+      docId: args.docId,
+      variant: DRAFT_VARIANT,
+      revision,
+      document: stored,
+      createdAt: args.at,
+      updatedAt: args.at,
+    })
+    await appendLog(ctx, { collection: args.collection, docId: args.docId, revision, kind: 'replace', actor, at: args.at })
     const row = await ctx.db.get(id)
-    return row ? withUnfoldedDocument(row) : row
+    return { status: 'ok' as const, row: row ? withUnfoldedDocument(row) : null }
+  },
+})
+
+/**
+ * Path-level patches against a base revision (EC-595 binding point 4): THE merge runs
+ * here, in the transaction, against the current draft and the log rows in
+ * `(baseRevision, revision]`. Refused positions come back with their current values;
+ * the rest apply in one write (one revision bump, one log row). `missing` when the
+ * document does not exist.
+ */
+export const patchDocument = mutation({
+  args: {
+    collection: v.string(),
+    docId: v.string(),
+    patches: v.any(),
+    baseRevision: v.number(),
+    at: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const actor = await requireCapability(ctx, 'content.write') // EC-150
+    assertWithinWriteLimits(args.patches, 'patches')
+    const existing = await draftRow(ctx, args.collection, args.docId)
+    if (!existing) return { status: 'missing' as const }
+    const merged = applyDocumentPatches({
+      document: unfoldDocument(existing.document as CmsDocument),
+      patches: args.patches as DocumentPatch[],
+      since: await logAfter(ctx, args.collection, args.docId, args.baseRevision),
+      staleBase: args.baseRevision < (existing.patchLogFloor ?? 0) || args.baseRevision > existing.revision,
+    })
+    if (merged.applied.length === 0) {
+      return {
+        status: 'conflict' as const,
+        row: withUnfoldedDocument(existing),
+        refused: merged.refused,
+        appliedCount: 0,
+      }
+    }
+    const revision = existing.revision + 1
+    const patch = {
+      document: foldDocument(merged.document),
+      revision,
+      updatedAt: args.at,
+      ...(await changedFlag(
+        ctx,
+        args.collection,
+        args.docId,
+        existing.publishedVersion,
+        merged.document,
+        existing.hasUnpublishedChanges,
+      )),
+    }
+    await ctx.db.patch(existing._id, patch)
+    await appendLog(
+      ctx,
+      { collection: args.collection, docId: args.docId, revision, kind: 'patch', actor, at: args.at },
+      merged.applied,
+    )
+    const row = withUnfoldedDocument({ ...existing, ...patch })
+    return merged.refused.length === 0
+      ? { status: 'ok' as const, row }
+      : { status: 'conflict' as const, row, refused: merged.refused, appliedCount: merged.applied.length }
   },
 })
 
@@ -110,14 +293,112 @@ export const getDocument = query({
   args: { collection: v.string(), docId: v.string() },
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.read') // EC-150
-    const row = await ctx.db
-      .query('cmsDocuments')
-      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
-      .first()
+    const row = await draftRow(ctx, args.collection, args.docId)
     return row ? withUnfoldedDocument(row) : row // EC-260: unfold before returning
   },
 })
 
+/**
+ * The narrow document subscription (EC-595 binding point 7, EC-309's v1 slice): the draft
+ * row. The studio's reactive client re-runs it on every change of the row.
+ *
+ * EC-595 A2 — the row and the presence are TWO reactive queries ({@link watchPresence})
+ * behind the one `subscribeDocument` (the adapter merges them). Measured
+ * (`presence-cost.test.ts`): as one query, a ~20 KB document with two editors pushed
+ * 20,583 B to every subscriber on every presence heartbeat (2 editors × 360 heartbeats/h
+ * × 2 subscribers ≈ 29.6 MB/h per document, each push a re-run reading the row). Split,
+ * a heartbeat re-runs only the presence query (its read set holds no row, and this
+ * query's holds no presence) and pushes a few hundred bytes.
+ */
+export const watchDocument = query({
+  args: { collection: v.string(), docId: v.string() },
+  handler: async (ctx, args) => {
+    await requireCapability(ctx, 'content.read') // EC-150
+    const row = await draftRow(ctx, args.collection, args.docId)
+    return { row: row ? withUnfoldedDocument(row) : null }
+  },
+})
+
+/**
+ * The presence heartbeats on one document (EC-595 thin presence) — its own reactive
+ * query so a heartbeat never re-pushes the document (see {@link watchDocument}).
+ * Liveness is the READER's call (its injected clock); this query never reads
+ * `Date.now()`.
+ */
+export const watchPresence = query({
+  args: { collection: v.string(), docId: v.string() },
+  handler: async (ctx, args) => {
+    await requireCapability(ctx, 'content.read') // EC-150
+    const presence = await ctx.db
+      .query('documentPresence')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId).eq('variant', DRAFT_VARIANT))
+      .collect()
+    return presence.map((entry) => ({
+      sessionId: entry.sessionId,
+      ...(entry.actor !== undefined ? { actor: entry.actor } : {}),
+      ...(entry.actorName !== undefined ? { actorName: entry.actorName } : {}),
+      ...(entry.path !== undefined ? { path: entry.path } : {}),
+      at: entry.at,
+    }))
+  },
+})
+
+/**
+ * A field-presence heartbeat (EC-595 Stage A): upsert this session's row and delete the
+ * document's STALE heartbeats (older than the TTL relative to this heartbeat's `at`), so
+ * presence needs no timer. `content.read` suffices — a viewer is present too.
+ */
+export const reportPresence = mutation({
+  args: {
+    collection: v.string(),
+    docId: v.string(),
+    sessionId: v.string(),
+    actorName: v.optional(v.string()),
+    path: v.optional(v.any()),
+    at: v.string(),
+    ttlMs: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const actor = await requireCapability(ctx, 'content.read')
+    const rows = await ctx.db
+      .query('documentPresence')
+      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId).eq('variant', DRAFT_VARIANT))
+      .collect()
+    const now = Date.parse(args.at)
+    let own: (typeof rows)[number] | undefined
+    for (const row of rows) {
+      if (row.sessionId === args.sessionId) own = row
+      else if (now - Date.parse(row.at) > args.ttlMs) await ctx.db.delete(row._id)
+    }
+    const entry = {
+      collection: args.collection,
+      docId: args.docId,
+      variant: DRAFT_VARIANT,
+      sessionId: args.sessionId,
+      actor,
+      ...(args.actorName !== undefined ? { actorName: args.actorName } : {}),
+      path: args.path,
+      at: args.at,
+    }
+    if (own) await ctx.db.replace(own._id, entry)
+    else await ctx.db.insert('documentPresence', entry)
+  },
+})
+
+export const clearPresence = mutation({
+  args: { collection: v.string(), docId: v.string(), sessionId: v.string() },
+  handler: async (ctx, args) => {
+    await requireCapability(ctx, 'content.read')
+    const own = await ctx.db
+      .query('documentPresence')
+      .withIndex('by_doc_session', (q) =>
+        q.eq('collection', args.collection).eq('docId', args.docId).eq('variant', DRAFT_VARIANT).eq('sessionId', args.sessionId),
+      )
+      .first()
+    if (own) await ctx.db.delete(own._id)
+  },
+})
+
 export const listDocuments = query({
   args: { collection: v.optional(v.string()) },
   handler: async (ctx, args) => {
@@ -128,7 +409,15 @@ export const listDocuments = query({
           .withIndex('by_collection', (q) => q.eq('collection', args.collection as string))
           .collect()
       : await ctx.db.query('cmsDocuments').collect()
-    return rows.map(withUnfoldedDocument) // EC-260: unfold before returning
+    return rows.filter((row) => row.variant === DRAFT_VARIANT).map(withUnfoldedDocument) // EC-260
+  },
+})
+
+export const listDocumentPatches = query({
+  args: { collection: v.string(), docId: v.string(), afterRevision: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    await requireCapability(ctx, 'content.read') // EC-150
+    return logAfter(ctx, args.collection, args.docId, args.afterRevision ?? 0)
   },
 })
 
@@ -136,34 +425,25 @@ export const deleteDocument = mutation({
   args: { collection: v.string(), docId: v.string() },
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.write') // EC-150
-    const existing = await ctx.db
-      .query('cmsDocuments')
-      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
-      .first()
+    const existing = await draftRow(ctx, args.collection, args.docId)
     if (existing) await ctx.db.delete(existing._id)
-    // Cascade the version history (EC-224) — no orphaned snapshots survive a delete.
+    // Cascade the version history (EC-224), the patch log and presence (EC-595).
     const versions = await ctx.db
       .query('documentVersions')
       .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
       .collect()
     for (const row of versions) await ctx.db.delete(row._id)
+    await deleteBookkeeping(ctx, args.collection, args.docId)
     // EC-286: the write-chokepoint trigger drops this document's index rows (and
     // revalidates if it was published) when the `cmsDocuments` delete commits.
   },
 })
 
 /**
- * EC-576: drop every document and every version snapshot of the deployment — the
- * explicit drop a seeder runs before writing a known world. One transaction, so a
- * seed never observes a half-cleared store. Administration, not a content write:
- * it requires `project.administer`. Each row delete still passes through the EC-286
- * write-chokepoint trigger, which drops the reference-index rows and schedules the
- * host sweep for the published ones — a seeder re-publishes afterwards anyway.
- *
- * Convex bounds one transaction at 8192 written documents (its documented limit);
- * a store past that size fails loudly here rather than clearing half. That is far
- * above any v1 deployment (the largest measured, Konditorei, holds 331 rows across
- * both tables), so it is documented, not paginated.
+ * EC-576: drop every document, version snapshot, patch-log row and presence heartbeat of
+ * the deployment — the explicit drop a seeder runs before writing a known world. One
+ * transaction (Convex bounds it at 8192 written documents — far above any v1
+ * deployment; documented, not paginated). Requires `project.administer`.
  */
 export const clearDocuments = mutation({
   args: {},
@@ -171,14 +451,49 @@ export const clearDocuments = mutation({
     await requireCapability(ctx, 'project.administer')
     for (const row of await ctx.db.query('cmsDocuments').collect()) await ctx.db.delete(row._id)
     for (const row of await ctx.db.query('documentVersions').collect()) await ctx.db.delete(row._id)
+    for (const row of await ctx.db.query('documentPatches').collect()) await ctx.db.delete(row._id)
+    for (const row of await ctx.db.query('documentPresence').collect()) await ctx.db.delete(row._id)
   },
 })
 
 /**
- * Document version history (EC-224) — the document analogue of `graphs:*`.
- * Append-only snapshots in `documentVersions`; the live one is pinned by
- * `cmsDocuments.publishedVersion`. Version numbers are 1-based, monotonic per
- * document, computed atomically inside the mutation.
+ * Insert the next monotonic version row of a document (folded); returns it. `kind` is the
+ * mutation that records it (EC-585) — decided HERE, never taken from a client argument, so
+ * a `content.write` caller cannot mint a pinnable row through `saveDocumentVersion`.
+ */
+async function insertVersion(
+  ctx: MutationCtx,
+  args: { collection: string; docId: string; snapshot: unknown; label?: string; origin?: string; createdAt: string },
+  kind: DocumentVersionKind,
+) {
+  // EC-302: versions are appended monotonically, so the latest-created row holds the
+  // highest version — read just that one instead of the whole history.
+  const latest = await ctx.db
+    .query('documentVersions')
+    .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
+    .order('desc')
+    .first()
+  const version = (latest?.version ?? 0) + 1
+  const id = await ctx.db.insert('documentVersions', {
+    collection: args.collection,
+    docId: args.docId,
+    version,
+    // EC-260: the snapshot folds at rest like a draft. No trigger on this table.
+    snapshot: foldDocument(args.snapshot as CmsDocument),
+    ...(args.label ? { label: args.label } : {}),
+    ...(args.origin ? { origin: args.origin } : {}),
+    kind,
+    createdAt: args.createdAt,
+  })
+  return (await ctx.db.get(id))!
+}
+
+/**
+ * Document version history (EC-224): append-only snapshots in `documentVersions`; the
+ * live one is pinned by `cmsDocuments.publishedVersion`. Version numbers are 1-based,
+ * monotonic per document. Used by the pre-restore snapshot and `documents.snapshot`;
+ * publish records its version inside `publishDocument` (one step). A row written here is
+ * a `'snapshot'` (EC-585): a restore point `publishDocumentVersion` refuses to pin.
  */
 export const saveDocumentVersion = mutation({
   args: {
@@ -191,23 +506,80 @@ export const saveDocumentVersion = mutation({
   },
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.write') // EC-150
-    // EC-304 B-4: same defensive depth/byte clamp on the version snapshot chokepoint.
-    assertWithinWriteLimits(args.snapshot, 'snapshot')
-    // EC-302: versions are appended monotonically, so the latest-created row holds
-    // the highest version. Read just that one (index-ordered, newest first) instead
-    // of collecting the whole — unbounded — history to compute `max+1`.
-    const latest = await ctx.db
-      .query('documentVersions')
-      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
-      .order('desc')
-      .first()
-    const version = (latest?.version ?? 0) + 1
-    // EC-260: the snapshot embeds the CmsDocument at draft depth, so it folds at rest
-    // identically. `documentVersions` has no trigger — no walker to keep structured.
-    const stored = { ...args, snapshot: foldDocument(args.snapshot as CmsDocument), version }
-    const id = await ctx.db.insert('documentVersions', stored)
-    const row = await ctx.db.get(id)
-    return row ? withUnfoldedSnapshot(row) : row
+    assertWithinWriteLimits(args.snapshot, 'snapshot') // EC-304 B-4
+    const row = await insertVersion(ctx, args, 'snapshot')
+    return withUnfoldedSnapshot(row)
+  },
+})
+
+/**
+ * Publish ONE atomic step (EC-595 binding point 6, Codex P05): if the draft is still at
+ * `expectedRevision`, record it as the next version, pin it, derive the changed flag,
+ * bump the revision and log the publish — all in this transaction; otherwise refuse with
+ * `conflict` and the current row. The `cmsDocuments` trigger sees the pin move and
+ * reindexes + revalidates (EC-286 / EC-146) — the version row it reads exists already.
+ */
+export const publishDocument = mutation({
+  args: {
+    collection: v.string(),
+    docId: v.string(),
+    expectedRevision: v.number(),
+    label: v.optional(v.string()),
+    origin: v.optional(v.string()),
+    at: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const actor = await requireCapability(ctx, 'content.write') // EC-150
+    const existing = await draftRow(ctx, args.collection, args.docId)
+    if (!existing) return { status: 'missing' as const }
+    if (existing.revision !== args.expectedRevision) {
+      return { status: 'conflict' as const, current: withUnfoldedDocument(existing) }
+    }
+    const draft = unfoldDocument(existing.document as CmsDocument)
+    const version = await insertVersion(ctx, {
+      collection: args.collection,
+      docId: args.docId,
+      snapshot: draft,
+      label: args.label ?? 'published',
+      ...(args.origin ? { origin: args.origin } : {}),
+      createdAt: args.at,
+    }, 'publish')
+    const revision = existing.revision + 1
+    // EC-595 retention: compact the log behind the PREVIOUS publish (one cycle kept).
+    const previousPublish = (await logAfter(ctx, args.collection, args.docId, 0))
+      .reverse()
+      .find((row) => row.kind === 'publish')
+    let patchLogFloor = existing.patchLogFloor
+    if (previousPublish) {
+      const compacted = await ctx.db
+        .query('documentPatches')
+        .withIndex('by_doc_revision', (q) =>
+          q
+            .eq('collection', args.collection)
+            .eq('docId', args.docId)
+            .eq('variant', DRAFT_VARIANT)
+            .lte('revision', previousPublish.revision),
+        )
+        .collect()
+      for (const row of compacted) await ctx.db.delete(row._id)
+      patchLogFloor = Math.max(patchLogFloor ?? 0, previousPublish.revision)
+    }
+    const patch = {
+      revision,
+      publishedVersion: version.version,
+      // EC-447: SET-ONCE first-publish instant (server-side, in-transaction).
+      ...(existing.publishedAt === undefined ? { publishedAt: args.at } : {}),
+      ...(await changedFlag(ctx, args.collection, args.docId, version.version, draft, existing.hasUnpublishedChanges)),
+      ...(patchLogFloor !== undefined ? { patchLogFloor } : {}),
+      updatedAt: args.at,
+    }
+    await ctx.db.patch(existing._id, patch)
+    await appendLog(ctx, { collection: args.collection, docId: args.docId, revision, kind: 'publish', actor, at: args.at })
+    return {
+      status: 'ok' as const,
+      row: withUnfoldedDocument({ ...existing, ...patch }),
+      version: withUnfoldedSnapshot(version),
+    }
   },
 })
 
@@ -228,25 +600,14 @@ export const getDocumentVersion = query({
   args: { collection: v.string(), docId: v.string(), version: v.number() },
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.read') // EC-150
-    // EC-307: address the row directly via `by_doc_version` instead of collecting
-    // the whole — unbounded — per-document history and finding in JS. `version` is
-    // unique per (collection, docId), so `.unique()` both fetches and asserts that.
-    const row = await ctx.db
-      .query('documentVersions')
-      .withIndex('by_doc_version', (q) =>
-        q.eq('collection', args.collection).eq('docId', args.docId).eq('version', args.version),
-      )
-      .unique()
+    const row = await versionRow(ctx, args.collection, args.docId, args.version)
     return row ? withUnfoldedSnapshot(row) : row // EC-260: unfold before returning
   },
 })
 
 /**
- * The pinned published snapshot of every currently-published document (EC-307) —
- * one bulk read collapsing the per-document `listVersions` fan-out the studio's
- * published pool used to issue (`published-documents.ts`). Reads each published
- * document's pinned version row directly via `by_doc_version`. Returns the
- * `CmsDocument` snapshots (the live perspective); unpublished documents are absent.
+ * The pinned published snapshot of every currently-published document (EC-307) — one
+ * bulk read. Returns the `CmsDocument` snapshots; unpublished documents are absent.
  */
 export const listPublishedDocuments = query({
   args: { collection: v.optional(v.string()) },
@@ -262,13 +623,8 @@ export const listPublishedDocuments = query({
     const snapshots: unknown[] = []
     for (const doc of docs) {
       const version = doc.publishedVersion
-      if (version === undefined) continue
-      const pinned = await ctx.db
-        .query('documentVersions')
-        .withIndex('by_doc_version', (q) =>
-          q.eq('collection', doc.collection).eq('docId', doc.docId).eq('version', version),
-        )
-        .unique()
+      if (doc.variant !== DRAFT_VARIANT || version === undefined) continue
+      const pinned = await versionRow(ctx, doc.collection, doc.docId, version)
       // EC-260: unfold the pinned snapshot before it leaves the function.
       if (pinned) snapshots.push(unfoldDocument(pinned.snapshot as CmsDocument))
     }
@@ -286,78 +642,82 @@ export const listAllDocumentVersions = query({
   },
 })
 
+/**
+ * Pin an EXISTING version live (EC-224 `pinVersion`, changeset revert). Pin integrity is
+ * enforced here, in the transaction: the version must exist for THIS document
+ * (`missing-version` otherwise) and must have been recorded by `publishDocument`
+ * (`not-pinnable` otherwise — EC-585: a `saveDocumentVersion` row was never validated, so
+ * an editor calling this mutation directly cannot put one live; Codex P03). The changed
+ * flag is DERIVED against the pinned snapshot (a pin of an older version against a newer
+ * draft reads `true` — Codex P05's sibling), the revision bumps, a `pin` row is logged.
+ *
+ * Server-side trust (EC-565 1e, owner-ratified): the checks here are DATA-ONLY — revision,
+ * pin integrity, authority. Schema validation stays the client gate (`documents.publish`
+ * runs it, with the hidden-clear, before `publishDocument` records the row this pins).
+ */
 export const publishDocumentVersion = mutation({
   args: {
     collection: v.string(),
     docId: v.string(),
     version: v.number(),
     updatedAt: v.string(),
-    // EC-447: the candidate first-publish instant (a fresh publish-action timestamp,
-    // generated client-side like `updatedAt`). The handler writes it SET-ONCE below.
+    // EC-447: the candidate first-publish instant, written SET-ONCE below.
     publishedAt: v.string(),
   },
   handler: async (ctx, args) => {
-    await requireCapability(ctx, 'content.write') // EC-150
-    const doc = await ctx.db
-      .query('cmsDocuments')
-      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
-      .first()
-    if (!doc) return null
-    // EC-286: setting the live pin (`publishedVersion`) is a change the
-    // write-chokepoint trigger sees — it reindexes the published reference rows
-    // and fires host revalidation (EC-146 instant publish). No manual calls here.
-    // EC-447: materialize `publishedAt` SET-ONCE — only when the row has none yet, so
-    // the FIRST-publish instant is captured and PRESERVED across republishes (the
-    // guard is server-side + in-transaction, so it can't race).
-    // EC-449: the pinned version IS the published baseline now — publish always
-    // resolves `hasUnpublishedChanges` to `false`.
-    await ctx.db.patch(doc._id, {
+    const actor = await requireCapability(ctx, 'content.write') // EC-150
+    const doc = await draftRow(ctx, args.collection, args.docId)
+    if (!doc) return { status: 'missing' as const }
+    const target = await versionRow(ctx, args.collection, args.docId, args.version)
+    if (!target) return { status: 'missing-version' as const }
+    if (!isPinnableVersion(target)) return { status: 'not-pinnable' as const }
+    const revision = doc.revision + 1
+    const patch = {
+      revision,
       publishedVersion: args.version,
       updatedAt: args.updatedAt,
       ...(doc.publishedAt === undefined ? { publishedAt: args.publishedAt } : {}),
-      hasUnpublishedChanges: false,
-    })
-    const row = await ctx.db.get(doc._id)
-    return row ? withUnfoldedDocument(row) : row // EC-260: unfold before returning
+      ...(await changedFlag(
+        ctx,
+        args.collection,
+        args.docId,
+        args.version,
+        unfoldDocument(doc.document as CmsDocument),
+        doc.hasUnpublishedChanges,
+      )),
+    }
+    await ctx.db.patch(doc._id, patch)
+    await appendLog(ctx, { collection: args.collection, docId: args.docId, revision, kind: 'pin', actor, at: args.updatedAt })
+    return { status: 'ok' as const, row: withUnfoldedDocument({ ...doc, ...patch }) }
   },
 })
 
 export const unpublishDocument = mutation({
   args: { collection: v.string(), docId: v.string(), updatedAt: v.string() },
   handler: async (ctx, args) => {
-    await requireCapability(ctx, 'content.write') // EC-150
-    const doc = await ctx.db
-      .query('cmsDocuments')
-      .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
-      .first()
+    const actor = await requireCapability(ctx, 'content.write') // EC-150
+    const doc = await draftRow(ctx, args.collection, args.docId)
     if (!doc) return null
-    // Convex patch removes a field set to `undefined` — clears the live pin.
-    // EC-286: clearing the pin is a change the write-chokepoint trigger sees — it
-    // drops the published index rows and revalidates the host. No manual calls.
-    // EC-447: unpublish CLEARS `publishedAt` too (a later republish records a fresh
-    // first-publish stamp); `createdAt` is untouched.
-    // EC-449: `hasUnpublishedChanges` is cleared too — with no published baseline
-    // there is nothing to differ from (the dot reads `draft`/muted anyway).
+    const revision = doc.revision + 1
+    // Convex patch removes a field set to `undefined` — clears the live pin. EC-286: the
+    // trigger drops the published index rows and revalidates. EC-447/EC-449: the
+    // first-publish instant and the changed flag clear with it.
     await ctx.db.patch(doc._id, {
+      revision,
       publishedVersion: undefined,
       publishedAt: undefined,
       hasUnpublishedChanges: undefined,
       updatedAt: args.updatedAt,
     })
+    await appendLog(ctx, { collection: args.collection, docId: args.docId, revision, kind: 'unpublish', actor, at: args.updatedAt })
     const row = await ctx.db.get(doc._id)
     return row ? withUnfoldedDocument(row) : row // EC-260: unfold before returning
   },
 })
 
 /**
- * One-time data migrations (EC-450 principle): a migration mutation ships
- * transiently — added when a schema/behavior change needs to backfill existing
- * deployments, then REMOVED once every deployment has confirmed running it. It
- * never lingers in the permanent `@elytracms/*` shipped surface (a brand-new
- * consumer never needs it — nothing pre-dates the change it backfills). Pattern:
- * an `internalMutation` here delegating its per-row decision to a pure, unit-tested
- * core in `@elytracms/core/persistence`; the operator runs it once per deployment
- * via `npx convex run cms:<name>` after `convex deploy`, confirms all deployments,
- * then deletes both the mutation and its core in one removal pass (see EC-447/449
- * → EC-450 for the worked example).
+ * One-time data migrations (EC-450 principle): a migration mutation ships transiently —
+ * added when a schema/behavior change needs to backfill existing deployments, then
+ * REMOVED once every deployment has confirmed running it. EC-595 needs none: its schema
+ * change is a drop-and-reseed (the owner's ruling for pre-v1 data, EC-576).
  */