@kubun/mutation 0.17.1 → 0.18.0

package/lib/access-slot-only.d.ts

@@ -0,0 +1,3 @@
+import type { DocumentMutation, DocumentNode } from '@kubun/protocol';
+/** An exit notice requires a live held state and cannot carry application data. */
+export declare function isAccessSlotOnlyMutation(mutation: DocumentMutation, previous: DocumentNode | null): boolean;

package/lib/access-slot-only.js

@@ -0,0 +1,23 @@
+import { canonicalStringify } from '@sozai/codec';
+function withoutAccessSlots(data) {
+    const { accessPermissions: _hand, defaultAccessPermissions: _default, ...rest } = data;
+    return rest;
+}
+/** An exit notice requires a live held state and cannot carry application data. */ export function isAccessSlotOnlyMutation(mutation, previous) {
+    if (previous?.data == null || mutation.typ === 'tombstone') return false;
+    if (mutation.typ === 'set') {
+        return canonicalStringify(withoutAccessSlots(mutation.data)) === canonicalStringify(withoutAccessSlots(previous.data));
+    }
+    return mutation.patch.length > 0 && mutation.patch.every((patch)=>{
+        return [
+            '/accessPermissions',
+            '/accessPermissions/read',
+            '/accessPermissions/write',
+            '/defaultAccessPermissions'
+        ].includes(patch.path) && [
+            'add',
+            'replace',
+            'remove'
+        ].includes(patch.op) && !('from' in patch);
+    });
+}

package/lib/apply.d.ts

@@ -2,7 +2,7 @@ import { HLC } from '@kubun/hlc';
 import type { DocumentModelID } from '@kubun/id';
 import { DocumentID } from '@kubun/id';
 import type { ChangeDocumentMutation, DocumentData, DocumentModel, DocumentMutation, DocumentNode, SetDocumentMutation, TombstoneDocumentMutation } from '@kubun/protocol';
-import { type Validator } from '@sozai/schema';
+import type { Validator } from '@sozai/schema';
 export type DocumentValidator = Validator<DocumentData>;
 export type ValidatorsRecord = Record<string, Promise<DocumentValidator>>;
 /**
@@ -28,7 +28,11 @@ export declare const DELETE_FETCH_KEY = "/fetch";
  * effects (`saveDocument`, `createDocument`, `updateFieldHLCs`) are not
  * invoked when the gate denies, so engine state is unchanged.
  */
-export type PostStateGate = (postState: DocumentNode) => Promise<boolean> | boolean;
+export type PostStateGateContext = {
+    previous: DocumentNode | null;
+    mutation: DocumentMutation;
+};
+export type PostStateGate = (postState: DocumentNode, context: PostStateGateContext) => Promise<boolean> | boolean;
 /**
  * Minimal database interface required by mutation operations.
  * This decouples @kubun/mutation from the full KubunDB/store API,
@@ -61,6 +65,7 @@ export type MutationContext = {
      * injected checker, only the owner may write (owner-only safe default).
      */
     checkWriteAccess?: (doc: DocumentNode, mutation: DocumentMutation) => Promise<boolean>;
+    checkShareAccess?: (doc: DocumentNode, mutation: DocumentMutation) => Promise<boolean>;
     hlc?: HLC;
     maxDriftMS?: number;
     /**
@@ -83,6 +88,9 @@ export declare function getDocumentValidator(ctx: MutationContext, id: string):
 export declare const DEFAULT_MAX_DRIFT_MS = 3600000;
 export declare function validateFetchTokenDrift(token: string, maxDriftMS: number): void;
 export declare function getTopLevelField(path: string): string;
+/** Assemble visible fields and overlay the retained effective read rule. */
+export declare function assembleDocumentData(values: Record<string, unknown>): DocumentData;
+export declare function validateSetData(validator: DocumentValidator, rawData: Record<string, unknown>, documentID: string): DocumentData;
 /**
  * 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
@@ -103,11 +111,18 @@ export declare function resolveModelPolicy(ctx: MutationContext, modelID: Docume
  * SET classifier/register-winner logic below, which also need the frontier's
  * own token and liveness to compare a candidate against it.
  */
+export type ObservedProviderValue = {
+    fetchHLC: string;
+    valueDigest: string | null;
+    present: boolean;
+};
 export type FetchFrontier = {
     hlc: string;
     digest: string;
     alive: boolean;
+    observed?: ObservedProviderValue;
 };
+export declare function providerGroupDigest(group: Record<string, unknown>): string;
 /**
  * Pure merge-policy liveness read: the winning side's state digest alone —
  * the live `$setFetch` digest, or `DELETED_STATE_DIGEST` when the delete side

package/lib/apply.js

@@ -1,10 +1,10 @@
 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, IncompleteProviderGroupError, InvalidFetchTokenError, MergePolicyRemoveRequiresTombstoneError, MissingFetchTokenError, MutationSchemaValidationError, OwnerChangeError, ProviderGroupChangeRejectedError, TombstoneRequiresMergePolicyError, 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
@@ -70,6 +70,105 @@ export function getTopLevelField(path) {
 }
 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
@@ -86,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 = {
@@ -139,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
@@ -153,14 +265,7 @@ 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 data;
+    return assembleDocumentData(fieldValues);
 }
 /**
  * A model's provider merge policy, or `null` for an ordinary model. Read
@@ -195,14 +300,7 @@ 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 || path === DELETE_FETCH_KEY || path === SET_FETCH_KEY) {
-            continue;
-        }
-        data[path.slice(1)] = value;
-    }
-    return data;
+    return assembleDocumentData(fieldValues);
 }
 /**
  * Pure merge-policy liveness read: given a document's `field_values` cell map
@@ -222,14 +320,28 @@ const ACCESS_PERMISSIONS_FIELD = 'accessPermissions';
     const alive = s != null && (t == null || s > t);
     return alive ? {
         hlc: s,
-        digest: setCell.digest,
-        alive: true
+        digest: setCell?.digest,
+        alive: true,
+        observed: setCell?.observed
     } : {
         hlc: t,
         digest: DELETED_STATE_DIGEST,
-        alive: false
+        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
@@ -330,10 +442,15 @@ 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, policy] = await Promise.all([
         ctx.store.getFieldHLCs(docID),
@@ -376,7 +493,10 @@ 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 {
                     document: null
@@ -419,27 +539,55 @@ export async function applyChangeMutation(ctx, mutation) {
             }
         }
     }
+    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.
     //
-    // 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.
+    // 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 field = path.slice(1);
         const currentHLC = fieldHLCs[path];
         const beatsField = currentHLC == null || mutation.hlc > currentHLC;
-        const decoupled = field === ACCESS_PERMISSIONS_FIELD || groupFieldSet != null;
+        const decoupled = groupFieldSet != null;
         const beatsSet = decoupled || s == null || mutation.hlc > s;
         if (beatsField && beatsSet) {
             winningFields.push(path);
@@ -447,7 +595,7 @@ export async function applyChangeMutation(ctx, mutation) {
         }
     }
     // No winning field means no state change; the gate is not invoked.
-    if (winningFields.length === 0) {
+    if (winningFields.length === 0 && !defaultChanged && !permissionsChanged) {
         return {
             document: doc
         };
@@ -457,7 +605,7 @@ export async function applyChangeMutation(ctx, mutation) {
     // 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 || path === SET_FETCH_KEY || path === DELETE_FETCH_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;
@@ -491,6 +639,7 @@ export async function applyChangeMutation(ctx, mutation) {
         fieldValues[path] = validated[field];
         fieldHLCs[path] = mutation.hlc;
     }
+    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
@@ -505,7 +654,10 @@ 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 {
                 document: null
@@ -570,18 +722,7 @@ export async function applySetMutation(ctx, mutation) {
     // 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 ?? {}
     };
@@ -610,17 +751,26 @@ 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);
     }
-    let changed = false;
+    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) {
@@ -639,7 +789,7 @@ export async function applySetMutation(ctx, mutation) {
         // 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)) {
+            if (groupFields.has(field) || field === DEFAULT_ACCESS_PERMISSIONS_FIELD || field === ACCESS_PERMISSIONS_FIELD) {
                 continue;
             }
             const path = `/${field}`;
@@ -690,7 +840,10 @@ export async function applySetMutation(ctx, mutation) {
             }
             fieldValues[SET_FETCH_KEY] = {
                 hlc: token,
-                digest: candidateDigest
+                digest: candidateDigest,
+                ...frontier?.observed !== undefined && token <= frontier.observed.fetchHLC ? {
+                    observed: frontier.observed
+                } : {}
             };
             fieldHLCs[SET_FETCH_KEY] = token;
             setChanged = true;
@@ -709,6 +862,7 @@ export async function applySetMutation(ctx, mutation) {
             };
         }
     }
+    foldReadRule(fieldValues);
     const assembled = policy == null ? assemble(fieldValues, fieldHLCs) : assembleMergePolicy(fieldValues, fieldHLCs);
     const toResult = (document)=>mergeFields == null ? {
             document
@@ -727,7 +881,10 @@ 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 {
                     document: null
@@ -750,7 +907,10 @@ 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 {
                 document: null
@@ -758,11 +918,12 @@ export async function applySetMutation(ctx, mutation) {
         }
     }
     await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
-    return toResult(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`
@@ -862,6 +1023,16 @@ export async function applySetMutation(ctx, mutation) {
     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.
@@ -894,7 +1065,10 @@ 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 {
                 document: null

package/lib/errors.d.ts

@@ -1,11 +1,23 @@
+export type KubunMutationErrorCode = 'KB07' | 'KB09' | 'KB10' | 'KB11' | 'KB12' | 'KB13' | 'KB16' | 'KB17' | 'KB18' | 'KB19' | 'KB20' | 'KB21' | 'KB22';
+export type KubunMutationErrorParams = {
+    message: string;
+    code: KubunMutationErrorCode;
+    docID?: string;
+    cause?: unknown;
+};
+export declare class KubunMutationError extends Error {
+    #private;
+    constructor(params: KubunMutationErrorParams);
+    get code(): KubunMutationErrorCode;
+    get docID(): string | undefined;
+}
 /**
  * Thrown by the mutation apply path when a non-owner writer's capability
  * check fails. Tagged with the protocol-level error code `KB07` so callers
  * — particularly the RPC handler — can translate the throw into a
  * structured wire response without losing the reason.
  */
-export declare class WriteAccessDeniedError extends Error {
-    #private;
+export declare class WriteAccessDeniedError extends KubunMutationError {
     constructor(docID: string);
     get code(): 'KB07';
     get docID(): string;
@@ -19,8 +31,7 @@ export declare class WriteAccessDeniedError extends Error {
  * error code `KB09` so callers — particularly the RPC handler — can translate
  * the throw into a structured wire response without losing the reason.
  */
-export declare class DocumentIDMismatchError extends Error {
-    #private;
+export declare class DocumentIDMismatchError extends KubunMutationError {
     constructor(docID: string);
     get code(): 'KB09';
     get docID(): string;
@@ -32,7 +43,7 @@ export declare class DocumentIDMismatchError extends Error {
  * the bound — the reject is permanent. Tagged `KB10` so the RPC handler can
  * translate the throw into a structured wire response.
  */
-export declare class HLCDriftError extends Error {
+export declare class HLCDriftError extends KubunMutationError {
     #private;
     constructor(driftMS: number, maxDriftMS: number);
     get code(): 'KB10';
@@ -45,7 +56,7 @@ export declare class HLCDriftError extends Error {
  * `HLC.tryParse` validation. Tagged `KB16` so the RPC handler can translate the
  * throw into a structured wire response.
  */
-export declare class InvalidFetchTokenError extends Error {
+export declare class InvalidFetchTokenError extends KubunMutationError {
     #private;
     constructor(token: string);
     get code(): 'KB16';
@@ -58,7 +69,7 @@ export declare class InvalidFetchTokenError extends Error {
  * `KB17` so the RPC handler can translate the throw into a structured wire
  * response.
  */
-export declare class FetchTokenOrderError extends Error {
+export declare class FetchTokenOrderError extends KubunMutationError {
     constructor();
     get code(): 'KB17';
 }
@@ -70,7 +81,7 @@ export declare class FetchTokenOrderError extends Error {
  * value instead of throwing). Tagged `KB18` so the RPC handler can translate
  * the throw into a structured wire response.
  */
-export declare class IncompleteProviderGroupError extends Error {
+export declare class IncompleteProviderGroupError extends KubunMutationError {
     #private;
     constructor(docID: string, field: string);
     get code(): 'KB18';
@@ -86,8 +97,7 @@ export declare class IncompleteProviderGroupError extends Error {
  * `KB19` so the RPC handler can translate the throw into a structured wire
  * response.
  */
-export declare class TombstoneRequiresMergePolicyError extends Error {
-    #private;
+export declare class TombstoneRequiresMergePolicyError extends KubunMutationError {
     constructor(docID: string);
     get code(): 'KB19';
     get docID(): string;
@@ -101,7 +111,7 @@ export declare class TombstoneRequiresMergePolicyError extends Error {
  * CHANGE to a field outside the group is unaffected. Tagged `KB20` so the RPC
  * handler can translate the throw into a structured wire response.
  */
-export declare class ProviderGroupChangeRejectedError extends Error {
+export declare class ProviderGroupChangeRejectedError extends KubunMutationError {
     #private;
     constructor(docID: string, field: string);
     get code(): 'KB20';
@@ -118,8 +128,7 @@ export declare class ProviderGroupChangeRejectedError extends Error {
  * `KB21` so the RPC handler can translate the throw into a structured wire
  * response.
  */
-export declare class MissingFetchTokenError extends Error {
-    #private;
+export declare class MissingFetchTokenError extends KubunMutationError {
     constructor(docID: string);
     get code(): 'KB21';
     get docID(): string;
@@ -136,8 +145,7 @@ export declare class MissingFetchTokenError extends Error {
  * always fails. Tagged `KB22` so the RPC handler can translate the throw into a
  * structured wire response.
  */
-export declare class MergePolicyRemoveRequiresTombstoneError extends Error {
-    #private;
+export declare class MergePolicyRemoveRequiresTombstoneError extends KubunMutationError {
     constructor(docID: string);
     get code(): 'KB22';
     get docID(): string;
@@ -149,8 +157,7 @@ export declare class MergePolicyRemoveRequiresTombstoneError extends Error {
  * Tagged `KB11` so the RPC handler can translate the throw into a structured
  * wire response.
  */
-export declare class OwnerChangeError extends Error {
-    #private;
+export declare class OwnerChangeError extends KubunMutationError {
     constructor(docID: string, fromOwner: string, toOwner: string);
     get code(): 'KB11';
     get docID(): string;
@@ -161,7 +168,7 @@ export declare class OwnerChangeError extends Error {
  * deterministic, permanent reject. Tagged `KB12` so the RPC handler can
  * translate the throw into a structured wire response.
  */
-export declare class UnsupportedMutationTypeError extends Error {
+export declare class UnsupportedMutationTypeError extends KubunMutationError {
     #private;
     constructor(mutationType: string);
     get code(): 'KB12';
@@ -174,8 +181,7 @@ export declare class UnsupportedMutationTypeError extends Error {
  * preserved as `cause`. Tagged `KB13` so the RPC handler can translate the
  * throw into a structured wire response.
  */
-export declare class MutationSchemaValidationError extends Error {
-    #private;
+export declare class MutationSchemaValidationError extends KubunMutationError {
     constructor(docID: string, options?: {
         cause?: unknown;
     });
@@ -193,6 +199,15 @@ export declare class MutationSchemaValidationError extends Error {
 export declare class InvalidAccessPermissionsError extends Error {
     constructor(detail?: string);
 }
+export declare class InvalidDefaultAccessPermissionsError extends KubunMutationError {
+    constructor(docID: string);
+}
+type InvalidAccessRulePatchErrorParams = {
+    docID: string;
+};
+export declare class InvalidAccessRulePatchError extends KubunMutationError {
+    constructor(params: InvalidAccessRulePatchErrorParams);
+}
 /**
  * True when `err` carries a protocol error code identifying a deterministically
  * permanent mutation reject. A permanent reject is one the sender cannot fix by
@@ -201,3 +216,4 @@ export declare class InvalidAccessPermissionsError extends Error {
  * else — a transient store/db failure — is excluded so it stays retryable.
  */
 export declare function isPermanentApplyError(err: unknown): boolean;
+export {};

package/lib/errors.js

@@ -1,20 +1,40 @@
+export class KubunMutationError extends Error {
+    #code;
+    #docID;
+    constructor(params){
+        super(params.message, Object.hasOwn(params, 'cause') ? {
+            cause: params.cause
+        } : undefined);
+        this.name = 'KubunMutationError';
+        this.#code = params.code;
+        this.#docID = params.docID;
+    }
+    get code() {
+        return this.#code;
+    }
+    get docID() {
+        return this.#docID;
+    }
+}
 /**
  * Thrown by the mutation apply path when a non-owner writer's capability
  * check fails. Tagged with the protocol-level error code `KB07` so callers
  * — particularly the RPC handler — can translate the throw into a
  * structured wire response without losing the reason.
- */ export class WriteAccessDeniedError extends Error {
-    #docID;
+ */ export class WriteAccessDeniedError extends KubunMutationError {
     constructor(docID){
-        super(`Access denied: cannot write document ${docID}`);
+        super({
+            message: `Access denied: cannot write document ${docID}`,
+            code: 'KB07',
+            docID
+        });
         this.name = 'WriteAccessDeniedError';
-        this.#docID = docID;
     }
     get code() {
         return 'KB07';
     }
     get docID() {
-        return this.#docID;
+        return super.docID;
     }
 }
 /**
@@ -25,18 +45,20 @@
  * a victim's deterministic-unique document ID. Tagged with the protocol-level
  * error code `KB09` so callers — particularly the RPC handler — can translate
  * the throw into a structured wire response without losing the reason.
- */ export class DocumentIDMismatchError extends Error {
-    #docID;
+ */ export class DocumentIDMismatchError extends KubunMutationError {
     constructor(docID){
-        super(`Document ID mismatch: ${docID} is not bound to its owner and unique value`);
+        super({
+            message: `Document ID mismatch: ${docID} is not bound to its owner and unique value`,
+            code: 'KB09',
+            docID
+        });
         this.name = 'DocumentIDMismatchError';
-        this.#docID = docID;
     }
     get code() {
         return 'KB09';
     }
     get docID() {
-        return this.#docID;
+        return super.docID;
     }
 }
 /**
@@ -45,11 +67,14 @@
  * is a fixed property of the mutation, so resending cannot move it back under
  * the bound — the reject is permanent. Tagged `KB10` so the RPC handler can
  * translate the throw into a structured wire response.
- */ export class HLCDriftError extends Error {
+ */ export class HLCDriftError extends KubunMutationError {
     #driftMS;
     #maxDriftMS;
     constructor(driftMS, maxDriftMS){
-        super(`HLC timestamp too far in the future: ${driftMS}ms drift exceeds ${maxDriftMS}ms limit`);
+        super({
+            message: `HLC timestamp too far in the future: ${driftMS}ms drift exceeds ${maxDriftMS}ms limit`,
+            code: 'KB10'
+        });
         this.name = 'HLCDriftError';
         this.#driftMS = driftMS;
         this.#maxDriftMS = maxDriftMS;
@@ -69,10 +94,13 @@
  * malformed tokens or NaN values that would slip past `HLC.parse` but fail
  * `HLC.tryParse` validation. Tagged `KB16` so the RPC handler can translate the
  * throw into a structured wire response.
- */ export class InvalidFetchTokenError extends Error {
+ */ export class InvalidFetchTokenError extends KubunMutationError {
     #token;
     constructor(token){
-        super(`Invalid fetch token: malformed HLC timestamp '${token}'`);
+        super({
+            message: `Invalid fetch token: malformed HLC timestamp '${token}'`,
+            code: 'KB16'
+        });
         this.name = 'InvalidFetchTokenError';
         this.#token = token;
     }
@@ -89,9 +117,12 @@
  * this reject is permanent — resending cannot move the HLC forward. Tagged
  * `KB17` so the RPC handler can translate the throw into a structured wire
  * response.
- */ export class FetchTokenOrderError extends Error {
+ */ export class FetchTokenOrderError extends KubunMutationError {
     constructor(){
-        super('Fetch token ordering violated: mutation HLC must be >= sourceFetchHLC');
+        super({
+            message: 'Fetch token ordering violated: mutation HLC must be >= sourceFetchHLC',
+            code: 'KB17'
+        });
         this.name = 'FetchTokenOrderError';
     }
     get code() {
@@ -105,20 +136,22 @@
  * omitted OPTIONAL group field is legitimate — it clears that field's stored
  * value instead of throwing). Tagged `KB18` so the RPC handler can translate
  * the throw into a structured wire response.
- */ export class IncompleteProviderGroupError extends Error {
-    #docID;
+ */ export class IncompleteProviderGroupError extends KubunMutationError {
     #field;
     constructor(docID, field){
-        super(`Incomplete provider group: document ${docID} SET omits required field '${field}'`);
+        super({
+            message: `Incomplete provider group: document ${docID} SET omits required field '${field}'`,
+            code: 'KB18',
+            docID
+        });
         this.name = 'IncompleteProviderGroupError';
-        this.#docID = docID;
         this.#field = field;
     }
     get code() {
         return 'KB18';
     }
     get docID() {
-        return this.#docID;
+        return super.docID;
     }
     get field() {
         return this.#field;
@@ -132,18 +165,20 @@
  * HLC registers and deletes via the `/`→null CHANGE path instead. Tagged
  * `KB19` so the RPC handler can translate the throw into a structured wire
  * response.
- */ export class TombstoneRequiresMergePolicyError extends Error {
-    #docID;
+ */ export class TombstoneRequiresMergePolicyError extends KubunMutationError {
     constructor(docID){
-        super(`Tombstone requires a provider-merge-policy model: document ${docID}`);
+        super({
+            message: `Tombstone requires a provider-merge-policy model: document ${docID}`,
+            code: 'KB19',
+            docID
+        });
         this.name = 'TombstoneRequiresMergePolicyError';
-        this.#docID = docID;
     }
     get code() {
         return 'KB19';
     }
     get docID() {
-        return this.#docID;
+        return super.docID;
     }
 }
 /**
@@ -154,20 +189,22 @@
  * against it would mix two incompatible orderings on the same fields. A
  * CHANGE to a field outside the group is unaffected. Tagged `KB20` so the RPC
  * handler can translate the throw into a structured wire response.
- */ export class ProviderGroupChangeRejectedError extends Error {
-    #docID;
+ */ export class ProviderGroupChangeRejectedError extends KubunMutationError {
     #field;
     constructor(docID, field){
-        super(`Provider group CHANGE rejected: document ${docID} CHANGE targets provider group field '${field}'`);
+        super({
+            message: `Provider group CHANGE rejected: document ${docID} CHANGE targets provider group field '${field}'`,
+            code: 'KB20',
+            docID
+        });
         this.name = 'ProviderGroupChangeRejectedError';
-        this.#docID = docID;
         this.#field = field;
     }
     get code() {
         return 'KB20';
     }
     get docID() {
-        return this.#docID;
+        return super.docID;
     }
     get field() {
         return this.#field;
@@ -182,18 +219,20 @@
  * present by the time a merge-policy candidate reaches classification. Tagged
  * `KB21` so the RPC handler can translate the throw into a structured wire
  * response.
- */ export class MissingFetchTokenError extends Error {
-    #docID;
+ */ export class MissingFetchTokenError extends KubunMutationError {
     constructor(docID){
-        super(`Missing fetch token: document ${docID} merge-policy write carries no sourceFetchHLC`);
+        super({
+            message: `Missing fetch token: document ${docID} merge-policy write carries no sourceFetchHLC`,
+            code: 'KB21',
+            docID
+        });
         this.name = 'MissingFetchTokenError';
-        this.#docID = docID;
     }
     get code() {
         return 'KB21';
     }
     get docID() {
-        return this.#docID;
+        return super.docID;
     }
 }
 /**
@@ -207,18 +246,20 @@
  * `/fetch`. The rejection is deterministic and permanent — the same mutation
  * always fails. Tagged `KB22` so the RPC handler can translate the throw into a
  * structured wire response.
- */ export class MergePolicyRemoveRequiresTombstoneError extends Error {
-    #docID;
+ */ export class MergePolicyRemoveRequiresTombstoneError extends KubunMutationError {
     constructor(docID){
-        super(`Merge-policy remove requires a tombstone: document ${docID} must be deleted via the fetch-token tombstone path`);
+        super({
+            message: `Merge-policy remove requires a tombstone: document ${docID} must be deleted via the fetch-token tombstone path`,
+            code: 'KB22',
+            docID
+        });
         this.name = 'MergePolicyRemoveRequiresTombstoneError';
-        this.#docID = docID;
     }
     get code() {
         return 'KB22';
     }
     get docID() {
-        return this.#docID;
+        return super.docID;
     }
 }
 /**
@@ -227,18 +268,20 @@
  * deterministic, permanent reject — the same mutation will always fail.
  * Tagged `KB11` so the RPC handler can translate the throw into a structured
  * wire response.
- */ export class OwnerChangeError extends Error {
-    #docID;
+ */ export class OwnerChangeError extends KubunMutationError {
     constructor(docID, fromOwner, toOwner){
-        super(`Cannot change owner from ${fromOwner} to ${toOwner} in document: ${docID}`);
+        super({
+            message: `Cannot change owner from ${fromOwner} to ${toOwner} in document: ${docID}`,
+            code: 'KB11',
+            docID
+        });
         this.name = 'OwnerChangeError';
-        this.#docID = docID;
     }
     get code() {
         return 'KB11';
     }
     get docID() {
-        return this.#docID;
+        return super.docID;
     }
 }
 /**
@@ -246,10 +289,13 @@
  * not support. The type is fixed in the signed mutation, so this is a
  * deterministic, permanent reject. Tagged `KB12` so the RPC handler can
  * translate the throw into a structured wire response.
- */ export class UnsupportedMutationTypeError extends Error {
+ */ export class UnsupportedMutationTypeError extends KubunMutationError {
     #mutationType;
     constructor(mutationType){
-        super(`Unsupported mutation type: ${mutationType}`);
+        super({
+            message: `Unsupported mutation type: ${mutationType}`,
+            code: 'KB12'
+        });
         this.name = 'UnsupportedMutationTypeError';
         this.#mutationType = mutationType;
     }
@@ -266,18 +312,21 @@
  * is a deterministic, permanent reject. The original validation error is
  * preserved as `cause`. Tagged `KB13` so the RPC handler can translate the
  * throw into a structured wire response.
- */ export class MutationSchemaValidationError extends Error {
-    #docID;
+ */ export class MutationSchemaValidationError extends KubunMutationError {
     constructor(docID, options){
-        super(`Mutation payload failed model schema validation for document ${docID}`, options);
+        super({
+            message: `Mutation payload failed model schema validation for document ${docID}`,
+            code: 'KB13',
+            docID,
+            ...options
+        });
         this.name = 'MutationSchemaValidationError';
-        this.#docID = docID;
     }
     get code() {
         return 'KB13';
     }
     get docID() {
-        return this.#docID;
+        return super.docID;
     }
 }
 /**
@@ -293,6 +342,26 @@
         this.name = 'InvalidAccessPermissionsError';
     }
 }
+export class InvalidDefaultAccessPermissionsError extends KubunMutationError {
+    constructor(docID){
+        super({
+            message: 'Invalid default access rule or HLC: expected a rule and HLC no later than the mutation',
+            code: 'KB13',
+            docID
+        });
+        this.name = 'InvalidDefaultAccessPermissionsError';
+    }
+}
+export class InvalidAccessRulePatchError extends KubunMutationError {
+    constructor(params){
+        super({
+            message: 'Invalid access rule patch: replace or remove a whole slot or read/write rule',
+            code: 'KB13',
+            docID: params.docID
+        });
+        this.name = 'InvalidAccessRulePatchError';
+    }
+}
 const PERMANENT_APPLY_ERROR_CODES = new Set([
     'KB07',
     'KB09',

package/lib/index.d.ts

@@ -1,9 +1,12 @@
 export { HLC, type HLCTimestamp } from '@kubun/hlc';
-export type { DocumentValidator, FetchFrontier, MergeOutcome, MutationApplyResult, MutationContext, MutationDB, PostStateGate, ValidatorsRecord, } from './apply.js';
-export { applyChangeMutation, applyMutation, applySetMutation, applyTombstoneMutation, classifySetOutcome, classifyTombstoneOutcome, DEFAULT_MAX_DRIFT_MS, DELETE_FETCH_KEY, getTopLevelField, resolveModelPolicy, SET_FETCH_KEY, validateFetchTokenDrift, winnerStateDigestOf, } from './apply.js';
+export { isAccessSlotOnlyMutation } from './access-slot-only.js';
+export type { DocumentValidator, FetchFrontier, MergeOutcome, MutationApplyResult, MutationContext, MutationDB, PostStateGate, PostStateGateContext, ValidatorsRecord, } from './apply.js';
+export { applyChangeMutation, applyMutation, applySetMutation, applyTombstoneMutation, assembleDocumentData, classifySetOutcome, classifyTombstoneOutcome, DEFAULT_MAX_DRIFT_MS, DELETE_FETCH_KEY, getTopLevelField, providerGroupDigest, resolveModelPolicy, SET_FETCH_KEY, validateFetchTokenDrift, validateSetData, winnerStateDigestOf, } from './apply.js';
 export type { CreateChangeMutationParams, CreateRemoveMutationParams, CreateSetMutationParams, CreateTombstoneMutationParams, } from './create.js';
 export { createChangeMutation, createRemoveMutation, createSetMutation, createTombstoneMutation, } from './create.js';
-export { DocumentIDMismatchError, FetchTokenOrderError, HLCDriftError, IncompleteProviderGroupError, InvalidAccessPermissionsError, InvalidFetchTokenError, isPermanentApplyError, MergePolicyRemoveRequiresTombstoneError, MissingFetchTokenError, MutationSchemaValidationError, OwnerChangeError, ProviderGroupChangeRejectedError, TombstoneRequiresMergePolicyError, UnsupportedMutationTypeError, WriteAccessDeniedError, } from './errors.js';
+export type { KubunMutationErrorCode, KubunMutationErrorParams } from './errors.js';
+export { DocumentIDMismatchError, FetchTokenOrderError, HLCDriftError, IncompleteProviderGroupError, InvalidAccessPermissionsError, InvalidAccessRulePatchError, InvalidDefaultAccessPermissionsError, InvalidFetchTokenError, isPermanentApplyError, KubunMutationError, MergePolicyRemoveRequiresTombstoneError, MissingFetchTokenError, MutationSchemaValidationError, OwnerChangeError, ProviderGroupChangeRejectedError, TombstoneRequiresMergePolicyError, UnsupportedMutationTypeError, WriteAccessDeniedError, } from './errors.js';
+export { type HeldProviderMutation, type HeldProviderWinner, type SelectHeldProviderWinnerParams, selectHeldProviderWinner, } from './observation-winner.js';
 export type { CreateDocumentParams, CreateMutationOperationsParams, MutationOperations, RemoveDocumentParams, SetDocumentParams, UpdateDocumentParams, } from './operations.js';
 export { convertPatchInput, createMutationOperations } from './operations.js';
 export { DELETED_STATE_DIGEST, type StateDigestInput, stateDigest } from './state-digest.js';

package/lib/index.js

@@ -1,6 +1,8 @@
 export { HLC } from '@kubun/hlc';
-export { applyChangeMutation, applyMutation, applySetMutation, applyTombstoneMutation, classifySetOutcome, classifyTombstoneOutcome, DEFAULT_MAX_DRIFT_MS, DELETE_FETCH_KEY, getTopLevelField, resolveModelPolicy, SET_FETCH_KEY, validateFetchTokenDrift, winnerStateDigestOf } from './apply.js';
+export { isAccessSlotOnlyMutation } from './access-slot-only.js';
+export { applyChangeMutation, applyMutation, applySetMutation, applyTombstoneMutation, assembleDocumentData, classifySetOutcome, classifyTombstoneOutcome, DEFAULT_MAX_DRIFT_MS, DELETE_FETCH_KEY, getTopLevelField, providerGroupDigest, resolveModelPolicy, SET_FETCH_KEY, validateFetchTokenDrift, validateSetData, winnerStateDigestOf } from './apply.js';
 export { createChangeMutation, createRemoveMutation, createSetMutation, createTombstoneMutation } from './create.js';
-export { DocumentIDMismatchError, FetchTokenOrderError, HLCDriftError, IncompleteProviderGroupError, InvalidAccessPermissionsError, InvalidFetchTokenError, isPermanentApplyError, MergePolicyRemoveRequiresTombstoneError, MissingFetchTokenError, MutationSchemaValidationError, OwnerChangeError, ProviderGroupChangeRejectedError, TombstoneRequiresMergePolicyError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
+export { DocumentIDMismatchError, FetchTokenOrderError, HLCDriftError, IncompleteProviderGroupError, InvalidAccessPermissionsError, InvalidAccessRulePatchError, InvalidDefaultAccessPermissionsError, InvalidFetchTokenError, isPermanentApplyError, KubunMutationError, MergePolicyRemoveRequiresTombstoneError, MissingFetchTokenError, MutationSchemaValidationError, OwnerChangeError, ProviderGroupChangeRejectedError, TombstoneRequiresMergePolicyError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
+export { selectHeldProviderWinner } from './observation-winner.js';
 export { convertPatchInput, createMutationOperations } from './operations.js';
 export { DELETED_STATE_DIGEST, stateDigest } from './state-digest.js';

package/lib/observation-winner.d.ts

@@ -0,0 +1,19 @@
+import type { SetDocumentMutation, TombstoneDocumentMutation } from '@kubun/protocol';
+import { type DocumentValidator, type ObservedProviderValue } from './apply.js';
+export type HeldProviderMutation = (SetDocumentMutation | TombstoneDocumentMutation) & {
+    sourceFetchHLC: string;
+};
+export type HeldProviderWinner = {
+    mutation: HeldProviderMutation;
+    token: string;
+    digest: string;
+    present: boolean;
+    group: Record<string, unknown>;
+};
+export type SelectHeldProviderWinnerParams = {
+    mutations: ReadonlyArray<HeldProviderMutation>;
+    observed: ObservedProviderValue;
+    fields: ReadonlyArray<string>;
+    validator: DocumentValidator;
+};
+export declare function selectHeldProviderWinner(params: SelectHeldProviderWinnerParams): HeldProviderWinner | null;

package/lib/observation-winner.js

@@ -0,0 +1,48 @@
+import { providerGroupDigest, validateSetData } from './apply.js';
+import { DELETED_STATE_DIGEST, stateDigest } from './state-digest.js';
+function candidate(mutation, fields, validator) {
+    const token = mutation.sourceFetchHLC;
+    if (mutation.typ === 'tombstone') {
+        return {
+            mutation,
+            token,
+            digest: DELETED_STATE_DIGEST,
+            present: false,
+            group: {}
+        };
+    }
+    const group = {};
+    const data = validateSetData(validator, mutation.data, mutation.sub);
+    for (const field of fields){
+        if (field in data) group[field] = data[field];
+    }
+    return {
+        mutation,
+        token,
+        digest: stateDigest({
+            state: 'live',
+            group
+        }),
+        present: true,
+        group
+    };
+}
+function comparesAfter(left, right) {
+    if (left.token !== right.token) return left.token > right.token;
+    if (left.present !== right.present) return !left.present;
+    return left.digest > right.digest;
+}
+export function selectHeldProviderWinner(params) {
+    const { mutations, observed, fields, validator } = params;
+    let base = null;
+    let qualifying = null;
+    for (const mutation of mutations){
+        const current = candidate(mutation, fields, validator);
+        if (base === null || comparesAfter(current, base)) base = current;
+        const matches = current.present === observed.present && (current.present ? providerGroupDigest(current.group) === observed.valueDigest : observed.valueDigest === null);
+        if (current.token >= observed.fetchHLC || matches) {
+            if (qualifying === null || comparesAfter(current, qualifying)) qualifying = current;
+        }
+    }
+    return qualifying ?? base;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/mutation",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,15 +15,15 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/hlc": "^0.17.0",
-    "@kubun/id": "^0.17.0",
-    "@sozai/codec": "^0.4.0",
+    "@kubun/hlc": "^0.18.0",
+    "@kubun/id": "^0.18.0",
+    "@sozai/codec": "^0.4.3",
     "@sozai/patch": "^0.1.3",
     "@sozai/runtime": "^0.1.0",
-    "@sozai/schema": "^0.1.2"
+    "@sozai/schema": "^0.1.4"
   },
   "devDependencies": {
-    "@kubun/protocol": "^0.17.1"
+    "@kubun/protocol": "^0.18.0"
   },
   "publishConfig": {
     "access": "public"