@kubun/engine 0.10.3 → 0.12.0

package/lib/access-control.d.ts

@@ -1,4 +1,4 @@
-import { type VerifyTokenHook } from '@enkaku/capability';
+import { type VerifyTokenHook } from '@kokuin/capability';
 import type { DocumentNode } from '@kubun/protocol';
 import type { AccessLevel, StoredAccessRule } from '@kubun/store-graph';
 /**

package/lib/access-control.js

@@ -1 +1,250 @@
-import{checkCapability as e}from"@enkaku/capability";function r(e){return Array.isArray(e)&&e.every(e=>"string"==typeof e)?e:null}function l(e){var l;return e&&"object"==typeof e?"only_owner"!==(l=e.level)&&"anyone"!==l&&"restricted"!==l?null:{level:e.level,allowedDIDs:r(e.allowedDIDs),allowedCircles:r(e.allowedCircles),allowedGroups:r(e.allowedGroups)}:null}export function parseDocumentAccessPermissions(e){try{if(!e||"object"!=typeof e||!("accessPermissions"in e))return null;let r=e.accessPermissions;if(!r||"object"!=typeof r)return null;let t={},o=l(r.read);o&&(t.read=o);let n=l(r.write);return n&&(t.write=n),t}catch{return null}}export function validateDIDs(e){for(let r of e)if("string"!=typeof r||!r.startsWith("did:"))throw Error(`Invalid DID format: ${String(r)}`)}export function validateID(e,r){if("string"!=typeof e||0===e.trim().length)throw Error(`Invalid ${r} ID: must be a non-empty string`)}export function validateIDs(e,r){for(let l of e)validateID(l,r)}export async function resolveAccessRule(e,r,l,t,o,n){let a=parseDocumentAccessPermissions(e.data),i=a?.[t];if(null!=i&&("write"!==t||"anyone"!==i.level))return i;let s=await o.getUserModelAccessDefault(l,r,t);return s?{level:s.level,allowedDIDs:s.allowedDIDs,allowedCircles:s.allowedCircles,allowedGroups:s.allowedGroups}:{level:n[t],allowedDIDs:null,allowedCircles:null,allowedGroups:null}}async function t(r,l,t,o,n,a,i){if(!a||0===a.length)return!1;let s=await n.getModelInterfaces(t.model),u=[`urn:kubun:document:${t.id}`,`urn:kubun:model:${t.model}`,...s.map(e=>`urn:kubun:model:${e}`),`urn:kubun:user:${t.owner}`,"*"],c=`document/${o}`;for(let t of u)try{return await e({act:c,res:t},{iss:r,sub:l,cap:a},{atTime:i,verifyToken:n.revocationChecker}),!0}catch{}for(let t of a)for(let o of u)try{return await e({act:c,res:o},{iss:r,sub:l,cap:t},{atTime:i,verifyToken:n.revocationChecker}),!0}catch{}return!1}async function o(e,r,l,o,n,a,i){if(!r.owner)throw Error("Document missing owner field");if(e===r.owner)return!0;let s=await resolveAccessRule(r,r.model,r.owner,l,o,n);if("anyone"===s.level)return!0;if(!e)return!1;if("only_owner"===s.level)return await t(e,r.owner,r,l,o,a,i);if("restricted"===s.level){let n=s.allowedDIDs||[];if(n.includes(e)||"read"===l&&null!=s.allowedCircles&&s.allowedCircles.length>0&&await o.isMemberOfAnyCircle(e,s.allowedCircles)||"read"===l&&null!=s.allowedGroups&&s.allowedGroups.length>0&&await o.isMemberOfAnyGroup(e,s.allowedGroups))return!0;for(let s of n)if(await t(e,s,r,l,o,a,i))return!0}return!1}export function createAccessChecker(e){return async(r,l)=>await o(e.viewerDID,r,l,e.db,e.defaultAccessLevel,e.delegationTokens,e.atTime)}
+import { checkCapability } from '@kokuin/capability';
+// ---- Helpers ----
+/**
+ * Normalize a raw rule from persisted data into a runtime `AccessRule`.
+ *
+ * Empty arrays and missing fields both become `null`. Returns `null` if the
+ * input is not a well-formed rule object or carries an unknown `level`.
+ */ function stringArray(v) {
+    return Array.isArray(v) && v.every((item)=>typeof item === 'string') ? v : null;
+}
+function isAccessLevel(value) {
+    return value === 'only_owner' || value === 'anyone' || value === 'restricted';
+}
+function normalizeAccessRule(raw) {
+    if (!raw || typeof raw !== 'object') return null;
+    const rule = raw;
+    if (!isAccessLevel(rule.level)) return null;
+    return {
+        level: rule.level,
+        allowedDIDs: stringArray(rule.allowedDIDs),
+        allowedCircles: stringArray(rule.allowedCircles),
+        allowedGroups: stringArray(rule.allowedGroups)
+    };
+}
+/**
+ * Parse and validate access permissions from document data.
+ *
+ * Ensures every returned rule carries the `allowedGroups` field (defaulting
+ * to `null` when absent on input) and rejects rules with unknown `level`
+ * tokens.
+ */ export function parseDocumentAccessPermissions(data) {
+    try {
+        if (!data || typeof data !== 'object') return null;
+        if (!('accessPermissions' in data)) return null;
+        const perms = data.accessPermissions;
+        // Basic validation - check if the permission object has the expected structure
+        if (!perms || typeof perms !== 'object') {
+            return null;
+        }
+        const result = {};
+        const permsObj = perms;
+        const read = normalizeAccessRule(permsObj.read);
+        if (read) result.read = read;
+        const write = normalizeAccessRule(permsObj.write);
+        if (write) result.write = write;
+        return result;
+    } catch  {
+        return null;
+    }
+}
+/**
+ * Validate that DIDs have the correct format.
+ */ export function validateDIDs(dids) {
+    for (const did of dids){
+        if (typeof did !== 'string' || !did.startsWith('did:')) {
+            throw new Error(`Invalid DID format: ${String(did)}`);
+        }
+    }
+}
+/**
+ * Validate that an identifier (circle or group ID) is a non-empty,
+ * non-whitespace string. There is no canonical format helper for circle and
+ * group IDs in `@kubun/id` (they are app-supplied opaque strings — `@kubun/id`
+ * helpers cover content-addressed Kubun IDs only), so this check rejects only
+ * obvious garbage. Downstream membership checks won't match if the format is
+ * malformed beyond this — callers should treat malformed IDs as an empty
+ * scope.
+ */ export function validateID(id, kind) {
+    if (typeof id !== 'string' || id.trim().length === 0) {
+        throw new Error(`Invalid ${kind} ID: must be a non-empty string`);
+    }
+}
+/**
+ * Apply {@link validateID} to every entry of an array.
+ */ export function validateIDs(ids, kind) {
+    for (const id of ids){
+        validateID(id, kind);
+    }
+}
+/**
+ * Resolve the effective access rule for a document and permission type.
+ *
+ * Order of precedence:
+ * 1. Document accessPermissions override
+ * 2. User's model default from database
+ * 3. Server configuration default
+ *
+ * Document overrides with `'anyone'` on a `write` permission are rejected
+ * (anyone-write is not a valid configuration) and fall through to the next
+ * tier.
+ */ export async function resolveAccessRule(document, modelID, ownerDID, permissionType, db, defaultAccessLevel) {
+    // 1. Check document override
+    const docPerms = parseDocumentAccessPermissions(document.data);
+    const docRule = docPerms?.[permissionType];
+    if (docRule != null && !(permissionType === 'write' && docRule.level === 'anyone')) {
+        return docRule;
+    }
+    // 2. Check user's model default
+    const modelDefault = await db.getUserModelAccessDefault(ownerDID, modelID, permissionType);
+    if (modelDefault) {
+        return {
+            level: modelDefault.level,
+            allowedDIDs: modelDefault.allowedDIDs,
+            allowedCircles: modelDefault.allowedCircles,
+            allowedGroups: modelDefault.allowedGroups
+        };
+    }
+    // 3. Fall back to server default
+    const level = defaultAccessLevel[permissionType];
+    return {
+        level,
+        allowedDIDs: null,
+        allowedCircles: null,
+        allowedGroups: null
+    };
+}
+/**
+ * Check if viewer has access to document through delegation tokens.
+ */ async function checkDelegation(viewerDID, grantor, document, permissionType, db, delegationTokens, // Evaluate capability expiry at this time (epoch seconds) instead of now().
+// Lets a capability that was valid when a mutation was signed remain valid
+// across an offline sync delay, even if it has since expired.
+atTime) {
+    if (!delegationTokens || delegationTokens.length === 0) {
+        return false;
+    }
+    // Build expected permission based on specificity. Interface URNs sit between
+    // the concrete model and the user/wildcard tiers so a capability granted on
+    // an interface model authorizes mutations on any document whose concrete
+    // model implements that interface. `checkCapability` returns on the first
+    // matching resource, so order is efficiency only — any matching token
+    // authorizes regardless of position.
+    const interfaceIDs = await db.getModelInterfaces(document.model);
+    const resources = [
+        `urn:kubun:document:${document.id}`,
+        `urn:kubun:model:${document.model}`,
+        ...interfaceIDs.map((id)=>`urn:kubun:model:${id}`),
+        `urn:kubun:user:${document.owner}`,
+        '*'
+    ];
+    const action = `document/${permissionType}` // document/read or document/write
+    ;
+    // First, try tokens as a delegation chain (for A→B→C scenarios)
+    for (const res of resources){
+        try {
+            await checkCapability({
+                act: action,
+                res
+            }, {
+                iss: viewerDID,
+                sub: grantor,
+                cap: delegationTokens
+            }, {
+                atTime,
+                verifyToken: db.revocationChecker
+            });
+            return true;
+        } catch  {
+        // Token chain doesn't match this resource — continue
+        }
+    }
+    // If chain validation fails, try each token independently (for multiple independent grants)
+    for (const token of delegationTokens){
+        for (const res of resources){
+            try {
+                await checkCapability({
+                    act: action,
+                    res
+                }, {
+                    iss: viewerDID,
+                    sub: grantor,
+                    cap: token
+                }, {
+                    atTime,
+                    verifyToken: db.revocationChecker
+                });
+                return true;
+            } catch  {
+            // Token doesn't match this resource — continue
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Check if viewer has access to a document for the specified permission type.
+ */ async function checkAccess(viewerDID, document, permissionType, db, defaultAccessLevel, delegationTokens, // Evaluate capability expiry at this time (epoch seconds) instead of now().
+// Lets a capability that was valid when a mutation was signed remain valid
+// across an offline sync delay, even if it has since expired.
+atTime) {
+    // Validate document has owner
+    if (!document.owner) {
+        throw new Error('Document missing owner field');
+    }
+    // FAST PATH: Owner always has access
+    if (viewerDID === document.owner) {
+        return true;
+    }
+    // Resolve effective access rule
+    const rule = await resolveAccessRule(document, document.model, document.owner, permissionType, db, defaultAccessLevel);
+    // ANYONE: Always allow (read only — 'anyone' is never valid for write,
+    // so this branch only fires for read)
+    if (rule.level === 'anyone') {
+        return true;
+    }
+    // No viewer: Deny
+    if (!viewerDID) {
+        return false;
+    }
+    // ONLY_OWNER: Check delegation from owner
+    if (rule.level === 'only_owner') {
+        return await checkDelegation(viewerDID, document.owner, document, permissionType, db, delegationTokens, atTime);
+    }
+    // RESTRICTED: Check if viewer is in list, in a circle, or has delegation
+    if (rule.level === 'restricted') {
+        const allowedDIDs = rule.allowedDIDs || [];
+        if (allowedDIDs.includes(viewerDID)) {
+            return true;
+        }
+        // Check circle membership (read access only — circles don't grant write)
+        if (permissionType === 'read' && rule.allowedCircles != null && rule.allowedCircles.length > 0) {
+            if (await db.isMemberOfAnyCircle(viewerDID, rule.allowedCircles)) {
+                return true;
+            }
+        }
+        // Check group membership (read access only — groups don't grant write)
+        if (permissionType === 'read' && rule.allowedGroups != null && rule.allowedGroups.length > 0) {
+            if (await db.isMemberOfAnyGroup(viewerDID, rule.allowedGroups)) {
+                return true;
+            }
+        }
+        // Check if any allowedDID has delegated to viewer
+        for (const allowedDID of allowedDIDs){
+            if (await checkDelegation(viewerDID, allowedDID, document, permissionType, db, delegationTokens, atTime)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // Unknown access level
+    return false;
+}
+// ---- Public factory ----
+/**
+ * Create an access checker function bound to specific viewer, delegation tokens,
+ * database instance, and server default access level.
+ */ export function createAccessChecker(params) {
+    return async (doc, permissionType)=>{
+        return await checkAccess(params.viewerDID, doc, permissionType, params.db, params.defaultAccessLevel, params.delegationTokens, params.atTime);
+    };
+}

package/lib/catalog-match.js

@@ -1 +1,34 @@
-export async function catalogMatchesDoc(e,l,n){if(null!=e.models&&e.models.length>0&&!e.models.includes(l.model))return!1;let c=null!=e.owners&&e.owners.length>0,r=null!=e.circles&&e.circles.length>0;return!!(!c&&!r||c&&e.owners?.includes(l.owner)||r&&null!=e.circles&&await n.isMemberOfAnyCircle(l.owner,e.circles))}
+/**
+ * Determine whether a document matches a catalog's filter criteria.
+ *
+ * Each catalog field is AND'd, values within a field are OR'd, and the
+ * `circles` field expands to a union of circle members and merges with the
+ * explicit `owners` filter.
+ *
+ * Returns `true` iff the document would be included by this catalog.
+ */ export async function catalogMatchesDoc(criteria, doc, p2pStore) {
+    // Model filter: doc.model must be one of criteria.models (when specified).
+    if (criteria.models != null && criteria.models.length > 0) {
+        if (!criteria.models.includes(doc.model)) {
+            return false;
+        }
+    }
+    // Owner filter: union of explicit owners and circle members. When either
+    // `owners` or `circles` is specified, doc.owner must be in the union.
+    const hasExplicitOwners = criteria.owners != null && criteria.owners.length > 0;
+    const hasCircles = criteria.circles != null && criteria.circles.length > 0;
+    if (!hasExplicitOwners && !hasCircles) {
+        return true;
+    }
+    if (hasExplicitOwners && criteria.owners?.includes(doc.owner)) {
+        return true;
+    }
+    if (hasCircles && criteria.circles != null) {
+        // Single batched query: is the doc owner a member of ANY of the named
+        // circles? Replaces a per-circle `listCircleMembers` loop.
+        if (await p2pStore.isMemberOfAnyCircle(doc.owner, criteria.circles)) {
+            return true;
+        }
+    }
+    return false;
+}

package/lib/cipher.d.ts

@@ -0,0 +1,6 @@
+export type Cipher = {
+    encrypt(plaintext: string): string;
+    decrypt(ciphertext: string): string;
+};
+export declare function deriveAtRestKey(ikm: Uint8Array): Uint8Array;
+export declare function createDefaultCipher(key: Uint8Array): Cipher;

package/lib/cipher.js

@@ -0,0 +1,40 @@
+import { gcm } from '@noble/ciphers/aes.js';
+import { randomBytes } from '@noble/ciphers/utils.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { fromB64, fromUTF, toB64, toUTF } from '@sozai/codec';
+const ENVELOPE_PREFIX = 'v1:';
+const IV_LENGTH = 12;
+const KEY_LENGTH = 32;
+// HKDF-SHA-256 domain separation for keys used to protect data at rest.
+const AT_REST_SALT = fromUTF('kubun/at-rest');
+const AT_REST_INFO = fromUTF('v1');
+export function deriveAtRestKey(ikm) {
+    return hkdf(sha256, ikm, AT_REST_SALT, AT_REST_INFO, KEY_LENGTH);
+}
+export function createDefaultCipher(key) {
+    if (key.length !== KEY_LENGTH) {
+        throw new Error(`Cipher key must be ${KEY_LENGTH} bytes, received ${key.length}`);
+    }
+    return {
+        encrypt (plaintext) {
+            const iv = randomBytes(IV_LENGTH);
+            // gcm().encrypt appends the auth tag, so sealed = ciphertext || tag.
+            const sealed = gcm(key, iv).encrypt(fromUTF(plaintext));
+            const envelope = new Uint8Array(iv.length + sealed.length);
+            envelope.set(iv, 0);
+            envelope.set(sealed, iv.length);
+            return ENVELOPE_PREFIX + toB64(envelope);
+        },
+        decrypt (ciphertext) {
+            if (!ciphertext.startsWith(ENVELOPE_PREFIX)) {
+                throw new Error('Unrecognized cipher envelope, expected v1 prefix');
+            }
+            const envelope = fromB64(ciphertext.slice(ENVELOPE_PREFIX.length));
+            const iv = envelope.subarray(0, IV_LENGTH);
+            const sealed = envelope.subarray(IV_LENGTH);
+            // Wrong key or tampered bytes fail the GCM tag check and throw here.
+            return toUTF(gcm(key, iv).decrypt(sealed));
+        }
+    };
+}

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-events.js

@@ -1 +1,6 @@
-export{};
+/**
+ * Event types emitted by the engine during document operations.
+ *
+ * These events are emitted after successful mutations and can be
+ * observed by plugins or application code via the EngineEventBus.
+ */ export { };

package/lib/engine.d.ts

@@ -1,14 +1,17 @@
-import { type VerifyTokenHook } from '@enkaku/capability';
-import { type Runtime } from '@enkaku/runtime';
-import type { Identity } from '@enkaku/token';
+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';
+import { type PatchOperation } from '@kubun/graphql';
 import { type Logger } from '@kubun/logger';
-import type { DeployGraphParams, DeployGraphResult, DocumentNode, ExecuteGraphResult, ListGraphResult, LoadGraphParams, LoadGraphResult } from '@kubun/protocol';
+import type { DeployGraphParams, DeployGraphResult, DocumentData, DocumentNode, ExecuteGraphResult, ListGraphResult, LoadGraphParams, LoadGraphResult } from '@kubun/protocol';
 import { type DocumentMutation } from '@kubun/protocol';
 import { type GraphStoreAPI } from '@kubun/store-graph';
+import { type P2PStoreAPI } from '@kubun/store-p2p';
+import { type Runtime } from '@sozai/runtime';
 import type { GraphQLSchema } from 'graphql';
 import { type DefaultAccessLevel } from './access-control.js';
+import { type Cipher } from './cipher.js';
 import type { EngineEvents } from './engine-events.js';
 import { EngineEventBus } from './events.js';
 import type { Engine, EngineGraphParams, GraphQLSource, GraphQLSourceParams } from './executor.js';
@@ -67,6 +70,20 @@ export type EngineParams = {
      * unbounded so offline-first writes always apply. Defaults to one hour.
      */
     maxDriftMS?: number;
+    /**
+     * Maximum number of undelivered events buffered per subscription generator
+     * before the oldest are dropped. Guards against a slow subscriber growing
+     * memory without bound. Defaults to the GraphQL context default (1000).
+     */
+    maxSubscriptionQueueSize?: number;
+    /**
+     * Explicit at-rest cipher override. When omitted the engine derives one from
+     * an `OwnIdentity` (full identity carrying a `privateKey`), and leaves it
+     * undefined for read-only identities. The app/CLI wiring layer is responsible
+     * for building an env-key-based cipher (e.g. from `KUBUN_AT_REST_KEY`) and
+     * passing it here — the engine itself never reads `process.env`.
+     */
+    cipher?: Cipher;
 };
 /**
  * Optional pre-persist gate. Receives the synthesized post-apply
@@ -81,6 +98,25 @@ export type EngineParams = {
  * resulting decision through this hook.
  */
 export type AccessGate = (postState: DocumentNode) => boolean | Promise<boolean>;
+/**
+ * Transaction-scoped stores handed to an {@link AccessGateFactory} so the gate
+ * resolves access state through the apply transaction's connection.
+ */
+export type AccessGateStores = {
+    graphStore: GraphStoreAPI;
+    p2pStore?: P2PStoreAPI;
+};
+/**
+ * Builds an {@link AccessGate} bound to the apply transaction's stores.
+ *
+ * The apply runs inside a DB transaction; a gate that reads access state must
+ * read through that transaction, not a main-connection handle captured at
+ * construction time (which deadlocks on single-connection SQLite and reads a
+ * stale snapshot on Postgres). The engine invokes this factory with its
+ * transaction-scoped stores and uses the returned gate. Returning `undefined`
+ * skips the gate (apply proceeds).
+ */
+export type AccessGateFactory = (stores: AccessGateStores) => AccessGate | undefined;
 export type ApplyVerifiedMutationParams = {
     /** The signed mutation JWT token */
     token: string;
@@ -91,10 +127,12 @@ export type ApplyVerifiedMutationParams = {
      */
     origin?: 'local' | 'peer';
     /**
-     * Optional gate evaluated after compute, before persist + event emit.
-     * On deny: no DB write, no events, result returns `dropped: true`.
+     * Optional gate factory evaluated after compute, before persist + event emit.
+     * The engine invokes it with its transaction-scoped stores so gate reads run
+     * inside the apply transaction. On deny: no DB write, no events, result
+     * returns `dropped: true`.
      */
-    accessGate?: AccessGate;
+    accessGate?: AccessGateFactory;
     /**
      * MLS group the mutation was delivered through, on the broadcast receive
      * path; absent on merkle/RPC where the doc's groups are resolved by walk.
@@ -132,16 +170,46 @@ export type ApplyVerifiedMutationsParams = {
      */
     origin?: 'local' | 'peer';
     /**
-     * Optional gate evaluated per entry. Each entry's gate decision is
-     * independent — some entries may be applied while others are dropped.
+     * Optional gate factory evaluated per entry. The engine invokes it once with
+     * its transaction-scoped stores; each entry's gate decision is independent —
+     * some entries may be applied while others are dropped.
      */
-    accessGate?: AccessGate;
+    accessGate?: AccessGateFactory;
 };
 export type ApplyVerifiedMutationsResult = {
     results: Array<ApplyVerifiedMutationResult>;
     /** Count of entries dropped via the access gate. */
     dropped: number;
 };
+/**
+ * A single document write for `mutateDocuments`. The engine signs each write
+ * with its own identity, optionally on behalf of `owner`, and applies it inside
+ * one signed write transaction — no GraphQL text is parsed or executed.
+ */
+export type DocumentWrite = {
+    type: 'create';
+    modelID: string;
+    data: DocumentData;
+} | {
+    type: 'set';
+    modelID: string;
+    unique: Uint8Array;
+    data: DocumentData;
+} | {
+    type: 'update';
+    docID: string;
+    patch: Array<PatchOperation>;
+} | {
+    type: 'remove';
+    docID: string;
+};
+export type MutateDocumentsParams = {
+    /** DID the written documents are owned by; defaults to the signer. */
+    owner?: string;
+    /** Delegation tokens to attach, unioned with tokens this device holds. */
+    delegationTokens?: Array<string>;
+    writes: Array<DocumentWrite>;
+};
 export type ExecuteParams = {
     graphID: string;
     text: string;
@@ -158,7 +226,9 @@ export declare class KubunEngine implements Engine {
     get identity(): Identity;
     get eventBus(): EngineEventBus<EngineEvents>;
     /**
-     * Dispose the engine by shutting down all plugins in parallel.
+     * 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.
      */
     dispose(): Promise<void>;
     /**
@@ -180,6 +250,13 @@ export declare class KubunEngine implements Engine {
     deployGraph(params: DeployGraphParams): Promise<DeployGraphResult>;
     queryGraph<Data extends Record<string, unknown> = Record<string, unknown>>(params: EngineGraphParams): Promise<ExecuteGraphResult<Data>>;
     mutateGraph<Data extends Record<string, unknown> = Record<string, unknown>>(params: EngineGraphParams): Promise<ExecuteGraphResult<Data>>;
+    /**
+     * 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.
+     */
+    mutateDocuments(params: MutateDocumentsParams): Promise<Array<ApplyVerifiedMutationResult>>;
     subscribeToGraph<Data extends Record<string, unknown> = Record<string, unknown>>(params: EngineGraphParams): Promise<AsyncGenerator<ExecuteGraphResult<Data>> | ExecuteGraphResult<Data>>;
     getAPI<T extends Record<string, unknown> = Record<string, unknown>>(name: string): Promise<T>;
 }