@elytracms/studio 0.0.95 → 0.0.97

package/convex/cms.ts

@@ -1,7 +1,9 @@
 import { v } from 'convex/values'
 import {
+  DOCUMENT_KEY_SEPARATOR,
   DRAFT_VARIANT,
   applyDocumentPatches,
+  documentKey,
   documentsSemanticEqual,
   foldDocument,
   foldPatchesForStorage,
@@ -26,10 +28,13 @@ import { assertWithinWriteLimits } from './write-limits'
  *
  * 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`).
+ * be the lens and the mask to put on the data." So these handlers enforce only data-only
+ * facts: **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), **authority** (`requireCapability`) and — EC-649 — the
+ * **strict-reference facts the operation's guard judged** (a publish's strict targets are
+ * still published; an unpublish / delete target has no published referrer the guard did not
+ * judge): the operation decides what is strict, these handlers only re-check that data.
  * 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).
@@ -136,6 +141,32 @@ async function logAfter(ctx: Ctx, collection: string, docId: string, afterRevisi
   }))
 }
 
+/** EC-669 — the floor a removed identity left (`null`: none of its lifetimes was ever removed). */
+function floorRow(ctx: Ctx, collection: string, docId: string) {
+  return ctx.db
+    .query('documentFloors')
+    .withIndex('by_doc', (q) => q.eq('collection', collection).eq('docId', docId))
+    .unique()
+}
+
+/**
+ * EC-669 — INVARIANT: a revision or version number names one state of ONE lifetime. Both
+ * removal mutations raise the identity's floor to what the removed lifetime reached, in the same
+ * transaction as the removal, so a later create of the same `collection:docId` starts above
+ * every token it minted. `existing` lets `clearDocuments` pass the row it already read.
+ */
+async function raiseFloor(
+  ctx: MutationCtx,
+  identity: { collection: string; docId: string; revision: number; version: number },
+  existing?: Awaited<ReturnType<typeof floorRow>>,
+): Promise<void> {
+  const floor = existing === undefined ? await floorRow(ctx, identity.collection, identity.docId) : existing
+  const revision = Math.max(floor?.revision ?? 0, identity.revision)
+  const version = Math.max(floor?.version ?? 0, identity.version)
+  if (!floor) await ctx.db.insert('documentFloors', { ...identity, revision, version })
+  else if (revision !== floor.revision || version !== floor.version) await ctx.db.patch(floor._id, { revision, version })
+}
+
 /** 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
@@ -156,6 +187,110 @@ const preconditionValidator = v.union(
   v.object({ ifCollectionEmpty: v.literal(true) }),
 )
 
+// --- EC-649: strict-reference integrity as data preconditions (Codex F08) -------------
+//
+// The operation judges strictness (it holds the schema); these handlers hold none (EC-565
+// 1e). They re-check, inside their own transaction, only the DATA the operation's guard
+// judged: a publish / pin's strict targets are still published; an unpublish / delete's
+// target has no published referrer the guard did not judge at its current pin. Convex OCC
+// makes the check and the write one serializable step: a concurrent publish of a referrer
+// writes the very `referenceEntries` range (by_target) and `cmsDocuments` rows read here.
+
+const documentRefValidator = v.object({ collection: v.string(), id: v.string() })
+const publishedReferrerValidator = v.object({
+  collection: v.string(),
+  id: v.string(),
+  publishedVersion: v.number(),
+})
+/** EC-668 — one draft referrer the delete's guard judged, at the revision it read. */
+const draftReferrerValidator = v.object({
+  collection: v.string(),
+  id: v.string(),
+  revision: v.number(),
+})
+
+interface WireRef {
+  collection: string
+  id: string
+}
+
+/** The strict targets that are gone or carry no pin (a publish / pin refuses on any). */
+async function unpublishedStrictTargets(ctx: MutationCtx, targets: readonly WireRef[] | undefined): Promise<WireRef[]> {
+  const unpublished: WireRef[] = []
+  for (const target of targets ?? []) {
+    const row = await draftRow(ctx, target.collection, target.id)
+    if (row?.publishedVersion === undefined) unpublished.push({ collection: target.collection, id: target.id })
+  }
+  return unpublished
+}
+
+/**
+ * The published referrers of `collection:docId` the guard did not judge at their current pin —
+ * read from the reference index's PUBLISHED variant (`by_target`, written from the pinned
+ * snapshot in the same transaction as every pin move — EC-286 / EC-589), so a referrer published
+ * after the guard read is seen here. `undefined` judged = not checked (a caller without the
+ * precondition).
+ */
+async function unjudgedPublishedReferrers(
+  ctx: MutationCtx,
+  collection: string,
+  docId: string,
+  judged: readonly (WireRef & { publishedVersion: number })[] | undefined,
+): Promise<WireRef[]> {
+  if (!judged) return []
+  const targetKey = documentKey({ collection, id: docId })
+  const pins = new Map(judged.map((referrer) => [documentKey(referrer), referrer.publishedVersion]))
+  const entries = await ctx.db
+    .query('referenceEntries')
+    .withIndex('by_target', (q) => q.eq('targetType', 'document').eq('targetId', targetKey).eq('variant', 'published'))
+    .collect()
+  const unjudged: WireRef[] = []
+  for (const sourceId of new Set(entries.map((entry) => entry.sourceId))) {
+    if (sourceId === targetKey) continue
+    // A collection id never contains the separator (EC-578 F10), so the first one splits.
+    const at = sourceId.indexOf(DOCUMENT_KEY_SEPARATOR)
+    const source = { collection: sourceId.slice(0, at), id: sourceId.slice(at + 1) }
+    const row = await draftRow(ctx, source.collection, source.id)
+    if (row?.publishedVersion === undefined) continue
+    if (pins.get(sourceId) !== row.publishedVersion) unjudged.push(source)
+  }
+  return unjudged
+}
+
+/**
+ * EC-668 (Codex F08 residual) — the documents whose working DRAFT references `collection:docId`
+ * that the delete's guard did not judge at their current revision — read from the reference
+ * index's DRAFT variant (`by_target`, written from the draft by the trigger in the same
+ * transaction as every `cmsDocuments` write), so a referrer saved after the guard read is seen
+ * here, and Convex OCC conflicts this read with that write. Schema-free (the index is), so the
+ * judged set includes soft referrers. `undefined` judged = not checked.
+ */
+async function unjudgedDraftReferrers(
+  ctx: MutationCtx,
+  collection: string,
+  docId: string,
+  judged: readonly (WireRef & { revision: number })[] | undefined,
+): Promise<WireRef[]> {
+  if (!judged) return []
+  const targetKey = documentKey({ collection, id: docId })
+  const revisions = new Map(judged.map((referrer) => [documentKey(referrer), referrer.revision]))
+  const entries = await ctx.db
+    .query('referenceEntries')
+    .withIndex('by_target', (q) => q.eq('targetType', 'document').eq('targetId', targetKey).eq('variant', 'draft'))
+    .collect()
+  const unjudged: WireRef[] = []
+  for (const sourceId of new Set(entries.map((entry) => entry.sourceId))) {
+    if (sourceId === targetKey) continue
+    // A collection id never contains the separator (EC-578 F10), so the first one splits.
+    const at = sourceId.indexOf(DOCUMENT_KEY_SEPARATOR)
+    const source = { collection: sourceId.slice(0, at), id: sourceId.slice(at + 1) }
+    const row = await draftRow(ctx, source.collection, source.id)
+    if (!row) continue
+    if (revisions.get(sourceId) !== row.revision) unjudged.push(source)
+  }
+  return unjudged
+}
+
 /**
  * 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 —
@@ -191,7 +326,8 @@ export const replaceDocument = mutation({
       }
     }
     const draft = args.document as CmsDocument
-    const revision = (existing?.revision ?? 0) + 1
+    // EC-669: a create starts above every revision a removed lifetime of this identity reached.
+    const revision = (existing?.revision ?? (await floorRow(ctx, args.collection, args.docId))?.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)
@@ -421,21 +557,61 @@ export const listDocumentPatches = query({
   },
 })
 
+/**
+ * Delete a document with its version history, patch log and presence. EC-648: an optional
+ * `precondition: { revision }` — the delete happens only while the draft is at exactly that
+ * revision, checked in this transaction (a changeset reverting its own create carries the
+ * revision the create recorded, so a colleague's later edit refuses it). Data-only (1e).
+ * Returns `{ status: 'conflict', current }` when the precondition does not hold. EC-649: the
+ * precondition's `publishedReferrers` (the ones the operation's strict guard judged) — a
+ * published referrer not among them refuses the delete with `{ status: 'unjudged-referrers' }`;
+ * EC-668: so does a draft referrer not among `draftReferrers` at its current revision.
+ */
 export const deleteDocument = mutation({
-  args: { collection: v.string(), docId: v.string() },
+  args: {
+    collection: v.string(),
+    docId: v.string(),
+    precondition: v.optional(
+      v.object({
+        revision: v.optional(v.number()),
+        publishedReferrers: v.optional(v.array(publishedReferrerValidator)),
+        // EC-668: and the draft referrers it judged.
+        draftReferrers: v.optional(v.array(draftReferrerValidator)),
+      }),
+    ),
+  },
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.write') // EC-150
     const existing = await draftRow(ctx, args.collection, args.docId)
-    if (existing) await ctx.db.delete(existing._id)
+    const revision = args.precondition?.revision
+    if (revision !== undefined && existing?.revision !== revision) {
+      return { status: 'conflict' as const, current: existing ? withUnfoldedDocument(existing) : null }
+    }
+    // EC-668 — INVARIANT: the delete's read set covers every referrer its guard judged — the
+    // published pins (EC-649) AND the drafts — in this transaction, before any write.
+    const unjudged = [
+      ...(await unjudgedPublishedReferrers(ctx, args.collection, args.docId, args.precondition?.publishedReferrers)),
+      ...(await unjudgedDraftReferrers(ctx, args.collection, args.docId, args.precondition?.draftReferrers)),
+    ]
+    if (unjudged.length > 0) return { status: 'unjudged-referrers' as const, refs: unjudged }
     // 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()
+    // EC-669: the identity keeps the revision and version this lifetime reached.
+    await raiseFloor(ctx, {
+      collection: args.collection,
+      docId: args.docId,
+      revision: existing?.revision ?? 0,
+      version: Math.max(0, ...versions.map((row) => row.version)),
+    })
+    if (existing) await ctx.db.delete(existing._id)
     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.
+    return { status: 'ok' as const }
   },
 })
 
@@ -443,14 +619,31 @@ export const deleteDocument = mutation({
  * 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`.
+ * deployment; documented, not paginated). Requires `project.administer`. EC-669: every
+ * identity it removes keeps its floor (`documentFloors`, one row per identity — which this
+ * drop never clears), so a re-seeded document starts above every token its removed lifetime
+ * minted; the floor writes count toward the same bound.
  */
 export const clearDocuments = mutation({
   args: {},
   handler: async (ctx) => {
     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)
+    const documents = await ctx.db.query('cmsDocuments').collect()
+    const versions = await ctx.db.query('documentVersions').collect()
+    // EC-669: the highest revision and version each removed identity reached, raised in place.
+    const reached = new Map<string, { collection: string; docId: string; revision: number; version: number }>()
+    const reach = (row: { collection: string; docId: string }, field: 'revision' | 'version', value: number) => {
+      const key = documentKey({ collection: row.collection, id: row.docId })
+      const entry = reached.get(key) ?? { collection: row.collection, docId: row.docId, revision: 0, version: 0 }
+      entry[field] = Math.max(entry[field], value)
+      reached.set(key, entry)
+    }
+    for (const row of documents) reach(row, 'revision', row.revision)
+    for (const row of versions) reach(row, 'version', row.version)
+    const floors = new Map((await ctx.db.query('documentFloors').collect()).map((row) => [documentKey({ collection: row.collection, id: row.docId }), row]))
+    for (const [key, entry] of reached) await raiseFloor(ctx, entry, floors.get(key) ?? null)
+    for (const row of documents) await ctx.db.delete(row._id)
+    for (const row of versions) 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)
   },
@@ -473,7 +666,8 @@ async function insertVersion(
     .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
     .order('desc')
     .first()
-  const version = (latest?.version ?? 0) + 1
+  // EC-669: a lifetime's first version starts above every version a removed one recorded.
+  const version = (latest?.version ?? (await floorRow(ctx, args.collection, args.docId))?.version ?? 0) + 1
   const id = await ctx.db.insert('documentVersions', {
     collection: args.collection,
     docId: args.docId,
@@ -518,6 +712,11 @@ export const saveDocumentVersion = mutation({
  * 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.
+ * EC-649: `strictTargets` (the ones the operation's guard judged published) must still be
+ * published, else `{ status: 'strict-targets', refs }` and nothing is written. EC-663: `patches`
+ * — the hidden-clear the operation computed — apply to the draft IN this transaction (a `patch`
+ * log row at +1, the publish at +2), so a refused publish clears nothing; a patch that does not
+ * apply refuses with `conflict`. The values are data: the store applies them, never judges them.
  */
 export const publishDocument = mutation({
   args: {
@@ -527,15 +726,30 @@ export const publishDocument = mutation({
     label: v.optional(v.string()),
     origin: v.optional(v.string()),
     at: v.string(),
+    strictTargets: v.optional(v.array(documentRefValidator)),
+    // EC-663 (Codex F17): the hidden-clear the operation computed, applied in THIS transaction.
+    patches: v.optional(v.any()),
   },
   handler: async (ctx, args) => {
     const actor = await requireCapability(ctx, 'content.write') // EC-150
+    if (args.patches !== undefined) assertWithinWriteLimits(args.patches, 'patches') // EC-304 B-4
     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 unpublished = await unpublishedStrictTargets(ctx, args.strictTargets)
+    if (unpublished.length > 0) return { status: 'strict-targets' as const, refs: unpublished }
+    // EC-663 (F17) — INVARIANT: a refused publish has no effect. The clear applies to the draft
+    // at the revision just checked (nothing since, so only an invalid patch can refuse — and then
+    // nothing is written); the version records the cleared draft, in one transaction.
+    const patches = (args.patches ?? []) as DocumentPatch[]
+    const clear =
+      patches.length > 0
+        ? applyDocumentPatches({ document: unfoldDocument(existing.document as CmsDocument), patches, since: [] })
+        : undefined
+    if (clear && clear.refused.length > 0) return { status: 'conflict' as const, current: withUnfoldedDocument(existing) }
+    const draft = clear ? clear.document : unfoldDocument(existing.document as CmsDocument)
     const version = await insertVersion(ctx, {
       collection: args.collection,
       docId: args.docId,
@@ -544,7 +758,8 @@ export const publishDocument = mutation({
       ...(args.origin ? { origin: args.origin } : {}),
       createdAt: args.at,
     }, 'publish')
-    const revision = existing.revision + 1
+    // The clear is its own log row (+1, so per-path conflict detection sees it); the publish +2.
+    const revision = existing.revision + (clear ? 2 : 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()
@@ -565,6 +780,8 @@ export const publishDocument = mutation({
       patchLogFloor = Math.max(patchLogFloor ?? 0, previousPublish.revision)
     }
     const patch = {
+      // EC-260: the cleared draft is structured (unfolded above), folded strictly before `ctx.db`.
+      ...(clear ? { document: foldDocument(clear.document) } : {}),
       revision,
       publishedVersion: version.version,
       // EC-447: SET-ONCE first-publish instant (server-side, in-transaction).
@@ -574,6 +791,13 @@ export const publishDocument = mutation({
       updatedAt: args.at,
     }
     await ctx.db.patch(existing._id, patch)
+    if (clear) {
+      await appendLog(
+        ctx,
+        { collection: args.collection, docId: args.docId, revision: existing.revision + 1, kind: 'patch', actor, at: args.at },
+        clear.applied,
+      )
+    }
     await appendLog(ctx, { collection: args.collection, docId: args.docId, revision, kind: 'publish', actor, at: args.at })
     return {
       status: 'ok' as const,
@@ -652,8 +876,11 @@ export const listAllDocumentVersions = query({
  * 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).
+ * pin integrity, authority, and (EC-649) the strict targets the operation judged are still
+ * published (`{ status: 'strict-targets', refs }` otherwise) and (EC-663) the caller's
+ * `expectedRevision` (`{ status: 'conflict', current }` otherwise). 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: {
@@ -663,14 +890,24 @@ export const publishDocumentVersion = mutation({
     updatedAt: v.string(),
     // EC-447: the candidate first-publish instant, written SET-ONCE below.
     publishedAt: v.string(),
+    strictTargets: v.optional(v.array(documentRefValidator)),
+    // EC-663 (Codex F16): pin only at exactly this revision (a changeset's re-pin inverse).
+    expectedRevision: v.optional(v.number()),
   },
   handler: async (ctx, args) => {
     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 }
+    // EC-663 — INVARIANT: a token is checked inside the write that spends it — a pin at a
+    // revision the document moved past (a colleague's publish since) refuses, nothing written.
+    if (args.expectedRevision !== undefined && doc.revision !== args.expectedRevision) {
+      return { status: 'conflict' as const, current: withUnfoldedDocument(doc) }
+    }
     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 unpublished = await unpublishedStrictTargets(ctx, args.strictTargets)
+    if (unpublished.length > 0) return { status: 'strict-targets' as const, refs: unpublished }
     const revision = doc.revision + 1
     const patch = {
       revision,
@@ -692,12 +929,31 @@ export const publishDocumentVersion = mutation({
   },
 })
 
+/**
+ * Clear the live pin (EC-224). EC-649: `publishedReferrers` — the published referrers the
+ * operation's strict guard judged; a published referrer of this document not among them (at
+ * its current pin) refuses the unpublish with `{ status: 'unjudged-referrers', refs }`. EC-663:
+ * `expectedRevision` — refused with `{ status: 'conflict', current }` unless at exactly it.
+ */
 export const unpublishDocument = mutation({
-  args: { collection: v.string(), docId: v.string(), updatedAt: v.string() },
+  args: {
+    collection: v.string(),
+    docId: v.string(),
+    updatedAt: v.string(),
+    publishedReferrers: v.optional(v.array(publishedReferrerValidator)),
+    // EC-663 (Codex F16): unpublish only at exactly this revision (a changeset's inverse).
+    expectedRevision: v.optional(v.number()),
+  },
   handler: async (ctx, args) => {
     const actor = await requireCapability(ctx, 'content.write') // EC-150
     const doc = await draftRow(ctx, args.collection, args.docId)
     if (!doc) return null
+    // EC-663 — INVARIANT: checked in this transaction, before the write, as the pin's.
+    if (args.expectedRevision !== undefined && doc.revision !== args.expectedRevision) {
+      return { status: 'conflict' as const, current: withUnfoldedDocument(doc) }
+    }
+    const unjudged = await unjudgedPublishedReferrers(ctx, args.collection, args.docId, args.publishedReferrers)
+    if (unjudged.length > 0) return { status: 'unjudged-referrers' as const, refs: unjudged }
     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

package/convex/delivery-folded-drift.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import { makeFunctionReference } from 'convex/server'
+import { foldEnvelope } from '@elytracms/core/cms-core'
+import type { CollectionDef } from '@elytracms/core/cms-core'
+// The host's reader, from its own module — the package index also loads the React delivery
+// kit, which the edge-runtime environment cannot evaluate.
+import { assembleLiveSource } from '../../next/src/host-content'
+import schema from './schema'
+
+/**
+ * EC-670 (Codex F19, `tasks/codex-review-2026-10-27-r3/backend.convex.test.ts` "F19") — a
+ * folded value whose stored payload does not parse, through the REAL `delivery:snapshot`
+ * (convex-test) and the REAL host loader (`assembleLiveSource`).
+ *
+ * Before: the codec handed the undecodable envelope back to its own walk, which recursed
+ * until the stack overflowed — the public snapshot REJECTED for every visitor (measured on
+ * the base: `Maximum call stack size exceeded`). Now the row is withheld with one located
+ * issue on the snapshot's `documentIssues` strand, which the host carries into its
+ * `sourceIssues` and onto the document's own read; every other row serves.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+const snapshot = makeFunctionReference<'query'>('delivery:snapshot')
+const draftSnapshot = makeFunctionReference<'query'>('delivery:draftSnapshot')
+
+const AT = '2026-10-27T12:00:00.000Z'
+const UNDECODABLE = { type: 'elytra/folded', v: 1, json: '{' }
+const POST: CollectionDef = {
+  id: 'post',
+  kind: 'document',
+  fields: [
+    { name: 'title', type: 'text' },
+    { name: 'body', type: 'object', multiple: false, fields: [{ name: 'text', type: 'text' }] },
+  ],
+}
+const OPTIONS = { locales: { default: 'en', locales: ['en'] }, collections: [POST], routes: [] }
+
+function env(): Record<string, string | undefined> {
+  return (globalThis as { process: { env: Record<string, string | undefined> } }).process.env
+}
+afterEach(() => {
+  delete env()['DRAFT_PREVIEW_TOKEN']
+})
+
+/** Two published documents — `good` clean (its body folded, legitimately), `bad` holding the drift. */
+async function deployment() {
+  const t = convexTest(schema, modules)
+  await t.run(async (ctx) => {
+    const publish = async (docId: string, values: Record<string, unknown>) => {
+      await ctx.db.insert('cmsDocuments', { collection: 'post', docId, variant: 'draft', revision: 1, document: { collection: 'post', id: docId, values }, publishedVersion: 1, createdAt: AT, updatedAt: AT })
+      await ctx.db.insert('documentVersions', { collection: 'post', docId, version: 1, snapshot: { collection: 'post', id: docId, values }, kind: 'publish', createdAt: AT })
+    }
+    await publish('good', { title: 'GOOD', body: foldEnvelope({ text: 'deep enough to fold' }) })
+    await publish('bad', { title: 'BAD', body: UNDECODABLE })
+  })
+  return t
+}
+
+describe('EC-670 — one undecodable folded value in a pinned snapshot', () => {
+  it('withholds THAT row with a located issue and serves every other row (was: the whole snapshot rejected)', async () => {
+    const t = await deployment()
+    // Positive observation control: the drifted row really is stored and pinned.
+    const stored = await t.run((ctx) => ctx.db.query('documentVersions').collect())
+    expect(stored.map((row) => row.docId).sort()).toEqual(['bad', 'good'])
+
+    const payload = await t.query(snapshot, { projectId: 'site' })
+    // Control: the clean row serves, its legitimately folded body unfolded.
+    expect(payload.documents).toEqual([
+      { collection: 'post', id: 'good', values: { title: 'GOOD', body: { text: 'deep enough to fold' } } },
+    ])
+    // F19, inverted: was `rejects.toThrow(/call stack/)`.
+    expect(payload.documentIssues).toEqual([
+      expect.objectContaining({
+        code: 'invalid-stored-document',
+        path: ['documents', 'post:bad', 'values', 'body'],
+        collectionId: 'post',
+        documentId: 'bad',
+      }),
+    ])
+    // Public strand: identity and path, never a value of the withheld row.
+    expect(JSON.stringify(payload.documentIssues)).not.toContain('BAD')
+
+    // The host carries the strand into its source and onto the document's own read.
+    const client = assembleLiveSource(payload, OPTIONS, 'published').client({ perspective: 'published' })
+    expect(client.sourceIssues.map((issue) => [issue.code, issue.documentId])).toEqual([
+      ['invalid-stored-document', 'bad'],
+    ])
+    expect(client.getDocument('post', 'bad').document).toBeNull()
+    expect(client.getDocument('post', 'bad').issues.map((issue) => issue.code)).toEqual(['invalid-stored-document'])
+    expect(client.getDocument('post', 'good').document).not.toBeNull()
+  })
+
+  it('the draft snapshot withholds a draft row the same way', async () => {
+    const t = await deployment()
+    env()['DRAFT_PREVIEW_TOKEN'] = 'preview-token-670'
+    const payload = await t.query(draftSnapshot, { projectId: 'site', token: 'preview-token-670' })
+    expect(payload.documents.map((doc: { id: string }) => doc.id)).toEqual(['good'])
+    expect(payload.documentIssues.map((issue: { documentId: string }) => issue.documentId)).toEqual(['bad'])
+  })
+})

package/convex/delivery.ts

@@ -1,6 +1,6 @@
 import { v } from 'convex/values'
-import { DRAFT_PERSPECTIVE, DRAFT_VARIANT, readLiveRedirects, unfoldValue, variantOf } from '@elytracms/core/cms-core'
-import type { Perspective } from '@elytracms/core/cms-core'
+import { DRAFT_PERSPECTIVE, DRAFT_VARIANT, readLiveRedirects, unfoldForDelivery, variantOf } from '@elytracms/core/cms-core'
+import type { CmsValidationIssue, Perspective } from '@elytracms/core/cms-core'
 import { assetRecordFromRow, deliveryAssetRecord } from '@elytracms/core/persistence'
 import { constantTimeEquals } from '@elytracms/core/revalidation'
 import type { AssetRecord } from '@elytracms/core/persistence'
@@ -67,6 +67,12 @@ interface DeliverySnapshot {
    * a variant — that variant's rows only.
    */
   documents: unknown[]
+  /**
+   * EC-670 — one `invalid-stored-document` issue per stored row the snapshot withheld because
+   * it holds a folded value whose payload does not parse (identity + field paths — never a
+   * value). Every other row still serves; the host carries these into its source issues.
+   */
+  documentIssues: unknown[]
   /** Asset metadata in the delivery `AssetRecord` shape (with serve URLs). */
   assets: unknown[]
   /**
@@ -123,8 +129,19 @@ export async function loadSnapshot(
   const documentRows = await ctx.db.query('cmsDocuments').collect()
   // EC-260: the stored `document`/`snapshot` blobs are folded; unfold every one
   // before it enters the delivery snapshot so the host receives STRUCTURED content
-  // (no client ever sees an envelope). `unfoldValue` is identity on legacy data.
-  const unfoldDraft = (row: { document: unknown }): unknown => unfoldValue(row.document)
+  // (no client ever sees an envelope). Unfolding is identity on legacy data.
+  //
+  // EC-670 (Codex F19): a blob holding a folded value whose payload does not parse is
+  // WITHHELD with a located issue on `documentIssues` — never served opaque as content,
+  // and never the whole snapshot (one such value used to overflow the stack and reject
+  // the query for every visitor of the site).
+  const documents: unknown[] = []
+  const documentIssues: CmsValidationIssue[] = []
+  const deliver = (stored: unknown, row: { collection: string; docId: string }): void => {
+    const read = unfoldForDelivery(stored, { collection: row.collection, id: row.docId })
+    if (read.ok) documents.push(read.document)
+    else documentIssues.push(read.issue)
+  }
   // THE published-content invariant (the trust boundary): the public snapshot
   // ships ONLY published content — never a draft. Under the EC-224 pointer model
   // a published row is served as its *pinned version snapshot* (decoupled from
@@ -138,11 +155,9 @@ export async function loadSnapshot(
   // 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 (variant !== undefined) {
-    documents = documentRows.filter((row) => row.variant === variant).map(unfoldDraft)
+    for (const row of documentRows) if (row.variant === variant) deliver(row.document, row)
   } else {
-    documents = []
     for (const row of documentRows) {
       if (row.variant !== DRAFT_VARIANT || row.publishedVersion === undefined) continue
       // EC-308: read THIS document's pinned version directly via `by_doc_version`
@@ -158,7 +173,7 @@ export async function loadSnapshot(
           q.eq('collection', row.collection).eq('docId', row.docId).eq('version', version),
         )
         .unique()
-      if (pinned) documents.push(unfoldValue(pinned.snapshot))
+      if (pinned) deliver(pinned.snapshot, row)
     }
   }
 
@@ -178,6 +193,7 @@ export async function loadSnapshot(
     projectId,
     perspective,
     documents,
+    documentIssues,
     assets,
     redirects: live.redirects,
     redirectIssues: live.issues,