@kubun/mutation 0.16.0 → 0.17.1

package/lib/apply.js

@@ -4,7 +4,8 @@ import { isValidAccessRule, RESERVED_DOCUMENT_FIELDS } from '@kubun/protocol';
 import { fromB64 } from '@sozai/codec';
 import { applyPatches } from '@sozai/patch';
 import { asType, createValidator } from '@sozai/schema';
-import { DocumentIDMismatchError, HLCDriftError, MutationSchemaValidationError, OwnerChangeError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
+import { DocumentIDMismatchError, HLCDriftError, IncompleteProviderGroupError, InvalidFetchTokenError, MergePolicyRemoveRequiresTombstoneError, MissingFetchTokenError, MutationSchemaValidationError, OwnerChangeError, ProviderGroupChangeRejectedError, TombstoneRequiresMergePolicyError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
+import { DELETED_STATE_DIGEST, stateDigest } from './state-digest.js';
 /**
  * Reserved `field_hlcs` key holding the greatest delete HLC observed for the
  * document (the tombstone timestamp `t`).
@@ -13,6 +14,20 @@ import { DocumentIDMismatchError, HLCDriftError, MutationSchemaValidationError,
  * Reserved `field_hlcs` key holding the greatest set HLC observed for the
  * document (the set timestamp `s`).
  */ const SET_KEY = '$set';
+/**
+ * Reserved key holding a merge-policy model's winning-live fetch-order
+ * register for its provider group: `{ hlc, digest }`, the greatest
+ * `sourceFetchHLC` observed for a live candidate, paired with that
+ * candidate's state digest. The bare `hlc` also lands in `field_hlcs` under
+ * this same key (mirroring `SET_KEY`) for the total-order comparison;
+ * `field_values` carries the full cell so `winnerStateDigestOf` can read the
+ * digest without a second store round trip.
+ */ export const SET_FETCH_KEY = '$setFetch';
+/**
+ * Reserved key holding a merge-policy model's winning-delete fetch-order
+ * register: `{ hlc }`, the greatest deleting `sourceFetchHLC` observed. Same
+ * `field_hlcs`/`field_values` split as `SET_FETCH_KEY`.
+ */ export const DELETE_FETCH_KEY = '/fetch';
 export function getDocumentValidator(ctx, id) {
     if (ctx.validators[id] == null) {
         ctx.validators[id] = ctx.store.getDocumentModel(id).then((model)=>createValidator({
@@ -33,14 +48,22 @@ export function getDocumentValidator(ctx, id) {
  * other. The past direction is deliberately unbounded — an offline-first write
  * lands whenever it lands.
  */ export const DEFAULT_MAX_DRIFT_MS = 3_600_000;
-function validateHLCDrift(hlcString, maxDriftMS) {
-    const ts = HLC.parse(hlcString);
-    const now = Date.now();
-    const drift = ts.wallTime - now;
+function assertTokenDrift(token, maxDriftMS) {
+    const ts = HLC.tryParse(token);
+    if (ts == null) {
+        throw new InvalidFetchTokenError(token);
+    }
+    const drift = ts.wallTime - Date.now();
     if (drift > maxDriftMS) {
         throw new HLCDriftError(drift, maxDriftMS);
     }
 }
+function validateHLCDrift(hlcString, maxDriftMS) {
+    assertTokenDrift(hlcString, maxDriftMS);
+}
+export function validateFetchTokenDrift(token, maxDriftMS) {
+    assertTokenDrift(token, maxDriftMS);
+}
 export function getTopLevelField(path) {
     const secondSlash = path.indexOf('/', 1);
     return secondSlash === -1 ? path : path.slice(0, secondSlash);
@@ -139,6 +162,160 @@ const ACCESS_PERMISSIONS_FIELD = 'accessPermissions';
     }
     return data;
 }
+/**
+ * A model's provider merge policy, or `null` for an ordinary model. Read
+ * straight from the store on every call (no cache) since it gates which
+ * branch a SET/tombstone apply takes. `requiredGroupFields` is the subset of
+ * `group` the model schema's own `required` array names — the fields a
+ * complete-group SET may never omit (an omitted OPTIONAL group field is
+ * legitimate: it clears that field's stored value on a winning SET instead).
+ */ export async function resolveModelPolicy(ctx, modelID) {
+    const model = await ctx.store.getDocumentModel(modelID);
+    if (model.providerMergePolicy == null) {
+        return null;
+    }
+    const schemaRequired = new Set(model.schema.required);
+    const requiredGroupFields = new Set(model.providerMergePolicy.group.filter((field)=>schemaRequired.has(field)));
+    return {
+        group: model.providerMergePolicy.group,
+        requiredGroupFields
+    };
+}
+/**
+ * `assemble`'s merge-policy variant: liveness keys on the fetch-order
+ * registers — `(setFetchHLC, live)` vs `(deleteFetchHLC, deleted)` — instead
+ * of the plain `$set`/`/` HLC registers, so a document's visible state
+ * follows the total order over provider projections rather than mutation
+ * arrival order. A tied token fails safe to deleted, mirroring the same
+ * strict-greater rule `assemble` already applies to `$set`/`/`.
+ */ function assembleMergePolicy(fieldValues, fieldHLCs) {
+    const s = fieldHLCs[SET_FETCH_KEY];
+    const t = fieldHLCs[DELETE_FETCH_KEY];
+    const alive = s != null && (t == null || s > t);
+    if (!alive) {
+        return null;
+    }
+    const data = {};
+    for (const [path, value] of Object.entries(fieldValues)){
+        if (path === DELETE_KEY || path === SET_KEY || path === DELETE_FETCH_KEY || path === SET_FETCH_KEY) {
+            continue;
+        }
+        data[path.slice(1)] = value;
+    }
+    return data;
+}
+/**
+ * Pure merge-policy liveness read: given a document's `field_values` cell map
+ * alone, determines whether the fetch-order registers keep a live winner or a
+ * delete winner under the total order (a tied token fails safe to deleted, per
+ * `assembleMergePolicy`). Returns `null` when neither register is present (an
+ * ordinary model, or a merge-policy document never yet touched). No store
+ * access: the `hlc` embedded in each register cell is enough to compare.
+ */ function resolveFetchFrontier(fieldValues) {
+    const setCell = fieldValues[SET_FETCH_KEY];
+    const deleteCell = fieldValues[DELETE_FETCH_KEY];
+    const s = setCell?.hlc;
+    const t = deleteCell?.hlc;
+    if (s == null && t == null) {
+        return null;
+    }
+    const alive = s != null && (t == null || s > t);
+    return alive ? {
+        hlc: s,
+        digest: setCell.digest,
+        alive: true
+    } : {
+        hlc: t,
+        digest: DELETED_STATE_DIGEST,
+        alive: false
+    };
+}
+/**
+ * Pure merge-policy liveness read: the winning side's state digest alone —
+ * the live `$setFetch` digest, or `DELETED_STATE_DIGEST` when the delete side
+ * wins, or `null` when neither register is present. This is what lets
+ * `@kubun/store-graph`'s `readWinnerStateDigest` reuse the comparison after
+ * its own single-column read instead of also threading `field_hlcs`.
+ */ export function winnerStateDigestOf(fieldValues) {
+    return resolveFetchFrontier(fieldValues)?.digest ?? null;
+}
+/**
+ * Fetch-token-first diagnostic classification of an incoming live SET
+ * candidate against the stored frontier (`F_hlc` = the frontier's own token,
+ * equal to `max(setFetchHLC, deleteFetchHLC)` by construction — whichever
+ * register wins carries the greater of the two). Discriminates on the
+ * candidate's token alone; state/digest is inspected only at an exact token
+ * tie, so this is exclusive and total: a below-frontier candidate is never
+ * simultaneously `dominated` (hash irrelevant beneath the frontier) and
+ * `nonconforming` (hash only inspected at an exact tie).
+ *
+ * This is the diagnostic label only — separate from which side the register
+ * actually keeps (`setWinsFrontier` below). At an exact tie with unequal
+ * digests the register still picks the lexically greater one deterministically,
+ * even though the label stays `nonconforming` for both directions: the label
+ * flags the disagreement, it does not report which side won it.
+ */ export function classifySetOutcome(token, candidateDigest, frontier) {
+    if (frontier == null || token > frontier.hlc) {
+        return 'applied';
+    }
+    if (token < frontier.hlc) {
+        return 'dominated';
+    }
+    return candidateDigest === frontier.digest ? 'applied' : 'nonconforming';
+}
+/**
+ * Full total-key winner decision for a live SET candidate against the stored
+ * frontier — `(sourceFetchHLC, stateRank, contentHash)`, live ranked below
+ * deleted. A strictly greater token always wins; a lower token never does. At
+ * an exact tie, a deleted frontier keeps the register unconditionally (rank
+ * beats a live candidate regardless of digest); a live frontier breaks the
+ * tie on the lexically greater state digest, so two replicas applying an
+ * equal-token pair of different-content live candidates in opposite arrival
+ * orders both converge on the same (greater-digest) winner rather than
+ * whichever arrived first.
+ */ function setWinsFrontier(token, candidateDigest, frontier) {
+    if (frontier == null || token > frontier.hlc) {
+        return true;
+    }
+    if (token < frontier.hlc) {
+        return false;
+    }
+    return frontier.alive && candidateDigest > frontier.digest;
+}
+/**
+ * Delete-side winner decision for a tombstone candidate against the stored
+ * frontier — the `/fetch` analog of `setWinsFrontier`. A strictly greater
+ * token always wins, a lower token never does, and an exact tie is the
+ * fail-safe "delete wins" rule, unconditionally: unlike the set side, every
+ * delete reduces to the same state (`DELETED_STATE_DIGEST`), so there is no
+ * content to distinguish two equal-token deletes and no digest tiebreak is
+ * needed on this side.
+ */ function deleteWinsFrontier(token, frontier) {
+    if (frontier == null || token > frontier.hlc) {
+        return true;
+    }
+    if (token < frontier.hlc) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Fetch-token-first diagnostic classification of an incoming tombstone
+ * candidate against the stored frontier, mirroring `classifySetOutcome`. At
+ * an exact token tie the register always keeps the delete (fail-safe), so a
+ * tie against an already-deleted frontier is `applied` (idempotent
+ * re-tombstoning) while a tie against a live frontier is `nonconforming` —
+ * the label flags the disagreement even though the register still resolves
+ * it deterministically to the delete.
+ */ export function classifyTombstoneOutcome(token, frontier) {
+    if (frontier == null || token > frontier.hlc) {
+        return 'applied';
+    }
+    if (token < frontier.hlc) {
+        return 'dominated';
+    }
+    return frontier.alive ? 'nonconforming' : 'applied';
+}
 export async function applyChangeMutation(ctx, mutation) {
     const id = DocumentID.fromString(mutation.sub);
     const docID = id.toString();
@@ -158,9 +335,10 @@ export async function applyChangeMutation(ctx, mutation) {
         validateHLCDrift(mutation.hlc, ctx.maxDriftMS);
     }
     const modelID = id.model.toString();
-    const [storedHLCs, storedValues] = await Promise.all([
+    const [storedHLCs, storedValues, policy] = await Promise.all([
         ctx.store.getFieldHLCs(docID),
-        ctx.store.getFieldValues(docID)
+        ctx.store.getFieldValues(docID),
+        resolveModelPolicy(ctx, modelID)
     ]);
     const fieldHLCs = {
         ...storedHLCs ?? {}
@@ -173,8 +351,20 @@ export async function applyChangeMutation(ctx, mutation) {
     // A delete is a single root replace to null. It only advances the tombstone
     // timestamp; it never erases retained field values or field timestamps, so a
     // later set above the tombstone can revive the exact prior field set.
-    const isDelete = mutation.patch.length === 1 && mutation.patch[0].op === 'replace' && mutation.patch[0].path === DELETE_KEY && mutation.patch[0].value === null;
+    const firstPatch = mutation.patch[0];
+    const isDelete = mutation.patch.length === 1 && firstPatch != null && firstPatch.op === 'replace' && firstPatch.path === DELETE_KEY && firstPatch.value === null;
     if (isDelete) {
+        // A merge-policy document's liveness lives in the fetch-order registers
+        // (`$setFetch`/`/fetch`), which this generic delete CHANGE never advances:
+        // it would null the visible data while leaving the live register standing,
+        // so a later provider SET or any outside-group CHANGE would resurrect the
+        // document with stale group data. Reject it and force the deletion through
+        // the fetch-token tombstone path (which advances `/fetch`). A conforming
+        // tombstone reaches `applyTombstoneMutation`, not this delete-CHANGE path,
+        // so it is unaffected.
+        if (policy != null) {
+            throw new MergePolicyRemoveRequiresTombstoneError(docID);
+        }
         fieldHLCs[DELETE_KEY] = t == null || mutation.hlc > t ? mutation.hlc : t;
         const assembled = assemble(fieldValues, fieldHLCs);
         // The gate guards state-changing applies. A delete can only move a live
@@ -188,15 +378,19 @@ export async function applyChangeMutation(ctx, mutation) {
             };
             const allowed = await ctx.postStateGate(postState);
             if (!allowed) {
-                return null;
+                return {
+                    document: null
+                };
             }
         }
         await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
-        return await ctx.store.saveDocument({
-            id,
-            existing: doc,
-            data: assembled
-        });
+        return {
+            document: await ctx.store.saveDocument({
+                id,
+                existing: doc,
+                data: assembled
+            })
+        };
     }
     const validator = await getDocumentValidator(ctx, modelID);
     // Group patches by top-level field for LWW comparison.
@@ -212,16 +406,41 @@ export async function applyChangeMutation(ctx, mutation) {
             ]);
         }
     }
+    // Single-authority gate: a merge-policy model's provider group is governed
+    // atomically by the fetch-order registers, so it must never receive a local
+    // HLC-ordered CHANGE (mixing the two orderings on the same fields would be
+    // noncommutative). A field outside the group is unaffected.
+    const groupFieldSet = policy != null ? new Set(policy.group) : null;
+    if (groupFieldSet != null) {
+        for (const path of patchesByField.keys()){
+            const field = path.slice(1);
+            if (groupFieldSet.has(field)) {
+                throw new ProviderGroupChangeRejectedError(docID, field);
+            }
+        }
+    }
     // A change field write wins when its HLC beats the field's current HLC and
     // also strictly beats the set timestamp. Losing the set comparison means a
     // newer (or concurrent) set already authored the field set, so a refining
     // change cannot override it.
+    //
+    // Two kinds of field drop the `beatsSet` term and order by their own
+    // per-field HLC alone: the reserved `accessPermissions` field (engine
+    // metadata orthogonal to provider content, on every model) and, on a
+    // merge-policy model, any field outside its provider group (a
+    // local-annotation field — group fields never reach here, rejected above).
+    // Coupling either to the provider group's `$set`/fetch-order frontier would
+    // make acceptance depend on that frontier's arrival order relative to the
+    // change, which is noncommutative. An ordinary model's non-reserved fields
+    // keep the coupled gate unchanged.
     const winningFields = [];
     const winningPatches = [];
     for (const [path, patches] of patchesByField){
+        const field = path.slice(1);
         const currentHLC = fieldHLCs[path];
         const beatsField = currentHLC == null || mutation.hlc > currentHLC;
-        const beatsSet = s == null || mutation.hlc > s;
+        const decoupled = field === ACCESS_PERMISSIONS_FIELD || groupFieldSet != null;
+        const beatsSet = decoupled || s == null || mutation.hlc > s;
         if (beatsField && beatsSet) {
             winningFields.push(path);
             winningPatches.push(...patches);
@@ -229,14 +448,16 @@ export async function applyChangeMutation(ctx, mutation) {
     }
     // No winning field means no state change; the gate is not invoked.
     if (winningFields.length === 0) {
-        return doc;
+        return {
+            document: doc
+        };
     }
     // Reconstruct the full prior field set from retained values so the validator
     // always sees a complete object: a set carried a fully validated document and
     // a change only refines fields it already authored.
     const base = {};
     for (const [path, value] of Object.entries(fieldValues)){
-        if (path === DELETE_KEY || path === SET_KEY) {
+        if (path === DELETE_KEY || path === SET_KEY || path === SET_FETCH_KEY || path === DELETE_FETCH_KEY) {
             continue;
         }
         base[path.slice(1)] = value;
@@ -270,7 +491,12 @@ export async function applyChangeMutation(ctx, mutation) {
         fieldValues[path] = validated[field];
         fieldHLCs[path] = mutation.hlc;
     }
-    const assembled = assemble(fieldValues, fieldHLCs);
+    // A merge-policy document's liveness and visible data follow the
+    // fetch-order registers, not `$set`/`/` — mirrors `applySetMutation`'s same
+    // choice. The registers themselves are untouched by this change (the group
+    // never reaches here, rejected above), so this only affects how the
+    // resulting data is assembled and which reserved keys are excluded from it.
+    const assembled = policy == null ? assemble(fieldValues, fieldHLCs) : assembleMergePolicy(fieldValues, fieldHLCs);
     // Synthesize the post-state for gate evaluation BEFORE any write
     // (updateFieldHLCs + saveDocument). The cloned node is dropped on deny —
     // engine state stays identical to pre-apply.
@@ -281,15 +507,19 @@ export async function applyChangeMutation(ctx, mutation) {
         };
         const allowed = await ctx.postStateGate(postState);
         if (!allowed) {
-            return null;
+            return {
+                document: null
+            };
         }
     }
     await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
-    return await ctx.store.saveDocument({
-        id,
-        existing: doc,
-        data: assembled
-    });
+    return {
+        document: await ctx.store.saveDocument({
+            id,
+            existing: doc,
+            data: assembled
+        })
+    };
 }
 export async function applySetMutation(ctx, mutation) {
     const owner = mutation.aud ?? mutation.iss;
@@ -307,12 +537,36 @@ export async function applySetMutation(ctx, mutation) {
     if (ctx.maxDriftMS != null) {
         validateHLCDrift(mutation.hlc, ctx.maxDriftMS);
     }
-    const [doc, validator, storedHLCs, storedValues] = await Promise.all([
+    const [doc, validator, storedHLCs, storedValues, policy] = await Promise.all([
         ctx.store.getDocument(id),
         getDocumentValidator(ctx, modelID),
         ctx.store.getFieldHLCs(docID),
-        ctx.store.getFieldValues(docID)
+        ctx.store.getFieldValues(docID),
+        resolveModelPolicy(ctx, modelID)
     ]);
+    // A merge-policy model is single-authority over its provider group: every
+    // write carries the fetch token that orders it, so an incoming write with
+    // no token is rejected outright rather than classified. (Ordinary models
+    // are unaffected; `sourceFetchHLC` stays optional for them.)
+    let fetchToken = null;
+    if (policy != null) {
+        fetchToken = mutation.sourceFetchHLC ?? null;
+        if (fetchToken == null) {
+            throw new MissingFetchTokenError(docID);
+        }
+        if (ctx.maxDriftMS != null) {
+            validateFetchTokenDrift(fetchToken, ctx.maxDriftMS);
+        }
+        // Complete-group-or-reject: a merge-policy SET is an atomic replacement
+        // of the whole provider group, so every schema-required group field must
+        // be present. An OMITTED optional group field is legitimate — it clears
+        // that field's stored value when this SET wins the frontier, below.
+        for (const field of policy.requiredGroupFields){
+            if (!(field in mutation.data)) {
+                throw new IncompleteProviderGroupError(docID, field);
+            }
+        }
+    }
     // Reserved fields are engine metadata the model schema never declares. Split
     // them out before validating the model-declared remainder, then re-attach so
     // they persist unchanged.
@@ -360,27 +614,112 @@ export async function applySetMutation(ctx, mutation) {
     if (doc != null && doc.owner !== owner) {
         throw new OwnerChangeError(id.toString(), doc.owner, owner);
     }
-    // Per-field LWW: a set field write wins when its HLC beats the field's
-    // current HLC. Winning writes update both the retained value and timestamp.
     let changed = false;
-    for (const [field, value] of Object.entries(data)){
-        const path = `/${field}`;
-        const currentHLC = fieldHLCs[path];
-        if (currentHLC == null || mutation.hlc > currentHLC) {
-            fieldValues[path] = value;
-            fieldHLCs[path] = mutation.hlc;
-            changed = true;
+    let setChanged = false;
+    let mergeFields = null;
+    if (policy == null) {
+        // Per-field LWW: a set field write wins when its HLC beats the field's
+        // current HLC. Winning writes update both the retained value and timestamp.
+        for (const [field, value] of Object.entries(data)){
+            const path = `/${field}`;
+            const currentHLC = fieldHLCs[path];
+            if (currentHLC == null || mutation.hlc > currentHLC) {
+                fieldValues[path] = value;
+                fieldHLCs[path] = mutation.hlc;
+                changed = true;
+            }
+        }
+        // The set timestamp advances to the greatest set HLC observed.
+        const previousSet = s;
+        fieldHLCs[SET_KEY] = s == null || mutation.hlc > s ? mutation.hlc : s;
+        setChanged = fieldHLCs[SET_KEY] !== previousSet;
+    } else {
+        const token = fetchToken;
+        const groupFields = new Set(policy.group);
+        // Local-annotation fields (outside the provider group) keep plain
+        // per-field HLC LWW, exactly like an ordinary model's fields.
+        for (const [field, value] of Object.entries(data)){
+            if (groupFields.has(field)) {
+                continue;
+            }
+            const path = `/${field}`;
+            const currentHLC = fieldHLCs[path];
+            if (currentHLC == null || mutation.hlc > currentHLC) {
+                fieldValues[path] = value;
+                fieldHLCs[path] = mutation.hlc;
+                changed = true;
+            }
+        }
+        // The candidate's complete-group state digest, computed only from the
+        // group fields present in this SET — an omitted optional field is not
+        // part of the candidate's group content.
+        const group = {};
+        for (const field of policy.group){
+            if (field in data) {
+                group[field] = data[field];
+            }
+        }
+        const candidateDigest = stateDigest({
+            state: 'live',
+            group
+        });
+        const frontier = resolveFetchFrontier(fieldValues);
+        const outcome = classifySetOutcome(token, candidateDigest, frontier);
+        // The provider group is governed atomically by the total order over
+        // (fetch token, state rank, content digest): the greatest token wins
+        // outright, regardless of arrival order and regardless of the mutation's
+        // own HLC. `setWinsFrontier` also resolves an exact-token tie — a
+        // deleted frontier keeps the register (rank beats a live candidate), a
+        // live frontier breaks the tie on the lexically greater digest so
+        // replicas applying an equal-token pair of different-content candidates
+        // in either arrival order converge on the same winner.
+        if (setWinsFrontier(token, candidateDigest, frontier)) {
+            // A winning SET is an atomic replacement of the whole group, not a
+            // merge into it: a group field present in stored state but absent
+            // from this SET (necessarily an optional field — a required one would
+            // have already been rejected above) is cleared rather than left stale.
+            for (const field of policy.group){
+                const path = `/${field}`;
+                if (field in data) {
+                    fieldValues[path] = data[field];
+                    fieldHLCs[path] = token;
+                } else {
+                    delete fieldValues[path];
+                    delete fieldHLCs[path];
+                }
+            }
+            fieldValues[SET_FETCH_KEY] = {
+                hlc: token,
+                digest: candidateDigest
+            };
+            fieldHLCs[SET_FETCH_KEY] = token;
+            setChanged = true;
+            mergeFields = {
+                outcome,
+                candidateDigest,
+                winnerDigest: candidateDigest,
+                winnerChanged: frontier?.digest !== candidateDigest
+            };
+        } else {
+            mergeFields = {
+                outcome,
+                candidateDigest,
+                winnerDigest: frontier?.digest ?? candidateDigest,
+                winnerChanged: false
+            };
         }
     }
-    // The set timestamp advances to the greatest set HLC observed.
-    const previousSet = s;
-    fieldHLCs[SET_KEY] = s == null || mutation.hlc > s ? mutation.hlc : s;
-    const setChanged = fieldHLCs[SET_KEY] !== previousSet;
-    const assembled = assemble(fieldValues, fieldHLCs);
+    const assembled = policy == null ? assemble(fieldValues, fieldHLCs) : assembleMergePolicy(fieldValues, fieldHLCs);
+    const toResult = (document)=>mergeFields == null ? {
+            document
+        } : {
+            document,
+            ...mergeFields
+        };
     // Nothing changed: neither a field value nor the liveness-bearing set
     // timestamp moved. The persisted node already reflects this state.
     if (!changed && !setChanged) {
-        return doc ?? null;
+        return toResult(doc ?? null);
     }
     if (doc == null) {
         if (ctx.postStateGate != null) {
@@ -390,7 +729,9 @@ export async function applySetMutation(ctx, mutation) {
             };
             const allowed = await ctx.postStateGate(postState);
             if (!allowed) {
-                return null;
+                return {
+                    document: null
+                };
             }
         }
         const result = await ctx.store.createDocument({
@@ -400,7 +741,7 @@ export async function applySetMutation(ctx, mutation) {
             unique: fromB64(mutation.unq)
         });
         await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
-        return result;
+        return toResult(result);
     }
     // Synthesize the post-state for gate evaluation BEFORE any write
     // (updateFieldHLCs + saveDocument). The cloned node is dropped on deny.
@@ -411,15 +752,167 @@ export async function applySetMutation(ctx, mutation) {
         };
         const allowed = await ctx.postStateGate(postState);
         if (!allowed) {
-            return null;
+            return {
+                document: null
+            };
         }
     }
     await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
-    return await ctx.store.saveDocument({
+    return toResult(await ctx.store.saveDocument({
         id,
         existing: doc,
         data: assembled
-    });
+    }));
+}
+/**
+ * A fetch-token-carrying deletion on a merge-policy document's `/fetch`
+ * liveness register. Unlike `applyChangeMutation`'s delete branch, a
+ * tombstone may arrive before the document exists at all — it carries the
+ * full SET-equivalent creation-and-authorization surface (`aud`/`unq`) so a
+ * first-seen tombstone can establish a `data: null` row exactly as a SET
+ * creates state from `owner`+`unq`. Ordering is governed by the same total
+ * key as the set side (`deleteWinsFrontier`), so sets and deletes commute
+ * regardless of arrival order.
+ *
+ * A tombstone is a merge-policy-only concept — an ordinary model deletes via
+ * the `/`→null CHANGE path, never a tombstone — so a model with no
+ * `providerMergePolicy` rejects outright rather than running the fetch-order
+ * registers against a document whose liveness is governed by plain
+ * `$set`/`/` HLC registers instead.
+ */ export async function applyTombstoneMutation(ctx, mutation) {
+    const owner = mutation.aud;
+    const id = DocumentID.fromString(mutation.sub);
+    const docID = id.toString();
+    const modelID = id.model.toString();
+    // Bind owner↔ID exactly as a SET does: the document ID must hash from the
+    // document's model, the claimed owner, and the unique value.
+    const expected = DocumentID.create(id.model, owner, fromB64(mutation.unq));
+    if (expected.toString() !== mutation.sub) {
+        throw new DocumentIDMismatchError(docID);
+    }
+    if (ctx.maxDriftMS != null) {
+        validateHLCDrift(mutation.hlc, ctx.maxDriftMS);
+    }
+    const [doc, storedHLCs, storedValues, policy] = await Promise.all([
+        ctx.store.getDocument(id),
+        ctx.store.getFieldHLCs(docID),
+        ctx.store.getFieldValues(docID),
+        resolveModelPolicy(ctx, modelID)
+    ]);
+    if (policy == null) {
+        throw new TombstoneRequiresMergePolicyError(docID);
+    }
+    // A merge-policy tombstone is single-authority exactly like a merge-policy
+    // SET: the wire schema and `createTombstoneMutation` both require
+    // `sourceFetchHLC`, so this is a defensive gate against a raw/malformed
+    // mutation reaching classification with no token.
+    if (mutation.sourceFetchHLC == null) {
+        throw new MissingFetchTokenError(docID);
+    }
+    if (ctx.maxDriftMS != null) {
+        validateFetchTokenDrift(mutation.sourceFetchHLC, ctx.maxDriftMS);
+    }
+    const fieldHLCs = {
+        ...storedHLCs ?? {}
+    };
+    const fieldValues = {
+        ...storedValues ?? {}
+    };
+    // Synthesized post-state for a not-yet-persisted (first-seen) document,
+    // reused by the write-access check the same way `applySetMutation` reuses
+    // its own synthesized post-state.
+    const synthesizedPostState = {
+        id: docID,
+        model: modelID,
+        owner,
+        data: null,
+        createdAt: new Date(0),
+        updatedAt: null
+    };
+    // A non-owner writer must present a valid write capability — mirrors the
+    // non-owner CHANGE/SET path. Absent an injected checker, only the owner
+    // may write.
+    if (mutation.iss !== owner) {
+        const target = doc ?? synthesizedPostState;
+        const allowed = ctx.checkWriteAccess != null && await ctx.checkWriteAccess(target, mutation);
+        if (!allowed) {
+            throw new WriteAccessDeniedError(docID);
+        }
+    }
+    if (doc != null && doc.owner !== owner) {
+        throw new OwnerChangeError(docID, doc.owner, owner);
+    }
+    const token = mutation.sourceFetchHLC;
+    const frontier = resolveFetchFrontier(fieldValues);
+    const outcome = classifyTombstoneOutcome(token, frontier);
+    // A tombstone candidate's content is always the deleted state — there is
+    // no group data to hash — so its own digest is the constant deleted marker.
+    const candidateDigest = DELETED_STATE_DIGEST;
+    if (!deleteWinsFrontier(token, frontier)) {
+        // A stale delete is dominated by a fresher candidate already at the
+        // frontier (set or delete): no state change.
+        return {
+            document: doc ?? null,
+            outcome,
+            candidateDigest,
+            winnerDigest: frontier?.digest ?? candidateDigest,
+            winnerChanged: false
+        };
+    }
+    fieldValues[DELETE_FETCH_KEY] = {
+        hlc: token
+    };
+    fieldHLCs[DELETE_FETCH_KEY] = token;
+    // A winning delete always moves the register to the constant deleted
+    // digest, regardless of what the frontier held before.
+    const winnerDigest = candidateDigest;
+    const winnerChanged = frontier?.digest !== winnerDigest;
+    const assembled = assembleMergePolicy(fieldValues, fieldHLCs);
+    if (doc == null) {
+        // First-seen tombstone: establishes a tombstoned row for a document
+        // never previously observed. A never-live -> dead transition is not a
+        // visible state change, so the post-state gate is not invoked (mirrors
+        // the ordinary delete no-op in `applyChangeMutation`).
+        const result = await ctx.store.createDocument({
+            id,
+            owner,
+            data: assembled,
+            unique: fromB64(mutation.unq)
+        });
+        await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
+        return {
+            document: result,
+            outcome,
+            candidateDigest,
+            winnerDigest,
+            winnerChanged
+        };
+    }
+    // The gate guards a genuine live -> dead transition only.
+    if (doc.data != null && assembled == null && ctx.postStateGate != null) {
+        const postState = {
+            ...doc,
+            data: assembled
+        };
+        const allowed = await ctx.postStateGate(postState);
+        if (!allowed) {
+            return {
+                document: null
+            };
+        }
+    }
+    await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
+    return {
+        document: await ctx.store.saveDocument({
+            id,
+            existing: doc,
+            data: assembled
+        }),
+        outcome,
+        candidateDigest,
+        winnerDigest,
+        winnerChanged
+    };
 }
 export async function applyMutation(ctx, mutation) {
     const mutationType = mutation.typ;
@@ -428,6 +921,8 @@ export async function applyMutation(ctx, mutation) {
             return await applyChangeMutation(ctx, mutation);
         case 'set':
             return await applySetMutation(ctx, mutation);
+        case 'tombstone':
+            return await applyTombstoneMutation(ctx, mutation);
         default:
             throw new UnsupportedMutationTypeError(mutationType);
     }