@kubun/mutation 0.17.0 → 0.18.0

package/lib/apply.js

@@ -1,10 +1,11 @@
 import { HLC } from '@kubun/hlc';
-import { DocumentID } from '@kubun/id';
+import { DocumentID, digestJSON } from '@kubun/id';
 import { isValidAccessRule, RESERVED_DOCUMENT_FIELDS } from '@kubun/protocol';
-import { fromB64 } from '@sozai/codec';
+import { canonicalStringify, fromB64, toB64U } 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, InvalidAccessRulePatchError, InvalidDefaultAccessPermissionsError, 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,20 +48,127 @@ 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);
 }
 const RESERVED_FIELD_SET = new Set(RESERVED_DOCUMENT_FIELDS);
 const ACCESS_PERMISSIONS_FIELD = 'accessPermissions';
+const DEFAULT_ACCESS_PERMISSIONS_FIELD = 'defaultAccessPermissions';
+const EFFECTIVE_READ_KEY = '$readRule';
+function defaultSlot(value, mutationHLC, docID) {
+    if (value == null || typeof value !== 'object') throw new InvalidDefaultAccessPermissionsError(docID);
+    const slot = value;
+    if (!isValidAccessRule(slot.rule) || typeof slot.hlc !== 'string' || HLC.tryParse(slot.hlc) == null || slot.hlc > mutationHLC) {
+        throw new InvalidDefaultAccessPermissionsError(docID);
+    }
+    return {
+        rule: slot.rule,
+        hlc: slot.hlc
+    };
+}
+function applyDefaultSlot(value, mutationHLC, docID, values, stamps) {
+    const slot = defaultSlot(value, mutationHLC, docID);
+    const path = `/${DEFAULT_ACCESS_PERMISSIONS_FIELD}`;
+    const current = stamps[path];
+    if (current != null && (slot.hlc < current || slot.hlc === current && (values[path] == null || canonicalStringify(slot) <= canonicalStringify(values[path])))) return false;
+    values[path] = slot;
+    stamps[path] = slot.hlc;
+    return true;
+}
+function applyHandPermissions(value, mutationHLC, values, stamps, touched) {
+    if (value != null && sanitizeAccessPermissions(value) == null) return false;
+    const candidate = value != null && typeof value === 'object' ? value : {};
+    const permissions = {
+        ...values['/accessPermissions']
+    };
+    let changed = false;
+    for (const permission of [
+        'read',
+        'write'
+    ]){
+        if (!touched.has(permission)) continue;
+        const rule = candidate[permission];
+        if (rule != null && !isValidAccessRule(rule)) continue;
+        const path = `/accessPermissions/${permission}`;
+        if (stamps[path] != null && mutationHLC <= stamps[path]) continue;
+        if (rule == null) delete permissions[permission];
+        else permissions[permission] = rule;
+        stamps[path] = mutationHLC;
+        changed = true;
+    }
+    if (changed) {
+        values['/accessPermissions'] = permissions;
+        const stamp = stamps['/accessPermissions'];
+        stamps['/accessPermissions'] = stamp == null || mutationHLC > stamp ? mutationHLC : stamp;
+    }
+    return changed;
+}
+function foldReadRule(values) {
+    const hand = values['/accessPermissions'];
+    const slot = values['/defaultAccessPermissions'];
+    const read = hand?.read ?? slot?.rule;
+    if (read == null) delete values[EFFECTIVE_READ_KEY];
+    else values[EFFECTIVE_READ_KEY] = read;
+}
+/** Assemble visible fields and overlay the retained effective read rule. */ export function assembleDocumentData(values) {
+    const data = {};
+    for (const [path, value] of Object.entries(values)){
+        if (path.startsWith('/') && path !== DELETE_KEY && path !== DELETE_FETCH_KEY) data[path.slice(1)] = value;
+    }
+    const read = values[EFFECTIVE_READ_KEY];
+    if (read != null) data.accessPermissions = {
+        ...data.accessPermissions,
+        read
+    };
+    return data;
+}
+function setNeedsShare(data) {
+    return ACCESS_PERMISSIONS_FIELD in data || DEFAULT_ACCESS_PERMISSIONS_FIELD in data;
+}
+function changeNeedsShare(patch) {
+    return patch.some((item)=>[
+            '/accessPermissions',
+            '/defaultAccessPermissions'
+        ].includes(getTopLevelField(item.path)));
+}
+function validateAccessRulePatches(mutation) {
+    for (const patch of mutation.patch){
+        const field = getTopLevelField(patch.path);
+        const targetsSlot = field === '/accessPermissions' || field === '/defaultAccessPermissions';
+        const allowedPath = [
+            '/accessPermissions',
+            '/accessPermissions/read',
+            '/accessPermissions/write',
+            '/defaultAccessPermissions'
+        ].includes(patch.path);
+        const source = 'from' in patch && patch.from != null ? getTopLevelField(patch.from) : null;
+        if (targetsSlot && (!allowedPath || ![
+            'add',
+            'replace',
+            'set',
+            'remove'
+        ].includes(patch.op)) || source === '/accessPermissions' || source === '/defaultAccessPermissions') throw new InvalidAccessRulePatchError({
+            docID: mutation.sub
+        });
+    }
+}
 /**
  * Salvage a candidate `accessPermissions` value per rule, mirroring the engine
  * parser (`parseDocumentAccessPermissions`): a malformed `read` or `write` rule
@@ -63,7 +185,7 @@ const ACCESS_PERMISSIONS_FIELD = 'accessPermissions';
     const perms = value;
     const readValid = perms.read !== undefined && isValidAccessRule(perms.read);
     const writeValid = perms.write !== undefined && isValidAccessRule(perms.write);
-    if (!readValid && !writeValid) {
+    if (!readValid && !writeValid && Object.keys(perms).length > 0) {
         return null;
     }
     const sanitized = {
@@ -116,6 +238,19 @@ const ACCESS_PERMISSIONS_FIELD = 'accessPermissions';
         droppedReserved
     };
 }
+export function validateSetData(validator, rawData, documentID) {
+    const { model, reserved } = splitReservedFields(rawData);
+    try {
+        return {
+            ...asType(validator, model),
+            ...reserved
+        };
+    } catch (err) {
+        throw new MutationSchemaValidationError(documentID, {
+            cause: err
+        });
+    }
+}
 /**
  * Compute the visible document data from the per-field winning values and the
  * reserved set/delete timestamps. A document is alive when it carries a set
@@ -130,14 +265,168 @@ const ACCESS_PERMISSIONS_FIELD = 'accessPermissions';
     if (!alive) {
         return null;
     }
-    const data = {};
-    for (const [path, value] of Object.entries(fieldValues)){
-        if (path === DELETE_KEY || path === SET_KEY) {
-            continue;
-        }
-        data[path.slice(1)] = value;
+    return assembleDocumentData(fieldValues);
+}
+/**
+ * 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;
     }
-    return data;
+    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;
+    }
+    return assembleDocumentData(fieldValues);
+}
+/**
+ * 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,
+        observed: setCell?.observed
+    } : {
+        hlc: t,
+        digest: DELETED_STATE_DIGEST,
+        alive: false,
+        observed: setCell?.observed
+    };
+}
+function omitObjectNulls(value) {
+    if (Array.isArray(value)) return value.map(omitObjectNulls);
+    if (value === null || typeof value !== 'object') return value;
+    const result = {};
+    for (const [key, item] of Object.entries(value)){
+        if (item !== null && item !== undefined) result[key] = omitObjectNulls(item);
+    }
+    return result;
+}
+export function providerGroupDigest(group) {
+    return toB64U(digestJSON(omitObjectNulls(group)));
+}
+/**
+ * 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);
@@ -153,14 +442,20 @@ export async function applyChangeMutation(ctx, mutation) {
         if (!allowed) {
             throw new WriteAccessDeniedError(docID);
         }
+        if (changeNeedsShare(mutation.patch)) {
+            const shared = ctx.checkShareAccess != null && await ctx.checkShareAccess(doc, mutation);
+            if (!shared) throw new WriteAccessDeniedError(docID);
+        }
     }
     if (ctx.maxDriftMS != null) {
         validateHLCDrift(mutation.hlc, ctx.maxDriftMS);
     }
+    validateAccessRulePatches(mutation);
     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 ?? {}
@@ -176,6 +471,17 @@ export async function applyChangeMutation(ctx, mutation) {
     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
@@ -187,17 +493,24 @@ export async function applyChangeMutation(ctx, mutation) {
                 ...doc,
                 data: assembled
             };
-            const allowed = await ctx.postStateGate(postState);
+            const allowed = await ctx.postStateGate(postState, {
+                previous: doc,
+                mutation
+            });
             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.
@@ -213,31 +526,86 @@ 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);
+            }
+        }
+    }
+    let permissionsChanged = false;
+    const permissionPatches = patchesByField.get('/accessPermissions');
+    if (permissionPatches != null) {
+        const candidate = {
+            accessPermissions: structuredClone(fieldValues['/accessPermissions'] ?? {})
+        };
+        applyPatches(candidate, permissionPatches, false);
+        const touched = new Set();
+        for (const patch of permissionPatches){
+            if (patch.path === '/accessPermissions') {
+                touched.add('read');
+                touched.add('write');
+            } else touched.add(patch.path.split('/')[2] ?? '');
+        }
+        permissionsChanged = applyHandPermissions(candidate.accessPermissions, mutation.hlc, fieldValues, fieldHLCs, touched);
+        patchesByField.delete('/accessPermissions');
+    }
+    let defaultChanged = false;
+    const defaultPatches = patchesByField.get('/defaultAccessPermissions');
+    if (defaultPatches != null) {
+        const candidate = {
+            defaultAccessPermissions: structuredClone(fieldValues['/defaultAccessPermissions'])
+        };
+        applyPatches(candidate, defaultPatches, false);
+        if (!('defaultAccessPermissions' in candidate)) {
+            const path = '/defaultAccessPermissions';
+            if (fieldHLCs[path] == null || mutation.hlc >= fieldHLCs[path]) {
+                delete fieldValues[path];
+                fieldHLCs[path] = mutation.hlc;
+                defaultChanged = true;
+            }
+        } else {
+            defaultChanged = applyDefaultSlot(candidate.defaultAccessPermissions, mutation.hlc, docID, fieldValues, fieldHLCs);
+        }
+        patchesByField.delete('/defaultAccessPermissions');
+    }
     // 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.
+    //
+    // Access slots were ordered independently above. Provider-local annotations
+    // also order independently of the provider group's set frontier.
     const winningFields = [];
     const winningPatches = [];
     for (const [path, patches] of patchesByField){
         const currentHLC = fieldHLCs[path];
         const beatsField = currentHLC == null || mutation.hlc > currentHLC;
-        const beatsSet = s == null || mutation.hlc > s;
+        const decoupled = groupFieldSet != null;
+        const beatsSet = decoupled || s == null || mutation.hlc > s;
         if (beatsField && beatsSet) {
             winningFields.push(path);
             winningPatches.push(...patches);
         }
     }
     // No winning field means no state change; the gate is not invoked.
-    if (winningFields.length === 0) {
-        return doc;
+    if (winningFields.length === 0 && !defaultChanged && !permissionsChanged) {
+        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 || path === EFFECTIVE_READ_KEY) {
             continue;
         }
         base[path.slice(1)] = value;
@@ -271,7 +639,13 @@ export async function applyChangeMutation(ctx, mutation) {
         fieldValues[path] = validated[field];
         fieldHLCs[path] = mutation.hlc;
     }
-    const assembled = assemble(fieldValues, fieldHLCs);
+    foldReadRule(fieldValues);
+    // 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.
@@ -280,17 +654,24 @@ export async function applyChangeMutation(ctx, mutation) {
             ...doc,
             data: assembled
         };
-        const allowed = await ctx.postStateGate(postState);
+        const allowed = await ctx.postStateGate(postState, {
+            previous: doc,
+            mutation
+        });
         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;
@@ -308,27 +689,40 @@ 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.
-    const { model: modelData, reserved } = splitReservedFields(mutation.data);
-    let data;
-    try {
-        data = {
-            ...asType(validator, modelData),
-            ...reserved
-        };
-    } catch (err) {
-        throw new MutationSchemaValidationError(docID, {
-            cause: err
-        });
-    }
+    const data = validateSetData(validator, mutation.data, docID);
     const fieldHLCs = {
         ...storedHLCs ?? {}
     };
@@ -357,31 +751,129 @@ export async function applySetMutation(ctx, mutation) {
         if (!allowed) {
             throw new WriteAccessDeniedError(docID);
         }
+        if (setNeedsShare(mutation.data)) {
+            const shared = ctx.checkShareAccess != null && await ctx.checkShareAccess(target, mutation);
+            if (!shared) throw new WriteAccessDeniedError(docID);
+        }
     }
     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 changed = DEFAULT_ACCESS_PERMISSIONS_FIELD in data && applyDefaultSlot(data.defaultAccessPermissions, mutation.hlc, docID, fieldValues, fieldHLCs);
+    if (ACCESS_PERMISSIONS_FIELD in data) {
+        const permissions = data.accessPermissions;
+        changed = applyHandPermissions(permissions, mutation.hlc, fieldValues, fieldHLCs, new Set(Object.keys(permissions))) || changed;
+    }
+    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)){
+            if (field === DEFAULT_ACCESS_PERMISSIONS_FIELD || field === ACCESS_PERMISSIONS_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 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) || field === DEFAULT_ACCESS_PERMISSIONS_FIELD || field === ACCESS_PERMISSIONS_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,
+                ...frontier?.observed !== undefined && token <= frontier.observed.fetchHLC ? {
+                    observed: frontier.observed
+                } : {}
+            };
+            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);
+    foldReadRule(fieldValues);
+    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) {
@@ -389,9 +881,14 @@ export async function applySetMutation(ctx, mutation) {
                 ...synthesizedPostState,
                 data: assembled
             };
-            const allowed = await ctx.postStateGate(postState);
+            const allowed = await ctx.postStateGate(postState, {
+                previous: doc,
+                mutation
+            });
             if (!allowed) {
-                return null;
+                return {
+                    document: null
+                };
             }
         }
         const result = await ctx.store.createDocument({
@@ -401,7 +898,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.
@@ -410,17 +907,186 @@ export async function applySetMutation(ctx, mutation) {
             ...doc,
             data: assembled
         };
-        const allowed = await ctx.postStateGate(postState);
+        const allowed = await ctx.postStateGate(postState, {
+            previous: doc,
+            mutation
+        });
         if (!allowed) {
-            return null;
+            return {
+                document: null
+            };
         }
     }
     await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
-    return await ctx.store.saveDocument({
+    const saved = await ctx.store.saveDocument({
         id,
         existing: doc,
         data: assembled
     });
+    return toResult(saved);
+}
+/**
+ * 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
+    };
+    if (frontier?.observed !== undefined && token > frontier.observed.fetchHLC) {
+        const setCell = fieldValues[SET_FETCH_KEY];
+        if (setCell !== undefined) {
+            if (setCell.hlc === undefined) delete fieldValues[SET_FETCH_KEY];
+            else fieldValues[SET_FETCH_KEY] = {
+                hlc: setCell.hlc,
+                digest: setCell.digest
+            };
+        }
+    }
+    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, {
+            previous: doc,
+            mutation
+        });
+        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;
@@ -429,6 +1095,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);
     }