@elytracms/studio 0.0.94 → 0.0.96

package/convex/asset-alt-migration.test.ts

@@ -80,7 +80,7 @@ describe('EC-587 — assets:liftLegacyAlt moves the legacy column home, once', (
   it('lifts the column into meta.alt (meta.alt wins when both), unsets it, and keeps every alt reading', async () => {
     const t = await seededBackend()
     const before = await storedRows(t)
-    expect(Object.fromEntries(Object.entries(before).map(([id, r]) => [id, assetAlt(r)]))).toEqual(READ_BEFORE)
+    expect(Object.fromEntries(Object.entries(before).map(([id, r]) => [id, assetAlt(r, null)]))).toEqual(READ_BEFORE)
 
     const report = (await t.mutation(liftLegacyAlt, {})) as { scanned: number; lifted: string[] }
     expect(report.scanned).toBe(4)
@@ -94,7 +94,7 @@ describe('EC-587 — assets:liftLegacyAlt moves the legacy column home, once', (
       expect(measureMaxDepth(stored.meta).depth).toBeLessThanOrEqual(16)
     }
     // The lift changes no reading: every alt is what it was.
-    expect(Object.fromEntries(Object.entries(after).map(([id, r]) => [id, assetAlt(r)]))).toEqual(READ_BEFORE)
+    expect(Object.fromEntries(Object.entries(after).map(([id, r]) => [id, assetAlt(r, null)]))).toEqual(READ_BEFORE)
   })
 
   it('is idempotent: a second run lifts nothing and writes nothing', async () => {

package/convex/asset-meta-patch.test.ts

@@ -0,0 +1,218 @@
+import { readFileSync } from 'node:fs'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import type { FunctionReference } from 'convex/server'
+import { defaultAssetCollection, measureMaxDepth } from '@elytracms/core/cms-core'
+import { InMemoryBlobStorage, InMemoryPersistenceAdapter, PersistenceValidationError, assetAlt } from '@elytracms/core/persistence'
+import type { AssetRepository } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import { runUpload } from '../src/lib/assets/upload'
+import {
+  assetMetaDraft,
+  assetMetaDraftPatch,
+  setAssetMetaField,
+  updateAssetMetadata,
+} from '../src/components/assets/asset-metadata'
+import schema from './schema'
+
+// convex-test fires a `runAfter(0)` on a REAL timer; fake timers keep the scheduled
+// revalidation queued (its row written, the `webhooks:deliver` fetch never fired).
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/**
+ * EC-634 — an asset's `meta` is written per key, inside the mutation, on BOTH adapters:
+ * two sessions (two adapters over ONE backend — two studio tabs on one deployment) whose
+ * dialog saves interleave keep both keys; a dialog save landing while a file replace is in
+ * flight survives the replace; a not-yet-migrated legacy `alt` column is lifted into the
+ * stored bag by the same transaction. convex-test serialises mutations, so this proves the
+ * per-key MERGE in `assets:upsert`, not Convex's OCC retry (which re-runs the same handler
+ * against the newer row — the merge is what makes that retry correct).
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const PROJECT_ID = 'asset-meta-patch'
+const SESSION_USER_ID = 'user_admin'
+const STAMP = '2026-10-27T00:00:00.000Z'
+
+async function convexBackend() {
+  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 })
+  })
+  const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+  const session = () =>
+    new ConvexPersistenceAdapter(
+      {
+        query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => asAdmin.query(ref, args ?? {}),
+        mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) =>
+          asAdmin.mutation(ref, args ?? {}),
+      } as unknown as ConvexHttpClient,
+      PROJECT_ID,
+    ).assets
+  return { t, a: session(), b: session() }
+}
+
+function memoryBackend() {
+  const adapter = new InMemoryPersistenceAdapter()
+  return { a: adapter.assets, b: adapter.assets }
+}
+
+async function seed(assets: AssetRepository, meta: Record<string, unknown>) {
+  await assets.upsertAsset(PROJECT_ID, {
+    id: 'hero',
+    filename: 'hero.jpg',
+    contentType: 'image/jpeg',
+    byteSize: 1,
+    storageKey: 'blob_old',
+    url: 'https://assets.test/old.jpg',
+    meta,
+  })
+}
+
+async function openDialog(assets: AssetRepository) {
+  const opened = assetMetaDraft(await assets.getAsset(PROJECT_ID, 'hero'))
+  let draft = opened
+  return {
+    edit: (key: string, value: unknown) => {
+      draft = setAssetMetaField(draft, { name: key }, null, value)
+    },
+    commit: () => updateAssetMetadata({ assets }, PROJECT_ID, 'hero', assetMetaDraftPatch(opened, draft)),
+  }
+}
+
+/** Two dialogs open on one asset, each edits one key, the commits interleave. */
+async function interleavedDialogs({ a, b }: { a: AssetRepository; b: AssetRepository }) {
+  await seed(a, { alt: 'old alt', credit: 'old credit' })
+  const dialogA = await openDialog(a)
+  const dialogB = await openDialog(b)
+  dialogA.edit('alt', 'A alt')
+  dialogB.edit('credit', 'B credit')
+  expect((await dialogA.commit()).ok).toBe(true)
+  expect((await dialogB.commit()).ok).toBe(true)
+  return (await b.getAsset(PROJECT_ID, 'hero')).meta
+}
+
+const iptcJpeg = new Uint8Array(
+  readFileSync(new URL('../../core/src/cms-core/__fixtures__/embedded-metadata/iptc-xmp.jpg', import.meta.url)),
+)
+
+/** A replace whose read is followed — before its write — by another session's dialog save. */
+async function replaceRacingADialog({ a, b }: { a: AssetRepository; b: AssetRepository }) {
+  await seed(a, { alt: 'old alt', note: 'old note' })
+  const dialogB = await openDialog(b)
+  dialogB.edit('note', 'B note')
+  const racing: AssetRepository = {
+    // B's dialog commits at the worst moment: right before A's replace writes.
+    upsertAsset: async (projectId, input) => {
+      await dialogB.commit()
+      return a.upsertAsset(projectId, input)
+    },
+    getAsset: (projectId, id) => a.getAsset(projectId, id),
+    listAssets: (projectId) => a.listAssets(projectId),
+    removeAsset: (projectId, id) => a.removeAsset(projectId, id),
+    resolveMany: (projectId, ids) => a.resolveMany(projectId, ids),
+    findAsset: (projectId, id) => a.findAsset(projectId, id),
+  }
+  const result = await runUpload(
+    {
+      blobs: new InMemoryBlobStorage(),
+      assets: racing,
+      assetFields: defaultAssetCollection().fields,
+      detectDimensions: async () => ({ width: 8, height: 6 }),
+      generateVariants: async () => ({}),
+    },
+    {
+      projectId: PROJECT_ID,
+      file: {
+        name: 'new.jpg',
+        type: 'image/jpeg',
+        size: iptcJpeg.byteLength,
+        arrayBuffer: async () => iptcJpeg.slice().buffer as ArrayBuffer,
+      },
+      replace: { assetId: 'hero' },
+    },
+  )
+  expect(result.ok).toBe(true)
+  return (await a.getAsset(PROJECT_ID, 'hero')).meta
+}
+
+describe('EC-634 — asset meta is patched per key in the write, on both adapters', () => {
+  it('two sessions’ interleaved dialog saves of different keys keep both (the worst row)', async () => {
+    const expected = { alt: 'A alt', credit: 'B credit' }
+    expect(await interleavedDialogs(memoryBackend())).toEqual(expected)
+    expect(await interleavedDialogs(await convexBackend())).toEqual(expected)
+  })
+
+  it('a dialog save landing just before a replace’s write survives the replace', async () => {
+    const memory = await replaceRacingADialog(memoryBackend())
+    const convex = await replaceRacingADialog(await convexBackend())
+    expect(convex).toEqual(memory)
+    expect(convex).toMatchObject({ alt: 'A harbour at dusk & boats', note: 'B note' })
+  })
+
+  it('a patch lifts a not-yet-migrated legacy alt column into the stored bag, in the same mutation', async () => {
+    const { t, a } = await convexBackend()
+    await t.run(async (ctx) => {
+      await ctx.db.insert('assets', {
+        assetId: 'legacy',
+        filename: 'l.jpg',
+        contentType: 'image/jpeg',
+        byteSize: 1,
+        storageKey: 'k_legacy',
+        alt: 'Column alt',
+        createdAt: STAMP,
+        updatedAt: STAMP,
+      })
+    })
+    // An edit of ANOTHER key: the alt it did not name moves home and is kept.
+    const kept = await a.upsertAsset(PROJECT_ID, { id: 'legacy', metaPatch: { credit: 'Ada' } })
+    expect(kept.meta).toEqual({ alt: 'Column alt', credit: 'Ada' })
+    expect(kept.alt).toBeUndefined()
+    expect(assetAlt(kept, null)).toBe('Column alt')
+    // A clear of the alt stays cleared — no column left to re-surface it (ASSETS D21).
+    const cleared = await a.upsertAsset(PROJECT_ID, { id: 'legacy', metaPatch: { alt: null } })
+    expect(assetAlt(cleared, null)).toBeNull()
+    const row = await t.run((ctx) => ctx.db.query('assets').filter((q) => q.eq(q.field('assetId'), 'legacy')).first())
+    expect(row?.alt).toBeUndefined()
+    expect(row?.meta).toEqual({ credit: 'Ada' })
+  })
+
+  it('EC-632 — per-locale buckets are stored by the real mutation, and the stored row measures its depth', async () => {
+    const { t, a, b } = await convexBackend()
+    await seed(a, { credit: 'Ada' })
+    // Two translators, two sessions, interleaved: both locales are kept.
+    await a.upsertAsset(PROJECT_ID, { id: 'hero', localizedMetaPatch: { de: { alt: 'Hafen' } } })
+    await b.upsertAsset(PROJECT_ID, {
+      id: 'hero',
+      localizedMetaPatch: { en: { alt: 'Harbour', disclosure: { shown: true, badge: { corner: 'tl', tone: 'dark' } } } },
+    })
+    const row = await t.run((ctx) => ctx.db.query('assets').filter((q) => q.eq(q.field('assetId'), 'hero')).first())
+    expect(row?.localizedMeta).toEqual({
+      de: { alt: 'Hafen' },
+      en: { alt: 'Harbour', disclosure: { shown: true, badge: { corner: 'tl', tone: 'dark' } } },
+    })
+    expect(row?.meta).toEqual({ credit: 'Ada' })
+    // The stored Convex document (system fields included): 5 of Convex's 16 levels.
+    expect(measureMaxDepth(row).depth).toBe(5)
+  })
+
+  it('refuses meta and metaPatch together, through the rule (a PersistenceValidationError naming metaPatch)', async () => {
+    const { a } = await convexBackend()
+    await seed(a, { alt: 'x' })
+    await expect(
+      a.upsertAsset(PROJECT_ID, { id: 'hero', meta: { alt: 'y' }, metaPatch: { credit: 'z' } }),
+    ).rejects.toBeInstanceOf(PersistenceValidationError)
+    expect((await a.getAsset(PROJECT_ID, 'hero')).meta).toEqual({ alt: 'x' })
+  })
+})

package/convex/asset-replace-delete-race.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import type { FunctionReference } from 'convex/server'
+import { InMemoryBlobStorage, InMemoryPersistenceAdapter } from '@elytracms/core/persistence'
+import type { AssetRepository } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import { runUpload } from '../src/lib/assets/upload'
+import schema from './schema'
+
+// convex-test fires a `runAfter(0)` on a REAL timer; fake timers keep the scheduled
+// revalidation queued (its row written, the `webhooks:deliver` fetch never fired).
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/**
+ * EC-634 follow-on — a replace is an UPDATE of a stored asset, never a create. Session A
+ * replaces the file; session B deletes the asset in the window between A's check and A's
+ * write. The replace used to carry every column a create needs, so it silently RE-CREATED
+ * the asset B had deleted (a colleague's delete undone). Two sessions over ONE backend,
+ * in-memory AND Convex (the real `assets:upsert` over convex-test).
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const PROJECT_ID = 'asset-replace-race'
+const SESSION_USER_ID = 'user_admin'
+
+async function convexSessions() {
+  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 })
+  })
+  const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+  const session = () =>
+    new ConvexPersistenceAdapter(
+      {
+        query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => asAdmin.query(ref, args ?? {}),
+        mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) =>
+          asAdmin.mutation(ref, args ?? {}),
+      } as unknown as ConvexHttpClient,
+      PROJECT_ID,
+    ).assets
+  return { a: session(), b: session() }
+}
+
+function memorySessions() {
+  const adapter = new InMemoryPersistenceAdapter()
+  return { a: adapter.assets, b: adapter.assets }
+}
+
+/** A's replace, with B's delete landing right after A checked that the asset exists. */
+async function replaceRacingADelete({ a, b }: { a: AssetRepository; b: AssetRepository }) {
+  await a.upsertAsset(PROJECT_ID, {
+    id: 'hero',
+    filename: 'old.jpg',
+    contentType: 'image/jpeg',
+    byteSize: 1,
+    storageKey: 'blob_old',
+    url: 'https://assets.test/old.jpg',
+  })
+  // B's delete lands immediately before A's write — after anything A checked or read.
+  const racing: AssetRepository = {
+    upsertAsset: async (projectId, input) => {
+      await b.removeAsset(projectId, 'hero')
+      return a.upsertAsset(projectId, input)
+    },
+    getAsset: (projectId, id) => a.getAsset(projectId, id),
+    listAssets: (projectId) => a.listAssets(projectId),
+    removeAsset: (projectId, id) => a.removeAsset(projectId, id),
+    resolveMany: (projectId, ids) => a.resolveMany(projectId, ids),
+    findAsset: (projectId, id) => a.findAsset(projectId, id),
+  }
+  const result = await runUpload(
+    {
+      blobs: new InMemoryBlobStorage(),
+      assets: racing,
+      detectDimensions: async () => ({ width: 8, height: 6 }),
+      generateVariants: async () => ({}),
+    },
+    {
+      projectId: PROJECT_ID,
+      file: { name: 'new.jpg', type: 'image/jpeg', size: 3, arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer },
+      replace: { assetId: 'hero' },
+    },
+  )
+  return { result, stored: await b.findAsset(PROJECT_ID, 'hero') }
+}
+
+describe('EC-634 follow-on — a replace never re-creates an asset another session deleted', () => {
+  for (const [name, backend] of [
+    ['in-memory', async () => memorySessions()],
+    ['Convex', convexSessions],
+  ] as const) {
+    it(`${name}: the replace is refused, visibly, and the delete stands`, async () => {
+      const { result, stored } = await replaceRacingADelete(await backend())
+      expect(stored).toBeUndefined()
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.failure.stage).toBe('confirm')
+        expect(result.failure.message).toContain('hero')
+      }
+    })
+  }
+
+  it('control: without the delete the replace lands (same id, the new file)', async () => {
+    const { a } = memorySessions()
+    await a.upsertAsset(PROJECT_ID, { id: 'hero', filename: 'old.jpg', contentType: 'image/jpeg', byteSize: 1 })
+    const result = await runUpload(
+      { blobs: new InMemoryBlobStorage(), assets: a, detectDimensions: async () => undefined, generateVariants: async () => ({}) },
+      {
+        projectId: PROJECT_ID,
+        file: { name: 'new.jpg', type: 'image/jpeg', size: 3, arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer },
+        replace: { assetId: 'hero' },
+      },
+    )
+    expect(result.ok && result.asset).toMatchObject({ id: 'hero', filename: 'new.jpg' })
+  })
+})

package/convex/assets.ts

@@ -25,8 +25,9 @@ const clearable = <T, F extends string>(validator: Validator<T, 'required', F>)
 /**
  * Write one asset (EC-577). The ONE write rule (`resolveAssetWrite`, shared with
  * the in-memory adapter) runs here, inside the transaction: a column absent from
- * the args keeps its stored value, `null` clears it, a value sets it — and the legacy
- * `alt` column can only be cleared (EC-587: an asset's alt is `meta.alt`). An edit is
+ * the args keeps its stored value, `null` clears it, a value sets it — the legacy
+ * `alt` column can only be cleared (EC-587: an asset's alt is `meta.alt`), and a
+ * `metaPatch` changes `meta` per key against the row read here (EC-634). An edit is
  * ONE `db.patch` — the rule's store patch, where a cleared column is `undefined`,
  * which `db.patch` removes — so the write-chokepoint triggers fire once. No stored
  * asset → ONE `db.insert` of the complete row (the `defaults` fill what the write
@@ -65,6 +66,30 @@ export const upsert = mutation({
     lqip: clearable(v.string()),
     /** Schema-driven asset metadata bag (EC-301): alt, copyright, credit, …. `null` clears it. */
     meta: v.optional(v.any()),
+    /**
+     * EC-634 — a per-key change to `meta` (a value sets the key, `null` removes it), applied
+     * by the rule to the row as stored HERE, in this transaction — so an editor's save never
+     * carries a stale copy of a key another session changed. Validated by the rule (an
+     * object of keys, never beside `meta`), as `meta` is.
+     */
+    metaPatch: v.optional(v.any()),
+    /**
+     * EC-632 — the per-locale buckets of the asset collection's `localized: true` fields
+     * (`{ [locale]: { [field]: value } }`): `null` clears them, an object replaces them
+     * whole (a create, an import); an editor sends `localizedMetaPatch` instead.
+     */
+    localizedMeta: v.optional(v.any()),
+    /**
+     * EC-632 — a per-locale, per-key change to those buckets, applied by the rule to the
+     * row as stored HERE (as `metaPatch` is to `meta`). Validated by the rule.
+     */
+    localizedMetaPatch: v.optional(v.any()),
+    /**
+     * EC-634 follow-on — this write only UPDATES a stored asset (a file replace): with the
+     * row gone (deleted by another session) the rule refuses it here, so it never re-creates
+     * what a colleague deleted.
+     */
+    mustExist: v.optional(v.boolean()),
     /**
      * What a CREATE fills in when the write leaves it absent (`assetCreateDefaults`
      * in core). Sent by the adapter because only it knows the project — rows carry

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).
@@ -156,6 +161,70 @@ 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(),
+})
+
+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
+}
+
 /**
  * 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 —
@@ -421,11 +490,35 @@ 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' }`.
+ */
 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)),
+      }),
+    ),
+  },
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.write') // EC-150
     const existing = await draftRow(ctx, args.collection, args.docId)
+    const revision = args.precondition?.revision
+    if (revision !== undefined && existing?.revision !== revision) {
+      return { status: 'conflict' as const, current: existing ? withUnfoldedDocument(existing) : null }
+    }
+    const unjudged = await unjudgedPublishedReferrers(ctx, args.collection, args.docId, args.precondition?.publishedReferrers)
+    if (unjudged.length > 0) return { status: 'unjudged-referrers' as const, refs: unjudged }
     if (existing) await ctx.db.delete(existing._id)
     // Cascade the version history (EC-224), the patch log and presence (EC-595).
     const versions = await ctx.db
@@ -436,6 +529,7 @@ export const deleteDocument = mutation({
     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 }
   },
 })
 
@@ -518,6 +612,8 @@ 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.
  */
 export const publishDocument = mutation({
   args: {
@@ -527,6 +623,7 @@ export const publishDocument = mutation({
     label: v.optional(v.string()),
     origin: v.optional(v.string()),
     at: v.string(),
+    strictTargets: v.optional(v.array(documentRefValidator)),
   },
   handler: async (ctx, args) => {
     const actor = await requireCapability(ctx, 'content.write') // EC-150
@@ -535,6 +632,8 @@ export const publishDocument = mutation({
     if (existing.revision !== args.expectedRevision) {
       return { status: 'conflict' as const, current: withUnfoldedDocument(existing) }
     }
+    const unpublished = await unpublishedStrictTargets(ctx, args.strictTargets)
+    if (unpublished.length > 0) return { status: 'strict-targets' as const, refs: unpublished }
     const draft = unfoldDocument(existing.document as CmsDocument)
     const version = await insertVersion(ctx, {
       collection: args.collection,
@@ -652,8 +751,10 @@ 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). 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,6 +764,7 @@ 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)),
   },
   handler: async (ctx, args) => {
     const actor = await requireCapability(ctx, 'content.write') // EC-150
@@ -671,6 +773,8 @@ export const publishDocumentVersion = mutation({
     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 +796,24 @@ 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 }`.
+ */
 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)),
+  },
   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
+    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