@kubun/mutation 0.10.1 → 0.12.0

package/lib/apply.d.ts

@@ -1,8 +1,8 @@
-import { type Validator } from '@enkaku/schema';
 import { HLC } from '@kubun/hlc';
 import type { DocumentModelID } from '@kubun/id';
 import { DocumentID } from '@kubun/id';
 import type { ChangeDocumentMutation, DocumentData, DocumentModel, DocumentMutation, DocumentNode, SetDocumentMutation } from '@kubun/protocol';
+import { type Validator } from '@sozai/schema';
 export type DocumentValidator = Validator<DocumentData>;
 export type ValidatorsRecord = Record<string, Promise<DocumentValidator>>;
 /**
@@ -33,7 +33,8 @@ export type MutationDB = {
         data: DocumentData | null;
     }): Promise<DocumentNode>;
     getFieldHLCs(documentID: string): Promise<Record<string, string> | null>;
-    updateFieldHLCs(docID: DocumentID, fieldHLCs: Record<string, string>): Promise<void>;
+    getFieldValues(documentID: string): Promise<Record<string, unknown> | null>;
+    updateFieldHLCs(docID: DocumentID, fieldHLCs: Record<string, string>, fieldValues: Record<string, unknown>): Promise<void>;
 };
 export type MutationContext = {
     store: MutationDB;

package/lib/apply.js

@@ -1 +1,426 @@
-import{fromB64 as t}from"@enkaku/codec";import{applyPatches as e}from"@enkaku/patch";import{asType as a,createValidator as r}from"@enkaku/schema";import{HLC as l}from"@kubun/hlc";import{DocumentID as o}from"@kubun/id";import{WriteAccessDeniedError as n}from"./errors.js";export function getDocumentValidator(t,e){return null==t.validators[e]&&(t.validators[e]=t.store.getDocumentModel(e).then(t=>r({...t.schema,$id:e}))),t.validators[e]}function i(t,e){let a=l.parse(t),r=Date.now(),o=a.wallTime-r;if(o>e)throw Error(`HLC timestamp too far in the future: ${o}ms drift exceeds ${e}ms limit`)}export function getTopLevelField(t){let e=t.indexOf("/",1);return -1===e?t:t.slice(0,e)}export async function applyChangeMutation(t,r){let l=o.fromString(r.sub),u=l.toString(),s=await t.store.getDocument(l);if(null==s)throw Error(`Document not found: ${u}`);if(r.iss!==s.owner&&!(null!=t.checkWriteAccess&&await t.checkWriteAccess(s,r)))throw new n(u);null!=t.maxDriftMS&&i(r.hlc,t.maxDriftMS);let c=l.model.toString(),p=await t.store.getFieldHLCs(u)??{};if(1===r.patch.length&&"replace"===r.patch[0].op&&"/"===r.patch[0].path&&null===r.patch[0].value){let e={...p,"/":r.hlc},a=Object.entries(e).every(([t,e])=>"/"===t||r.hlc>=e);if(a&&null!=t.postStateGate){let e={...s,data:null};if(!await t.postStateGate(e))return null}return(await t.store.updateFieldHLCs(l,e),a)?await t.store.saveDocument({id:l,existing:s,data:null}):s}if(null!=p["/"]&&null===s.data)return s;let f=await getDocumentValidator(t,c),d=new Map;for(let t of r.patch){let e=getTopLevelField(t.path),a=d.get(e);null!=a?a.push(t):d.set(e,[t])}let m={...p},h=[];for(let[t,e]of d){let a=p[t];(null==a||r.hlc>a)&&(h.push(...e),m[t]=r.hlc)}if(0===h.length)return s;let w=structuredClone(s.data??{});e(w,h,!1);let g=a(f,w);if(null!=t.postStateGate){let e={...s,data:g};if(!await t.postStateGate(e))return null}return await t.store.updateFieldHLCs(l,m),await t.store.saveDocument({id:l,existing:s,data:g})}export async function applySetMutation(e,r){let l=r.aud??r.iss,u=o.fromString(r.sub),s=u.toString(),c=u.model.toString();null!=e.maxDriftMS&&i(r.hlc,e.maxDriftMS);let[p,f]=await Promise.all([e.store.getDocument(u),getDocumentValidator(e,c)]),d=a(f,r.data),m={};for(let t of Object.keys(d))m[`/${t}`]=r.hlc;let h={id:s,model:c,owner:l,data:d,createdAt:new Date(0),updatedAt:null};if(r.iss!==l){let t=p??h;if(!(null!=e.checkWriteAccess&&await e.checkWriteAccess(t,r)))throw new n(s)}if(null===p){if(null!=e.postStateGate&&!await e.postStateGate(h))return null;let a=await e.store.createDocument({id:u,owner:l,data:d,unique:t(r.unq)});return await e.store.updateFieldHLCs(u,m),a}if(p.owner!==l)throw Error(`Cannot change owner from ${p.owner} to ${l} in document: ${u.toString()}`);let w=await e.store.getFieldHLCs(s)??{},g={...p.data??{}},S={...w},D=!1;for(let[t,e]of Object.entries(d)){let a=`/${t}`,l=w[a];(null==l||r.hlc>l)&&(g[t]=e,S[a]=r.hlc,D=!0)}if(!D)return p;let x=a(f,g);if(null!=e.postStateGate){let t={...p,data:x};if(!await e.postStateGate(t))return null}return await e.store.updateFieldHLCs(u,S),await e.store.saveDocument({id:u,existing:p,data:x})}export async function applyMutation(t,e){switch(e.typ){case"change":return await applyChangeMutation(t,e);case"set":return await applySetMutation(t,e);default:throw Error("Unsupported mutation type")}}
+import { HLC } from '@kubun/hlc';
+import { DocumentID } from '@kubun/id';
+import { isValidAccessRule, RESERVED_DOCUMENT_FIELDS } from '@kubun/protocol';
+import { fromB64 } from '@sozai/codec';
+import { applyPatches } from '@sozai/patch';
+import { asType, createValidator } from '@sozai/schema';
+import { DocumentIDMismatchError, HLCDriftError, MutationSchemaValidationError, OwnerChangeError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
+/**
+ * Reserved `field_hlcs` key holding the greatest delete HLC observed for the
+ * document (the tombstone timestamp `t`).
+ */ const DELETE_KEY = '/';
+/**
+ * Reserved `field_hlcs` key holding the greatest set HLC observed for the
+ * document (the set timestamp `s`).
+ */ const SET_KEY = '$set';
+export function getDocumentValidator(ctx, id) {
+    if (ctx.validators[id] == null) {
+        ctx.validators[id] = ctx.store.getDocumentModel(id).then((model)=>createValidator({
+                ...model.schema,
+                $id: id
+            })).catch((err)=>{
+            delete ctx.validators[id];
+            throw err;
+        });
+    }
+    return ctx.validators[id];
+}
+function validateHLCDrift(hlcString, maxDriftMS) {
+    const ts = HLC.parse(hlcString);
+    const now = Date.now();
+    const drift = ts.wallTime - now;
+    if (drift > maxDriftMS) {
+        throw new HLCDriftError(drift, 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';
+/**
+ * Salvage a candidate `accessPermissions` value per rule, mirroring the engine
+ * parser (`parseDocumentAccessPermissions`): a malformed `read` or `write` rule
+ * is dropped on its own while a valid sibling — and any unknown extra keys —
+ * survive. Returns `null` only when the value is not a plain object or no valid
+ * rule remains; otherwise a sanitized copy carrying just the valid rules (plus
+ * unrecognized keys the parser ignores). Enforcing per-rule at the storage
+ * boundary means the SQL read predicates only ever see valid shapes or absence,
+ * and a partly-garbage object never discards a legitimate sibling rule.
+ */ function sanitizeAccessPermissions(value) {
+    if (value == null || typeof value !== 'object') {
+        return null;
+    }
+    const perms = value;
+    const readValid = perms.read !== undefined && isValidAccessRule(perms.read);
+    const writeValid = perms.write !== undefined && isValidAccessRule(perms.write);
+    if (!readValid && !writeValid) {
+        return null;
+    }
+    const sanitized = {
+        ...perms
+    };
+    if (perms.read !== undefined && !readValid) {
+        delete sanitized.read;
+    }
+    if (perms.write !== undefined && !writeValid) {
+        delete sanitized.write;
+    }
+    return sanitized;
+}
+/**
+ * Partition a candidate document into model-declared fields and engine-reserved
+ * fields. Only the model half is validated against the model schema; the
+ * reserved half is re-attached to the persisted result unchanged.
+ *
+ * A malformed `accessPermissions` value is sanitized per rule here rather than
+ * rejecting the mutation: rejecting a signed remote mutation the owner's log
+ * already contains would fork merkle sync permanently, whereas sanitizing keeps
+ * document-data convergence and lets access resolve to model/server defaults.
+ * A salvaged value keeps its valid rules (added to `reserved`); the field is
+ * added to `droppedReserved` and left out of `reserved` only when nothing valid
+ * remains. A well-behaved producer never emits garbage (mint-time validation
+ * catches it first), so this only fires on hostile or buggy remote input.
+ */ function splitReservedFields(data) {
+    const model = {};
+    const reserved = {};
+    const droppedReserved = new Set();
+    for (const [key, value] of Object.entries(data)){
+        if (RESERVED_FIELD_SET.has(key)) {
+            if (key === ACCESS_PERMISSIONS_FIELD) {
+                const sanitized = sanitizeAccessPermissions(value);
+                if (sanitized == null) {
+                    droppedReserved.add(key);
+                    continue;
+                }
+                reserved[key] = sanitized;
+                continue;
+            }
+            reserved[key] = value;
+        } else {
+            model[key] = value;
+        }
+    }
+    return {
+        model,
+        reserved,
+        droppedReserved
+    };
+}
+/**
+ * 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
+ * timestamp that is strictly greater than any tombstone timestamp; only then
+ * does it surface data. The visible object is assembled solely from the
+ * retained field values (keyed by `/field` paths), so the result is a pure
+ * function of the accumulated state regardless of the order mutations arrived.
+ */ function assemble(fieldValues, fieldHLCs) {
+    const s = fieldHLCs[SET_KEY];
+    const t = fieldHLCs[DELETE_KEY];
+    const alive = s != null && (t == null || s > t);
+    if (!alive) {
+        return null;
+    }
+    const data = {};
+    for (const [path, value] of Object.entries(fieldValues)){
+        if (path === DELETE_KEY || path === SET_KEY) {
+            continue;
+        }
+        data[path.slice(1)] = value;
+    }
+    return data;
+}
+export async function applyChangeMutation(ctx, mutation) {
+    const id = DocumentID.fromString(mutation.sub);
+    const docID = id.toString();
+    const doc = await ctx.store.getDocument(id);
+    if (doc == null) {
+        throw new Error(`Document not found: ${docID}`);
+    }
+    // A non-owner writer must present a valid write capability. Absent an
+    // injected checker, only the owner may write (owner-only safe default).
+    if (mutation.iss !== doc.owner) {
+        const allowed = ctx.checkWriteAccess != null && await ctx.checkWriteAccess(doc, mutation);
+        if (!allowed) {
+            throw new WriteAccessDeniedError(docID);
+        }
+    }
+    if (ctx.maxDriftMS != null) {
+        validateHLCDrift(mutation.hlc, ctx.maxDriftMS);
+    }
+    const modelID = id.model.toString();
+    const [storedHLCs, storedValues] = await Promise.all([
+        ctx.store.getFieldHLCs(docID),
+        ctx.store.getFieldValues(docID)
+    ]);
+    const fieldHLCs = {
+        ...storedHLCs ?? {}
+    };
+    const fieldValues = {
+        ...storedValues ?? {}
+    };
+    const s = fieldHLCs[SET_KEY];
+    const t = fieldHLCs[DELETE_KEY];
+    // A delete is a single root replace to null. It only advances the tombstone
+    // timestamp; it never erases retained field values or field timestamps, so a
+    // later set above the tombstone can revive the exact prior field set.
+    const isDelete = mutation.patch.length === 1 && mutation.patch[0].op === 'replace' && mutation.patch[0].path === DELETE_KEY && mutation.patch[0].value === null;
+    if (isDelete) {
+        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
+        // document to dead (it never revives one and never alters field values), so
+        // visible state changes exactly when a previously-live document becomes
+        // tombstoned. Any other delete is a no-op for visible state.
+        if (doc.data != null && assembled == null && ctx.postStateGate != null) {
+            const postState = {
+                ...doc,
+                data: assembled
+            };
+            const allowed = await ctx.postStateGate(postState);
+            if (!allowed) {
+                return null;
+            }
+        }
+        await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
+        return await ctx.store.saveDocument({
+            id,
+            existing: doc,
+            data: assembled
+        });
+    }
+    const validator = await getDocumentValidator(ctx, modelID);
+    // Group patches by top-level field for LWW comparison.
+    const patchesByField = new Map();
+    for (const patch of mutation.patch){
+        const field = getTopLevelField(patch.path);
+        const group = patchesByField.get(field);
+        if (group != null) {
+            group.push(patch);
+        } else {
+            patchesByField.set(field, [
+                patch
+            ]);
+        }
+    }
+    // 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.
+    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;
+        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;
+    }
+    // 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) {
+            continue;
+        }
+        base[path.slice(1)] = value;
+    }
+    const cloned = structuredClone(base);
+    applyPatches(cloned, winningPatches, false);
+    // 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 (a patch on a reserved field applies as normal).
+    const { model: modelFields, reserved, droppedReserved } = splitReservedFields(cloned);
+    let validatedModel;
+    try {
+        validatedModel = asType(validator, modelFields);
+    } catch (err) {
+        throw new MutationSchemaValidationError(docID, {
+            cause: err
+        });
+    }
+    const validated = {
+        ...validatedModel,
+        ...reserved
+    };
+    for (const path of winningFields){
+        const field = path.slice(1);
+        // A dropped reserved field (malformed accessPermissions) is neither
+        // persisted nor allowed to advance its field HLC, so a later valid update
+        // from the owner still wins the LWW comparison and applies.
+        if (droppedReserved.has(field)) {
+            continue;
+        }
+        fieldValues[path] = validated[field];
+        fieldHLCs[path] = mutation.hlc;
+    }
+    const assembled = assemble(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.
+    if (ctx.postStateGate != null) {
+        const postState = {
+            ...doc,
+            data: assembled
+        };
+        const allowed = await ctx.postStateGate(postState);
+        if (!allowed) {
+            return null;
+        }
+    }
+    await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
+    return await ctx.store.saveDocument({
+        id,
+        existing: doc,
+        data: assembled
+    });
+}
+export async function applySetMutation(ctx, mutation) {
+    const owner = mutation.aud ?? mutation.iss;
+    const id = DocumentID.fromString(mutation.sub);
+    const docID = id.toString();
+    const modelID = id.model.toString();
+    // Bind owner↔ID: the document ID must hash from the document's model, the
+    // claimed owner, and the unique value. A mismatch means the writer is
+    // claiming an ID that does not derive from their own owner identity, so the
+    // write is rejected before touching any store state.
+    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, validator, storedHLCs, storedValues] = await Promise.all([
+        ctx.store.getDocument(id),
+        getDocumentValidator(ctx, modelID),
+        ctx.store.getFieldHLCs(docID),
+        ctx.store.getFieldValues(docID)
+    ]);
+    // 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 fieldHLCs = {
+        ...storedHLCs ?? {}
+    };
+    const fieldValues = {
+        ...storedValues ?? {}
+    };
+    const s = fieldHLCs[SET_KEY];
+    // Synthesized post-state for a not-yet-persisted node, reused by both the
+    // write-access check (new-doc case) and the post-state gate. Timestamps are
+    // unknown until createDocument runs, but both gates inspect access fields
+    // (owner, data) only — not timestamps.
+    const synthesizedPostState = {
+        id: docID,
+        model: modelID,
+        owner,
+        data,
+        createdAt: new Date(0),
+        updatedAt: null
+    };
+    // A non-owner writer must present a valid write capability — for an existing
+    // doc, evaluated against the current node; for a new doc, against the
+    // synthesized post-state. 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(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;
+        }
+    }
+    // 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);
+    // 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;
+    }
+    if (doc == null) {
+        if (ctx.postStateGate != null) {
+            const postState = {
+                ...synthesizedPostState,
+                data: assembled
+            };
+            const allowed = await ctx.postStateGate(postState);
+            if (!allowed) {
+                return null;
+            }
+        }
+        const result = await ctx.store.createDocument({
+            id,
+            owner,
+            data: assembled,
+            unique: fromB64(mutation.unq)
+        });
+        await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
+        return result;
+    }
+    // Synthesize the post-state for gate evaluation BEFORE any write
+    // (updateFieldHLCs + saveDocument). The cloned node is dropped on deny.
+    if (ctx.postStateGate != null) {
+        const postState = {
+            ...doc,
+            data: assembled
+        };
+        const allowed = await ctx.postStateGate(postState);
+        if (!allowed) {
+            return null;
+        }
+    }
+    await ctx.store.updateFieldHLCs(id, fieldHLCs, fieldValues);
+    return await ctx.store.saveDocument({
+        id,
+        existing: doc,
+        data: assembled
+    });
+}
+export async function applyMutation(ctx, mutation) {
+    const mutationType = mutation.typ;
+    switch(mutation.typ){
+        case 'change':
+            return await applyChangeMutation(ctx, mutation);
+        case 'set':
+            return await applySetMutation(ctx, mutation);
+        default:
+            throw new UnsupportedMutationTypeError(mutationType);
+    }
+}

package/lib/create.js

@@ -1 +1,76 @@
-import{toB64 as e}from"@enkaku/codec";import{HLC as t}from"@kubun/hlc";import{DocumentID as a}from"@kubun/id";export async function createSetMutation(c){let n=c.issuer,u=c.owner??n,r=await a.create(c.modelID,u,c.unique);return{typ:"set",iss:n,aud:u,sub:r.toString(),data:c.data,hlc:t.serialize(c.hlc.now()),unq:e(c.unique),...null!=c.cap?{cap:c.cap}:{}}}export function createChangeMutation(e){return{typ:"change",iss:e.issuer,sub:a.from(e.docID).toString(),patch:e.patch,hlc:t.serialize(e.hlc.now()),...null!=e.cap?{cap:e.cap}:{}}}export function createRemoveMutation(e){return{typ:"change",iss:e.issuer,sub:e.docID,patch:[{op:"replace",path:"/",value:null}],hlc:t.serialize(e.hlc.now()),...null!=e.cap?{cap:e.cap}:{}}}
+import { HLC } from '@kubun/hlc';
+import { DocumentID } from '@kubun/id';
+import { isValidAccessPermissions } from '@kubun/protocol';
+import { toB64 } from '@sozai/codec';
+import { InvalidAccessPermissionsError } from './errors.js';
+const ACCESS_PERMISSIONS_FIELD = 'accessPermissions';
+const ACCESS_PERMISSIONS_PATH = `/${ACCESS_PERMISSIONS_FIELD}`;
+/**
+ * Reject a mint whose data carries a malformed reserved `accessPermissions`
+ * field. Absent is fine; present must be well-formed.
+ */ function assertSetAccessPermissions(data) {
+    if (ACCESS_PERMISSIONS_FIELD in data && !isValidAccessPermissions(data[ACCESS_PERMISSIONS_FIELD])) {
+        throw new InvalidAccessPermissionsError('set mutation data');
+    }
+}
+/**
+ * Reject a mint whose patch replaces the whole `accessPermissions` object with a
+ * malformed value. Only whole-object `add`/`replace` ops are checked — that is
+ * the shape every producer emits. Deeper sub-paths and removals are left to the
+ * tolerant apply path, which cannot mis-grant on garbage.
+ */ function assertPatchAccessPermissions(patch) {
+    for (const op of patch){
+        if (op.path === ACCESS_PERMISSIONS_PATH && (op.op === 'add' || op.op === 'replace') && !isValidAccessPermissions(op.value)) {
+            throw new InvalidAccessPermissionsError('change mutation patch');
+        }
+    }
+}
+export async function createSetMutation(params) {
+    assertSetAccessPermissions(params.data);
+    const issuer = params.issuer;
+    const owner = params.owner ?? issuer;
+    const docID = await DocumentID.create(params.modelID, owner, params.unique);
+    return {
+        typ: 'set',
+        iss: issuer,
+        aud: owner,
+        sub: docID.toString(),
+        data: params.data,
+        hlc: HLC.serialize(params.hlc.now()),
+        unq: toB64(params.unique),
+        ...params.cap != null ? {
+            cap: params.cap
+        } : {}
+    };
+}
+export function createChangeMutation(params) {
+    assertPatchAccessPermissions(params.patch);
+    return {
+        typ: 'change',
+        iss: params.issuer,
+        sub: DocumentID.from(params.docID).toString(),
+        patch: params.patch,
+        hlc: HLC.serialize(params.hlc.now()),
+        ...params.cap != null ? {
+            cap: params.cap
+        } : {}
+    };
+}
+export function createRemoveMutation(params) {
+    return {
+        typ: 'change',
+        iss: params.issuer,
+        sub: params.docID,
+        patch: [
+            {
+                op: 'replace',
+                path: '/',
+                value: null
+            }
+        ],
+        hlc: HLC.serialize(params.hlc.now()),
+        ...params.cap != null ? {
+            cap: params.cap
+        } : {}
+    };
+}

package/lib/errors.d.ts

@@ -5,7 +5,96 @@
  * structured wire response without losing the reason.
  */
 export declare class WriteAccessDeniedError extends Error {
-    readonly code: "KB07";
-    readonly docID: string;
+    #private;
     constructor(docID: string);
+    get code(): 'KB07';
+    get docID(): string;
 }
+/**
+ * Thrown by the set apply path when the document ID in `sub` does not match the
+ * ID deterministically derived from the document's model, owner, and unique
+ * value. This binds owner↔ID so a writer cannot claim a document ID that does
+ * not hash from their own owner identity, preventing an attacker from squatting
+ * 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 declare class DocumentIDMismatchError extends Error {
+    #private;
+    constructor(docID: string);
+    get code(): 'KB09';
+    get docID(): string;
+}
+/**
+ * Thrown by the mutation apply path when an incoming mutation's HLC timestamp
+ * sits further in the future than the allowed drift bound. A signed timestamp
+ * 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 declare class HLCDriftError extends Error {
+    #private;
+    constructor(driftMS: number, maxDriftMS: number);
+    get code(): 'KB10';
+    get driftMS(): number;
+    get maxDriftMS(): number;
+}
+/**
+ * Thrown by the set apply path when a mutation would reassign an existing
+ * document's owner. Ownership is immutable once a document exists, so this is a
+ * 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 declare class OwnerChangeError extends Error {
+    #private;
+    constructor(docID: string, fromOwner: string, toOwner: string);
+    get code(): 'KB11';
+    get docID(): string;
+}
+/**
+ * Thrown by the apply dispatcher when a mutation carries a type the engine does
+ * 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 declare class UnsupportedMutationTypeError extends Error {
+    #private;
+    constructor(mutationType: string);
+    get code(): 'KB12';
+    get mutationType(): string;
+}
+/**
+ * Thrown by the apply path when a mutation's payload fails its model's schema
+ * validation. The payload is a fixed property of the signed mutation, so this
+ * 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 declare class MutationSchemaValidationError extends Error {
+    #private;
+    constructor(docID: string, options?: {
+        cause?: unknown;
+    });
+    get code(): 'KB13';
+    get docID(): string;
+}
+/**
+ * Thrown at mutation-mint time when a `set`/`change` mutation would carry a
+ * malformed reserved `accessPermissions` field. Minting is strict so a producer
+ * bug is caught at signing; the receive/apply path stays tolerant (an already
+ * signed remote mutation is never re-rejected on this basis, so convergence is
+ * preserved). Not tagged with a KB apply code because it never reaches the apply
+ * path — it fails before the mutation is signed.
+ */
+export declare class InvalidAccessPermissionsError extends Error {
+    constructor(detail?: string);
+}
+/**
+ * True when `err` carries a protocol error code identifying a deterministically
+ * permanent mutation reject. A permanent reject is one the sender cannot fix by
+ * resending (bad signature/access, malformed payload, immutable-property
+ * violation), so the apply path persists a `rejected` log row for it. Anything
+ * else — a transient store/db failure — is excluded so it stays retryable.
+ */
+export declare function isPermanentApplyError(err: unknown): boolean;

package/lib/errors.js

@@ -1 +1,159 @@
-export class WriteAccessDeniedError extends Error{code="KB07";docID;constructor(e){super(`Access denied: cannot write document ${e}`),this.name="WriteAccessDeniedError",this.docID=e}}
+/**
+ * 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;
+    constructor(docID){
+        super(`Access denied: cannot write document ${docID}`);
+        this.name = 'WriteAccessDeniedError';
+        this.#docID = docID;
+    }
+    get code() {
+        return 'KB07';
+    }
+    get docID() {
+        return this.#docID;
+    }
+}
+/**
+ * Thrown by the set apply path when the document ID in `sub` does not match the
+ * ID deterministically derived from the document's model, owner, and unique
+ * value. This binds owner↔ID so a writer cannot claim a document ID that does
+ * not hash from their own owner identity, preventing an attacker from squatting
+ * 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;
+    constructor(docID){
+        super(`Document ID mismatch: ${docID} is not bound to its owner and unique value`);
+        this.name = 'DocumentIDMismatchError';
+        this.#docID = docID;
+    }
+    get code() {
+        return 'KB09';
+    }
+    get docID() {
+        return this.#docID;
+    }
+}
+/**
+ * Thrown by the mutation apply path when an incoming mutation's HLC timestamp
+ * sits further in the future than the allowed drift bound. A signed timestamp
+ * 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 {
+    #driftMS;
+    #maxDriftMS;
+    constructor(driftMS, maxDriftMS){
+        super(`HLC timestamp too far in the future: ${driftMS}ms drift exceeds ${maxDriftMS}ms limit`);
+        this.name = 'HLCDriftError';
+        this.#driftMS = driftMS;
+        this.#maxDriftMS = maxDriftMS;
+    }
+    get code() {
+        return 'KB10';
+    }
+    get driftMS() {
+        return this.#driftMS;
+    }
+    get maxDriftMS() {
+        return this.#maxDriftMS;
+    }
+}
+/**
+ * Thrown by the set apply path when a mutation would reassign an existing
+ * document's owner. Ownership is immutable once a document exists, so this is a
+ * 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;
+    constructor(docID, fromOwner, toOwner){
+        super(`Cannot change owner from ${fromOwner} to ${toOwner} in document: ${docID}`);
+        this.name = 'OwnerChangeError';
+        this.#docID = docID;
+    }
+    get code() {
+        return 'KB11';
+    }
+    get docID() {
+        return this.#docID;
+    }
+}
+/**
+ * Thrown by the apply dispatcher when a mutation carries a type the engine does
+ * 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 {
+    #mutationType;
+    constructor(mutationType){
+        super(`Unsupported mutation type: ${mutationType}`);
+        this.name = 'UnsupportedMutationTypeError';
+        this.#mutationType = mutationType;
+    }
+    get code() {
+        return 'KB12';
+    }
+    get mutationType() {
+        return this.#mutationType;
+    }
+}
+/**
+ * Thrown by the apply path when a mutation's payload fails its model's schema
+ * validation. The payload is a fixed property of the signed mutation, so this
+ * 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;
+    constructor(docID, options){
+        super(`Mutation payload failed model schema validation for document ${docID}`, options);
+        this.name = 'MutationSchemaValidationError';
+        this.#docID = docID;
+    }
+    get code() {
+        return 'KB13';
+    }
+    get docID() {
+        return this.#docID;
+    }
+}
+/**
+ * Thrown at mutation-mint time when a `set`/`change` mutation would carry a
+ * malformed reserved `accessPermissions` field. Minting is strict so a producer
+ * bug is caught at signing; the receive/apply path stays tolerant (an already
+ * signed remote mutation is never re-rejected on this basis, so convergence is
+ * preserved). Not tagged with a KB apply code because it never reaches the apply
+ * path — it fails before the mutation is signed.
+ */ export class InvalidAccessPermissionsError extends Error {
+    constructor(detail){
+        super(`Invalid accessPermissions shape${detail != null ? `: ${detail}` : ''}`);
+        this.name = 'InvalidAccessPermissionsError';
+    }
+}
+const PERMANENT_APPLY_ERROR_CODES = new Set([
+    'KB07',
+    'KB09',
+    'KB10',
+    'KB11',
+    'KB12',
+    'KB13'
+]);
+/**
+ * True when `err` carries a protocol error code identifying a deterministically
+ * permanent mutation reject. A permanent reject is one the sender cannot fix by
+ * resending (bad signature/access, malformed payload, immutable-property
+ * violation), so the apply path persists a `rejected` log row for it. Anything
+ * else — a transient store/db failure — is excluded so it stays retryable.
+ */ export function isPermanentApplyError(err) {
+    if (typeof err === 'object' && err != null && 'code' in err) {
+        const code = err.code;
+        return typeof code === 'string' && PERMANENT_APPLY_ERROR_CODES.has(code);
+    }
+    return false;
+}

package/lib/index.d.ts

@@ -3,6 +3,6 @@ export type { DocumentValidator, MutationContext, MutationDB, PostStateGate, Val
 export { applyChangeMutation, applyMutation, applySetMutation, getTopLevelField } from './apply.js';
 export type { CreateChangeMutationParams, CreateRemoveMutationParams, CreateSetMutationParams, } from './create.js';
 export { createChangeMutation, createRemoveMutation, createSetMutation } from './create.js';
-export { WriteAccessDeniedError } from './errors.js';
+export { DocumentIDMismatchError, HLCDriftError, InvalidAccessPermissionsError, isPermanentApplyError, MutationSchemaValidationError, OwnerChangeError, UnsupportedMutationTypeError, WriteAccessDeniedError, } from './errors.js';
 export type { CreateDocumentParams, CreateMutationOperationsParams, MutationOperations, RemoveDocumentParams, SetDocumentParams, UpdateDocumentParams, } from './operations.js';
 export { convertPatchInput, createMutationOperations } from './operations.js';

package/lib/index.js

@@ -1 +1,5 @@
-export{HLC}from"@kubun/hlc";export{applyChangeMutation,applyMutation,applySetMutation,getTopLevelField}from"./apply.js";export{createChangeMutation,createRemoveMutation,createSetMutation}from"./create.js";export{WriteAccessDeniedError}from"./errors.js";export{convertPatchInput,createMutationOperations}from"./operations.js";
+export { HLC } from '@kubun/hlc';
+export { applyChangeMutation, applyMutation, applySetMutation, getTopLevelField } from './apply.js';
+export { createChangeMutation, createRemoveMutation, createSetMutation } from './create.js';
+export { DocumentIDMismatchError, HLCDriftError, InvalidAccessPermissionsError, isPermanentApplyError, MutationSchemaValidationError, OwnerChangeError, UnsupportedMutationTypeError, WriteAccessDeniedError } from './errors.js';
+export { convertPatchInput, createMutationOperations } from './operations.js';

package/lib/operations.d.ts

@@ -1,11 +1,12 @@
-import type { GetRandomValues } from '@enkaku/runtime';
 import type { PatchOperation } from '@kubun/graphql';
 import type { HLC } from '@kubun/hlc';
 import type { ChangeDocumentMutation, DocumentData, SetDocumentMutation } from '@kubun/protocol';
+import type { GetRandomValues } from '@sozai/runtime';
 export type CreateMutationOperationsParams<T> = {
     issuer: string;
     hlc: HLC;
     getRandomValues: GetRandomValues;
+    owner?: string;
     cap?: string | Array<string>;
     processSetMutation(mutation: SetDocumentMutation, transactionID?: string | null): Promise<T>;
     processChangeMutation(mutation: ChangeDocumentMutation, transactionID?: string | null): Promise<T>;
@@ -14,12 +15,22 @@ export type CreateDocumentParams = {
     modelID: string;
     data: DocumentData;
     transactionID?: string | null;
+    /**
+     * Per-call document owner, overriding the ops-level owner for this write only.
+     * Omitted means owner = the ops-level owner (or the signer when unset).
+     */
+    owner?: string;
 };
 export type SetDocumentParams = {
     modelID: string;
     unique: Uint8Array;
     data: DocumentData;
     transactionID?: string | null;
+    /**
+     * Per-call document owner, overriding the ops-level owner for this write only.
+     * Omitted means owner = the ops-level owner (or the signer when unset).
+     */
+    owner?: string;
 };
 export type UpdateDocumentParams = {
     docID: string;

package/lib/operations.js

@@ -1 +1,61 @@
-import{createChangeMutation as t,createRemoveMutation as e,createSetMutation as r}from"./create.js";export function createMutationOperations(n){let{issuer:a,hlc:c,getRandomValues:u,cap:o,processSetMutation:i,processChangeMutation:m}=n;return{async createDocument({modelID:t,data:e,transactionID:n}){let m=u(new Uint8Array(12)),s=await r({issuer:a,hlc:c,modelID:t,data:e,unique:m,cap:o});return await i(s,n)},async setDocument({modelID:t,unique:e,data:n,transactionID:u}){let m=await r({issuer:a,hlc:c,modelID:t,data:n,unique:e,cap:o});return await i(m,u)},async updateDocument({docID:e,patch:r,transactionID:n}){let u=t({issuer:a,hlc:c,docID:e,patch:r,cap:o});return await m(u,n)},async removeDocument({docID:t,transactionID:r}){let n=e({docID:t,issuer:a,hlc:c,cap:o});return await m(n,r)}}}export function convertPatchInput(t){return t.map(t=>{let[e,r]=Object.entries(t)[0];return{...r,op:e}})}
+import { createChangeMutation, createRemoveMutation, createSetMutation } from './create.js';
+export function createMutationOperations(params) {
+    const { issuer, hlc, getRandomValues, owner, cap, processSetMutation, processChangeMutation } = params;
+    return {
+        async createDocument (params) {
+            const { modelID, data, transactionID } = params;
+            const unique = getRandomValues(new Uint8Array(12));
+            const mutation = await createSetMutation({
+                issuer,
+                hlc,
+                modelID,
+                data,
+                unique,
+                owner: params.owner ?? owner,
+                cap
+            });
+            return await processSetMutation(mutation, transactionID);
+        },
+        async setDocument (params) {
+            const { modelID, unique, data, transactionID } = params;
+            const mutation = await createSetMutation({
+                issuer,
+                hlc,
+                modelID,
+                data,
+                unique,
+                owner: params.owner ?? owner,
+                cap
+            });
+            return await processSetMutation(mutation, transactionID);
+        },
+        async updateDocument ({ docID, patch, transactionID }) {
+            const mutation = createChangeMutation({
+                issuer,
+                hlc,
+                docID,
+                patch,
+                cap
+            });
+            return await processChangeMutation(mutation, transactionID);
+        },
+        async removeDocument ({ docID, transactionID }) {
+            const mutation = createRemoveMutation({
+                docID,
+                issuer,
+                hlc,
+                cap
+            });
+            return await processChangeMutation(mutation, transactionID);
+        }
+    };
+}
+export function convertPatchInput(patch) {
+    return patch.map((p)=>{
+        const [op, rest] = Object.entries(p)[0];
+        return {
+            ...rest,
+            op
+        };
+    });
+}

package/package.json

@@ -1,39 +1,39 @@
 {
   "name": "@kubun/mutation",
-  "version": "0.10.1",
-  "license": "see LICENSE.md",
+  "version": "0.12.0",
   "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib/*",
     "LICENSE.md"
   ],
-  "sideEffects": false,
   "dependencies": {
-    "@enkaku/codec": "^0.16.0",
-    "@enkaku/patch": "^0.16.0",
-    "@enkaku/runtime": "^0.16.0",
-    "@enkaku/schema": "^0.16.0",
-    "@kubun/hlc": "^0.10.1",
-    "@kubun/id": "^0.10.0"
+    "@sozai/codec": "^0.4.0",
+    "@sozai/patch": "^0.1.3",
+    "@sozai/runtime": "^0.1.0",
+    "@sozai/schema": "^0.1.1",
+    "@kubun/hlc": "^0.12.0",
+    "@kubun/id": "^0.12.0"
   },
   "devDependencies": {
-    "@kubun/protocol": "^0.10.0",
-    "@kubun/graphql": "^0.10.1"
+    "@kubun/graphql": "^0.12.0",
+    "@kubun/protocol": "^0.12.0"
   },
   "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
-    "build:js": "swc src -d ./lib --config-file ../../swc.json --strip-leading-paths",
+    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
     "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
-    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit -p tsconfig.test.json",
-    "test:unit": "vitest run",
-    "test": "pnpm run test:types && pnpm run test:unit"
+    "test:unit": "vitest run"
   }
 }