@kubun/engine 0.8.0

package/LICENSE.md

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: Paul Le Cam
+
+Source Code: https://github.com/PaulLeCam/kubun
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

package/lib/access-control.d.ts

@@ -0,0 +1,35 @@
+import type { KubunDB } from '@kubun/db';
+import type { DocumentNode } from '@kubun/protocol';
+export type AccessLevel = 'only_owner' | 'anyone' | 'allowed_dids';
+export type AccessRule = {
+    level: AccessLevel;
+    allowedDIDs: Array<string> | null;
+    allowedCircles: Array<string> | null;
+};
+export type AccessPermissions = {
+    read?: AccessRule;
+    write?: AccessRule;
+};
+export type DefaultAccessLevel = {
+    read: AccessLevel;
+    write: 'only_owner' | 'allowed_dids';
+};
+export type AccessChecker = (doc: DocumentNode, permissionType: 'read' | 'write') => Promise<boolean>;
+/**
+ * Parse and validate access permissions from document data.
+ */
+export declare function parseDocumentAccessPermissions(data: unknown): AccessPermissions | null;
+/**
+ * Validate that DIDs have the correct format.
+ */
+export declare function validateDIDs(dids: Array<string>): void;
+/**
+ * Create an access checker function bound to specific viewer, delegation tokens,
+ * database instance, and server default access level.
+ */
+export declare function createAccessChecker(params: {
+    viewerDID: string | undefined;
+    delegationTokens?: Array<string>;
+    db: KubunDB;
+    defaultAccessLevel: DefaultAccessLevel;
+}): AccessChecker;

package/lib/access-control.js

@@ -0,0 +1 @@
+import{checkCapability as e}from"@enkaku/capability";export function parseDocumentAccessPermissions(e){try{if(!e||"object"!=typeof e||!("accessPermissions"in e))return null;let l=e.accessPermissions;if("object"!=typeof l)return null;return l}catch{return null}}export function validateDIDs(e){for(let l of e)if(!l.startsWith("did:"))throw Error(`Invalid DID format: ${l}`)}async function l(e,l,r,n,t,o){let a=parseDocumentAccessPermissions(e.data);if(a?.[n]){var i;let e=a[n];if(e&&(i=e.level,"read"===n?"only_owner"===i||"anyone"===i||"allowed_dids"===i:"only_owner"===i||"allowed_dids"===i))return{level:e.level,allowedDIDs:e.allowedDIDs||null,allowedCircles:e.allowedCircles||null}}let s=await t.getUserModelAccessDefault(r,l,n);return s?{level:s.level,allowedDIDs:s.allowedDIDs,allowedCircles:null}:{level:o[n],allowedDIDs:null,allowedCircles:null}}async function r(l,r,n,t,o){if(!o||0===o.length)return!1;let a=[`urn:kubun:document:${n.id}`,`urn:kubun:model:${n.model}`,"*"],i=`document/${t}`;for(let n of a)try{return await e({act:i,res:n},{iss:l,sub:r,cap:o}),!0}catch{}for(let n of o)for(let t of a)try{return await e({act:i,res:t},{iss:l,sub:r,cap:n}),!0}catch{}return!1}async function n(e,n,t,o,a,i){if(!n.owner)throw Error("Document missing owner field");if(e===n.owner)return!0;let s=await l(n,n.model,n.owner,t,o,a);if("anyone"===s.level)return!0;if(!e)return!1;if("only_owner"===s.level)return await r(e,n.owner,n,t,i);if("allowed_dids"===s.level){let l=s.allowedDIDs||[];if(l.includes(e)||"read"===t&&null!=s.allowedCircles&&s.allowedCircles.length>0&&await o.isMemberOfAnyCircle(e,s.allowedCircles))return!0;for(let o of l)if(await r(e,o,n,t,i))return!0}return!1}export function createAccessChecker(e){return async(l,r)=>await n(e.viewerDID,l,r,e.db,e.defaultAccessLevel,e.delegationTokens)}

package/lib/engine-events.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 type EngineEvents = {
+    'engine:document:created': {
+        documentID: string;
+        modelID: string;
+        viewerDID: string;
+    };
+    'engine:document:updated': {
+        documentID: string;
+        modelID: string;
+        viewerDID: string;
+    };
+    'engine:document:removed': {
+        documentID: string;
+        viewerDID: string;
+    };
+    'engine:mutation:applied': {
+        type: 'create' | 'update' | 'remove';
+        documentID: string;
+        viewerDID: string;
+    };
+};

package/lib/engine-events.js

@@ -0,0 +1 @@
+export{};

package/lib/engine.d.ts

@@ -0,0 +1,122 @@
+import { type Runtime } from '@enkaku/runtime';
+import type { Identity } from '@enkaku/token';
+import { type DBParams, KubunDB } from '@kubun/db';
+import type { Adapter } from '@kubun/db-adapter';
+import { type Logger } from '@kubun/logger';
+import type { DeployGraphParams, DeployGraphResult, DocumentNode, ExecuteGraphResult, ListGraphResult, LoadGraphParams, LoadGraphResult } from '@kubun/protocol';
+import { type DocumentMutation } from '@kubun/protocol';
+import type { GraphQLSchema } from 'graphql';
+import type { Migration, Transaction } from 'kysely';
+import type { EngineEvents } from './engine-events.js';
+import { EngineEventBus } from './events.js';
+import type { Engine, EngineGraphParams, GraphQLSource, GraphQLSourceParams } from './executor.js';
+import type { KubunPlugin, PluginFactoryParams } from './plugin.js';
+export type { Engine };
+export type PluginMigrationContext = {
+    types: Adapter['types'];
+    functions: Adapter['functions'];
+};
+export type PluginMigrations = {
+    name: string;
+    migrations: Record<string, Migration> | ((context: PluginMigrationContext) => Record<string, Migration>);
+};
+/**
+ * Transactional context passed to the callback within ExecutionContext.transaction().
+ * Provides a Kysely transaction handle and buffered event emission.
+ */
+export type TransactionContext = {
+    /** Kysely transaction handle — same query builder API as Kysely<Database> */
+    db: Transaction<Record<string, unknown>>;
+    /** Emit an event that will be buffered until the transaction commits */
+    emit(name: string, data: unknown): void;
+};
+/**
+ * Per-request execution context provided to plugin operations.
+ * Only carries what's per-request — shared resources (identity, hlc, logger, etc.)
+ * are already captured in the plugin closure from PluginFactoryParams.
+ */
+export type ExecutionContext = {
+    viewerDID: string;
+    /** On-demand transaction factory — not created until called */
+    transaction<R>(fn: (tx: TransactionContext) => Promise<R>): Promise<R>;
+};
+/**
+ * A function that produces per-request context fields.
+ * Called by the engine for each execute()/subscribe() invocation.
+ */
+export type ContextFactory = (executionContext: ExecutionContext) => Record<string, unknown>;
+export type EngineParams = {
+    db: DBParams | KubunDB;
+    identity: Identity;
+    logger?: Logger;
+    runtime?: Partial<Runtime>;
+    /** Plugin factories — called with shared params, return plugin descriptors. */
+    plugins?: Array<(params: PluginFactoryParams) => KubunPlugin>;
+    eventBus?: EngineEventBus<EngineEvents>;
+};
+export type ApplyVerifiedMutationParams = {
+    /** The signed mutation JWT token */
+    token: string;
+    /** The graph ID (needed to resolve validators for the document model) */
+    graphID: string;
+};
+export type ApplyVerifiedMutationResult = {
+    /** The resulting document after mutation */
+    document: DocumentNode;
+    /** The verified mutation payload */
+    mutation: DocumentMutation;
+    /** The DID of the mutation author (from JWT issuer) */
+    authorDID: string;
+    /** BLAKE3 hash of the mutation JWT */
+    hash: string;
+};
+export type ApplyVerifiedMutationsParams = {
+    tokens: Array<string>;
+    graphID: string;
+};
+export type ApplyVerifiedMutationsResult = {
+    results: Array<ApplyVerifiedMutationResult>;
+};
+export type ExecuteParams = {
+    graphID: string;
+    text: string;
+    variables?: Record<string, unknown>;
+    viewerDID?: string;
+    contextExtensions?: Record<string, unknown>;
+};
+export declare class KubunEngine implements Engine {
+    #private;
+    constructor(params: EngineParams);
+    get did(): string;
+    get identity(): Identity;
+    get eventBus(): EngineEventBus<EngineEvents>;
+    /**
+     * Resolves when the engine has finished initializing (migrations, plugins, schema hooks).
+     * Consumers must await this before calling execute() or deploy().
+     */
+    get ready(): Promise<void>;
+    /**
+     * Dispose the engine by shutting down all plugins in parallel.
+     */
+    dispose(): Promise<void>;
+    /**
+     * 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: GraphQLSourceParams): GraphQLSource;
+    /**
+     * Register a context factory that contributes per-request fields to the
+     * GraphQL execution context. Each factory is called on every execute()/subscribe()
+     * invocation with the request info.
+     */
+    registerContextFactory(factory: ContextFactory): void;
+    getGraphQLSchema(id: string): Promise<GraphQLSchema>;
+    listGraphs(): Promise<ListGraphResult>;
+    loadGraph(params: LoadGraphParams): Promise<LoadGraphResult>;
+    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>>;
+    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>;
+}

package/lib/engine.js

@@ -0,0 +1 @@
+import{createRuntime as e}from"@enkaku/runtime";import{asType as t,createValidator as i}from"@enkaku/schema";import{isSigningIdentity as s,stringifyToken as n,verifyToken as a}from"@enkaku/token";import{KubunDB as r}from"@kubun/db";import{createReadContext as o,createSchema as l}from"@kubun/graphql";import{HLC as u}from"@kubun/hlc";import{getKubunLogger as c}from"@kubun/logger";import{applyChangeMutation as d,applyMutation as h,applySetMutation as m,convertPatchInput as p,createMutationOperations as g}from"@kubun/mutation";import{clusterToRecord as y,documentMutation as w,GraphModel as v}from"@kubun/protocol";import{execute as f,GraphQLError as b,Kind as D,parse as x,subscribe as I}from"graphql";import{Migrator as M}from"kysely";import{EngineEventBus as E}from"./events.js";import{computeMutationHash as k}from"./mutation-hash.js";import{runPolicies as G}from"./policies.js";import{createRegistry as O}from"./registry.js";let P=i(w);export class KubunEngine{#e=[];#t;#i;#s={};#n;#a;#r;#o={};#l=new Map;#u=[];#c;#d;#h;#m={};#p={};constructor(t){this.#t=t.db instanceof r?t.db:new r(t.db),this.#a=t.identity,this.#n=new u({nodeID:t.identity.id}),this.#r=t.logger??c("engine"),this.#i=t.eventBus??new E({logger:this.#r.getChild("events")}),this.#h=e(t.runtime),this.#d=O(),this.#c=this.#g(t)}get did(){return this.#a.id}get identity(){return this.#a}get eventBus(){return this.#i}get ready(){return this.#c}async dispose(){await Promise.all(this.#u.filter(e=>null!=e.dispose).map(e=>e.dispose?.()))}getGraphQLSource(e){let{graphID:t}=e,i=e.getViewerDID??(()=>this.#a.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.#y({graphID:t,text:e.text,variables:e.variables,viewerDID:i()??void 0})}}registerContextFactory(e){this.#e.push(e)}#w(e){let t=e.viewerDID??this.#a.id,i=this.#v(t),s={};for(let e of this.#e)s={...s,...e(i)};null!=e.contextExtensions&&(s={...s,...e.contextExtensions});let n=e.graphID;return this.#p[n]??={},function(e){let t={db:e.db,validators:e.validators,hlc:e.hlc},i=g({issuer:e.viewerDID,hlc:e.hlc,getRandomValues:e.runtime.getRandomValues,processSetMutation:e=>m(t,e),processChangeMutation:e=>d(t,e)}),{eventBus:s,viewerDID:n}=e,a={...o({db:e.db,viewerDID:e.viewerDID}),async executeCreateMutation({modelID:e,data:t}){let a=await i.createDocument({modelID:e,data:t});return await s.emit("engine:document:created",{documentID:a.id,modelID:a.model,viewerDID:n}),await s.emit("engine:mutation:applied",{type:"create",documentID:a.id,viewerDID:n}),a},executeSetMutation:async({modelID:e,unique:t,data:s})=>await i.setDocument({modelID:e,unique:t,data:s}),async executeUpdateMutation({input:e}){let t=await i.updateDocument({docID:e.id,patch:p(e.patch)});return await s.emit("engine:document:updated",{documentID:t.id,modelID:t.model,viewerDID:n}),await s.emit("engine:mutation:applied",{type:"update",documentID:t.id,viewerDID:n}),t},async executeRemoveMutation({id:e}){await i.removeDocument({docID:e}),await s.emit("engine:document:removed",{documentID:e,viewerDID:n}),await s.emit("engine:mutation:applied",{type:"remove",documentID:e,viewerDID:n})},async executeSetModelAccessDefaults(){throw Error("Access control mutations are not supported in engine mode")},async executeRemoveModelAccessDefaults(){throw Error("Access control mutations are not supported in engine mode")},async executeSetDocumentAccessOverride(){throw Error("Access control mutations are not supported in engine mode")},async executeRemoveDocumentAccessOverride(){throw Error("Access control mutations are not supported in engine mode")},beginTransaction(){throw Error("Transaction mutations are not supported in engine mode")},async commitTransaction(){throw Error("Transaction mutations are not supported in engine mode")},rollbackTransaction(){throw Error("Transaction mutations are not supported in engine mode")}};return null!=e.contextExtensions?{...a,...e.contextExtensions}:a}({db:this.#t,viewerDID:t,hlc:this.#n,runtime:this.#h,validators:this.#p[n],eventBus:this.#i,contextExtensions:Object.keys(s).length>0?s:void 0})}#v(e){let t=this.#t,i=this.#h,s=this.#i;return{viewerDID:e,async transaction(e){let n=i.getRandomID();s.beginTransaction(n);try{let i=await t.getDB(),a=await i.transaction().execute(async t=>await e({db:t,emit(e,t){s.emitBuffered(n,e,t)}}));return await s.commit(n),a}catch(e){throw s.rollback(n),e}}}}async #g(e){let t=e.plugins??[],i={engine:this,graph:{execute:e=>this.#f(e),subscribe:e=>this.#y(e),applyVerifiedMutation:e=>this.#b(e),applyVerifiedMutations:e=>this.#D(e)},db:this.#t,runtime:this.#h,identity:this.#a,eventBus:this.#i,hlc:this.#n,getLogger:e=>this.#r.getChild(e)};for(let e of t){let t=e(i);this.#u.push(t),null!=t.api&&this.#d.registerPlugin(t.name,t.api)}this.#d.closeGate();let s=[];for(let e of this.#u)null!=e.migrations&&s.push(e.migrations);for(let e of(s.length>0&&await this.#x(s),this.#u))null!=e.schemaExtension&&this.#l.set(e.name,e.schemaExtension);for(let e of this.#u)null!=e.createContextFactory&&this.#e.push(e.createContextFactory());for(let e of this.#u)if(null!=e.policies)for(let[t,i]of Object.entries(e.policies)){null==this.#o[t]&&(this.#o[t]={sync:[],async:[]});let e=this.#o[t];null!=i.sync&&(e.sync=[...e.sync??[],...i.sync]),null!=i.async&&(e.async=[...e.async??[],...i.async])}this.#r.info("engine initialized with {count} plugins",{count:this.#u.length})}async #x(e){if(0===e.length)return;let t=await this.#t.getDB(),i=this.#t.adapter,s={types:i.types,functions:i.functions};for(let i of e){let e="function"==typeof i.migrations?i.migrations(s):i.migrations,n=new M({db:t,provider:{getMigrations:()=>Promise.resolve(e)},migrationTableName:`kubun_${i.name}_migration`,migrationLockTableName:`kubun_${i.name}_migration_lock`}),a=await n.migrateToLatest();if(null!=a.error)throw a.error;this.#r.info("plugin {name} migrations complete",{name:i.name})}}async #I(e){return null==this.#s[e]&&(this.#s[e]=this.#t.getGraph(e).then(t=>{if(null==t)throw this.#r.warn("graph {id} not found",{id:e}),delete this.#s[e],Error(`Graph not found: ${e}`);return this.#r.debug("cached model for graph {id}",{id:e}),{aliases:t.aliases,record:t.record,extensionSDL:t.extension_sdl??void 0,pluginConfig:t.plugin_config??void 0}})),await this.#s[e]}async getGraphQLSchema(e){return null==this.#m[e]&&(this.#m[e]=this.#I(e).then(t=>{let i;if(null!=t.pluginConfig){let e={},s={},n={},a={},r={};for(let[i,o]of Object.entries(t.pluginConfig)){let t=this.#l.get(i);if(null!=t){let i=t(o);if(Object.assign(e,i.resolvers.queryFields??{}),Object.assign(s,i.resolvers.mutationFields??{}),Object.assign(n,i.resolvers.subscriptionFields??{}),Object.assign(r,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:n,typeFields:a,nodeResolvers:r}}let s=l({...t,extensionResolvers:i});return this.#r.debug("cached schema for graph {id}",{id:e}),s}).catch(t=>{throw delete this.#m[e],t})),await this.#m[e]}async #M(e,t){let i=t??x(e.text);if(null==i.definitions[0])throw Error("Missing GraphQL document definition");return{schema:await this.getGraphQLSchema(e.graphID),document:i,contextValue:this.#w(e),variableValues:e.variables}}#E(e){let t=e.definitions[0];return null!=t&&t.kind===D.OPERATION_DEFINITION?t.operation:"query"}async #k(e,t){let i=await G(this.#o,e,{viewerDID:t});return"issues"in i&&null!=i.issues&&i.issues.length>0?{errors:i.issues.map(e=>new b(e.message,{extensions:null!=e.path?{path:e.path}:void 0}))}:null}async listGraphs(){return{graphs:(await this.#t.listGraphs()).map(e=>({id:e.id,name:e.name}))}}async loadGraph(e){let t=await this.#I(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,y(t));let n=v.fromClusters({clusters:s});if(null!=e.plugins){i=e.plugins;let s=[];for(let[e,t]of Object.entries(i)){let i=this.#l.get(e);if(null==i)throw Error(`Plugin "${e}" not found or does not provide schema extensions`);let n=i(t);s.push(n.sdl)}s.length>0&&(t=s.join("\n"))}let a=await this.#t.createGraph({id:e.id??this.#h.getRandomID(),name:e.name,record:n.record,extensionSDL:t,pluginConfig:i}),r=n.toJSON();return this.#s[a]=Promise.resolve({...r,extensionSDL:t,pluginConfig:i}),delete this.#m[a],delete this.#p[a],this.#r.info("deployed graph {id}",{id:a}),{id:a,...r}}async #G(e){for(let{document:t,mutation:i,authorDID:s}of e)"set"===i.typ?await this.#i.emit("engine:document:created",{documentID:t.id,modelID:t.model,viewerDID:s}):await this.#i.emit("engine:document:updated",{documentID:t.id,modelID:t.model,viewerDID:s}),await this.#i.emit("engine:mutation:applied",{type:"set"===i.typ?"create":"update",documentID:t.id,viewerDID:s})}async #b(e){let{token:i,graphID:s}=e,n=t(P,(await a(i)).payload);this.#p[s]??={};let r={db:this.#t,validators:this.#p[s],hlc:this.#n},o=await h(r,n),l=k(i),u=n.iss;await this.#t.insertMutationLogEntry({mutation_hash:l,model_id:o.model,document_id:o.id,author_did:u,hlc:n.hlc,mutation_jwt:i,status:"applied"});let c={document:o,mutation:n,authorDID:u,hash:l};return await this.#G([c]),c}async #D(e){let{tokens:i,graphID:s}=e;this.#p[s]??={};let n=await Promise.all(i.map(async e=>{let i=t(P,(await a(e)).payload);return{token:e,mutation:i}})),r=[];return await this.#t.withTransaction(async e=>{for(let{token:t,mutation:i}of n){let n={db:e,validators:this.#p[s],hlc:this.#n},a=await h(n,i),o=k(t);await e.insertMutationLogEntry({mutation_hash:o,model_id:a.model,document_id:a.id,author_did:i.iss,hlc:i.hlc,mutation_jwt:t,status:"applied"}),r.push({document:a,mutation:i,authorDID:i.iss,hash:o})}}),await this.#G(r),{results:r}}async #f(e){let t=x(e.text),i=this.#E(t),s=await this.#k(i,e.viewerDID??this.#a.id);if(null!=s)return s;let n=await this.#M(e,t);return await f(n)}async #y(e){let t=await this.#M(e);return await I(t)}async queryGraph(e){let t=x(e.text);if("mutation"===this.#E(t))throw Error("queryGraph() does not accept mutation operations. Use mutateGraph() instead.");return await this.#f({graphID:e.id,text:e.text,variables:e.variables??{},viewerDID:e.viewerDID})}async mutateGraph(e){if(!s(this.#a))throw Error("mutateGraph requires a SigningIdentity");let t=this.#a,i=e.id,a=async e=>{let s=n(await t.signToken(e)),{document:a}=await this.#b({token:s,graphID:i});return a},r=g({issuer:t.id,hlc:this.#n,getRandomValues:this.#h.getRandomValues,processSetMutation:async e=>await a(e),processChangeMutation:async e=>await a(e)});return await this.#f({graphID:i,text:e.text,variables:e.variables??{},viewerDID:e.viewerDID??t.id,contextExtensions:{executeCreateMutation:async e=>await r.createDocument({modelID:e.modelID,data:e.data}),executeSetMutation:async e=>await r.setDocument({modelID:e.modelID,unique:e.unique,data:e.data}),executeUpdateMutation:async e=>await r.updateDocument({docID:e.input.id,patch:p(e.input.patch)}),executeRemoveMutation:async e=>{await r.removeDocument({docID:e.id})}}})}async subscribeToGraph(e){return await this.#y({graphID:e.id,text:e.text,variables:e.variables??{},viewerDID:e.viewerDID})}async getAPI(e){return await this.#d.getAPI(e)}}

package/lib/events.d.ts

@@ -0,0 +1,55 @@
+import { type UnsubscribeFunction } from '@enkaku/event';
+import type { Logger } from '@kubun/logger';
+/**
+ * Map of event names to their data types.
+ * Uses `Record<string, unknown>` so any namespaced string key is valid.
+ */
+type EventMap = Record<string, unknown>;
+/**
+ * Transaction-aware event bus built on top of `@enkaku/event`.
+ *
+ * Events emitted outside a transaction fire immediately.
+ * Events emitted inside a transaction are buffered until commit,
+ * and discarded on rollback.
+ */
+export declare class EngineEventBus<TEvents extends EventMap = EventMap> {
+    #private;
+    constructor(options?: {
+        logger?: Logger;
+    });
+    /**
+     * Subscribe to a namespaced event.
+     * Returns an unsubscribe function.
+     */
+    on<TName extends keyof TEvents & string>(name: TName, listener: (data: TEvents[TName]) => void | Promise<void>): UnsubscribeFunction;
+    /**
+     * Emit an event immediately (not inside any transaction).
+     */
+    emit<TName extends keyof TEvents & string>(name: TName, data: TEvents[TName]): Promise<void>;
+    /**
+     * Begin a new transaction context for event buffering.
+     * Events emitted via `emitBuffered` with this transaction ID
+     * will be held until `commit` or `rollback` is called.
+     */
+    beginTransaction(transactionID: string): void;
+    /**
+     * Emit an event inside a transaction. The event is buffered
+     * and will only be delivered to listeners upon commit.
+     */
+    emitBuffered<TName extends keyof TEvents & string>(transactionID: string, name: TName, data: TEvents[TName]): void;
+    /**
+     * Commit a transaction: release all buffered events to listeners
+     * in the order they were emitted.
+     *
+     * Listener errors do not prevent remaining buffered events from firing.
+     * Since `@enkaku/event` uses `Promise.allSettled` internally, all listeners
+     * for a given event run even if some throw. Errors from individual event
+     * emissions are caught so the full buffer is always drained.
+     */
+    commit(transactionID: string): Promise<void>;
+    /**
+     * Rollback a transaction: discard all buffered events.
+     */
+    rollback(transactionID: string): void;
+}
+export {};

package/lib/events.js

@@ -0,0 +1 @@
+import{EventEmitter as t}from"@enkaku/event";export class EngineEventBus{#t;#r;#n;constructor(r){this.#t=new t,this.#r=r?.logger,this.#n=new Map}on(t,r){return this.#t.on(t,r)}async emit(t,r){await this.#t.emit(t,r)}beginTransaction(t){if(this.#n.has(t))throw Error(`Transaction already exists: ${t}`);this.#n.set(t,[])}emitBuffered(t,r,n){let e=this.#n.get(t);if(null==e)throw Error(`Transaction not found: ${t}`);e.push({name:r,data:n})}async commit(t){let r=this.#n.get(t);if(null==r)throw Error(`Transaction not found: ${t}`);for(let n of(this.#n.delete(t),r))try{await this.#t.emit(n.name,n.data)}catch(t){this.#r?.warn("event listener error during commit for {event}: {error}",{event:n.name,error:String(t)})}}rollback(t){if(!this.#n.has(t))throw Error(`Transaction not found: ${t}`);this.#n.delete(t)}}

package/lib/executor.d.ts

@@ -0,0 +1,18 @@
+import type { ExecuteGraphParams, ExecuteGraphResult, GraphsProvider } from '@kubun/protocol';
+export type { GraphQLOperationParams, GraphQLSource, GraphQLSourceParams, GraphQLSourceProvider, GraphsProvider, } from '@kubun/protocol';
+import type { GetAPI } from './registry.js';
+/**
+ * Engine-specific graph params extending the protocol-level params with viewerDID.
+ * viewerDID is resolved server-side (not sent over the wire), so it belongs
+ * on the engine type rather than the protocol schema.
+ */
+export type EngineGraphParams = ExecuteGraphParams & {
+    viewerDID?: string;
+};
+export type Engine = Omit<GraphsProvider, 'queryGraph' | 'mutateGraph' | 'subscribeToGraph'> & {
+    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>>;
+    subscribeToGraph<Data extends Record<string, unknown> = Record<string, unknown>>(params: EngineGraphParams): Promise<AsyncGenerator<ExecuteGraphResult<Data>> | ExecuteGraphResult<Data>>;
+    getAPI: GetAPI;
+    ready: Promise<void>;
+};

package/lib/executor.js

@@ -0,0 +1 @@
+export{};

package/lib/index.d.ts

@@ -0,0 +1,13 @@
+export type { AccessChecker, AccessLevel, AccessPermissions, AccessRule, DefaultAccessLevel, } from './access-control.js';
+export { createAccessChecker, parseDocumentAccessPermissions, validateDIDs, } from './access-control.js';
+export type { ApplyVerifiedMutationParams, ApplyVerifiedMutationResult, ApplyVerifiedMutationsParams, ApplyVerifiedMutationsResult, ContextFactory, EngineParams, ExecuteParams, ExecutionContext, PluginMigrationContext, PluginMigrations, TransactionContext, } from './engine.js';
+export { KubunEngine } from './engine.js';
+export type { EngineEvents } from './engine-events.js';
+export { EngineEventBus } from './events.js';
+export type { Engine, EngineGraphParams, GraphQLOperationParams, GraphQLSource, GraphQLSourceParams, GraphQLSourceProvider, GraphsProvider, } from './executor.js';
+export { computeMutationHash } from './mutation-hash.js';
+export type { GraphInternals, KubunPlugin, PluginFactoryParams, SchemaExtension } from './plugin.js';
+export type { AsyncPolicyCheck, PolicyGateMap, PolicyIssue, PolicyPathSegment, PolicyResult, SyncPolicyCheck, } from './policies.js';
+export { runPolicies } from './policies.js';
+export type { GetAPI, Registry } from './registry.js';
+export { createRegistry } from './registry.js';

package/lib/index.js

@@ -0,0 +1 @@
+export{createAccessChecker,parseDocumentAccessPermissions,validateDIDs}from"./access-control.js";export{KubunEngine}from"./engine.js";export{EngineEventBus}from"./events.js";export{computeMutationHash}from"./mutation-hash.js";export{runPolicies}from"./policies.js";export{createRegistry}from"./registry.js";

package/lib/mutation-hash.d.ts

@@ -0,0 +1 @@
+export declare function computeMutationHash(jwt: string): string;

package/lib/mutation-hash.js

@@ -0,0 +1 @@
+import{blake3 as e}from"@noble/hashes/blake3.js";import{bytesToHex as o}from"@noble/hashes/utils.js";let t=new TextEncoder;export function computeMutationHash(n){return o(e(t.encode(n)))}

package/lib/plugin.d.ts

@@ -0,0 +1,59 @@
+import type { Runtime } from '@enkaku/runtime';
+import type { Identity } from '@enkaku/token';
+import type { KubunDB } from '@kubun/db';
+import type { ExtensionResolvers } from '@kubun/graphql';
+import type { HLC } from '@kubun/hlc';
+import type { Logger } from '@kubun/logger';
+import type { ExecutionResult } from 'graphql';
+import type { ApplyVerifiedMutationParams, ApplyVerifiedMutationResult, ApplyVerifiedMutationsParams, ApplyVerifiedMutationsResult, ContextFactory, ExecuteParams, PluginMigrations } from './engine.js';
+import type { EngineEventBus } from './events.js';
+import type { Engine } from './executor.js';
+import type { PolicyGateMap } from './policies.js';
+export type SchemaExtension = {
+    sdl: string;
+    resolvers: ExtensionResolvers;
+};
+/**
+ * Low-level graph operations available only to plugins.
+ * These bypass the public Engine API to allow plugins (RPC, sync, etc.)
+ * to execute GraphQL and apply pre-verified mutations directly.
+ */
+export type GraphInternals = {
+    execute<Data extends Record<string, unknown> = Record<string, unknown>>(params: ExecuteParams): Promise<ExecutionResult<Data>>;
+    subscribe<Data extends Record<string, unknown> = Record<string, unknown>>(params: ExecuteParams): Promise<AsyncGenerator<ExecutionResult<Data>> | ExecutionResult<Data>>;
+    applyVerifiedMutation(params: ApplyVerifiedMutationParams): Promise<ApplyVerifiedMutationResult>;
+    applyVerifiedMutations(params: ApplyVerifiedMutationsParams): Promise<ApplyVerifiedMutationsResult>;
+};
+/**
+ * Parameters provided by the engine to plugin factories.
+ * Shared resources flow from the engine — plugins must use these
+ * rather than creating their own instances.
+ */
+export type PluginFactoryParams = {
+    engine: Engine;
+    graph: GraphInternals;
+    db: KubunDB;
+    runtime: Runtime;
+    identity: Identity;
+    eventBus: EngineEventBus;
+    hlc: HLC;
+    getLogger: (name: string) => Logger;
+};
+/**
+ * Plugin descriptor returned by a plugin factory.
+ *
+ * Plugins expose APIs via the `api` field. Other plugins access them
+ * via `engine.getAPI(name)`. Lifecycle coordination uses lazy promises
+ * on plugin APIs (e.g. `httpAPI.listening`) rather than a central registry.
+ */
+export type KubunPlugin = {
+    name: string;
+    migrations?: PluginMigrations;
+    policies?: PolicyGateMap;
+    schemaExtension?: (config: Record<string, unknown>) => SchemaExtension;
+    events?: Record<string, string>;
+    /** Plugin's public API, available to other plugins via engine.getAPI(name) */
+    api?: unknown;
+    createContextFactory?: () => ContextFactory;
+    dispose?: () => Promise<void> | void;
+};

package/lib/plugin.js

@@ -0,0 +1 @@
+export{};

package/lib/policies.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Policy gate module for the Kubun engine.
+ *
+ * Policies gate engine operations with sync-before-async ordering.
+ * Each gate has optional sync and async check arrays. Sync checks run first
+ * (fast, in-memory). If any sync check fails, async checks are skipped entirely.
+ *
+ * Result types follow the Standard Schema output specification:
+ * - Success: `{ value }` — the context passes through
+ * - Failure: `{ issues }` — an array of issues with at minimum a `message` field
+ */
+/**
+ * A path segment in a policy issue, matching StandardSchemaV1.PathSegment.
+ */
+export type PolicyPathSegment = {
+    readonly key: PropertyKey;
+};
+/**
+ * A policy issue, matching StandardSchemaV1.Issue.
+ */
+export type PolicyIssue = {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | PolicyPathSegment> | undefined;
+};
+/**
+ * Successful policy check result.
+ */
+export type PolicySuccessResult<TContext = unknown> = {
+    readonly value: TContext;
+    readonly issues?: undefined;
+};
+/**
+ * Failed policy check result.
+ */
+export type PolicyFailureResult = {
+    readonly issues: ReadonlyArray<PolicyIssue>;
+};
+/**
+ * The result of a policy check — either success or failure.
+ */
+export type PolicyResult<TContext = unknown> = PolicySuccessResult<TContext> | PolicyFailureResult;
+/**
+ * A synchronous policy check function.
+ * Returns a Standard Schema result immediately (in-memory, fast).
+ */
+export type SyncPolicyCheck<TContext = unknown> = (context: TContext) => PolicyResult<TContext>;
+/**
+ * An asynchronous policy check function.
+ * Returns a Promise of a Standard Schema result (may involve DB lookups, etc.).
+ */
+export type AsyncPolicyCheck<TContext = unknown> = (context: TContext) => Promise<PolicyResult<TContext>>;
+/**
+ * A single policy gate with optional sync and async check arrays.
+ */
+export type PolicyGate<TContext = unknown> = {
+    sync?: Array<SyncPolicyCheck<TContext>>;
+    async?: Array<AsyncPolicyCheck<TContext>>;
+};
+/**
+ * Map of gate type names to their policy gates.
+ */
+export type PolicyGateMap<TContext = unknown> = Record<string, PolicyGate<TContext>>;
+/**
+ * Run all policy checks for a given gate type.
+ *
+ * Execution order:
+ * 1. Run ALL sync checks — fail fast if any return issues
+ * 2. Run ALL async checks — fail fast if any return issues
+ * 3. Return success with the original context
+ *
+ * If the gate type is not present in the map, the operation is allowed by default.
+ */
+export declare function runPolicies<TContext>(gates: PolicyGateMap<TContext>, gateType: string, context: TContext): Promise<PolicyResult<TContext>>;

package/lib/policies.js

@@ -0,0 +1 @@
+function e(e){return"issues"in e&&null!=e.issues&&e.issues.length>0}export async function runPolicies(n,t,u){let r=n[t];if(null==r)return{value:u};for(let n of r.sync??[]){let t=n(u);if(e(t))return t}for(let n of r.async??[]){let t=await n(u);if(e(t))return t}return{value:u}}

package/lib/registry.d.ts

@@ -0,0 +1,7 @@
+export type GetAPI = <T extends Record<string, unknown> = Record<string, unknown>>(name: string) => Promise<T>;
+export type Registry = {
+    registerPlugin(name: string, api: unknown): void;
+    closeGate(): void;
+    getAPI: GetAPI;
+};
+export declare function createRegistry(): Registry;

package/lib/registry.js

@@ -0,0 +1 @@
+import{defer as e}from"@enkaku/async";export function createRegistry(){let r=e(),t={};return{registerPlugin:function(e,r){t[e]=r},closeGate:function(){r.resolve()},getAPI:function(e){return r.promise.then(()=>{let r=t[e];if(null==r)throw Error(`API not registered: ${e}`);return r})}}}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kubun/engine",
+  "version": "0.8.0",
+  "license": "see LICENSE.md",
+  "keywords": [],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*",
+    "LICENSE.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@enkaku/async": "^0.14.0",
+    "@enkaku/capability": "^0.14.0",
+    "@enkaku/event": "^0.14.1",
+    "@enkaku/runtime": "^0.14.0",
+    "@enkaku/schema": "^0.14.0",
+    "@enkaku/token": "0.14.1",
+    "@noble/hashes": "^2.2.0",
+    "graphql": "^16.13.2",
+    "kysely": "^0.28.16",
+    "@kubun/db": "^0.8.0",
+    "@kubun/db-adapter": "^0.8.0",
+    "@kubun/protocol": "^0.8.0",
+    "@kubun/mutation": "^0.8.0",
+    "@kubun/graphql": "^0.8.0",
+    "@kubun/logger": "^0.8.0",
+    "@kubun/hlc": "^0.8.0"
+  },
+  "devDependencies": {
+    "@kubun/id": "^0.8.0",
+    "@kubun/test-utils": "^0.8.0"
+  },
+  "scripts": {
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../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:types": "tsc --noEmit -p tsconfig.test.json",
+    "test:unit": "vitest run",
+    "test": "pnpm run test:types && pnpm run test:unit"
+  }
+}