@kubun/engine 0.11.0 → 0.12.0

package/lib/engine-events.d.ts

@@ -51,4 +51,28 @@ export type EngineEvents = {
         /** Document model ID. */
         modelID: string;
     };
+    /**
+     * Emitted when this peer sets its own model access-default for a
+     * (modelID, permissionType). Carries the full rule so a subscriber can
+     * replicate the owner's sharing policy to co-members without re-reading it.
+     */
+    'engine:access-default:set': {
+        ownerDID: string;
+        modelID: string;
+        permissionType: 'read' | 'write';
+        accessLevel: string;
+        allowedDIDs: Array<string> | null;
+        allowedCircles: Array<string> | null;
+        allowedGroups: Array<string> | null;
+        /** LWW anchor stamped by this peer. */
+        hlc: string;
+    };
+    /** Emitted when this peer removes its own model access-default(s). */
+    'engine:access-default:removed': {
+        ownerDID: string;
+        modelID: string;
+        permissionTypes: Array<'read' | 'write'>;
+        /** LWW anchor stamped by this peer. */
+        hlc: string;
+    };
 };

package/lib/engine.d.ts

@@ -1,4 +1,4 @@
-import { type VerifyTokenHook } from '@kokuin/capability';
+import type { VerifyTokenHook } from '@kokuin/capability';
 import type { Identity } from '@kokuin/token';
 import { KubunDB, type StoreProvider } from '@kubun/db';
 import type { Adapter } from '@kubun/db-adapter';

package/lib/engine.js

@@ -1,4 +1,3 @@
-import { createRevocationChecker } from '@kokuin/capability';
 import { isOwnIdentity, isSigningIdentity, stringifyToken, verifyToken } from '@kokuin/token';
 import { KubunDB } from '@kubun/db';
 import { createReadContext, createSchema } from '@kubun/graphql';
@@ -7,7 +6,7 @@ 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 { createDelegationRevocationChecker, 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';
@@ -124,6 +123,28 @@ function accessControlNotSupported() {
 function transactionNotSupported() {
     throw new Error('Transaction mutations are not supported by the engine core — plugin override required (see plugin-rpc).');
 }
+const ACCESS_LEVELS = new Set([
+    'only_owner',
+    'anyone',
+    'restricted'
+]);
+function assertAccessLevel(value) {
+    if (!ACCESS_LEVELS.has(value)) {
+        throw new Error(`Invalid access level: ${value}`);
+    }
+    return value;
+}
+function assertPermissionType(value) {
+    if (value !== 'read' && value !== 'write') {
+        throw new Error(`Invalid permission type: ${value}`);
+    }
+    return value;
+}
+/** Extract a document's stored `accessPermissions` object, or undefined. */ function readAccessPermissions(data) {
+    if (data == null) return undefined;
+    const perms = data.accessPermissions;
+    return perms != null && typeof perms === 'object' ? perms : undefined;
+}
 const baseMutationStubs = {
     executeCreateMutation: graphMutationNotSupported,
     executeSetMutation: graphMutationNotSupported,
@@ -181,6 +202,13 @@ export class KubunEngine {
     #maxSubscriptionQueueSize;
     #logger;
     #mergedPolicies = {};
+    /**
+   * Mutation field names declared non-transactional by a plugin schema
+   * extension. Populated as extensions are instantiated (schema build / deploy)
+   * and consulted by `mutateGraph` to decide whether to open the write
+   * transaction. Engine-wide: a field name marked here is non-transactional
+   * wherever it appears.
+   */ #nonTransactionalMutationFields = new Set();
     #pluginExtensions = new Map();
     #plugins = [];
     #registry;
@@ -447,7 +475,7 @@ export class KubunEngine {
         // 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));
+        const revocationChecker = createDelegationRevocationChecker(delegationStore);
         let accessControlDB;
         let viewerReadAccess;
         if (p2pStore != null) {
@@ -551,6 +579,9 @@ export class KubunEngine {
                         const extensionFn = this.#pluginExtensions.get(pluginName);
                         if (extensionFn != null) {
                             const ext = extensionFn(config);
+                            for (const field of ext.nonTransactionalMutationFields ?? []){
+                                this.#nonTransactionalMutationFields.add(field);
+                            }
                             Object.assign(qf, ext.resolvers.queryFields ?? {});
                             Object.assign(mf, ext.resolvers.mutationFields ?? {});
                             Object.assign(sf, ext.resolvers.subscriptionFields ?? {});
@@ -697,6 +728,9 @@ export class KubunEngine {
                     throw new Error(`Plugin "${pluginName}" not found or does not provide schema extensions`);
                 }
                 const ext = extensionFn(config);
+                for (const field of ext.nonTransactionalMutationFields ?? []){
+                    this.#nonTransactionalMutationFields.add(field);
+                }
                 sdlParts.push(ext.sdl);
             }
             if (sdlParts.length > 0) {
@@ -704,12 +738,24 @@ export class KubunEngine {
             }
         }
         const store = await this.#getGraphStore();
+        // The clusters ride the graph's own transaction rather than following it in
+        // a second pass. `createGraph` stores models one by one and loses the
+        // grouping, and the cluster is what lets a peer ship a model's definition to
+        // a device that lacks it — so a failure between the two writes leaves a graph
+        // that works locally and cannot be synced to a device that has never seen it.
         const id = await store.createGraph({
             id: params.id ?? this.#runtime.getRandomID(),
             name: params.name,
             record: model.record,
             extensionSDL,
-            pluginConfig
+            pluginConfig,
+            clusters: Object.fromEntries(Object.entries(clustersRecord).map(([clusterID, cluster])=>[
+                    clusterID,
+                    {
+                        definition: cluster,
+                        models: cluster.record
+                    }
+                ]))
         });
         // 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
@@ -931,7 +977,7 @@ export class KubunEngine {
         if (held.length > 0) {
             extraTokensByIssuer.set(mutation.iss, held.map((row)=>row.token));
         }
-        const revocationChecker = createRevocationChecker(createRevocationBackend(delegationStore));
+        const revocationChecker = createDelegationRevocationChecker(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
@@ -1124,7 +1170,7 @@ export class KubunEngine {
             // the transaction provider `tx` so the lookups run inside this batch's
             // transaction.
             const delegationStore = await getDelegationStore(tx);
-            const revocationChecker = createRevocationChecker(createRevocationBackend(delegationStore));
+            const revocationChecker = createDelegationRevocationChecker(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;
@@ -1277,6 +1323,29 @@ export class KubunEngine {
         });
     }
     /**
+   * The `cap` array a signed write carries: the caller-supplied delegation
+   * tokens plus every token this device holds for `audience` that is unexpired
+   * right now. Auto-attaching the held ones is what lets a delegate write to
+   * documents it does not own without the app passing tokens manually.
+   * Delegation storage is core-registered, so the store is always present.
+   * Returns `undefined` when there is nothing to attach.
+   *
+   * `provider` must be the provider the write itself runs against — the ambient
+   * write transaction where one is open, the root provider otherwise.
+   */ async #collectWriteCapabilities(params) {
+        const atTime = Math.floor(Date.now() / 1000);
+        const capTokens = new Set(params.delegationTokens ?? []);
+        const delegationStore = await getDelegationStore(params.provider);
+        const held = await delegationStore.getHeldTokens({
+            audience: params.audience,
+            atTime
+        });
+        for (const row of held){
+            capTokens.add(row.token);
+        }
+        return capTokens.size > 0 ? Array.from(capTokens) : undefined;
+    }
+    /**
    * 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
@@ -1322,23 +1391,14 @@ export class KubunEngine {
                 }
                 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({
+            // 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 cap = await this.#collectWriteCapabilities({
+                provider: tx,
                 audience: signingIdentity.id,
-                atTime
+                delegationTokens: params.delegationTokens
             });
-            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
@@ -1377,6 +1437,300 @@ export class KubunEngine {
         await this.#emitMutationEvents(mutationResults, 'local');
         return result;
     }
+    /**
+   * Collect the top-level field names selected by a mutation operation. Used to
+   * route the operation onto the transactional or non-transactional mutation
+   * path. A non-mutation operation yields no names.
+   *
+   * The operation text can come from any RPC client, so fragment spreads and
+   * inline fragments at the mutation root are resolved rather than skipped: a
+   * side-effecting field reachable only through `... on Mutation { ... }` or a
+   * named fragment must still route onto the non-transactional path, otherwise
+   * its network I/O runs inside the write transaction and a nested apply
+   * deadlocks on single-connection SQLite. This runs before GraphQL validation,
+   * so a missing or cyclic fragment must not throw or recurse forever.
+   */ #getRootMutationFieldNames(document) {
+        const operation = getOperationDefinition(document);
+        if (operation == null || operation.operation !== 'mutation') {
+            return [];
+        }
+        const fragments = new Map();
+        for (const definition of document.definitions){
+            if (definition.kind === Kind.FRAGMENT_DEFINITION && !fragments.has(definition.name.value)) {
+                // A duplicate fragment name is invalid GraphQL and rejected downstream;
+                // keeping the first makes collection deterministic until then.
+                fragments.set(definition.name.value, definition);
+            }
+        }
+        const names = [];
+        const expanded = new Set();
+        const collect = (selectionSet)=>{
+            for (const selection of selectionSet.selections){
+                switch(selection.kind){
+                    case Kind.FIELD:
+                        // Introspection meta-fields are not mutation fields: `__typename` at
+                        // the mutation root resolves to a string and mutates nothing, so
+                        // counting it makes a lone non-transactional field look like a
+                        // mixed operation and rejects it. Latent only because Apollo adds
+                        // `__typename` inside selection sets and not beside the root field.
+                        if (!selection.name.value.startsWith('__')) {
+                            names.push(selection.name.value);
+                        }
+                        break;
+                    case Kind.INLINE_FRAGMENT:
+                        collect(selection.selectionSet);
+                        break;
+                    case Kind.FRAGMENT_SPREAD:
+                        {
+                            const name = selection.name.value;
+                            if (expanded.has(name)) {
+                                break;
+                            }
+                            expanded.add(name);
+                            const fragment = fragments.get(name);
+                            if (fragment != null) {
+                                collect(fragment.selectionSet);
+                            }
+                            break;
+                        }
+                }
+            }
+        };
+        collect(operation.selectionSet);
+        return names;
+    }
+    /**
+   * Build the signed mutation operations exposed to a `mutateGraph` execution as
+   * `contextExtensions`. Shared by the transactional and non-transactional
+   * paths: `ops` and `provider` determine the transaction boundary (an ambient
+   * write transaction, or per-op autocommit), while `onAccessDefault` decides
+   * when access-default replication events fire (deferred to post-commit, or
+   * immediately). The signing identity and authorization are identical on both
+   * paths — only the transaction differs.
+   */ #buildGraphMutationContextExtensions(params) {
+        const { ops, provider, signingIdentity, onAccessDefault } = params;
+        return {
+            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
+                });
+            },
+            executeSetModelAccessDefaults: async (p)=>{
+                const permissionType = assertPermissionType(p.permissionType);
+                const accessLevel = assertAccessLevel(p.accessLevel);
+                // A device states only its own policy — the owner is always the
+                // signer, never a foreign DID from the request.
+                const ownerDID = signingIdentity.id;
+                const hlc = HLC.serialize(this.#hlc.now());
+                const store = await getGraphStore(provider);
+                await store.setUserModelAccessDefault({
+                    ownerDID,
+                    modelID: p.modelID,
+                    permissionType,
+                    accessLevel,
+                    allowedDIDs: p.allowedDIDs,
+                    allowedCircles: p.allowedCircles,
+                    allowedGroups: p.allowedGroups,
+                    hlc
+                });
+                await onAccessDefault({
+                    name: 'engine:access-default:set',
+                    data: {
+                        ownerDID,
+                        modelID: p.modelID,
+                        permissionType,
+                        accessLevel,
+                        allowedDIDs: p.allowedDIDs,
+                        allowedCircles: p.allowedCircles,
+                        allowedGroups: p.allowedGroups,
+                        hlc
+                    }
+                });
+                const [read, write] = await Promise.all([
+                    store.getUserModelAccessDefault(ownerDID, p.modelID, 'read'),
+                    store.getUserModelAccessDefault(ownerDID, p.modelID, 'write')
+                ]);
+                const permissions = {};
+                if (read != null) permissions.read = read;
+                if (write != null) permissions.write = write;
+                return {
+                    ownerDID,
+                    modelID: p.modelID,
+                    permissions
+                };
+            },
+            executeRemoveModelAccessDefaults: async (modelID, permissionTypes)=>{
+                const types = permissionTypes.map(assertPermissionType);
+                // One HLC stamps both the retained tombstone (the LWW anchor) and
+                // the replication event, so co-members reject a stale set by the
+                // same clock the local row carries.
+                const hlc = HLC.serialize(this.#hlc.now());
+                const store = await getGraphStore(provider);
+                await store.removeUserModelAccessDefaults(signingIdentity.id, modelID, types, hlc);
+                await onAccessDefault({
+                    name: 'engine:access-default:removed',
+                    data: {
+                        ownerDID: signingIdentity.id,
+                        modelID,
+                        permissionTypes: types,
+                        hlc
+                    }
+                });
+            },
+            executeSetDocumentAccessOverride: async (p)=>{
+                const permissionType = assertPermissionType(p.permissionType);
+                const accessLevel = assertAccessLevel(p.accessLevel);
+                const store = await getGraphStore(provider);
+                const existing = await store.getDocument(DocumentID.fromString(p.documentID));
+                if (existing == null) {
+                    throw new Error(`Document not found: ${p.documentID}`);
+                }
+                const current = readAccessPermissions(existing.data);
+                const nextPermissions = {
+                    ...current,
+                    [permissionType]: {
+                        level: accessLevel,
+                        allowedDIDs: p.allowedDIDs,
+                        allowedCircles: p.allowedCircles,
+                        allowedGroups: p.allowedGroups
+                    }
+                };
+                // Ride the signed update machinery so the override is a real
+                // logged, synced mutation subject to normal write authz.
+                return await ops.updateDocument({
+                    docID: p.documentID,
+                    patch: [
+                        {
+                            op: current == null ? 'add' : 'replace',
+                            path: '/accessPermissions',
+                            value: nextPermissions
+                        }
+                    ]
+                });
+            },
+            executeRemoveDocumentAccessOverride: async (documentID, permissionTypes)=>{
+                const types = permissionTypes.map(assertPermissionType);
+                const store = await getGraphStore(provider);
+                const existing = await store.getDocument(DocumentID.fromString(documentID));
+                if (existing == null) return;
+                const current = readAccessPermissions(existing.data);
+                if (current == null) return;
+                const next = {
+                    ...current
+                };
+                let changed = false;
+                for (const type of types){
+                    if (type in next) {
+                        delete next[type];
+                        changed = true;
+                    }
+                }
+                if (!changed) return;
+                const patch = Object.keys(next).length > 0 ? [
+                    {
+                        op: 'replace',
+                        path: '/accessPermissions',
+                        value: next
+                    }
+                ] : [
+                    {
+                        op: 'remove',
+                        path: '/accessPermissions'
+                    }
+                ];
+                await ops.updateDocument({
+                    docID: documentID,
+                    patch
+                });
+            }
+        };
+    }
+    /**
+   * Execute a mutation operation whose fields are all declared
+   * non-transactional. No outer write transaction is opened: the resolver runs
+   * against the root provider (autocommit), and each signed document write
+   * applies in its OWN transaction via `#applyVerifiedMutation` (the
+   * per-mutation durability path), emitting its own events. Access-default
+   * writes autocommit and emit immediately. There is no sync-wide rollback —
+   * side-effecting sync-shaped ops are convergent and retry-safe, so per-step
+   * atomicity (which each apply already owns) is the correct granularity.
+   *
+   * Signing and authorization are identical to the transactional path: writes
+   * are still owner-signed by this engine's identity with held delegation
+   * tokens auto-attached. Only the DB transaction boundary differs.
+   */ async #executeNonTransactionalMutation(params, signingIdentity) {
+        // Floor the clock to the stored mutation maximum before any local mint
+        // (autocommit document writes and access-default writes both mint below).
+        // Idempotent/memoized, so a following per-apply floor is a no-op.
+        await this.#ensureHLCFloored();
+        // Read against the root provider — there is no ambient transaction here.
+        const cap = await this.#collectWriteCapabilities({
+            provider: this.#db,
+            audience: signingIdentity.id,
+            delegationTokens: params.delegationTokens
+        });
+        // Each signed write applies in its own transaction (no ambient provider)
+        // and emits its own events — the same per-mutation durability the ingest
+        // path uses. No shared `mutationResults` accumulator / post-commit emit.
+        const signAndApply = async (mutation)=>{
+            const signed = await signingIdentity.signToken(mutation);
+            const jwt = stringifyToken(signed);
+            const applied = await this.#applyVerifiedMutation({
+                token: jwt
+            });
+            if (applied.document == null) {
+                throw new Error('Unexpected dropped mutation in non-transactional write (no gate configured)');
+            }
+            return applied.document;
+        };
+        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)
+        });
+        const contextExtensions = this.#buildGraphMutationContextExtensions({
+            ops,
+            provider: this.#db,
+            signingIdentity,
+            // No transaction to await — the store write already committed, so emit
+            // the replication event immediately.
+            onAccessDefault: (event)=>this.#eventBus.emit(event.name, event.data)
+        });
+        // No `stores` override: the plugin context factory and all reads use the
+        // root provider (autocommit), so nothing joins a transaction that is not open.
+        return await this.#execute({
+            graphID: params.id,
+            text: params.text,
+            variables: params.variables ?? {},
+            viewerDID: params.viewerDID ?? signingIdentity.id,
+            contextExtensions
+        });
+    }
     async mutateGraph(params) {
         if (!isSigningIdentity(this.#identity)) {
             throw new Error('mutateGraph requires a SigningIdentity');
@@ -1386,9 +1740,30 @@ export class KubunEngine {
         // 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.
+        // cannot run while the connection's own transaction is open. Warming also
+        // populates `#nonTransactionalMutationFields` (from the graph's plugin
+        // extensions), which the routing below reads.
         await this.getGraphQLSchema(graphID);
-        return await this.#signedWriteTransaction({
+        // Route side-effecting mutation fields (peer connect/sync, dance
+        // round-trips) OUTSIDE the write transaction. Such a resolver performs
+        // network I/O and/or opens its own per-step transactions; holding the outer
+        // write transaction across it would deadlock a nested apply on
+        // single-connection SQLite. The opt-out affects ONLY the transaction —
+        // signing and authorization are unchanged (see `#executeNonTransactionalMutation`).
+        const rootFields = this.#getRootMutationFieldNames(parse(params.text));
+        const nonTransactional = rootFields.filter((name)=>this.#nonTransactionalMutationFields.has(name));
+        if (nonTransactional.length > 0) {
+            if (nonTransactional.length !== rootFields.length) {
+                throw new Error(`A mutation operation cannot mix transactional and non-transactional fields: ${rootFields.join(', ')}`);
+            }
+            return await this.#executeNonTransactionalMutation(params, signingIdentity);
+        }
+        // Access-default writes are local policy, not signed document mutations, so
+        // they never ride `mutationResults`. Collect their replication events here
+        // and fire them after the transaction commits (below), alongside the same
+        // post-commit discipline the document events follow.
+        const accessDefaultEvents = [];
+        const result = await this.#signedWriteTransaction({
             owner: params.owner,
             delegationTokens: params.delegationTokens,
             drive: async ({ ops, tx, writeErrors })=>{
@@ -1398,34 +1773,16 @@ export class KubunEngine {
                     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
-                            });
+                    contextExtensions: this.#buildGraphMutationContextExtensions({
+                        ops,
+                        provider: tx,
+                        signingIdentity,
+                        // Transactional path: defer replication events so they fire only
+                        // after the write transaction commits (below).
+                        onAccessDefault: (event)=>{
+                            accessDefaultEvents.push(event);
                         }
-                    }
+                    })
                 });
                 // A plugin mutation resolver can mark its transaction fatal by throwing
                 // `TransactionFatalError`; graphql-js wraps that throw into a
@@ -1451,6 +1808,15 @@ export class KubunEngine {
                 return executed;
             }
         });
+        // Emit access-default replication events after the transaction commits. A
+        // rollback carries the sentinel result with `data === null`, so skip
+        // emission there — the rule write did not persist.
+        if (result.data != null) {
+            for (const event of accessDefaultEvents){
+                await this.#eventBus.emit(event.name, event.data);
+            }
+        }
+        return result;
     }
     /**
    * Apply a batch of document writes signed by this engine's identity, all

package/lib/errors.d.ts

@@ -10,8 +10,9 @@
  * (matching the RPC batch path) without throwing to the app.
  */
 export declare class MutateGraphWriteRollback extends Error {
-    readonly result: unknown;
+    #private;
     constructor(result: unknown);
+    get result(): unknown;
 }
 /**
  * Marker a plugin mutation resolver throws to force its whole `mutateGraph`
@@ -23,9 +24,12 @@ export declare class MutateGraphWriteRollback extends Error {
  * it and rolls back, matching the core-model write-failure path.
  */
 export declare class TransactionFatalError extends Error {
+    #private;
     constructor(message: string, options?: {
         cause?: unknown;
+        extensions?: Record<string, unknown>;
     });
+    get extensions(): Record<string, unknown> | undefined;
 }
 /** Whether `err` is a {@link TransactionFatalError} marker. */
 export declare function isTransactionFatal(err: unknown): boolean;

package/lib/errors.js

@@ -9,10 +9,14 @@
  * this sentinel out of the transaction callback makes the apply all-or-nothing
  * (matching the RPC batch path) without throwing to the app.
  */ export class MutateGraphWriteRollback extends Error {
-    result;
+    #result;
     constructor(result){
-        super('mutateGraph write resolver failed'), this.result = result;
+        super('mutateGraph write resolver failed');
         this.name = 'MutateGraphWriteRollback';
+        this.#result = result;
+    }
+    get result() {
+        return this.#result;
     }
 }
 /**
@@ -24,9 +28,23 @@
  * marker on any internal failure; `mutateGraph` scans the execution errors for
  * it and rolls back, matching the core-model write-failure path.
  */ export class TransactionFatalError extends Error {
+    /**
+   * Extensions to carry onto the `GraphQLError` graphql-js wraps this throw in.
+   *
+   * `locatedError` copies `originalError.extensions` when it builds that
+   * wrapper, so this is what lets a TYPED refusal — an access code an app
+   * matches on — survive a rollback. Without it, every refusal raised inside a
+   * wrapped body reaches the client as a bare message, and the only way to keep
+   * a code was to run the check before the `try`, which a check that must read
+   * the state it is refusing cannot do.
+   */ #extensions;
     constructor(message, options){
         super(message, options);
         this.name = 'TransactionFatalError';
+        this.#extensions = options?.extensions;
+    }
+    get extensions() {
+        return this.#extensions;
     }
 }
 /** Whether `err` is a {@link TransactionFatalError} marker. */ export function isTransactionFatal(err) {

package/lib/plugin.d.ts

@@ -14,6 +14,25 @@ import type { PolicyGateMap } from './policies.js';
 export type SchemaExtension = {
     sdl: string;
     resolvers: ExtensionResolvers;
+    /**
+     * Names of `Mutation` fields whose resolvers must run OUTSIDE `mutateGraph`'s
+     * write transaction. Side-effecting operations (peer connect/sync, dance
+     * round-trips) perform network I/O and/or open their own per-step
+     * transactions; wrapping them in the outer write transaction would hold the
+     * DB connection across a network round-trip and, on single-connection
+     * SQLite, deadlock a nested apply against the ambient transaction.
+     *
+     * The opt-out affects ONLY the DB transaction. Such resolvers still run
+     * through `mutateGraph`'s owner-signed authorization path and still receive
+     * the signed mutation operations (`executeCreateMutation`, etc.), which
+     * autocommit each write instead of sharing one ambient transaction. Store
+     * reads and writes route through the root provider, so nothing joins a
+     * transaction that is not open.
+     *
+     * A single mutation operation must not mix transactional and
+     * non-transactional root fields — the engine rejects such an operation.
+     */
+    nonTransactionalMutationFields?: Array<string>;
 };
 /**
  * Low-level graph operations available only to plugins.

package/package.json

@@ -1,55 +1,55 @@
 {
   "name": "@kubun/engine",
-  "version": "0.11.0",
-  "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": {
-    "@sozai/async": "^0.1.0",
-    "@kokuin/capability": "^0.1.0",
-    "@sozai/event": "^0.1.0",
-    "@sozai/runtime": "^0.1.0",
-    "@sozai/schema": "^0.1.0",
-    "@kokuin/token": "^0.1.1",
+    "@kokuin/capability": "^0.2.1",
+    "@kokuin/token": "^0.3.0",
     "@noble/ciphers": "^2.2.0",
     "@noble/hashes": "^2.2.0",
-    "@sozai/codec": "^0.1.0",
+    "@sozai/async": "^0.2.1",
+    "@sozai/codec": "^0.4.0",
+    "@sozai/event": "^0.1.3",
+    "@sozai/runtime": "^0.1.0",
+    "@sozai/schema": "^0.1.1",
     "graphql": "^16.14.2",
-    "@kubun/db": "^0.11.0",
-    "@kubun/graphql": "^0.11.0",
-    "@kubun/db-adapter": "^0.11.0",
-    "@kubun/protocol": "^0.11.0",
-    "@kubun/logger": "^0.11.0",
-    "@kubun/hlc": "^0.11.0",
-    "@kubun/store-delegation": "^0.11.0",
-    "@kubun/mutation": "^0.11.0",
-    "@kubun/store-graph": "^0.11.0",
-    "@kubun/store-p2p": "^0.11.0"
+    "@kubun/db": "^0.12.0",
+    "@kubun/hlc": "^0.12.0",
+    "@kubun/db-adapter": "^0.12.0",
+    "@kubun/logger": "^0.12.0",
+    "@kubun/graphql": "^0.12.0",
+    "@kubun/store-delegation": "^0.12.0",
+    "@kubun/mutation": "^0.12.0",
+    "@kubun/protocol": "^0.12.0",
+    "@kubun/store-graph": "^0.12.0",
+    "@kubun/store-p2p": "^0.12.0"
   },
   "devDependencies": {
-    "@testcontainers/postgresql": "^12.0.4",
-    "@kubun/db-postgres": "^0.11.0",
-    "@kubun/id": "^0.11.0",
-    "@kubun/test-utils": "^0.11.0"
+    "@testcontainers/postgresql": "^12.1.0",
+    "@kubun/id": "^0.12.0",
+    "@kubun/db-postgres": "^0.12.0",
+    "@kubun/test-utils": "^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 ../../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"
   }
 }