@kubun/engine 0.10.3 → 0.11.0

package/lib/engine.js

@@ -1 +1,1511 @@
-import{createRevocationChecker as e}from"@enkaku/capability";import{createRuntime as t}from"@enkaku/runtime";import{asType as i,createValidator as s}from"@enkaku/schema";import{isSigningIdentity as r,stringifyToken as a,verifyToken as n}from"@enkaku/token";import{KubunDB as o}from"@kubun/db";import{createReadContext as l,createSchema as u}from"@kubun/graphql";import{HLC as c}from"@kubun/hlc";import{DocumentID as d}from"@kubun/id";import{getKubunLogger as h}from"@kubun/logger";import{applyMutation as p,convertPatchInput as m,createMutationOperations as g,WriteAccessDeniedError as f}from"@kubun/mutation";import{clusterToRecord as w,documentMutation as v,GraphModel as D}from"@kubun/protocol";import{GRAPH_STORE as y,getGraphStore as b,graphStoreDefinition as x}from"@kubun/store-graph";import{createP2PRevocationBackend as M,getP2PStore as I}from"@kubun/store-p2p";import{execute as C,GraphQLError as A,Kind as G,parse as k,subscribe as E,validate as S}from"graphql";import{createAccessChecker as R}from"./access-control.js";import{EngineEventBus as L}from"./events.js";import{checkMembership as F}from"./membership-check.js";import{computeMutationHash as O}from"./mutation-hash.js";import{runPolicies as T}from"./policies.js";import{createRegistry as j}from"./registry.js";let P=s(v);function U(e){if(null==e)return;let t=c.parse(e).wallTime;return Number.isFinite(t)?Math.floor(t/1e3):void 0}export function buildWriteAccessChecker(e){let{store:t,defaultAccessLevel:i,extraTokensByIssuer:s,revocationChecker:r}=e,a=new Map,n={getUserModelAccessDefault:(e,i,s)=>t.getUserModelAccessDefault(e,i,s),isMemberOfAnyGroup:async()=>!1,isMemberOfAnyCircle:async()=>!1,getModelInterfaces:async e=>{let i=a.get(e);if(null!=i)return i;let s=await t.getModelInterfaces(e);return a.set(e,s),s},revocationChecker:r};return(e,t)=>{var r;let a=(null==(r=t.cap)?void 0:Array.isArray(r)?r:[r])??[],o=s?.get(t.iss)??[],l=0===a.length&&0===o.length?void 0:[...a,...o];return R({viewerDID:t.iss,delegationTokens:l,db:n,defaultAccessLevel:i,atTime:U(t.hlc)})(e,"write")}}function q(){throw Error("Graph mutations require mutateGraph() — the core context does not sign or log writes. Use KubunEngine.mutateGraph() instead.")}function H(){throw Error("Access control mutations are not supported by the engine core — plugin override required.")}function B(){throw Error("Transaction mutations are not supported by the engine core — plugin override required (see plugin-rpc).")}let _={executeCreateMutation:q,executeSetMutation:q,executeUpdateMutation:q,executeRemoveMutation:q,executeSetModelAccessDefaults:H,executeRemoveModelAccessDefaults:H,executeSetDocumentAccessOverride:H,executeRemoveDocumentAccessOverride:H,beginTransaction:B,commitTransaction:B,rollbackTransaction:B};export class KubunEngine{#e=[];#t=[];#i;#s;#r;#a={};#n;#o;#l;#u;#c;#d={};#h=new Map;#p=[];#m;#g;#f={};#w={};constructor(e){this.#i=e.db instanceof o?e.db:new o({adapter:e.db}),this.#i.register(x),this.#l=e.identity,this.#s=e.defaultAccessLevel??{read:"anyone",write:"only_owner"},this.#n=new c({nodeID:e.identity.id}),this.#u=e.maxDriftMS??36e5,this.#c=e.logger??h("engine"),this.#r=e.eventBus??new L({logger:this.#c.getChild("events")}),this.#g=t(e.runtime),this.#m=j();let i=e.plugins??[],s={engine:this,graph:{execute:e=>this.#v(e),subscribe:e=>this.#D(e),applyVerifiedMutation:e=>this.#y(e),applyVerifiedMutations:e=>this.#b(e)},db:this.#i,runtime:this.#g,identity:this.#l,eventBus:this.#r,hlc:this.#n,getLogger:e=>this.#c.getChild(e)};for(let e of i){let t=e(s);this.#p.push(t),null!=t.api&&this.#m.registerPlugin(t.name,t.api)}this.#m.closeGate();let r=new Set;for(let e of this.#p){if(null!=e.schemaExtension&&this.#h.set(e.name,e.schemaExtension),null!=e.createContextFactory){if(r.has(e.name))throw Error(`Duplicate plugin namespace: ${e.name}`);r.add(e.name),this.#e.push({name:e.name,factory:e.createContextFactory()})}if(null!=e.policies)for(let[t,i]of Object.entries(e.policies)){null==this.#d[t]&&(this.#d[t]={sync:[],async:[]});let e=this.#d[t];null!=i.sync&&(e.sync=[...e.sync??[],...i.sync]),null!=i.async&&(e.async=[...e.async??[],...i.async])}}this.#c.info("engine initialized with {count} plugin(s)",{count:this.#p.length})}get did(){return this.#l.id}get identity(){return this.#l}get eventBus(){return this.#r}async dispose(){await Promise.all(this.#p.filter(e=>null!=e.dispose).map(e=>e.dispose?.()))}getGraphQLSource(e){let{graphID:t}=e,i=e.getViewerDID??(()=>this.#l.id);return{query:async e=>await this.queryGraph({id:t,text:e.text,variables:e.variables,viewerDID:i()??void 0}),mutate:async e=>await this.mutateGraph({id:t,text:e.text,variables:e.variables,viewerDID:i()??void 0}),subscribe:e=>this.#D({graphID:t,text:e.text,variables:e.variables,viewerDID:i()??void 0})}}registerContextFactory(e){this.#t.push(e)}async #x(){return await b(this.#i)}async #M(e){return null!=this.#o||(this.#o=(async()=>{let t=null!=e?await b(e):await this.#x(),i=await t.getMaxMutationHLC();if(null!=i){let e=c.parse(i),t=Date.now()+this.#u,s=Math.min(e.wallTime,t);this.#n.receive({...e,wallTime:s})}})()),await this.#o}async #I(t){var i;let s,r,a,n,o=t.viewerDID??this.#l.id,u=this.#C(o),c=t.stores??this.#i,d={};for(let{name:e,factory:t}of this.#e)d[e]=t(u,c);for(let e of this.#t)d={...d,...e(u,c)};null!=t.contextExtensions&&(d={...d,...t.contextExtensions});let h=await b(c);try{s=await I(c)}catch{s=void 0}if(null!=s){let t=s;r={getUserModelAccessDefault:(e,t,i)=>h.getUserModelAccessDefault(e,t,i),isMemberOfAnyGroup:(e,i)=>t.isMemberOfAnyGroup(e,i),isMemberOfAnyCircle:(e,i)=>t.isMemberOfAnyCircle(e,i),getModelInterfaces:e=>h.getModelInterfaces(e),revocationChecker:e(M(t))};let[i,n]=await Promise.all([t.getGroupsForMember(o),t.getCirclesForMember(o)]);a={viewerDID:o,groupIDs:i.map(e=>e.id),circleIDs:n.map(e=>e.id),serverDefault:this.#s.read}}else r={getUserModelAccessDefault:(e,t,i)=>h.getUserModelAccessDefault(e,t,i),isMemberOfAnyGroup:async()=>!1,isMemberOfAnyCircle:async()=>!1,getModelInterfaces:e=>h.getModelInterfaces(e)},a={viewerDID:o,groupIDs:[],circleIDs:[],serverDefault:this.#s.read};let p=R({viewerDID:o,db:r,defaultAccessLevel:this.#s});return n={...l({store:(i={store:h,viewerDID:o,eventBus:this.#r,accessChecker:p,viewerReadAccess:a,contextExtensions:Object.keys(d).length>0?d:void 0}).store,viewerDID:i.viewerDID,events:i.eventBus,accessChecker:i.accessChecker,viewerReadAccess:i.viewerReadAccess}),..._},null!=i.contextExtensions?{...n,...i.contextExtensions}:n}#C(e){return{viewerDID:e}}async #A(e){return null==this.#a[e]&&(this.#a[e]=this.#x().then(async t=>{let i=await t.getGraph(e);if(null==i)throw this.#c.warn("graph {id} not found",{id:e}),delete this.#a[e],Error(`Graph not found: ${e}`);return this.#c.debug("cached model for graph {id}",{id:e}),{aliases:i.aliases,record:i.record,extensionSDL:i.extension_sdl??void 0,pluginConfig:i.plugin_config??void 0}})),await this.#a[e]}async getGraphQLSchema(e){return null==this.#f[e]&&(this.#f[e]=this.#A(e).then(t=>{let i;if(null!=t.pluginConfig){let e={},s={},r={},a={},n={};for(let[i,o]of Object.entries(t.pluginConfig)){let t=this.#h.get(i);if(null!=t){let i=t(o);if(Object.assign(e,i.resolvers.queryFields??{}),Object.assign(s,i.resolvers.mutationFields??{}),Object.assign(r,i.resolvers.subscriptionFields??{}),Object.assign(n,i.resolvers.nodeResolvers??{}),null!=i.resolvers.typeFields)for(let[e,t]of Object.entries(i.resolvers.typeFields))a[e]={...a[e],...t}}}i={queryFields:e,mutationFields:s,subscriptionFields:r,typeFields:a,nodeResolvers:n}}let s=u({...t,extensionResolvers:i});return this.#c.debug("cached schema for graph {id}",{id:e}),s}).catch(t=>{throw delete this.#f[e],t})),await this.#f[e]}async #G(e){let t=k(e.text),i=this.#k(t),s=await this.#E(i,e.viewerDID??this.#l.id);if(null!=s)return{result:s};let r=await this.getGraphQLSchema(e.graphID),a=S(r,t);return a.length>0?{result:{errors:a}}:{document:t,schema:r}}async #S(e,t,i){if(null==t.definitions[0])throw Error("Missing GraphQL document definition");return{schema:i,document:t,contextValue:await this.#I(e),variableValues:e.variables}}#k(e){let t=e.definitions[0];return null!=t&&t.kind===G.OPERATION_DEFINITION?t.operation:"query"}async #E(e,t){let i=await T(this.#d,e,{viewerDID:t});return"issues"in i&&null!=i.issues&&i.issues.length>0?{errors:i.issues.map(e=>new A(e.message,{extensions:null!=e.path?{path:e.path}:void 0}))}:null}async listGraphs(){let e=await this.#x();return{graphs:(await e.listGraphs()).map(e=>({id:e.id,name:e.name}))}}async loadGraph(e){let t=await this.#A(e.id);return{aliases:t.aliases,record:t.record,extensionSDL:t.extensionSDL}}async deployGraph(e){let t,i,s={};for(let t of e.clusters)Object.assign(s,w(t));let r=D.fromClusters({clusters:s});if(null!=e.plugins){i=e.plugins;let s=[];for(let[e,t]of Object.entries(i)){let i=this.#h.get(e);if(null==i)throw Error(`Plugin "${e}" not found or does not provide schema extensions`);let r=i(t);s.push(r.sdl)}s.length>0&&(t=s.join("\n"))}let a=await this.#x(),n=await a.createGraph({id:e.id??this.#g.getRandomID(),name:e.name,record:r.record,extensionSDL:t,pluginConfig:i});delete this.#a[n],delete this.#f[n],this.#c.info("deployed graph {id}",{id:n});let o=await this.#A(n);return{id:n,aliases:o.aliases,record:o.record}}async #R(e,t){let i="local"===t?"engine:mutation:authored":"engine:mutation:received",s=e.filter(e=>!e.dropped),r=new Map,a=[];for(let e of s){let t=function(e){if(null==e.document)throw Error("Cannot classify a dropped mutation result");return null==e.previousDoc?"create":null===e.document.data?"remove":"update"}(e);a.push(t);let i=e.document.id,s=r.get(i);null==s&&(s={docID:i,hasCreate:!1,hasUpdate:!1,hasRemove:!1,lastUpdateResult:null,lastRemoveResult:null,lastResult:e},r.set(i,s)),s.lastResult=e,"create"===t?s.hasCreate=!0:"update"===t?(s.hasUpdate=!0,s.lastUpdateResult=e):(s.hasRemove=!0,s.lastRemoveResult=e)}for(let e of r.values()){if(e.hasCreate&&e.hasRemove)continue;let t=e.lastResult.document;if(e.hasRemove){let t=e.lastRemoveResult??e.lastResult,i=t.document;await this.#r.emit("engine:document:removed",{documentID:i.id,viewerDID:t.authorDID});continue}if(e.hasCreate&&await this.#r.emit("engine:document:created",{documentID:t.id,modelID:t.model,viewerDID:e.lastResult.authorDID}),e.hasUpdate){let t=e.lastUpdateResult??e.lastResult,i=t.document;await this.#r.emit("engine:document:updated",{documentID:i.id,modelID:i.model,viewerDID:t.authorDID})}let i={type:e.hasCreate&&!e.hasUpdate?"create":"update",document:t,previous:{data:e.lastResult.previousDoc?.data??null},getCursor:()=>t.id};await this.#r.emit("document:saved",i)}for(let e=0;e<s.length;e++){let t=s[e],r=t.document;await this.#r.emit(i,{type:a[e],documentID:r.id,viewerDID:t.authorDID,mutationJWT:t.token,version:t.mutation.hlc,modelID:r.model})}}#L(e,t,i){return buildWriteAccessChecker({store:e,defaultAccessLevel:this.#s,extraTokensByIssuer:t,revocationChecker:i})}async #y(t,s){let r,a,{token:o,accessGate:l}=t,u=t.origin??"local";await this.#M(s);let h=i(P,(await n(o)).payload),m=null!=s?await b(s):await this.#x(),g=s??this.#i,w=U(h.hlc)??Math.floor(Date.now()/1e3),v=new Map;try{a=await I(g);let t=await a.getHeldTokens({audience:h.iss,atTime:w});t.length>0&&v.set(h.iss,t.map(e=>e.token)),r=e(M(a))}catch{a=void 0}let D={store:m,validators:this.#w,hlc:this.#n,maxDriftMS:this.#u,checkWriteAccess:this.#L(m,v,r),postStateGate:l},y=await m.getDocument(d.fromString(h.sub));if(null!=a&&null!=y&&y.owner!==h.iss){let e=await F({p2pStore:a,graphStore:m,selfDID:this.did,iss:h.iss,mutationHLC:h.hlc,doc:y,arrivalGroupID:t.arrivalGroupID});if(!e.ok){if(this.#c.warn("mutation denied: issuer removed from group",{iss:h.iss,docID:y.id,mutationHLC:h.hlc,removedGroupID:e.removedGroupID,removedAtHLC:e.removedAtHLC,origin:u}),"peer"===u)return{document:null,previousDoc:y,mutation:h,authorDID:h.iss,hash:O(o),token:o,dropped:!0};throw new f(y.id)}}let x=await p(D,h);"local"!==u&&this.#n.receive(c.parse(h.hlc));let C=O(o),A=h.iss;if(null==x)return{document:null,previousDoc:y,mutation:h,authorDID:A,hash:C,token:o,dropped:!0};await m.insertMutationLogEntry({mutation_hash:C,model_id:x.model,document_id:x.id,author_did:A,hlc:h.hlc,mutation_jwt:o,status:"applied"});let G={document:x,previousDoc:y,mutation:h,authorDID:A,hash:C,token:o,dropped:!1};return null==s&&await this.#R([G],u),G}async #b(t){let{tokens:s,accessGate:r}=t,a=t.origin??"local";await this.#M();let o=await Promise.all(s.map(async e=>{let t=i(P,(await n(e)).payload);return{token:e,mutation:t}})),l=[];return await this.#i.withTransaction(async t=>{let i,s,n=await t.getStore(y),u=new Map,h=new Map,m=new Set,g=Math.floor(Date.now()/1e3);for(let{mutation:e}of o){let t=U(e.hlc);if(null==t){m.add(e.iss);continue}let i=h.get(e.iss);(null==i||t<i)&&h.set(e.iss,t)}for(let r of new Set(o.map(e=>e.mutation.iss))){let a=h.get(r),n=m.has(r)||null==a?Math.min(a??g,g):a;try{let a=await I(t);s=a;let o=await a.getHeldTokens({audience:r,atTime:n});o.length>0&&u.set(r,o.map(e=>e.token)),i??=e(M(a))}catch{}}let w=this.#L(n,u,i);for(let{token:e,mutation:t}of o){let i={store:n,validators:this.#w,hlc:this.#n,maxDriftMS:this.#u,checkWriteAccess:w,postStateGate:r},o=await n.getDocument(d.fromString(t.sub));if(null!=s&&null!=o&&o.owner!==t.iss){let e=await F({p2pStore:s,graphStore:n,selfDID:this.did,iss:t.iss,mutationHLC:t.hlc,doc:o,arrivalGroupID:void 0});if(!e.ok)throw this.#c.warn("mutation denied: issuer removed from group",{iss:t.iss,docID:o.id,mutationHLC:t.hlc,removedGroupID:e.removedGroupID,removedAtHLC:e.removedAtHLC,origin:a}),new f(o.id)}let u=await p(i,t);"local"!==a&&this.#n.receive(c.parse(t.hlc));let h=O(e);if(null==u){l.push({document:null,previousDoc:o,mutation:t,authorDID:t.iss,hash:h,token:e,dropped:!0});continue}await n.insertMutationLogEntry({mutation_hash:h,model_id:u.model,document_id:u.id,author_did:t.iss,hlc:t.hlc,mutation_jwt:e,status:"applied"}),l.push({document:u,previousDoc:o,mutation:t,authorDID:t.iss,hash:h,token:e,dropped:!1})}}),await this.#R(l,a),{results:l,dropped:l.filter(e=>e.dropped).length}}async #v(e){let t=await this.#G(e);if("result"in t)return t.result;let i=await this.#S(e,t.document,t.schema);return await C(i)}async #D(e){let t=await this.#G(e);if("result"in t)return t.result;let i=await this.#S(e,t.document,t.schema);return await E(i)}async queryGraph(e){let t=k(e.text);if("mutation"===this.#k(t))throw Error("queryGraph() does not accept mutation operations. Use mutateGraph() instead.");return await this.#v({graphID:e.id,text:e.text,variables:e.variables??{},viewerDID:e.viewerDID})}async mutateGraph(e){if(!r(this.#l))throw Error("mutateGraph requires a SigningIdentity");let t=this.#l,i=e.id;await this.getGraphQLSchema(i);let s=[],n=await this.#i.withTransaction(async r=>{let n=async e=>{let i=a(await t.signToken(e)),n=await this.#y({token:i},r);if(s.push(n),null==n.document)throw Error("Unexpected dropped mutation in mutateGraph (no gate configured)");return n.document},o=Math.floor(Date.now()/1e3),l=new Set(e.delegationTokens??[]);try{let e=await I(r);for(let i of(await e.getHeldTokens({audience:t.id,atTime:o})))l.add(i.token)}catch{}let u=l.size>0?Array.from(l):void 0;await this.#M(r);let c=g({issuer:t.id,hlc:this.#n,getRandomValues:this.#g.getRandomValues,cap:u,processSetMutation:e=>n(e),processChangeMutation:e=>n(e)});return await this.#v({graphID:i,text:e.text,variables:e.variables??{},viewerDID:e.viewerDID??t.id,stores:r,contextExtensions:{executeCreateMutation:async e=>await c.createDocument({modelID:e.modelID,data:e.data}),executeSetMutation:async e=>await c.setDocument({modelID:e.modelID,unique:e.unique,data:e.data}),executeUpdateMutation:async e=>await c.updateDocument({docID:e.input.id,patch:m(e.input.patch)}),executeRemoveMutation:async e=>{await c.removeDocument({docID:e.id})}}})});return await this.#R(s,"local"),n}async subscribeToGraph(e){return await this.#D({graphID:e.id,text:e.text,variables:e.variables??{},viewerDID:e.viewerDID})}async getAPI(e){return await this.#m.getAPI(e)}}
+import { createRevocationChecker } from '@kokuin/capability';
+import { isOwnIdentity, isSigningIdentity, stringifyToken, verifyToken } from '@kokuin/token';
+import { KubunDB } from '@kubun/db';
+import { createReadContext, createSchema } from '@kubun/graphql';
+import { HLC } from '@kubun/hlc';
+import { DocumentID } from '@kubun/id';
+import { getKubunLogger } from '@kubun/logger';
+import { applyMutation, convertPatchInput, createMutationOperations, WriteAccessDeniedError } from '@kubun/mutation';
+import { clusterToRecord, documentMutation, GraphModel } from '@kubun/protocol';
+import { createRevocationBackend, delegationStoreDefinition, getDelegationStore } from '@kubun/store-delegation';
+import { GRAPH_STORE, getGraphStore, graphStoreDefinition } from '@kubun/store-graph';
+import { getP2PStore, P2P_STORE } from '@kubun/store-p2p';
+import { createRuntime } from '@sozai/runtime';
+import { asType, createValidator } from '@sozai/schema';
+import { execute, GraphQLError, Kind, parse, subscribe, validate } from 'graphql';
+import { createAccessChecker } from './access-control.js';
+import { createDefaultCipher, deriveAtRestKey } from './cipher.js';
+import { isTransactionFatal, MutateGraphWriteRollback } from './errors.js';
+import { EngineEventBus } from './events.js';
+import { checkMembership } from './membership-check.js';
+import { computeMutationHash } from './mutation-hash.js';
+import { runPolicies } from './policies.js';
+import { createRegistry } from './registry.js';
+const validateMutation = createValidator(documentMutation);
+/**
+ * Normalize a mutation's `cap` field (a single token or an array) into the
+ * array shape the access checker expects, preserving absence as `undefined`.
+ */ function normalizeCap(cap) {
+    return cap == null ? undefined : Array.isArray(cap) ? cap : [
+        cap
+    ];
+}
+/**
+ * Derive a mutation's signing time as epoch seconds from its HLC string.
+ * Returns `undefined` when the HLC is missing or un-parseable so callers fall
+ * back to now() rather than failing the access check.
+ */ function mutationSigningTimeSeconds(hlc) {
+    if (hlc == null) return undefined;
+    const wallTimeMS = HLC.parse(hlc).wallTime;
+    return Number.isFinite(wallTimeMS) ? Math.floor(wallTimeMS / 1000) : undefined;
+}
+/**
+ * Build a write-access checker closure bound to a graph store. When provided,
+ * `extraTokensByIssuer` supplies additional delegation tokens held locally for
+ * a given issuer DID; they are unioned with the mutation's inline `cap` so
+ * server-side application can authorize a write whose held credentials live in
+ * the receiving peer's p2p store rather than on the wire.
+ *
+ * Exported (without `#`) so unit tests can construct the checker with a
+ * hand-built map and exercise the union math directly. The Engine method
+ * `#buildWriteAccessChecker` delegates to this helper.
+ */ export function buildWriteAccessChecker(params) {
+    const { store, defaultAccessLevel, extraTokensByIssuer, revocationChecker } = params;
+    // Per-closure cache: a single write-apply transaction enters this helper
+    // once and may resolve the same model's interface list multiple times
+    // (e.g. during delegation resource enumeration). Memoizing per call keeps
+    // the cost at one underlying store lookup per modelID. The cache is scoped
+    // to this closure so it never leaks across transactions.
+    const interfaceCache = new Map();
+    const writeAccessDB = {
+        getUserModelAccessDefault: (ownerDID, modelID, permissionType)=>store.getUserModelAccessDefault(ownerDID, modelID, permissionType),
+        isMemberOfAnyGroup: async ()=>false,
+        isMemberOfAnyCircle: async ()=>false,
+        getModelInterfaces: async (modelID)=>{
+            const cached = interfaceCache.get(modelID);
+            if (cached != null) return cached;
+            const fetched = await store.getModelInterfaces(modelID);
+            interfaceCache.set(modelID, fetched);
+            return fetched;
+        },
+        revocationChecker
+    };
+    return (doc, mutation)=>{
+        const inline = normalizeCap(mutation.cap) ?? [];
+        const extra = extraTokensByIssuer?.get(mutation.iss) ?? [];
+        const delegationTokens = inline.length === 0 && extra.length === 0 ? undefined : [
+            ...inline,
+            ...extra
+        ];
+        return createAccessChecker({
+            viewerDID: mutation.iss,
+            delegationTokens,
+            db: writeAccessDB,
+            defaultAccessLevel,
+            // Honor a capability that was valid when the mutation was signed, even
+            // if it has since expired during an offline sync delay. Falls back to
+            // now() when the HLC is missing or un-parseable.
+            atTime: mutationSigningTimeSeconds(mutation.hlc)
+        })(doc, 'write');
+    };
+}
+/**
+ * Find the operation definition in a parsed GraphQL document. A document may
+ * lead with fragment definitions (e.g. `fragment ... query ...`), so the
+ * operation is not necessarily `definitions[0]`. Returns `undefined` when the
+ * document contains no operation definition at all.
+ */ function getOperationDefinition(document) {
+    return document.definitions.find((definition)=>definition.kind === Kind.OPERATION_DEFINITION);
+}
+/**
+ * Classify an applied mutation result as a create, update, or remove based on
+ * the pre-apply snapshot and the post-apply document data. Shared by the
+ * per-doc dedup logic in `#emitMutationEvents` and kept as a module-level
+ * helper for clarity. Callers must filter out `dropped` results before
+ * classification — a dropped result has no post-state to classify.
+ */ function classifyMutationResult(result) {
+    if (result.document == null) {
+        throw new Error('Cannot classify a dropped mutation result');
+    }
+    if (result.previousDoc == null) {
+        return 'create';
+    }
+    if (result.document.data === null) {
+        return 'remove';
+    }
+    return 'update';
+}
+function graphMutationNotSupported() {
+    throw new Error('Graph mutations require mutateGraph() — the core context does not sign or log writes. Use KubunEngine.mutateGraph() instead.');
+}
+function accessControlNotSupported() {
+    throw new Error('Access control mutations are not supported by the engine core — plugin override required.');
+}
+function transactionNotSupported() {
+    throw new Error('Transaction mutations are not supported by the engine core — plugin override required (see plugin-rpc).');
+}
+const baseMutationStubs = {
+    executeCreateMutation: graphMutationNotSupported,
+    executeSetMutation: graphMutationNotSupported,
+    executeUpdateMutation: graphMutationNotSupported,
+    executeRemoveMutation: graphMutationNotSupported,
+    executeSetModelAccessDefaults: accessControlNotSupported,
+    executeRemoveModelAccessDefaults: accessControlNotSupported,
+    executeSetDocumentAccessOverride: accessControlNotSupported,
+    executeRemoveDocumentAccessOverride: accessControlNotSupported,
+    beginTransaction: transactionNotSupported,
+    commitTransaction: transactionNotSupported,
+    rollbackTransaction: transactionNotSupported
+};
+function createContext(params) {
+    const coreContext = {
+        ...createReadContext({
+            store: params.store,
+            viewerDID: params.viewerDID,
+            events: params.eventBus,
+            accessChecker: params.accessChecker,
+            viewerReadAccess: params.viewerReadAccess,
+            maxSubscriptionQueueSize: params.maxSubscriptionQueueSize
+        }),
+        ...baseMutationStubs
+    };
+    // Merge core context with any plugin context extensions
+    if (params.contextExtensions != null) {
+        return {
+            ...coreContext,
+            ...params.contextExtensions
+        };
+    }
+    return coreContext;
+}
+export class KubunEngine {
+    /**
+   * Plugin-scoped context factories. Each factory's return value is placed
+   * under `ctx[name]` at request time — structural collision safety.
+   */ #disposed = false;
+    #pluginContextFactories = [];
+    /**
+   * Imperative context factories from `registerContextFactory`. Flat-merged
+   * onto ctx. Escape hatch for test fixtures — not subject to the duplicate
+   * plugin namespace check.
+   */ #imperativeFactories = [];
+    #cipher;
+    #db;
+    #defaultAccessLevel;
+    #eventBus;
+    #graphModels = {};
+    #hlc;
+    #hlcFloorPromise;
+    #identity;
+    #maxDriftMS;
+    #maxSubscriptionQueueSize;
+    #logger;
+    #mergedPolicies = {};
+    #pluginExtensions = new Map();
+    #plugins = [];
+    #registry;
+    #runtime;
+    #schemas = {};
+    #validators = {};
+    constructor(params){
+        this.#db = params.db instanceof KubunDB ? params.db : new KubunDB({
+            adapter: params.db
+        });
+        this.#db.register(graphStoreDefinition);
+        this.#db.register(delegationStoreDefinition);
+        this.#identity = params.identity;
+        this.#cipher = params.cipher ?? (isOwnIdentity(params.identity) ? createDefaultCipher(deriveAtRestKey(params.identity.privateKey)) : undefined);
+        this.#defaultAccessLevel = params.defaultAccessLevel ?? {
+            read: 'anyone',
+            write: 'only_owner'
+        };
+        this.#hlc = new HLC({
+            nodeID: params.identity.id
+        });
+        this.#maxDriftMS = params.maxDriftMS ?? 3_600_000;
+        this.#maxSubscriptionQueueSize = params.maxSubscriptionQueueSize;
+        this.#logger = params.logger ?? getKubunLogger('engine');
+        this.#eventBus = params.eventBus ?? new EngineEventBus({
+            logger: this.#logger.getChild('events')
+        });
+        this.#runtime = createRuntime(params.runtime);
+        this.#registry = createRegistry();
+        // Synchronous initialization — no async #initialize needed
+        const pluginFactories = params.plugins ?? [];
+        // Build factory params
+        const factoryParams = {
+            engine: this,
+            graph: {
+                execute: (p)=>this.#execute(p),
+                subscribe: (p)=>this.#subscribe(p),
+                applyVerifiedMutation: (p)=>this.#applyVerifiedMutation(p),
+                applyVerifiedMutations: (p)=>this.#applyVerifiedMutations(p),
+                mutateDocuments: (p)=>this.mutateDocuments(p)
+            },
+            db: this.#db,
+            runtime: this.#runtime,
+            identity: this.#identity,
+            eventBus: this.#eventBus,
+            hlc: this.#hlc,
+            getLogger: (name)=>this.#logger.getChild(name),
+            cipher: this.#cipher
+        };
+        // Call all plugin factories
+        for (const factory of pluginFactories){
+            const plugin = factory(factoryParams);
+            this.#plugins.push(plugin);
+            // Register plugin API
+            if (plugin.api != null) {
+                this.#registry.registerPlugin(plugin.name, plugin.api);
+            }
+        }
+        // Close the gate — all factories returned, registry populated
+        this.#registry.closeGate();
+        // Collect extensions, context factories, and policies from plugins
+        const seenPluginNames = new Set();
+        for (const plugin of this.#plugins){
+            if (plugin.schemaExtension != null) {
+                this.#pluginExtensions.set(plugin.name, plugin.schemaExtension);
+            }
+            if (plugin.createContextFactory != null) {
+                if (seenPluginNames.has(plugin.name)) {
+                    throw new Error(`Duplicate plugin namespace: ${plugin.name}`);
+                }
+                seenPluginNames.add(plugin.name);
+                this.#pluginContextFactories.push({
+                    name: plugin.name,
+                    factory: plugin.createContextFactory()
+                });
+            }
+            if (plugin.policies != null) {
+                for (const [gateType, gate] of Object.entries(plugin.policies)){
+                    if (this.#mergedPolicies[gateType] == null) {
+                        this.#mergedPolicies[gateType] = {
+                            sync: [],
+                            async: []
+                        };
+                    }
+                    const merged = this.#mergedPolicies[gateType];
+                    if (gate.sync != null) {
+                        merged.sync = [
+                            ...merged.sync ?? [],
+                            ...gate.sync
+                        ];
+                    }
+                    if (gate.async != null) {
+                        merged.async = [
+                            ...merged.async ?? [],
+                            ...gate.async
+                        ];
+                    }
+                }
+            }
+        }
+        this.#logger.info('engine initialized with {count} plugin(s)', {
+            count: this.#plugins.length
+        });
+    }
+    get did() {
+        return this.#identity.id;
+    }
+    get identity() {
+        return this.#identity;
+    }
+    get eventBus() {
+        return this.#eventBus;
+    }
+    /**
+   * Dispose the engine by shutting down all plugins in reverse registration order.
+   * Second and subsequent calls are no-ops. Each plugin's disposal failure is
+   * logged but does not prevent remaining plugins from being disposed.
+   */ async dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        for(let i = this.#plugins.length - 1; i >= 0; i--){
+            const plugin = this.#plugins[i];
+            if (plugin.dispose != null) {
+                try {
+                    await plugin.dispose();
+                } catch (error) {
+                    this.#logger.error('plugin dispose failed', {
+                        pluginName: plugin.name,
+                        error
+                    });
+                }
+            }
+        }
+    }
+    /**
+   * Return a GraphQLSource bound to a specific graph (and optionally a viewer).
+   * The returned object delegates query/mutate/subscribe to the engine, injecting
+   * the graphID and viewerDID from the source params on each call.
+   */ getGraphQLSource(params) {
+        const { graphID } = params;
+        const getViewerDID = params.getViewerDID ?? (()=>this.#identity.id);
+        return {
+            query: async (opParams)=>{
+                return await this.queryGraph({
+                    id: graphID,
+                    text: opParams.text,
+                    variables: opParams.variables,
+                    viewerDID: getViewerDID() ?? undefined
+                });
+            },
+            mutate: async (opParams)=>{
+                return await this.mutateGraph({
+                    id: graphID,
+                    text: opParams.text,
+                    variables: opParams.variables,
+                    viewerDID: getViewerDID() ?? undefined
+                });
+            },
+            subscribe: (opParams)=>{
+                return this.#subscribe({
+                    graphID,
+                    text: opParams.text,
+                    variables: opParams.variables,
+                    viewerDID: getViewerDID() ?? undefined
+                });
+            }
+        };
+    }
+    /**
+   * Register a context factory that contributes per-request fields flatly to
+   * the GraphQL execution context. Escape hatch for test fixtures — not
+   * subject to the plugin-namespace collision check. Prefer `KubunPlugin`'s
+   * `createContextFactory` for plugin-scoped, namespaced contributions.
+   */ registerContextFactory(factory) {
+        this.#imperativeFactories.push(factory);
+    }
+    /**
+   * Get the graph store API. Lazily migrates on first access.
+   */ async #getGraphStore() {
+        return await getGraphStore(this.#db);
+    }
+    /**
+   * Floor the shared clock to the greatest HLC already in the mutation log,
+   * exactly once per engine instance. The engine constructor is synchronous, so
+   * this lazy read runs on the first write path instead. After a restart where
+   * the OS clock stepped backward, a freshly constructed HLC (`lastWallTime` 0)
+   * would mint a local timestamp below the node's own prior writes and lose
+   * last-writer-wins against its own history; observing the stored maximum via
+   * `receive()` advances the clock past it so a new local write out-orders
+   * everything currently stored. Reuses `receive()` (monotonic, idempotent) — no
+   * dedicated seed API. The memoized promise makes concurrent first-writes await
+   * a single floor read with no race.
+   */ async #ensureHLCFloored(provider) {
+        if (this.#hlcFloorPromise != null) {
+            return await this.#hlcFloorPromise;
+        }
+        this.#hlcFloorPromise = (async ()=>{
+            const store = provider != null ? await getGraphStore(provider) : await this.#getGraphStore();
+            const max = await store.getMaxMutationHLC();
+            if (max != null) {
+                // After a large backward clock step the stored max can exceed
+                // `now + maxDriftMS`. Flooring to it unclamped would push the clock past
+                // the drift bound, so the node's own next local write would then exceed
+                // the bound and be rejected by the uniform future-drift check. Cap the
+                // floored wall-time at the bound so local writes always pass; a remote
+                // HLC beyond the bound is already rejected at ingest, so the floor is the
+                // only source that needs clamping.
+                const parsed = HLC.parse(max);
+                const ceiling = Date.now() + this.#maxDriftMS;
+                const flooredWallTime = Math.min(parsed.wallTime, ceiling);
+                this.#hlc.receive({
+                    ...parsed,
+                    wallTime: flooredWallTime
+                });
+            }
+        })();
+        return await this.#hlcFloorPromise;
+    }
+    /**
+   * Build a fresh context for a single request, merging core context
+   * with all registered plugin context factories and any inline extensions.
+   */ async #buildRequestContext(params) {
+        const viewerDID = params.viewerDID ?? this.#identity.id;
+        const executionContext = this.#createExecutionContext(viewerDID);
+        const provider = params.stores ?? this.#db;
+        // Plugin-scoped factories: output goes under ctx[pluginName]
+        let extensions = {};
+        for (const { name, factory } of this.#pluginContextFactories){
+            extensions[name] = factory(executionContext, provider);
+        }
+        // Imperative factories: flat-merged (escape hatch)
+        for (const factory of this.#imperativeFactories){
+            extensions = {
+                ...extensions,
+                ...factory(executionContext, provider)
+            };
+        }
+        // Merge inline contextExtensions (from execute params, e.g. mutateGraph()
+        // injecting core mutation ops). Spreads last — intentional so inline ops
+        // can override plugin/imperative fields for a specific request. Keys here
+        // should not collide with plugin namespaces; collisions would silently
+        // overwrite plugin ctx. Current inline callers use engine-reserved names
+        // (`executeCreateMutation`, `executeSetMutation`, etc.).
+        if (params.contextExtensions != null) {
+            extensions = {
+                ...extensions,
+                ...params.contextExtensions
+            };
+        }
+        const store = await getGraphStore(provider);
+        // The P2P store is optional (e.g. light client): only its absence is caught
+        // here. Once it is present, membership-query failures propagate rather than
+        // being silently swallowed into a no-groups fallback.
+        let p2pStore;
+        try {
+            p2pStore = await getP2PStore(provider);
+        } catch  {
+            p2pStore = undefined;
+        }
+        // Delegation storage is core-registered and always present, so the read
+        // path's delegated-token revocation check is unconditional: a light client
+        // with no p2p store still holds delegation/revocation rows and must honor
+        // them when validating a delegated read chain.
+        const delegationStore = await getDelegationStore(provider);
+        const revocationChecker = createRevocationChecker(createRevocationBackend(delegationStore));
+        let accessControlDB;
+        let viewerReadAccess;
+        if (p2pStore != null) {
+            const memberStore = p2pStore;
+            accessControlDB = {
+                getUserModelAccessDefault: (ownerDID, modelID, permissionType)=>store.getUserModelAccessDefault(ownerDID, modelID, permissionType),
+                isMemberOfAnyGroup: (did, groupIDs)=>memberStore.isMemberOfAnyGroup(did, groupIDs),
+                isMemberOfAnyCircle: (did, circleIDs)=>memberStore.isMemberOfAnyCircle(did, circleIDs),
+                getModelInterfaces: (modelID)=>store.getModelInterfaces(modelID),
+                revocationChecker
+            };
+            const [groups, circles] = await Promise.all([
+                memberStore.getGroupsForMember(viewerDID),
+                memberStore.getCirclesForMember(viewerDID)
+            ]);
+            viewerReadAccess = {
+                viewerDID,
+                groupIDs: groups.map((group)=>group.id),
+                circleIDs: circles.map((circle)=>circle.id),
+                serverDefault: this.#defaultAccessLevel.read
+            };
+        } else {
+            // No P2P store: no group/circle memberships exist, so membership grants
+            // resolve to empty and the checker enforces only_owner and allowedDIDs
+            // rules correctly.
+            accessControlDB = {
+                getUserModelAccessDefault: (ownerDID, modelID, permissionType)=>store.getUserModelAccessDefault(ownerDID, modelID, permissionType),
+                isMemberOfAnyGroup: async ()=>false,
+                isMemberOfAnyCircle: async ()=>false,
+                getModelInterfaces: (modelID)=>store.getModelInterfaces(modelID),
+                revocationChecker
+            };
+            viewerReadAccess = {
+                viewerDID,
+                groupIDs: [],
+                circleIDs: [],
+                serverDefault: this.#defaultAccessLevel.read
+            };
+        }
+        const accessChecker = createAccessChecker({
+            viewerDID,
+            db: accessControlDB,
+            defaultAccessLevel: this.#defaultAccessLevel
+        });
+        return createContext({
+            store,
+            viewerDID,
+            eventBus: this.#eventBus,
+            accessChecker,
+            viewerReadAccess,
+            contextExtensions: Object.keys(extensions).length > 0 ? extensions : undefined,
+            maxSubscriptionQueueSize: this.#maxSubscriptionQueueSize
+        });
+    }
+    /**
+   * Create an ExecutionContext for a single request.
+   */ #createExecutionContext(viewerDID) {
+        return {
+            viewerDID
+        };
+    }
+    async #getGraphModel(id) {
+        if (this.#graphModels[id] == null) {
+            this.#graphModels[id] = this.#getGraphStore().then(async (store)=>{
+                const graph = await store.getGraph(id);
+                if (graph == null) {
+                    this.#logger.warn('graph {id} not found', {
+                        id
+                    });
+                    delete this.#graphModels[id];
+                    throw new Error(`Graph not found: ${id}`);
+                }
+                this.#logger.debug('cached model for graph {id}', {
+                    id
+                });
+                return {
+                    aliases: graph.aliases,
+                    record: graph.record,
+                    extensionSDL: graph.extension_sdl ?? undefined,
+                    pluginConfig: graph.plugin_config ?? undefined
+                };
+            }).catch((err)=>{
+                delete this.#graphModels[id];
+                throw err;
+            });
+        }
+        return await this.#graphModels[id];
+    }
+    async getGraphQLSchema(id) {
+        if (this.#schemas[id] == null) {
+            this.#schemas[id] = this.#getGraphModel(id).then((model)=>{
+                // Build extension resolvers from plugins if this graph has plugin config
+                let extensionResolvers;
+                if (model.pluginConfig != null) {
+                    const qf = {};
+                    const mf = {};
+                    const sf = {};
+                    const tf = {};
+                    const nr = {};
+                    for (const [pluginName, config] of Object.entries(model.pluginConfig)){
+                        const extensionFn = this.#pluginExtensions.get(pluginName);
+                        if (extensionFn != null) {
+                            const ext = extensionFn(config);
+                            Object.assign(qf, ext.resolvers.queryFields ?? {});
+                            Object.assign(mf, ext.resolvers.mutationFields ?? {});
+                            Object.assign(sf, ext.resolvers.subscriptionFields ?? {});
+                            Object.assign(nr, ext.resolvers.nodeResolvers ?? {});
+                            if (ext.resolvers.typeFields != null) {
+                                for (const [typeName, fields] of Object.entries(ext.resolvers.typeFields)){
+                                    tf[typeName] = {
+                                        ...tf[typeName],
+                                        ...fields
+                                    };
+                                }
+                            }
+                        }
+                    }
+                    extensionResolvers = {
+                        queryFields: qf,
+                        mutationFields: mf,
+                        subscriptionFields: sf,
+                        typeFields: tf,
+                        nodeResolvers: nr
+                    };
+                }
+                const schema = createSchema({
+                    ...model,
+                    extensionResolvers
+                });
+                this.#logger.debug('cached schema for graph {id}', {
+                    id
+                });
+                return schema;
+            }).catch((err)=>{
+                delete this.#schemas[id];
+                throw err;
+            });
+        }
+        return await this.#schemas[id];
+    }
+    /**
+   * Shared preparation for #execute and #subscribe: parse, run policies, then
+   * validate the document against the bound schema. Policies run before
+   * validation so a denied viewer receives the policy denial rather than a
+   * schema-validity probe. Returns the parsed document and the bound schema to
+   * proceed, or an ExecutionResult to short-circuit (policy denial or validation
+   * errors).
+   */ async #prepareOperation(params) {
+        const document = parse(params.text);
+        const operationType = this.#getOperationType(document);
+        const policyResult = await this.#runPolicies(operationType, params.viewerDID ?? this.#identity.id);
+        if (policyResult != null) {
+            return {
+                result: policyResult
+            };
+        }
+        const schema = await this.getGraphQLSchema(params.graphID);
+        const errors = validate(schema, document);
+        if (errors.length > 0) {
+            return {
+                result: {
+                    errors
+                }
+            };
+        }
+        return {
+            document,
+            schema
+        };
+    }
+    // `document` and `schema` are always produced by `#prepareOperation`, which has
+    // already validated the document against that schema. Requiring them here keeps
+    // the "validated before executed" invariant structural: there is no path to
+    // build execution args from an unvalidated document or a re-fetched schema.
+    async #getExecutionArgs(params, document, schema) {
+        if (getOperationDefinition(document) == null) {
+            throw new Error('Missing GraphQL operation definition');
+        }
+        return {
+            schema,
+            document,
+            contextValue: await this.#buildRequestContext(params),
+            variableValues: params.variables
+        };
+    }
+    /**
+   * Determine the GraphQL operation type from a parsed document.
+   * Returns 'query', 'mutation', or 'subscription'.
+   */ #getOperationType(document) {
+        const operation = getOperationDefinition(document);
+        return operation?.operation ?? 'query';
+    }
+    /**
+   * Run merged policies for the given gate type. Returns an ExecutionResult
+   * with errors if policies deny the operation, or null if allowed.
+   */ async #runPolicies(gateType, viewerDID) {
+        const policyContext = {
+            viewerDID
+        };
+        const result = await runPolicies(this.#mergedPolicies, gateType, policyContext);
+        if ('issues' in result && result.issues != null && result.issues.length > 0) {
+            return {
+                errors: result.issues.map((issue)=>new GraphQLError(issue.message, {
+                        extensions: issue.path != null ? {
+                            path: issue.path
+                        } : undefined
+                    }))
+            };
+        }
+        return null;
+    }
+    async listGraphs() {
+        const store = await this.#getGraphStore();
+        const graphs = await store.listGraphs();
+        return {
+            graphs: graphs.map((g)=>({
+                    id: g.id,
+                    name: g.name
+                }))
+        };
+    }
+    async loadGraph(params) {
+        const model = await this.#getGraphModel(params.id);
+        return {
+            aliases: model.aliases,
+            record: model.record,
+            extensionSDL: model.extensionSDL
+        };
+    }
+    async deployGraph(params) {
+        const clustersRecord = {};
+        for (const cluster of params.clusters){
+            Object.assign(clustersRecord, clusterToRecord(cluster));
+        }
+        const model = GraphModel.fromClusters({
+            clusters: clustersRecord
+        });
+        // Generate extension SDL from plugins
+        let extensionSDL;
+        let pluginConfig;
+        if (params.plugins != null) {
+            pluginConfig = params.plugins;
+            const sdlParts = [];
+            for (const [pluginName, config] of Object.entries(pluginConfig)){
+                const extensionFn = this.#pluginExtensions.get(pluginName);
+                if (extensionFn == null) {
+                    throw new Error(`Plugin "${pluginName}" not found or does not provide schema extensions`);
+                }
+                const ext = extensionFn(config);
+                sdlParts.push(ext.sdl);
+            }
+            if (sdlParts.length > 0) {
+                extensionSDL = sdlParts.join('\n');
+            }
+        }
+        const store = await this.#getGraphStore();
+        const id = await store.createGraph({
+            id: params.id ?? this.#runtime.getRandomID(),
+            name: params.name,
+            record: model.record,
+            extensionSDL,
+            pluginConfig
+        });
+        // The store write is additive (it accumulates models across deploys), so the
+        // in-memory model and schema must reflect the full merged graph, not just
+        // this call's clusters. Invalidate both caches and re-read the full graph
+        // from the store; the schema rebuilds lazily on the next getGraphQLSchema.
+        delete this.#graphModels[id];
+        delete this.#schemas[id];
+        this.#logger.info('deployed graph {id}', {
+            id
+        });
+        const full = await this.#getGraphModel(id);
+        return {
+            id,
+            aliases: full.aliases,
+            record: full.record
+        };
+    }
+    async #emitMutationEvents(results, origin) {
+        const mutationEventName = origin === 'local' ? 'engine:mutation:authored' : 'engine:mutation:received';
+        // Filter out results dropped by the access gate — they have no post-state
+        // and contribute nothing to events. This filter is the only behavioral
+        // difference for the no-gate hot path: when no gate is supplied, no
+        // entry is ever marked `dropped`, so this filter is a no-op pass-through.
+        const appliedResults = results.filter((r)=>!r.dropped);
+        const groups = new Map();
+        const classifications = [];
+        for (const result of appliedResults){
+            const type = classifyMutationResult(result);
+            classifications.push(type);
+            // applied results carry a non-null document — checked above by filter.
+            const document = result.document;
+            const docID = document.id;
+            let group = groups.get(docID);
+            if (group == null) {
+                group = {
+                    docID,
+                    hasCreate: false,
+                    hasUpdate: false,
+                    hasRemove: false,
+                    lastUpdateResult: null,
+                    lastRemoveResult: null,
+                    lastResult: result
+                };
+                groups.set(docID, group);
+            }
+            group.lastResult = result;
+            if (type === 'create') {
+                group.hasCreate = true;
+            } else if (type === 'update') {
+                group.hasUpdate = true;
+                group.lastUpdateResult = result;
+            } else {
+                group.hasRemove = true;
+                group.lastRemoveResult = result;
+            }
+        }
+        // Emit deduped lifecycle events per document.
+        for (const group of groups.values()){
+            // create + remove within the same batch cancel out — no lifecycle event
+            // fires for the doc. Mutation events still fire per result below.
+            if (group.hasCreate && group.hasRemove) {
+                continue;
+            }
+            // appliedResults guarantees non-null document on every group entry.
+            const lastDoc = group.lastResult.document;
+            if (group.hasRemove) {
+                const removeResult = group.lastRemoveResult ?? group.lastResult;
+                const removeDoc = removeResult.document;
+                await this.#eventBus.emit('engine:document:removed', {
+                    documentID: removeDoc.id,
+                    viewerDID: removeResult.authorDID
+                });
+                continue;
+            }
+            // No remove at this point — hasCreate and/or hasUpdate is true.
+            if (group.hasCreate) {
+                // First mutation classified as `create` determines create payload.
+                // `document.model` is stable across a batch so using lastResult's
+                // model is safe.
+                await this.#eventBus.emit('engine:document:created', {
+                    documentID: lastDoc.id,
+                    modelID: lastDoc.model,
+                    viewerDID: group.lastResult.authorDID
+                });
+            }
+            if (group.hasUpdate) {
+                const updateResult = group.lastUpdateResult ?? group.lastResult;
+                const updateDoc = updateResult.document;
+                await this.#eventBus.emit('engine:document:updated', {
+                    documentID: updateDoc.id,
+                    modelID: updateDoc.model,
+                    viewerDID: updateResult.authorDID
+                });
+            }
+            // document:saved: emit the net effect using the last result's snapshot.
+            // `type` is 'create' only when the doc was created and not updated
+            // afterwards within this batch; otherwise 'update' reflects the final
+            // state. We use lastResult's previousDoc to populate `previous.data` —
+            // this reflects the state immediately before the final mutation, which
+            // is what relation-tracking subscribers (e.g. edge-removed) need.
+            const savedType = group.hasCreate && !group.hasUpdate ? 'create' : 'update';
+            const savedEvent = {
+                type: savedType,
+                document: lastDoc,
+                previous: {
+                    data: group.lastResult.previousDoc?.data ?? null
+                },
+                getCursor: ()=>lastDoc.id
+            };
+            await this.#eventBus.emit('document:saved', savedEvent);
+        }
+        // Mutation events fire per applied result, in input order — no dedup here.
+        // Dropped entries contribute no mutation event (they were never applied).
+        for(let i = 0; i < appliedResults.length; i++){
+            const result = appliedResults[i];
+            const document = result.document;
+            await this.#eventBus.emit(mutationEventName, {
+                type: classifications[i],
+                documentID: document.id,
+                viewerDID: result.authorDID,
+                mutationJWT: result.token,
+                version: result.mutation.hlc,
+                modelID: document.model
+            });
+        }
+    }
+    /**
+   * Build the per-mutation write authorizer bound to a graph store. When a
+   * mutation's issuer is not the document owner, the write is allowed only if
+   * the mutation carries a valid delegation chain (`cap`) from the owner.
+   * Write enforcement never consults group/circle membership, so those checks
+   * are no-ops — only the model-default lookup (graph store) is needed.
+   *
+   * `extraTokensByIssuer`, when provided, supplies additional delegation tokens
+   * held locally for a given issuer (looked up once outside the closure). The
+   * checker unions them with the mutation's inline `cap` so server-side
+   * application can authorize a write whose held credentials live in the
+   * receiving peer's p2p store rather than on the wire.
+   */ #buildWriteAccessChecker(store, extraTokensByIssuer, revocationChecker) {
+        return buildWriteAccessChecker({
+            store,
+            defaultAccessLevel: this.#defaultAccessLevel,
+            extraTokensByIssuer,
+            revocationChecker
+        });
+    }
+    /**
+   * Verify a signed mutation JWT, apply it to the database, and capture it
+   * in the mutation log.
+   *
+   * When a StoreProvider is given, the caller owns the transaction and the
+   * post-commit emit: apply directly against the provider and return the
+   * result for the caller to emit. Without a provider this is the peer-ingest
+   * path: the read-modify-write (getDocument → membership → applyMutation →
+   * insertMutationLogEntry) is wrapped in a single DB transaction so a crash
+   * between updateFieldHLCs and saveDocument cannot advance a field HLC
+   * without its data, then events are emitted after the commit.
+   */ async #applyVerifiedMutation(params, provider) {
+        const origin = params.origin ?? 'local';
+        // Floor the clock to the stored mutation maximum once per engine, before
+        // any mint or receive on this path and before the no-provider transaction
+        // opens (a self-read inside the open transaction would deadlock on
+        // single-connection SQLite). Harmless before an ingest receive() (receive
+        // is monotonic); load-bearing for any local mint that reaches here.
+        await this.#ensureHLCFloored(provider);
+        // Verify the JWT signature and validate the payload before opening the
+        // transaction, mirroring the batch path which verifies upfront.
+        const verified = await verifyToken(params.token);
+        const mutation = asType(validateMutation, verified.payload);
+        // With a caller-supplied provider the caller owns both the transaction and
+        // the emit — apply directly and hand back the result.
+        if (provider != null) {
+            return await this.#applyVerifiedMutationBody(params, mutation, origin, provider);
+        }
+        // No provider: this is the real peer-ingest path. Wrap the apply body in a
+        // single transaction so the multi-statement read-modify-write commits
+        // atomically; all reads and writes route through the transaction provider
+        // `tx`, never the main connection — a separate read on single-connection
+        // SQLite would deadlock against the open write transaction.
+        const result = await this.#db.withTransaction(async (tx)=>{
+            return await this.#applyVerifiedMutationBody(params, mutation, origin, tx);
+        });
+        // Emit after the transaction commits, never inside — events for a mutation
+        // that rolled back must never fire. `#emitMutationEvents` filters dropped
+        // and null-document entries, so a membership-denied / gate-denied result is
+        // a no-op here.
+        await this.#emitMutationEvents([
+            result
+        ], origin);
+        return result;
+    }
+    /**
+   * Apply a verified mutation against an effective store provider and capture
+   * it in the mutation log, returning the result without emitting events.
+   * The caller (or the wrapping transaction in `#applyVerifiedMutation`) owns
+   * emission and transaction boundaries; every read and write here routes
+   * through the supplied `provider`.
+   */ async #applyVerifiedMutationBody(params, mutation, origin, provider) {
+        const { token, accessGate } = params;
+        // Get graph store and apply mutation. Validators cache is keyed by
+        // content-addressed modelID globally — no per-graph indirection.
+        const store = await getGraphStore(provider);
+        // Auto-attach delegation tokens this device holds for the mutation's
+        // issuer, and resolve the membership gate's p2p store. Single-issuer
+        // assumption: a single apply call carries exactly one issuer
+        // (`mutation.iss`); the per-issuer / per-time generalization for
+        // multi-mutation batches lives in the batch path.
+        const atTime = mutationSigningTimeSeconds(mutation.hlc) ?? Math.floor(Date.now() / 1000);
+        const extraTokensByIssuer = new Map();
+        // Delegation storage is core-registered and always present: held-token
+        // auto-attach and the revocation checker are unconditional. A light client
+        // with no p2p store still holds delegation grants and their revocations and
+        // must honor both on apply.
+        const delegationStore = await getDelegationStore(provider);
+        const held = await delegationStore.getHeldTokens({
+            audience: mutation.iss,
+            atTime
+        });
+        if (held.length > 0) {
+            extraTokensByIssuer.set(mutation.iss, held.map((row)=>row.token));
+        }
+        const revocationChecker = createRevocationChecker(createRevocationBackend(delegationStore));
+        // The MLS/membership gate is the only piece that needs the p2p store. Gate
+        // on store registration, not on whether the lookup throws. An unregistered
+        // p2p store is a light client with no membership to enforce, so the gate is
+        // legitimately skipped. A registered store that errors must propagate and
+        // fail the apply — swallowing it here would let a transient DB error open
+        // the membership gate and apply a removed/non-owner change.
+        let p2pStore;
+        if (provider.hasStore(P2P_STORE)) {
+            p2pStore = await getP2PStore(provider);
+        }
+        const mutationCtx = {
+            store,
+            validators: this.#validators,
+            hlc: this.#hlc,
+            maxDriftMS: this.#maxDriftMS,
+            checkWriteAccess: this.#buildWriteAccessChecker(store, extraTokensByIssuer, revocationChecker),
+            // Build the gate from this apply's transaction-scoped stores so its
+            // reads run inside the transaction. When no factory is supplied (or it
+            // returns undefined), apply.ts takes its existing no-gate branch.
+            postStateGate: accessGate?.({
+                graphStore: store,
+                p2pStore
+            })
+        };
+        // Snapshot the doc before apply so emitters can compute the correct
+        // event type (create vs update) and populate `previous.data`.
+        const previousDoc = await store.getDocument(DocumentID.fromString(mutation.sub));
+        // Membership gate: a peer removed from the doc's MLS group before (or at)
+        // the mutation's HLC can no longer write to it. Skipped for the light
+        // client (no p2p store), for creates (creator owns the new doc), and for
+        // owner self-writes (membership never gates the owner).
+        if (p2pStore != null && previousDoc != null && previousDoc.owner !== mutation.iss) {
+            const membership = await checkMembership({
+                p2pStore,
+                graphStore: store,
+                selfDID: this.did,
+                iss: mutation.iss,
+                mutationHLC: mutation.hlc,
+                doc: previousDoc,
+                arrivalGroupID: params.arrivalGroupID
+            });
+            if (!membership.ok) {
+                this.#logger.warn('mutation denied: issuer removed from group', {
+                    iss: mutation.iss,
+                    docID: previousDoc.id,
+                    mutationHLC: mutation.hlc,
+                    removedGroupID: membership.removedGroupID,
+                    removedAtHLC: membership.removedAtHLC,
+                    origin
+                });
+                if (origin === 'peer') {
+                    // Received from a peer: drop silently — no apply, no log, no events.
+                    return {
+                        document: null,
+                        previousDoc,
+                        mutation,
+                        authorDID: mutation.iss,
+                        hash: computeMutationHash(token),
+                        token,
+                        dropped: true
+                    };
+                }
+                throw new WriteAccessDeniedError(previousDoc.id);
+            }
+        }
+        const document = await applyMutation(mutationCtx, mutation);
+        // Advance the shared clock toward a remote observation's timestamp. A
+        // 'local' mutation's HLC was just minted by this.#hlc.now(), so receiving
+        // it back would double-bump the counter; only 'peer' origin is remote.
+        // Placed after applyMutation so a future-over-drift mutation (which
+        // throws inside applyMutation) never advances the clock. A mutation that
+        // passes drift but loses LWW still advances — it is a real observation. The
+        // anchor lets a local write issued right after ingesting an ahead-of-clock
+        // remote mutation win last-writer-wins instead of being silently lost.
+        if (origin !== 'local') {
+            this.#hlc.receive(HLC.parse(mutation.hlc));
+        }
+        const hash = computeMutationHash(token);
+        const authorDID = mutation.iss;
+        // Gate denied: no log insert, no events. Return the dropped result with
+        // pre-state preserved.
+        if (document == null) {
+            return {
+                document: null,
+                previousDoc,
+                mutation,
+                authorDID,
+                hash,
+                token,
+                dropped: true
+            };
+        }
+        // Capture to mutation log.
+        await store.insertMutationLogEntry({
+            mutation_hash: hash,
+            model_id: document.model,
+            document_id: document.id,
+            author_did: authorDID,
+            hlc: mutation.hlc,
+            mutation_jwt: token,
+            status: 'applied'
+        });
+        return {
+            document,
+            previousDoc,
+            mutation,
+            authorDID,
+            hash,
+            token,
+            dropped: false
+        };
+    }
+    /**
+   * Verify and apply multiple signed mutation JWTs atomically within a single
+   * database transaction. All tokens are verified upfront (fail fast); if any
+   * verification fails no mutations are applied. If any mutation application
+   * fails mid-transaction the entire batch is rolled back.
+   */ async #applyVerifiedMutations(params) {
+        const { tokens, accessGate } = params;
+        const origin = params.origin ?? 'local';
+        // Floor the clock to the stored mutation maximum once per engine, before the
+        // apply transaction opens. Done on the default store ahead of the write
+        // transaction to avoid a self-read inside the open transaction on
+        // single-connection SQLite. Harmless before ingest receive() (monotonic).
+        await this.#ensureHLCFloored();
+        // Verify all tokens upfront — fail fast before starting transaction
+        const verified = await Promise.all(tokens.map(async (token)=>{
+            const v = await verifyToken(token);
+            const mutation = asType(validateMutation, v.payload);
+            return {
+                token,
+                mutation
+            };
+        }));
+        // Apply all within a single DB transaction. Each entry's gate is
+        // evaluated independently inside apply.ts; a denied entry skips its
+        // own writes but does not affect siblings. The transaction still rolls
+        // back on actual errors (verify failures already happened above; this
+        // covers store-level failures).
+        const results = [];
+        await this.#db.withTransaction(async (tx)=>{
+            const txStore = await tx.getStore(GRAPH_STORE);
+            // Auto-attach held delegation tokens, grouped per issuer. Mixed-issuer
+            // batches are uncommon but legal: each issuer gets its own held-tokens
+            // lookup so issuer B's tokens are never unioned into issuer A's
+            // mutation. Read through the transaction provider `tx`, not the main
+            // connection — a separate read on single-connection SQLite would
+            // deadlock against the open write transaction.
+            //
+            // The per-issuer lookup `atTime` is the MIN signing time across that
+            // issuer's mutations. `getHeldTokens` filters `exp > atTime`, so a
+            // smaller `atTime` returns a broader (more permissive) set; the
+            // minimum signing time yields the widest superset that still bounds
+            // out tokens no mutation in this batch could possibly admit.
+            // Per-mutation expiry is then re-validated inside `checkCapability`
+            // via `mutationSigningTimeSeconds(mutation.hlc)` in the access
+            // checker, so a token that was valid at mutation A's signing time but
+            // expired by mutation B's signing time is admitted for A and rejected
+            // for B — preserving time-of-signing semantics symmetrically with
+            // mutateGraph. (A MAX strategy would incorrectly drop A's token from
+            // extras when any sibling mutation's signing time exceeded the
+            // token's exp.) If any of the issuer's mutations has a missing or
+            // un-parseable HLC, the per-mutation check falls back to now(), so
+            // the lookup must include now() as a candidate `atTime` to remain a
+            // superset; we MIN against now() in that case as well.
+            // Per-issuer try/catch keeps one issuer's p2p failure (light client,
+            // missing table, schema drift) from suppressing extras for other
+            // issuers; on failure that issuer falls back to `mutation.cap` only.
+            const extraTokensByIssuer = new Map();
+            const issuerAtTimes = new Map();
+            const issuerHasMissingHLC = new Set();
+            const fallbackNow = Math.floor(Date.now() / 1000);
+            for (const { mutation } of verified){
+                const t = mutationSigningTimeSeconds(mutation.hlc);
+                if (t == null) {
+                    issuerHasMissingHLC.add(mutation.iss);
+                    continue;
+                }
+                const prev = issuerAtTimes.get(mutation.iss);
+                if (prev == null || t < prev) {
+                    issuerAtTimes.set(mutation.iss, t);
+                }
+            }
+            // When the issuer has at least one parsed HLC, that mutation must use
+            // its signing-time atTime; the missing-HLC siblings (if any) use now().
+            // The widest superset is therefore the MIN of the two — and when every
+            // mutation has a missing HLC, only `now()` applies.
+            // Delegation storage is core-registered and always present, so held-token
+            // auto-attach and the revocation checker run unconditionally. Read through
+            // the transaction provider `tx` so the lookups run inside this batch's
+            // transaction.
+            const delegationStore = await getDelegationStore(tx);
+            const revocationChecker = createRevocationChecker(createRevocationBackend(delegationStore));
+            for (const iss of new Set(verified.map((v)=>v.mutation.iss))){
+                const minSigningTime = issuerAtTimes.get(iss);
+                const includeFallback = issuerHasMissingHLC.has(iss) || minSigningTime == null;
+                const atTime = includeFallback ? Math.min(minSigningTime ?? fallbackNow, fallbackNow) : minSigningTime;
+                const held = await delegationStore.getHeldTokens({
+                    audience: iss,
+                    atTime
+                });
+                if (held.length > 0) {
+                    extraTokensByIssuer.set(iss, held.map((row)=>row.token));
+                }
+            }
+            // The MLS/membership gate is the only piece that needs the p2p store. Gate
+            // on store registration, not on whether a lookup throws — mirrors the
+            // single-apply path. An unregistered p2p store is a light client with no
+            // membership to enforce, so the gate is legitimately skipped. A registered
+            // store that errors must propagate and fail the whole atomic batch —
+            // swallowing it here would let a transient DB error open the membership
+            // gate and apply removed/non-owner changes.
+            let p2pStore;
+            if (tx.hasStore(P2P_STORE)) {
+                p2pStore = await getP2PStore(tx);
+            }
+            const checkWriteAccess = this.#buildWriteAccessChecker(txStore, extraTokensByIssuer, revocationChecker);
+            // Build the gate once from the transaction-scoped stores so its reads run
+            // inside this transaction; reused for every entry's independent decision.
+            const postStateGate = accessGate?.({
+                graphStore: txStore,
+                p2pStore
+            });
+            for (const { token, mutation } of verified){
+                const mutationCtx = {
+                    store: txStore,
+                    validators: this.#validators,
+                    hlc: this.#hlc,
+                    maxDriftMS: this.#maxDriftMS,
+                    checkWriteAccess,
+                    // When no gate is supplied, omitted from ctx — apply.ts takes its
+                    // existing no-gate path.
+                    postStateGate
+                };
+                // Snapshot the doc before apply so emitters can compute the correct
+                // event type (create vs update) and populate `previous.data`.
+                const previousDoc = await txStore.getDocument(DocumentID.fromString(mutation.sub));
+                // Membership gate (RPC batch — walk resolution, no arrival group). A
+                // denial throws to abort the whole atomic batch. Skipped for the light
+                // client, creates, and owner self-writes (see single-apply path).
+                if (p2pStore != null && previousDoc != null && previousDoc.owner !== mutation.iss) {
+                    const membership = await checkMembership({
+                        p2pStore,
+                        graphStore: txStore,
+                        selfDID: this.did,
+                        iss: mutation.iss,
+                        mutationHLC: mutation.hlc,
+                        doc: previousDoc,
+                        arrivalGroupID: undefined
+                    });
+                    if (!membership.ok) {
+                        this.#logger.warn('mutation denied: issuer removed from group', {
+                            iss: mutation.iss,
+                            docID: previousDoc.id,
+                            mutationHLC: mutation.hlc,
+                            removedGroupID: membership.removedGroupID,
+                            removedAtHLC: membership.removedAtHLC,
+                            origin
+                        });
+                        throw new WriteAccessDeniedError(previousDoc.id);
+                    }
+                }
+                const document = await applyMutation(mutationCtx, mutation);
+                // Advance the shared clock toward a remote observation's timestamp.
+                // Mirror the single-apply path: skip 'local' (its HLC was just minted
+                // by this.#hlc.now()), advance for 'peer'. Placed after
+                // applyMutation so a future-over-drift mutation never advances the
+                // clock; a drift-ok mutation that loses LWW still advances.
+                if (origin !== 'local') {
+                    this.#hlc.receive(HLC.parse(mutation.hlc));
+                }
+                const hash = computeMutationHash(token);
+                if (document == null) {
+                    // Gate denied: no log insert, no event contribution. Pre-state on
+                    // disk is unchanged for this entry.
+                    results.push({
+                        document: null,
+                        previousDoc,
+                        mutation,
+                        authorDID: mutation.iss,
+                        hash,
+                        token,
+                        dropped: true
+                    });
+                    continue;
+                }
+                await txStore.insertMutationLogEntry({
+                    mutation_hash: hash,
+                    model_id: document.model,
+                    document_id: document.id,
+                    author_did: mutation.iss,
+                    hlc: mutation.hlc,
+                    mutation_jwt: token,
+                    status: 'applied'
+                });
+                results.push({
+                    document,
+                    previousDoc,
+                    mutation,
+                    authorDID: mutation.iss,
+                    hash,
+                    token,
+                    dropped: false
+                });
+            }
+        });
+        // Emit events after transaction commits — not inside, to avoid
+        // emitting events for mutations that may be rolled back. `#emitMutationEvents`
+        // filters dropped entries internally.
+        await this.#emitMutationEvents(results, origin);
+        return {
+            results,
+            dropped: results.filter((r)=>r.dropped).length
+        };
+    }
+    async #execute(params) {
+        const prepared = await this.#prepareOperation(params);
+        if ('result' in prepared) {
+            return prepared.result;
+        }
+        const args = await this.#getExecutionArgs(params, prepared.document, prepared.schema);
+        return await execute(args);
+    }
+    async #subscribe(params) {
+        const prepared = await this.#prepareOperation(params);
+        if ('result' in prepared) {
+            return prepared.result;
+        }
+        const args = await this.#getExecutionArgs(params, prepared.document, prepared.schema);
+        return await subscribe(args);
+    }
+    async queryGraph(params) {
+        const document = parse(params.text);
+        const operationType = this.#getOperationType(document);
+        if (operationType === 'mutation') {
+            throw new Error('queryGraph() does not accept mutation operations. Use mutateGraph() instead.');
+        }
+        return await this.#execute({
+            graphID: params.id,
+            text: params.text,
+            variables: params.variables ?? {},
+            viewerDID: params.viewerDID
+        });
+    }
+    /**
+   * Shared machinery for a signed write transaction: opens a write transaction,
+   * builds a `signAndApply` choke point that signs each mutation with this
+   * engine's identity and applies it, auto-attaches held delegation tokens as
+   * `cap`, floors the HLC, and exposes `MutationOperations` to a `drive`
+   * callback. After the transaction commits, mutation events are emitted.
+   *
+   * The `drive` callback consumes the operations and returns the transaction
+   * result. It may inspect `writeErrors` (populated when a `signAndApply` throw
+   * was swallowed by an inner layer, e.g. graphql-js) and throw
+   * `MutateGraphWriteRollback` to force a rollback while carrying a result out;
+   * that result is returned WITHOUT emitting events. Any other throw propagates
+   * after the transaction rolls back, also without emitting events.
+   */ async #signedWriteTransaction(params) {
+        if (!isSigningIdentity(this.#identity)) {
+            throw new Error('signed write requires a SigningIdentity');
+        }
+        const signingIdentity = this.#identity;
+        const mutationResults = [];
+        // Write failures recorded so the whole transaction can roll back even after
+        // an inner layer (e.g. graphql-js) has swallowed the throw. Only
+        // `signAndApply` (the write choke point) pushes here.
+        const writeErrors = [];
+        const transaction = async (tx)=>{
+            const signAndApply = async (mutation)=>{
+                const signed = await signingIdentity.signToken(mutation);
+                const jwt = stringifyToken(signed);
+                let applied;
+                try {
+                    applied = await this.#applyVerifiedMutation({
+                        token: jwt
+                    }, tx);
+                } catch (err) {
+                    // Record the failure so the transaction rolls back, then rethrow so an
+                    // inner layer (e.g. graphql-js) still records it in its errors.
+                    writeErrors.push(err);
+                    throw err;
+                }
+                mutationResults.push(applied);
+                // No `accessGate` is passed on this code path — `applied.document` is
+                // guaranteed non-null.
+                if (applied.document == null) {
+                    throw new Error('Unexpected dropped mutation in signed write (no gate configured)');
+                }
+                return applied.document;
+            };
+            // Auto-attach delegation tokens this device holds so a delegate can write
+            // to documents it does not own without the app passing tokens manually.
+            // Delegation storage is core-registered and always present. Read through
+            // the transaction provider `tx`, not the main connection: querying the
+            // main connection while this write transaction is open deadlocks on
+            // single-connection SQLite.
+            const atTime = Math.floor(Date.now() / 1000);
+            const capTokens = new Set(params.delegationTokens ?? []);
+            const delegationStore = await getDelegationStore(tx);
+            const held = await delegationStore.getHeldTokens({
+                audience: signingIdentity.id,
+                atTime
+            });
+            for (const row of held){
+                capTokens.add(row.token);
+            }
+            const cap = capTokens.size > 0 ? Array.from(capTokens) : undefined;
+            // Floor the clock to the stored mutation maximum before any local mint.
+            // `createMutationOperations` calls `hlc.now()` while building each
+            // mutation below, so the floor must complete first for a post-restart
+            // write to out-order the node's pre-restart writes under a backward clock.
+            await this.#ensureHLCFloored(tx);
+            const ops = createMutationOperations({
+                issuer: signingIdentity.id,
+                hlc: this.#hlc,
+                getRandomValues: this.#runtime.getRandomValues,
+                owner: params.owner,
+                cap,
+                processSetMutation: (mutation)=>signAndApply(mutation),
+                processChangeMutation: (mutation)=>signAndApply(mutation)
+            });
+            return await params.drive({
+                ops,
+                tx,
+                mutationResults,
+                writeErrors
+            });
+        };
+        let result;
+        try {
+            result = await this.#db.withTransaction(transaction);
+        } catch (err) {
+            // The transaction rolled back because a write failed. When the drive
+            // carried a result out on the rollback sentinel, return it WITHOUT
+            // emitting events — the writes were rolled back, so no event must fire.
+            // Any other error propagates, also without emitting events.
+            if (err instanceof MutateGraphWriteRollback) {
+                return err.result;
+            }
+            throw err;
+        }
+        // Emit events after transaction commits.
+        await this.#emitMutationEvents(mutationResults, 'local');
+        return result;
+    }
+    async mutateGraph(params) {
+        if (!isSigningIdentity(this.#identity)) {
+            throw new Error('mutateGraph requires a SigningIdentity');
+        }
+        const signingIdentity = this.#identity;
+        const graphID = params.id;
+        // Warm the schema/model cache before opening the write transaction. Building
+        // the schema reads the graph model from the main connection; doing that
+        // inside the transaction deadlocks on single-connection SQLite, where a read
+        // cannot run while the connection's own transaction is open.
+        await this.getGraphQLSchema(graphID);
+        return await this.#signedWriteTransaction({
+            owner: params.owner,
+            delegationTokens: params.delegationTokens,
+            drive: async ({ ops, tx, writeErrors })=>{
+                const executed = await this.#execute({
+                    graphID,
+                    text: params.text,
+                    variables: params.variables ?? {},
+                    viewerDID: params.viewerDID ?? signingIdentity.id,
+                    stores: tx,
+                    contextExtensions: {
+                        executeCreateMutation: async (p)=>{
+                            return await ops.createDocument({
+                                modelID: p.modelID,
+                                data: p.data,
+                                owner: p.owner
+                            });
+                        },
+                        executeSetMutation: async (p)=>{
+                            return await ops.setDocument({
+                                modelID: p.modelID,
+                                unique: p.unique,
+                                data: p.data,
+                                owner: p.owner
+                            });
+                        },
+                        executeUpdateMutation: async (p)=>{
+                            return await ops.updateDocument({
+                                docID: p.input.id,
+                                patch: convertPatchInput(p.input.patch)
+                            });
+                        },
+                        executeRemoveMutation: async (p)=>{
+                            await ops.removeDocument({
+                                docID: p.id
+                            });
+                        }
+                    }
+                });
+                // A plugin mutation resolver can mark its transaction fatal by throwing
+                // `TransactionFatalError`; graphql-js wraps that throw into a
+                // GraphQLError with `.originalError` set to the marker (one level deep),
+                // so scan both. This forces the same rollback path as a core-model write
+                // failure. Ordinary read/projection resolver errors (no marker) still
+                // commit, so a core-model batch's per-issuer partial success is
+                // preserved.
+                const pluginFatal = (executed.errors ?? []).some((e)=>isTransactionFatal(e) || isTransactionFatal(e.originalError));
+                // If any write resolver failed, force the whole transaction to roll back
+                // so no document is committed in part. The graphql result is carried out
+                // on the sentinel so the caller still receives the `errors` payload.
+                // `data` is nulled: the partial payload graphql-js built for the fields
+                // that ran before the failure refers to writes that did not persist, so
+                // surfacing it would be a phantom success for a caller that reads `data`
+                // without checking `errors`.
+                if (writeErrors.length > 0 || pluginFatal) {
+                    throw new MutateGraphWriteRollback({
+                        ...executed,
+                        data: null
+                    });
+                }
+                return executed;
+            }
+        });
+    }
+    /**
+   * Apply a batch of document writes signed by this engine's identity, all
+   * within a single signed write transaction. Unlike `mutateGraph` this does not
+   * parse or execute any GraphQL text — writes are driven directly onto the
+   * mutation operations. Returns the applied result for each write, in order.
+   */ async mutateDocuments(params) {
+        return await this.#signedWriteTransaction({
+            owner: params.owner,
+            delegationTokens: params.delegationTokens,
+            drive: async ({ ops, mutationResults })=>{
+                // Track how many results existed before this drive so only the writes
+                // applied here are returned (the accumulator is shared machinery).
+                const startIndex = mutationResults.length;
+                for (const write of params.writes){
+                    switch(write.type){
+                        case 'create':
+                            await ops.createDocument({
+                                modelID: write.modelID,
+                                data: write.data
+                            });
+                            break;
+                        case 'set':
+                            await ops.setDocument({
+                                modelID: write.modelID,
+                                unique: write.unique,
+                                data: write.data
+                            });
+                            break;
+                        case 'update':
+                            await ops.updateDocument({
+                                docID: write.docID,
+                                patch: write.patch
+                            });
+                            break;
+                        case 'remove':
+                            await ops.removeDocument({
+                                docID: write.docID
+                            });
+                            break;
+                    }
+                }
+                return mutationResults.slice(startIndex);
+            }
+        });
+    }
+    async subscribeToGraph(params) {
+        return await this.#subscribe({
+            graphID: params.id,
+            text: params.text,
+            variables: params.variables ?? {},
+            viewerDID: params.viewerDID
+        });
+    }
+    async getAPI(name) {
+        return await this.#registry.getAPI(name);
+    }
+}