@forge-cms/runtime 0.5.0 → 0.6.0

package/dist/operations.js

@@ -1,16 +1,20 @@
 import { getLogger, validateCollection } from '@forge-cms/core';
-import { isUniqueConstraintError as isDbUniqueConstraintError } from '@forge-cms/db';
-import { AccessDeniedError, ForgeError, InvalidInputError, NotFoundError, UniqueConstraintError, ValidationFailedError } from './errors.js';
+import { ATOMIC_WRITE_MAX_OPERATIONS, isAtomicWriteConditionError, isUniqueConstraintError as isDbUniqueConstraintError } from '@forge-cms/db';
+import { AccessDeniedError, ConcurrentModificationError, ForgeError, InvalidInputError, NotFoundError, UniqueConstraintError, ValidationFailedError } from './errors.js';
 import { documentMatches, mergeWhere } from './access.js';
+import { assertNotAuthManaged } from './auth-managed.js';
 import { validateSort, validateWhere } from './query-validation.js';
 import { applyAutoSlugs, applyFieldDefaults } from './defaults.js';
 import { checkAccess, statusConstraint } from './read-policy.js';
 import { runAfterChangeHooks, runAfterDeleteHooks, runAfterOperationHooks, runAfterReadHooks, runBeforeChangeHooks, runBeforeDeleteHooks, runBeforeOperationHooks, runBeforeReadHooks, runBeforeValidateHooks, runFieldHooks } from './hooks.js';
 import { assertWritableFields, filterReadableFields, FieldAccessError } from './field-access.js';
 import { populateRecord, populateRecords } from './populate.js';
-import { createVersion, getVersion, versionsEnabled } from './versions.js';
-import { isLocalizedCollection, storeLocalizedDocument, resolveLocalizedDocument } from './localization.js';
-import { checkDeleteRestrictions, handleCascadeDelete, handleSetNullOnDelete } from './relation-integrity.js';
+import { screenCreateInput, screenHookOutput, screenUpdateInput } from './system-fields.js';
+import { buildSnapshot, buildVersionRecord, diffAgainst, isVersionIdentityConflict, readLatestVersionNumber, readVersionForRestore, restoreTarget, versionsCollectionSlug, versionsEnabled } from './versions.js';
+import { isLocalizedCollection, isLocalizedField, storeLocalizedDocument, resolveLocalizedDocument } from './localization.js';
+import { collectWrittenTargets, echoedReferenceGuard, planRelationDelete, setNullPatch, targetAssertions, verifyTargetsExist } from './relation-lifecycle.js';
+import { afterStamp } from './concurrency.js';
+import { claimUploadIntent, deletionIntent, finishDeletion, recordUploadIntent, settleFailedUpload } from './storage-intents.js';
 function getCollectionOrThrow(ctx, slug) {
     const collection = ctx.getCollection(slug);
     if (!collection)
@@ -36,6 +40,243 @@ async function runWrite(collection, op) {
         throw err;
     }
 }
+/**
+ * The database for a versioned write. Document + snapshot must be one atomic batch (spec 062), so an
+ * adapter without `atomicWrite()` is refused rather than silently downgraded to two separate writes.
+ * `syncSchema()` already refuses it up front; this is the same check at the point of use.
+ */
+function atomicDatabase(ctx, collection) {
+    const database = ctx.adapters.database;
+    if (typeof database.atomicWrite !== 'function') {
+        throw new Error(`Collection '${collection.slug}' has versions enabled, which requires a DatabaseAdapter ` +
+            `implementing atomicWrite() (specs 060/062); '${database.name}' does not.`);
+    }
+    return database;
+}
+/**
+ * A relation target named by a write was deleted after the write verified it existed (spec 064 §4): the
+ * batch's `assertCount` failed and nothing was written. Reported as a conflict, never as bad input —
+ * "the target was missing to begin with" is only ever reported from the pre-batch read.
+ */
+function targetVanished(collection, id) {
+    return new ConcurrentModificationError(collection.slug, id, `A document referenced by this write to '${collection.slug}' was deleted by another request while ` +
+        `it was in progress; nothing was written. Reload and try again.`);
+}
+/**
+ * Maps what a rolled-back document + snapshot batch threw to the runtime's typed errors (spec 062 §3).
+ * The version table's `(documentId, versionNumber)` index is an internal detail: on update it means
+ * another writer committed first (`ConcurrentModificationError`); on create it means the id is already
+ * taken by an existing — possibly deleted — document's history, reported like any duplicate id. The
+ * internal table name never reaches the caller.
+ *
+ * With relation-target assertions in the batch (spec 064) an `AtomicWriteConditionError` on create can
+ * only be an assertion (creates never have to apply); on update it is either an assertion or the plain
+ * `update` of a document deleted meanwhile — the database does not say which, so both are a `409`.
+ */
+function toVersionedWriteError(err, collection, id, operation, hasAssertions) {
+    if (isVersionIdentityConflict(err, collection)) {
+        return operation === 'create'
+            ? new UniqueConstraintError(collection.slug, ['id'])
+            : new ConcurrentModificationError(collection.slug, id);
+    }
+    if (isDbUniqueConstraintError(err))
+        return new UniqueConstraintError(collection.slug, err.fields);
+    if (isAtomicWriteConditionError(err)) {
+        if (!hasAssertions)
+            return notFound(collection.slug, id);
+        return operation === 'create'
+            ? targetVanished(collection, id)
+            : new ConcurrentModificationError(collection.slug, id, `Document '${id}' in '${collection.slug}', or a document this update references, was changed ` +
+                `or deleted by another request while this one was in progress; nothing was written. Reload ` +
+                `it and try again.`);
+    }
+    return err;
+}
+/**
+ * Versioned create (spec 062 §2): the document and its version 1 in one `atomicWrite()`, preceded by
+ * the write's relation-target assertions (spec 064) — one batch, never a second transaction. The batch
+ * is declarative and cannot feed a generated id from one operation into the next, so the id is allocated
+ * here — a trusted caller's explicit `id` if it supplied one (spec 063 §2), otherwise a UUID, which is
+ * what the adapters would have generated. `row` is what the document row persists (content plus any
+ * Forge-owned metadata such as `_storageKey`); the snapshot is built from content only.
+ */
+async function createWithSnapshot(ctx, collection, input) {
+    const database = atomicDatabase(ctx, collection);
+    const id = input.id ?? crypto.randomUUID();
+    const { row, user, assertions } = input;
+    let results;
+    try {
+        results = await database.atomicWrite([
+            ...assertions,
+            { type: 'create', collection: collection.slug, data: { ...row, id } },
+            {
+                type: 'create',
+                collection: versionsCollectionSlug(collection.slug),
+                data: buildVersionRecord({
+                    documentId: id,
+                    versionNumber: 1,
+                    data: buildSnapshot(collection, row),
+                    user,
+                    full: true
+                })
+            }
+        ]);
+    }
+    catch (err) {
+        throw toVersionedWriteError(err, collection, id, 'create', assertions.length > 0);
+    }
+    const created = results[assertions.length];
+    if (created?.type !== 'create')
+        throw new Error('atomicWrite returned no created document');
+    return created.record;
+}
+/**
+ * The document write and snapshot of a prepared versioned update (spec 062 §3), as batch operations.
+ * `versionNumber` is one past the latest version observed *before* the document was read, so if anyone
+ * committed in between, the snapshot collides with theirs on the unique `(documentId, versionNumber)`
+ * index and the whole batch — document patch included — rolls back. Shared by `update()` and by the
+ * set-null updates a relation delete folds into its own batch (spec 064 §5), so there is one mechanism.
+ */
+function versionedUpdateOperations(prepared, echoGuard) {
+    const { collection, id, data, existing } = prepared;
+    return [
+        echoGuard === undefined
+            ? { type: 'update', collection: collection.slug, id, data }
+            : {
+                type: 'updateIf',
+                collection: collection.slug,
+                id,
+                data,
+                condition: { targetMatches: echoGuard },
+                requireApplied: true
+            },
+        {
+            type: 'create',
+            collection: versionsCollectionSlug(collection.slug),
+            data: buildVersionRecord({
+                documentId: id,
+                versionNumber: prepared.latestVersion + 1,
+                // `{ ...existing, ...data }` is exactly what the batch leaves in the row: it only commits if
+                // no one else wrote this document since `existing` was read.
+                data: buildSnapshot(collection, { ...existing, ...data }),
+                user: prepared.user,
+                full: true,
+                ...(prepared.versionLabel !== undefined && { label: prepared.versionLabel })
+            })
+        }
+    ];
+}
+/**
+ * Commits a prepared update: a versioned document with its snapshot (spec 062), and any relation-target
+ * assertions (spec 064) in the same single batch. A non-versioned update with nothing to assert keeps
+ * the plain single-call write.
+ */
+async function commitUpdate(ctx, prepared, assertions, echoGuard) {
+    const { collection, id, data } = prepared;
+    if (prepared.versioned) {
+        const database = atomicDatabase(ctx, collection);
+        let results;
+        try {
+            results = await database.atomicWrite([
+                ...assertions,
+                ...versionedUpdateOperations(prepared, echoGuard)
+            ]);
+        }
+        catch (err) {
+            throw toVersionedWriteError(err, collection, id, 'update', assertions.length > 0 || echoGuard !== undefined);
+        }
+        const updated = results[assertions.length];
+        if (updated?.type === 'update' || (updated?.type === 'updateIf' && updated.applied)) {
+            return updated.record;
+        }
+        throw new Error('atomicWrite returned no updated document');
+    }
+    if (assertions.length === 0 && echoGuard === undefined) {
+        return runWrite(collection.slug, () => ctx.adapters.database.update(collection.slug, id, data));
+    }
+    // Not required to apply: a document that is gone, or no longer holds the references this update
+    // re-sends, is `applied: false` (nothing written), so the only thing that can fail the batch is a
+    // target assertion.
+    let results;
+    try {
+        results = await ctx.adapters.database.atomicWrite([
+            ...assertions,
+            {
+                type: 'updateIf',
+                collection: collection.slug,
+                id,
+                data,
+                condition: echoGuard === undefined ? {} : { targetMatches: echoGuard }
+            }
+        ]);
+    }
+    catch (err) {
+        if (isAtomicWriteConditionError(err))
+            throw targetVanished(collection, id);
+        if (isDbUniqueConstraintError(err))
+            throw new UniqueConstraintError(collection.slug, err.fields);
+        throw err;
+    }
+    const updated = results[assertions.length];
+    if (updated?.type !== 'updateIf')
+        throw new Error('atomicWrite returned no update result');
+    if (updated.applied)
+        return updated.record;
+    // Which of the two it was only picks the error: nothing was written either way.
+    if (!(await ctx.adapters.database.findById(collection.slug, id))) {
+        throw notFound(collection.slug, id);
+    }
+    throw new ConcurrentModificationError(collection.slug, id, `Document '${id}' in '${collection.slug}' was changed by another request while this update was in ` +
+        `progress (it no longer matches the caller's update access, another locale was edited, or a ` +
+        `reference this update re-sends was cleared); nothing was written. Reload it and try again.`);
+}
+/**
+ * Commits a new non-versioned document. With relation-target assertions the create joins them in one
+ * batch (spec 064 §4); a create never has to apply, so a failed batch condition is always an assertion.
+ */
+async function commitCreate(ctx, collection, row, assertions) {
+    if (assertions.length === 0) {
+        return runWrite(collection.slug, () => ctx.adapters.database.create(collection.slug, row));
+    }
+    let results;
+    try {
+        results = await ctx.adapters.database.atomicWrite([
+            ...assertions,
+            { type: 'create', collection: collection.slug, data: row }
+        ]);
+    }
+    catch (err) {
+        if (isAtomicWriteConditionError(err)) {
+            throw targetVanished(collection, typeof row.id === 'string' ? row.id : '(new)');
+        }
+        if (isDbUniqueConstraintError(err))
+            throw new UniqueConstraintError(collection.slug, err.fields);
+        throw err;
+    }
+    const created = results[assertions.length];
+    if (created?.type !== 'create')
+        throw new Error('atomicWrite returned no created document');
+    return created.record;
+}
+/**
+ * Validates the relation targets a write introduces and returns the assertions that keep them valid
+ * until it commits (spec 064 §4). A known-missing target is a `400` here, before any write.
+ */
+async function relationTargetGuards(ctx, collection, data, existing, 
+/** A create's explicit id: a self reference names the document the same batch creates. */
+selfId) {
+    const targets = collectWrittenTargets(collection.fields, data, existing);
+    const self = selfId !== undefined ? targets.get(collection.slug) : undefined;
+    if (self && selfId !== undefined) {
+        self.ids.delete(selfId);
+        if (self.ids.size === 0)
+            targets.delete(collection.slug);
+    }
+    if (targets.size === 0)
+        return [];
+    await verifyTargetsExist(ctx, targets);
+    return targetAssertions(targets);
+}
 /**
  * Runs a stage that may reject the write. A hook throwing a plain `Error` is a rejection of the
  * caller's payload (400), not a server fault — preserving the spec-013 contract that a throwing
@@ -202,14 +443,71 @@ export async function count(ctx, args) {
     return result;
 }
 export async function create(ctx, args) {
+    return createDocument(ctx, args, undefined);
+}
+/**
+ * The multipart upload pipeline's create (spec 063 §5) — **package-private**: exported for
+ * `handlers.ts` only, never from the package entry point. `storageKey` is the key Forge itself just
+ * generated and stored the object under; it is merged into the persisted row only, outside caller
+ * `data` and hook `data`, so no caller of the public mutation surface can choose or rewrite it.
+ */
+export async function createUpload(ctx, args, upload) {
+    const collection = getCollectionOrThrow(ctx, args.collection);
+    if (collection.upload !== true) {
+        throw new Error(`Collection '${args.collection}' is not upload-enabled`);
+    }
+    return createDocument(ctx, args, upload);
+}
+/**
+ * The whole upload create (spec 067) — **package-private**, called by `handleCreate` for a multipart
+ * body: records a durable storage intent, stores the object under a Forge-generated key, then creates
+ * the document with the key and the intent claim in one batch. Any failure after the intent exists
+ * settles it: the object is deleted only while the intent is still there (the document never
+ * committed); otherwise the intent stays for `reconcileStorage()`. The file's `filename`, `url`,
+ * `contentType` and `filesize` fill whichever of those fields the collection declares, under `args.data`.
+ */
+export async function uploadFile(ctx, args, file) {
+    const collection = getCollectionOrThrow(ctx, args.collection);
+    if (collection.upload !== true) {
+        throw new Error(`Collection '${args.collection}' is not upload-enabled`);
+    }
+    assertNotAuthManaged(ctx, args.collection);
+    const storageKey = `${collection.slug}/${crypto.randomUUID()}-${file.name}`;
+    const intentId = await recordUploadIntent(ctx.adapters.database, collection.slug, storageKey);
+    try {
+        await ctx.adapters.storage.put({ key: storageKey, body: file, contentType: file.type });
+        const url = await ctx.adapters.storage.getPublicUrl(storageKey);
+        const derived = {
+            filename: file.name,
+            url,
+            contentType: file.type,
+            filesize: file.size
+        };
+        const data = {};
+        for (const [name, value] of Object.entries(derived)) {
+            if (collection.fields[name])
+                data[name] = value;
+        }
+        return await createDocument(ctx, { ...args, data: { ...data, ...args.data } }, { storageKey, intentId });
+    }
+    catch (err) {
+        await settleFailedUpload(ctx, intentId, storageKey);
+        throw err;
+    }
+}
+async function createDocument(ctx, args, upload) {
     const collection = getCollectionOrThrow(ctx, args.collection);
+    assertNotAuthManaged(ctx, args.collection);
     const user = args.user ?? null;
     const overrideAccess = args.overrideAccess !== false;
     await runBeforeOperationHooks(collection, { operation: 'create', user, overrideAccess });
     await checkAccess(collection, 'create', { ...args, data: args.data });
+    // Spec 063: Forge-owned metadata never comes from the caller. A trusted caller's explicit `id` is
+    // held aside (hooks never see or change it) and re-attached at persistence.
+    const { content, id: explicitId } = screenCreateInput(args.data, overrideAccess);
     if (args.overrideAccess === false) {
         try {
-            await assertWritableFields(args.data, collection, user, 'create');
+            await assertWritableFields(content, collection, user, 'create');
         }
         catch (err) {
             if (err instanceof FieldAccessError)
@@ -219,7 +517,7 @@ export async function create(ctx, args) {
     }
     // Defaults and auto-slugs are resolved before any hook runs, so a hook still gets the last word
     // and validation only ever sees the final value.
-    const seeded = applyAutoSlugs(collection, applyFieldDefaults(collection, args.data));
+    const seeded = applyAutoSlugs(collection, applyFieldDefaults(collection, content));
     // Process localized fields if the collection has locales configured
     const processedData = isLocalizedCollection(collection) && args.locale
         ? storeLocalizedDocument(seeded, collection, args.locale)
@@ -235,6 +533,7 @@ export async function create(ctx, args) {
         user,
         overrideAccess
     }), 'beforeValidate hook');
+    data = screenHookOutput(data, {}, 'beforeValidate', args.collection);
     assertDraftStatus(collection, data);
     if (collection.drafts === true && data._status === undefined) {
         data = { ...data, _status: 'draft' };
@@ -253,16 +552,19 @@ export async function create(ctx, args) {
         user,
         overrideAccess
     }), 'beforeChange hook');
-    const record = await runWrite(args.collection, () => ctx.adapters.database.create(args.collection, data));
-    // Create initial version if versions are enabled
-    if (versionsEnabled(collection)) {
-        await createVersion(ctx, {
-            collection: args.collection,
-            documentId: record.id,
-            data,
-            user
-        });
-    }
+    data = screenHookOutput(data, {}, 'beforeChange', args.collection);
+    // Every relation target this document names must exist, now and when it commits (spec 064 §4).
+    const assertions = await relationTargetGuards(ctx, collection, data, undefined, explicitId);
+    // An upload's storage intent is removed in the same batch that creates its owner (spec 067), so the
+    // intent exists exactly as long as the object is owned by nothing.
+    if (upload)
+        assertions.push(claimUploadIntent(upload.intentId));
+    // Forge-owned metadata joins the content only here, at the persistence boundary (spec 063 §4/§5).
+    const row = upload !== undefined ? { ...data, _storageKey: upload.storageKey } : data;
+    // A versioned document and its version 1 commit together or not at all (spec 062 §2).
+    const record = versionsEnabled(collection)
+        ? await createWithSnapshot(ctx, collection, { row, id: explicitId, user, assertions })
+        : await commitCreate(ctx, collection, explicitId !== undefined ? { ...row, id: explicitId } : row, assertions);
     await runAfterChangeHooks(collection, {
         operation: 'create',
         data,
@@ -271,31 +573,69 @@ export async function create(ctx, args) {
         user,
         overrideAccess
     });
-    const [doc] = await prepareForRead(ctx, collection, [record], args);
-    const result = doc ?? record;
+    const result = await writeResult(ctx, collection, record, args);
     await runAfterOperationHooks(collection, { operation: 'create', user, overrideAccess, result });
     return result;
 }
 export async function update(ctx, args) {
+    return updateDocument(ctx, args);
+}
+/**
+ * The update pipeline up to — never including — the write: `beforeOperation`, version-number read (spec
+ * 062 §3: before the document), document read, access, system-field screening, field-write access,
+ * locale storage, `beforeValidate`, validation, `beforeChange`. One implementation for `update()`,
+ * `restoreVersion()` and relation set-null (spec 064), so none of them can drift.
+ *
+ * `restore` (only ever passed by {@link restoreVersion}) replaces `args.data` with the difference between
+ * that version's content and the document as read *here* — after the version number was observed — so a
+ * restore is serialized exactly like any other update (spec 062 §6). `patch` computes the request from
+ * the document as read here (relation set-null); returning `null` means there is nothing to change, and
+ * the preparation stops (`null`) before any further hook.
+ */
+async function prepareUpdate(ctx, args, options = {}) {
     const collection = getCollectionOrThrow(ctx, args.collection);
+    assertNotAuthManaged(ctx, args.collection);
     const user = args.user ?? null;
     const overrideAccess = args.overrideAccess !== false;
     await runBeforeOperationHooks(collection, { operation: 'update', user, overrideAccess });
+    // Spec 062 §3: the latest version number is read BEFORE the document. A write that commits version
+    // N+1 therefore proves nobody committed between this observation and the document read below — the
+    // unique (documentId, versionNumber) index turns any such interleaving into a rolled-back conflict.
+    const versioned = versionsEnabled(collection);
+    const latestVersion = versioned
+        ? await readLatestVersionNumber(ctx.adapters.database, collection, args.id)
+        : 0;
     const existing = await ctx.adapters.database.findById(args.collection, args.id);
     if (!existing)
         throw notFound(args.collection, args.id);
+    let requested;
+    if (options.restore) {
+        requested = diffAgainst(restoreTarget(collection, options.restore), existing);
+    }
+    else if (options.patch) {
+        const patch = options.patch(existing);
+        if (patch === null)
+            return null;
+        requested = patch;
+    }
+    else {
+        requested = args.data;
+    }
     const decision = await checkAccess(collection, 'update', {
         ...args,
         id: args.id,
-        data: args.data,
+        data: requested,
         doc: existing
     });
     if (decision.where && !documentMatches(existing, decision.where)) {
         throw new AccessDeniedError();
     }
+    // Spec 063: echoes of the stored metadata are dropped; changing `id`, a timestamp or `_storageKey`
+    // is refused for every caller, `overrideAccess` included.
+    const input = screenUpdateInput(requested, existing);
     if (args.overrideAccess === false) {
         try {
-            await assertWritableFields(args.data, collection, user, 'update');
+            await assertWritableFields(input, collection, user, 'update');
         }
         catch (err) {
             if (err instanceof FieldAccessError)
@@ -305,8 +645,8 @@ export async function update(ctx, args) {
     }
     // Process localized fields if the collection has locales configured
     const processedData = isLocalizedCollection(collection) && args.locale
-        ? storeLocalizedDocument(args.data, collection, args.locale, existing)
-        : args.data;
+        ? storeLocalizedDocument(input, collection, args.locale, existing)
+        : input;
     let data = await runRejectableStage(async () => runBeforeValidateHooks(collection, {
         operation: 'update',
         data: await runFieldHooks(collection, 'beforeValidate', {
@@ -320,6 +660,7 @@ export async function update(ctx, args) {
         user,
         overrideAccess
     }), 'beforeValidate hook');
+    data = screenHookOutput(data, existing, 'beforeValidate', args.collection);
     assertDraftStatus(collection, data);
     // Validate the merged document so required fields already stored do not fail a partial update,
     // then report only the errors the caller can actually act on: fields they are touching, or fields
@@ -347,17 +688,24 @@ export async function update(ctx, args) {
         user,
         overrideAccess
     }), 'beforeChange hook');
-    const record = await runWrite(args.collection, () => ctx.adapters.database.update(args.collection, args.id, data));
-    // Create a version snapshot if versions are enabled
-    if (versionsEnabled(collection)) {
-        await createVersion(ctx, {
-            collection: args.collection,
-            documentId: args.id,
-            data,
-            user,
-            ...(args.versionLabel !== undefined && { label: args.versionLabel })
-        });
-    }
+    data = screenHookOutput(data, existing, 'beforeChange', args.collection);
+    return {
+        collection,
+        id: args.id,
+        args,
+        user,
+        overrideAccess,
+        existing,
+        data,
+        versioned,
+        latestVersion,
+        versionLabel: args.versionLabel,
+        accessWhere: decision.where
+    };
+}
+/** The post-commit half of an update: `afterChange`, the read pipeline, `afterOperation`. */
+async function finalizeUpdate(ctx, prepared, record) {
+    const { collection, data, existing, user, overrideAccess } = prepared;
     await runAfterChangeHooks(collection, {
         operation: 'update',
         data,
@@ -367,81 +715,164 @@ export async function update(ctx, args) {
         user,
         overrideAccess
     });
-    const [doc] = await prepareForRead(ctx, collection, [record], args);
-    const result = doc ?? record;
+    const result = await writeResult(ctx, collection, record, prepared.args);
     await runAfterOperationHooks(collection, { operation: 'update', user, overrideAccess, result });
     return result;
 }
+async function updateDocument(ctx, args, restore) {
+    const prepared = await prepareUpdate(ctx, args, restore ? { restore } : {});
+    if (!prepared)
+        throw new Error('update preparation produced no change'); // unreachable without `patch`
+    // Only relation values this update changes are validated (spec 064 §4) — a partial update never
+    // fails over a reference it does not touch.
+    const assertions = await relationTargetGuards(ctx, prepared.collection, prepared.data, prepared.existing);
+    // …and the references it re-sends unchanged must still be there when it commits.
+    const echoGuard = echoedReferenceGuard(prepared.collection.fields, prepared.data, prepared.existing);
+    // A locale write merged into the stored per-locale maps must not overwrite a concurrent edit of
+    // another locale: it commits only while the row is still the one it merged from (spec 067).
+    const localeGuard = localeMergeGuard(prepared);
+    if (localeGuard)
+        await afterStamp(prepared.existing.updated_at);
+    // A query-returning update rule is a row-level grant: the row must still match it when the write
+    // commits, not only when it was read (spec 068).
+    const guard = allOf([echoGuard, localeGuard, prepared.accessWhere]);
+    const record = await commitUpdate(ctx, prepared, assertions, guard);
+    return finalizeUpdate(ctx, prepared, record);
+}
+/**
+ * What a write returns (spec 068). A trusted write (or a caller who may read the result) gets the
+ * document through the normal read preparation (field access, locale, population, afterRead hooks). An
+ * access-checked caller whose *read* access does not reach the written document — the collection's read
+ * rule denies it, its query does not match, or it is a draft they could not read — gets only its `id`:
+ * being allowed to write a document is not permission to read it back.
+ */
+async function writeResult(ctx, collection, record, args) {
+    if (args.overrideAccess === false && !(await canRead(collection, record, args.user ?? null))) {
+        return { id: record.id };
+    }
+    const [doc] = await prepareForRead(ctx, collection, [record], args);
+    return doc ?? record;
+}
+/** The single-document read gate `findByID` applies, as a yes/no for an already-loaded row. */
+async function canRead(collection, record, user) {
+    let decision;
+    try {
+        // Exactly `findByID`'s arguments — no `doc`, so a read rule answers the same here as there.
+        decision = await checkAccess(collection, 'read', {
+            user,
+            overrideAccess: false,
+            id: record.id
+        });
+    }
+    catch (err) {
+        if (err instanceof AccessDeniedError)
+            return false;
+        throw err;
+    }
+    if (decision.where && !documentMatches(record, decision.where))
+        return false;
+    const status = statusConstraint(collection, undefined, user, false, 'all');
+    return !status || documentMatches(record, status);
+}
+/** The conjunction of the defined conditions, or `undefined` when there are none. */
+function allOf(conditions) {
+    const defined = conditions.filter((c) => c !== undefined);
+    if (defined.length === 0)
+        return undefined;
+    return defined.length === 1 ? defined[0] : { and: defined };
+}
+/** `updated_at` compare-and-set for an update that merged a `locale` into stored per-locale maps. */
+function localeMergeGuard(prepared) {
+    const { collection, args, data, existing } = prepared;
+    if (args.locale === undefined || !isLocalizedCollection(collection))
+        return undefined;
+    if (typeof existing.updated_at !== 'string')
+        return undefined;
+    const merges = Object.keys(data).some((name) => {
+        const field = collection.fields[name];
+        return field !== undefined && isLocalizedField(field);
+    });
+    return merges ? { updated_at: existing.updated_at } : undefined;
+}
 /**
- * Restores a document to a specific historical version — spec 058 §2. Unlike the pre-058
- * implementation (which wrote through `ctx.adapters.database.update()` directly, bypassing access,
- * validation, and hooks), this fetches the raw version snapshot and then calls this module's own
- * `update()`, so a restore gets exactly the same update-access/row-policy/field-write/validation/hook
- * pipeline a normal update gets, and creates exactly one labeled version (via `versionLabel`) instead
- * of a second, bespoke version write.
+ * Restores a document to a specific historical version — spec 058 §2, made atomic by spec 062. The raw
+ * snapshot is read (trusted — restore's authorization gate is `update()`'s own update-access check on
+ * the *current* document, see spec 058 §2) and handed to this module's own update pipeline, which turns
+ * it into a patch of only the fields that differ from the current document (spec 062 §6) and then runs
+ * the normal update-access / row-policy / field-write / validation / hook pipeline. The patch and one
+ * snapshot labeled `Restored from version N` commit in one atomic batch, so a forbidden, invalid or
+ * conflicting restore leaves both the document and its history unchanged.
  *
- * The version snapshot itself is always fetched unfiltered (`overrideAccess: true` on the internal
- * `getVersion` call) — restore's authorization gate is `update()`'s own update-access check on the
- * *current* document, exactly like calling `update()` directly would behave; there is no separate
- * "can this caller read this document's history" gate for restore (see spec 058 §2 for the reasoning).
- * A forbidden or invalid restore throws before `update()` ever reaches the adapter write, so both the
- * current document and its history are left unchanged.
+ * System metadata (`id`, `created_at`, `updated_at`, `_storageKey`) is never restored. A full (spec 062)
+ * snapshot sets every currently declared field, so a snapshot that predates a now-required field fails
+ * current validation instead of producing an invalid document.
  */
 export async function restoreVersion(ctx, args) {
     const collection = getCollectionOrThrow(ctx, args.collection);
+    // A restore is an update; refuse it before reading the snapshot so the answer never depends on it.
+    assertNotAuthManaged(ctx, args.collection);
     if (!versionsEnabled(collection)) {
         throw new Error(`Collection '${args.collection}' does not have versions enabled`);
     }
-    const version = await getVersion(ctx, {
+    const restorable = await readVersionForRestore(ctx, collection, args.versionId);
+    return updateDocument(ctx, {
         collection: args.collection,
-        versionId: args.versionId,
-        overrideAccess: true
-    });
-    return update(ctx, {
-        collection: args.collection,
-        id: version.documentId,
-        data: version.data,
+        id: restorable.version.documentId,
+        data: {},
         ...(args.user !== undefined && { user: args.user }),
         ...(args.overrideAccess !== undefined && { overrideAccess: args.overrideAccess }),
-        versionLabel: `Restored from version ${version.versionNumber}`
-    });
+        versionLabel: `Restored from version ${restorable.version.versionNumber}`
+    }, restorable);
 }
-const MEDIA_URL_PREFIX = '/api/media/';
 /**
- * Resolves the storage key a stored upload's underlying object lives under: the `_storageKey` every
- * upload-created document carries, or (for an older/manually-created record without one) a fallback
- * parsed from its `url`, matching the default `/api/media/<collection>/<key>` shape `handleFile` and
- * every `StorageAdapter`'s default `getPublicUrl` use.
+ * The storage object a deleted upload document owns: only the `_storageKey` Forge's own upload
+ * pipeline recorded (spec 063 §6). There is deliberately no fallback derived from `url` — that is a
+ * declared, caller-writable content field, and deleting whatever it points at let any caller with
+ * create/update + delete access destroy another document's object.
  */
-function resolveStorageKey(collectionSlug, doc) {
+function ownedStorageKey(doc) {
     const storageKey = doc._storageKey;
-    if (typeof storageKey === 'string' && storageKey.length > 0)
-        return storageKey;
-    const url = doc.url;
-    if (typeof url !== 'string')
-        return null;
-    const prefix = `${MEDIA_URL_PREFIX}${collectionSlug}/`;
-    const idx = url.indexOf(prefix);
-    return idx === -1 ? null : url.slice(idx + MEDIA_URL_PREFIX.length);
+    return typeof storageKey === 'string' && storageKey.length > 0 ? storageKey : null;
 }
-export async function deleteDocument(ctx, args) {
-    return deleteDocumentInternal(ctx, args, new Set());
+/**
+ * Compare-and-set against the document a relation delete planned with (spec 064 §5): it is only
+ * written if nobody changed it since. A row without `updated_at` (written outside the pipeline) can only
+ * be guarded by existence. Millisecond precision — see the spec's concurrency notes.
+ */
+function unchangedSince(doc) {
+    return typeof doc.updated_at === 'string'
+        ? { targetMatches: { updated_at: doc.updated_at } }
+        : {};
+}
+function warnNoStorageKey(collection, doc) {
+    getLogger().warn?.(`Upload document '${collection.slug}/${String(doc.id)}' has no Forge-recorded storage key; no ` +
+        `storage object will be deleted (spec 063 §6)`);
 }
 /**
- * The real implementation behind {@link deleteDocument}, plus every cascade-triggered dependent
- * delete (spec 058 §5) — cascade's `RelationMutator.deleteDocument` calls straight back into this
- * function with the same `visited` set, so a multi-level cascade chain runs the full pipeline (access,
- * hooks, relation integrity) at every level. Cycle/diamond protection lives entirely on the *caller*
- * side (`handleCascadeDelete`/`handleSetNullOnDelete` check `visited` before ever invoking the
- * mutator — see that module) — this function marks its own key visited (below) precisely so those
- * caller-side checks can see it, but does not re-check its own key at entry: by the time this function
- * is reached through the mutator, the caller has already decided this key needs processing exactly
- * once, and re-checking here would treat "the caller just claimed this key" as "already done" and skip
- * the actual deletion — see this spec's implementation notes for the regression this caused.
+ * Deletes a document together with its whole relation graph (spec 064 §5) — plan, prepare, **one**
+ * `atomicWrite`, finalize:
+ *
+ * 1. **Plan** (reads only): root `beforeOperation`, read, access; then {@link planRelationDelete} walks
+ *    every cascade/set-null/restrict reference to its fixpoint, judges restrict and required set-null
+ *    against the final state, and refuses a plan that cannot fit in one batch — before any `before*`
+ *    hook of the graph and before any write.
+ * 2. **Prepare** (hooks, validation; no writes): root `beforeDelete`; each cascaded document's
+ *    `beforeOperation` + `beforeDelete`; each set-null document through the same {@link prepareUpdate}
+ *    `update()` uses. Dependents run with `overrideAccess: true` — a consequence of an authorized delete,
+ *    like a database's own `ON DELETE CASCADE` (spec 058 §5) — but never skip validation or hooks.
+ * 3. **Commit**: set-null patches (versioned: spec 062's update + snapshot), cascaded deletes guarded by
+ *    the `updated_at` they were planned with, the root delete, and finally one "no reference remains"
+ *    `assertCount` per referring field — all in one batch, so a late failure or a reference created
+ *    concurrently leaves every row unchanged.
+ * 4. **Finalize** (after commit): storage cleanup for deleted upload documents, then after-hooks —
+ *    dependents first, root last.
+ *
+ * Before-hooks are not transactional: a side effect they performed outside the database survives a
+ * rollback of the batch (roadmap D01).
  */
-async function deleteDocumentInternal(ctx, args, visited) {
-    const key = `${args.collection}:${args.id}`;
+export async function deleteDocument(ctx, args) {
     const collection = getCollectionOrThrow(ctx, args.collection);
+    assertNotAuthManaged(ctx, args.collection);
     const user = args.user ?? null;
     const overrideAccess = args.overrideAccess !== false;
     await runBeforeOperationHooks(collection, { operation: 'delete', user, overrideAccess });
@@ -456,49 +887,213 @@ async function deleteDocumentInternal(ctx, args, visited) {
     if (decision.where && !documentMatches(existing, decision.where)) {
         throw new AccessDeniedError();
     }
+    // 1. Plan — reads only.
+    const plan = await planRelationDelete(ctx, { collection, doc: existing });
+    const dependents = plan.deletes.slice(1);
+    // 2. Prepare — hooks and validation, root first; nothing is written yet.
     await runRejectableStage(() => runBeforeDeleteHooks(collection, { user, overrideAccess, id: args.id, doc: existing }), 'beforeDelete hook');
-    visited.add(key);
-    // Check relation integrity constraints (restrict, and required-field-on-set-null) before any
-    // mutation happens.
-    await checkDeleteRestrictions(ctx, collection, args.id);
-    // Handle cascade and set-null before deleting — routed through this module's own
-    // `deleteDocument`/`update` via a `RelationMutator`, so dependent mutations get the full pipeline
-    // (access, field-write checks, validation, hooks, version snapshots) instead of a raw adapter write.
-    // Both run with `overrideAccess: true`: a cascade/set-null is a consequence of an already-authorized
-    // delete, the same way a database's own `ON DELETE CASCADE` doesn't re-run application ACL per
-    // cascaded row — a deliberate, documented choice, not an oversight (spec 058 §5).
-    const mutator = {
-        deleteDocument: (a) => deleteDocumentInternal(ctx, { ...a, overrideAccess: true }, visited),
-        update: (a) => update(ctx, { ...a, overrideAccess: true })
-    };
-    const integrityOptions = { mutator, visited, ...(user !== null && { user }) };
-    await handleCascadeDelete(ctx, collection, args.id, integrityOptions);
-    await handleSetNullOnDelete(ctx, collection, args.id, integrityOptions);
-    // The database delete must succeed — and only then does the underlying storage object get
-    // removed. Deleting the object first (or on a rejected/failed database delete) would orphan the
-    // document from its file; deleting it only after confirms the document is really gone.
-    await ctx.adapters.database.delete(args.collection, args.id);
-    if (collection.upload === true) {
-        const storageKey = resolveStorageKey(args.collection, existing);
-        if (storageKey) {
-            try {
-                await ctx.adapters.storage.delete(storageKey);
-            }
-            catch (cleanupErr) {
-                // The document is already gone; failing the whole operation over cleanup would be worse
-                // than a best-effort delete that gets logged and left for manual follow-up.
-                getLogger().error(`Failed to clean up storage object '${storageKey}' after document deletion`, cleanupErr);
-            }
-        }
+    for (const dependent of dependents) {
+        await prepareDependentDelete(dependent, user);
+    }
+    const updates = [];
+    // A set-null dependent's hooks may write other relation values; those are checked like any update's.
+    const targetGuards = [];
+    for (const planned of plan.setNulls) {
+        const prepared = await prepareSetNull(ctx, planned, user);
+        if (!prepared)
+            continue;
+        updates.push(prepared);
+        targetGuards.push(...(await relationTargetGuards(ctx, prepared.collection, prepared.data, prepared.existing)));
+    }
+    // Each deleted upload document's object gets a durable deletion intent in the same batch (spec 067).
+    const storageCleanups = plan.deletes.flatMap(({ collection: target, doc }) => {
+        const key = target.upload === true ? ownedStorageKey(doc) : null;
+        if (target.upload === true && key === null)
+            warnNoStorageKey(target, doc);
+        return key === null ? [] : [{ key, operation: deletionIntent(target.slug, key) }];
+    });
+    // 3. Commit — one batch, or the plain single delete when nothing else is involved.
+    let updatedRecords = [];
+    let intentIds = [];
+    if (dependents.length === 0 &&
+        updates.length === 0 &&
+        plan.assertions.length === 0 &&
+        targetGuards.length === 0 &&
+        storageCleanups.length === 0) {
+        await deleteRoot(ctx, collection, args.id, decision.where);
+    }
+    else {
+        ({ updatedRecords, intentIds } = await commitRelationDelete(ctx, { collection, id: args.id }, dependents, updates, [...targetGuards, ...plan.assertions], storageCleanups.map((cleanup) => cleanup.operation), decision.where));
+    }
+    // 4. Finalize — storage first (so a slow or failing hook cannot skip it), then after-hooks,
+    // dependents first and the root last, as before spec 064. A failed object delete keeps its intent.
+    for (const [index, { key }] of storageCleanups.entries()) {
+        const intentId = intentIds[index];
+        if (intentId !== undefined)
+            await finishDeletion(ctx, intentId, key);
+    }
+    for (const { collection: target, doc } of [...dependents].reverse()) {
+        const hookArgs = { user, overrideAccess: true, id: doc.id, doc };
+        await runAfterDeleteHooks(target, hookArgs);
+        await runAfterOperationHooks(target, {
+            operation: 'delete',
+            user,
+            overrideAccess: true,
+            result: doc
+        });
+    }
+    for (const [index, prepared] of updates.entries()) {
+        await finalizeUpdate(ctx, prepared, updatedRecords[index] ?? prepared.existing);
     }
     await runAfterDeleteHooks(collection, { user, overrideAccess, id: args.id, doc: existing });
+    // A trusted delete keeps returning the stored row; an access-checked one returns only what the caller
+    // may read of it (spec 068) — before, it returned the raw row, read-denied fields included.
+    const result = args.overrideAccess === false ? await writeResult(ctx, collection, existing, args) : existing;
     await runAfterOperationHooks(collection, {
         operation: 'delete',
         user,
         overrideAccess,
-        result: existing
+        result
+    });
+    return result;
+}
+/**
+ * The plain single-document delete. With a query-returning delete rule the row must still match it at
+ * the delete (spec 068): a row gone meanwhile is a `404`, one moved out of the caller's scope a `409`.
+ */
+async function deleteRoot(ctx, collection, id, accessWhere) {
+    if (accessWhere === undefined) {
+        await ctx.adapters.database.delete(collection.slug, id);
+        return;
+    }
+    const result = await ctx.adapters.database.deleteIf(collection.slug, id, {
+        targetMatches: accessWhere
     });
-    return existing;
+    if (result.applied)
+        return;
+    if (!(await ctx.adapters.database.findById(collection.slug, id)))
+        throw notFound(collection.slug, id);
+    throw new ConcurrentModificationError(collection.slug, id, `Document '${id}' in '${collection.slug}' was changed by another request so that it no longer ` +
+        `matches the caller's delete access; nothing was deleted. Reload it and try again.`);
+}
+/** A cascaded document's before-phase: the same hooks its own delete runs (trusted, spec 058 §5). */
+async function prepareDependentDelete(planned, user) {
+    const { collection, doc } = planned;
+    await runBeforeOperationHooks(collection, { operation: 'delete', user, overrideAccess: true });
+    await runRejectableStage(() => runBeforeDeleteHooks(collection, {
+        user,
+        overrideAccess: true,
+        id: doc.id,
+        doc
+    }), 'beforeDelete hook');
+}
+/**
+ * A set-null dependent through the normal update preparation, with the patch computed from the document
+ * as read there (spec 062's read order for a versioned dependent). `null` when there is nothing left to
+ * clear — the document no longer references the deleted ids, or no longer exists; the batch's final
+ * assertions still prove no reference survives.
+ */
+async function prepareSetNull(ctx, planned, user) {
+    try {
+        return await prepareUpdate(ctx, {
+            collection: planned.collection.slug,
+            id: planned.id,
+            data: {},
+            overrideAccess: true,
+            ...(user !== null && { user })
+        }, { patch: (doc) => setNullPatch(planned, doc) });
+    }
+    catch (err) {
+        if (err instanceof NotFoundError)
+            return null;
+        throw err;
+    }
+}
+/**
+ * The single batch of a relation delete. Order: set-null patches, cascaded deletes, the root delete,
+ * then the reference assertions — which therefore see the final state, including this batch's own
+ * writes. Any failed condition (a dependent changed since it was planned, a reference created
+ * concurrently, a dependent's snapshot losing its version race) rolls the whole batch back and is a
+ * `409` about the root; nothing was written. Returns the committed row of each set-null update, in order.
+ */
+async function commitRelationDelete(ctx, root, dependents, updates, assertions, intents = [], rootWhere) {
+    const operations = [];
+    const updateAt = [];
+    for (const prepared of updates) {
+        updateAt.push(operations.length);
+        if (prepared.versioned) {
+            atomicDatabase(ctx, prepared.collection);
+            operations.push(...versionedUpdateOperations(prepared));
+        }
+        else {
+            operations.push({
+                type: 'updateIf',
+                collection: prepared.collection.slug,
+                id: prepared.id,
+                data: prepared.data,
+                condition: unchangedSince(prepared.existing),
+                requireApplied: true
+            });
+        }
+    }
+    for (const { collection, doc } of dependents) {
+        operations.push({
+            type: 'deleteIf',
+            collection: collection.slug,
+            id: doc.id,
+            condition: unchangedSince(doc),
+            requireApplied: true
+        });
+    }
+    // The caller's delete-access query must still hold when the batch commits (spec 068).
+    operations.push(rootWhere === undefined
+        ? { type: 'delete', collection: root.collection.slug, id: root.id }
+        : {
+            type: 'deleteIf',
+            collection: root.collection.slug,
+            id: root.id,
+            condition: { targetMatches: rootWhere },
+            requireApplied: true
+        });
+    const intentsAt = operations.length;
+    operations.push(...intents);
+    operations.push(...assertions);
+    // Hook-written relation values of set-null dependents can add target checks after planning counted
+    // the batch; still refuse rather than chunk (spec 064 §5). Before-hooks have run by now; nothing is written.
+    if (operations.length > ATOMIC_WRITE_MAX_OPERATIONS) {
+        throw new InvalidInputError(`Cannot delete document '${root.id}' from '${root.collection.slug}': its dependents' hooks added ` +
+            `relation checks that take it past ${ATOMIC_WRITE_MAX_OPERATIONS} database operations, the most ` +
+            `ForgeCMS commits atomically in one operation. Nothing was changed.`);
+    }
+    let results;
+    try {
+        results = await ctx.adapters.database.atomicWrite(operations);
+    }
+    catch (err) {
+        const versionRace = updates.some((prepared) => prepared.versioned && isVersionIdentityConflict(err, prepared.collection));
+        if (versionRace || isAtomicWriteConditionError(err)) {
+            throw new ConcurrentModificationError(root.collection.slug, root.id, `Deleting document '${root.id}' from '${root.collection.slug}' conflicted with a concurrent ` +
+                `change to it or to a document that references it; nothing was deleted or changed. Reload and ` +
+                `try again.`);
+        }
+        if (isDbUniqueConstraintError(err))
+            throw new UniqueConstraintError(err.collection, err.fields);
+        throw err;
+    }
+    const updatedRecords = updateAt.map((at) => {
+        const result = results[at];
+        if (result && (result.type === 'update' || (result.type === 'updateIf' && result.applied))) {
+            return result.record;
+        }
+        throw new Error('atomicWrite returned no record for a set-null update');
+    });
+    const intentIds = intents.map((_, offset) => {
+        const result = results[intentsAt + offset];
+        if (result?.type !== 'create')
+            throw new Error('atomicWrite returned no storage intent');
+        return result.record.id;
+    });
+    return { updatedRecords, intentIds };
 }
 /**
  * A non-persistent simulation of a permitted create/update — spec 058 §3. Before this fix, preview
@@ -548,9 +1143,16 @@ export async function preview(ctx, args) {
         if (draftStatus && !documentMatches(existing, draftStatus)) {
             throw notFound(args.collection, args.id);
         }
+        // Preview returns the stored document merged with the changes, so the caller must also be able to
+        // *read* it, exactly as `findByID` would allow (spec 068 review): update access alone is not a read.
+        if (args.overrideAccess === false && !(await canRead(collection, existing, user))) {
+            throw notFound(args.collection, args.id);
+        }
+        // Preview models a permitted update, so it takes the same content input (spec 063 §7).
+        const input = screenUpdateInput(args.data, existing);
         if (args.overrideAccess === false) {
             try {
-                await assertWritableFields(args.data, collection, user, 'update');
+                await assertWritableFields(input, collection, user, 'update');
             }
             catch (err) {
                 if (err instanceof FieldAccessError)
@@ -558,7 +1160,7 @@ export async function preview(ctx, args) {
                 throw err;
             }
         }
-        previewData = { ...existing, ...args.data };
+        previewData = { ...existing, ...input };
     }
     else {
         await checkAccess(collection, 'create', {
@@ -566,9 +1168,10 @@ export async function preview(ctx, args) {
             ...(args.overrideAccess !== undefined && { overrideAccess: args.overrideAccess }),
             data: args.data
         });
+        const { content, id } = screenCreateInput(args.data, args.overrideAccess !== false);
         if (args.overrideAccess === false) {
             try {
-                await assertWritableFields(args.data, collection, user, 'create');
+                await assertWritableFields(content, collection, user, 'create');
             }
             catch (err) {
                 if (err instanceof FieldAccessError)
@@ -576,7 +1179,7 @@ export async function preview(ctx, args) {
                 throw err;
             }
         }
-        previewData = args.data;
+        previewData = id !== undefined ? { ...content, id } : content;
     }
     previewData = applyAutoSlugs(collection, applyFieldDefaults(collection, previewData), existing ?? undefined);
     if (args.depth && args.depth > 0) {