@humwick/server 0.130.0 → 0.130.2

package/node_modules/@humwick/kernel/module-host.ts

@@ -1,722 +0,0 @@
-import type { z } from "zod";
-import {
-  type Clock,
-  type CommandClient,
-  type CommandTarget,
-  type Grant,
-  type HealthReporter,
-  type HostCommandDecl,
-  type HostIdentity,
-  type HostCommandRun,
-  type HostCommandStatus,
-  type Logger,
-  type JsonValue,
-  type ModuleCtx,
-  type ModuleDefinition,
-  type ModuleManifest,
-  type Principal,
-  type ResolvedIdentity,
-  type Rng,
-  type Scope,
-  type SecretsReader,
-  type TraceContext,
-  type Transport,
-  type WaitCondition,
-  type WorkflowClient,
-  type WorkflowDecl,
-  type WorkflowRun,
-  type WorkflowStartOptions,
-  OpError,
-} from "./contract";
-import { type ConfigResolveOptions, resolveConfig } from "./config";
-import { createNetTransport, createRealClock, createSilentLogger, createSystemRng } from "./effects";
-import { AuthorizationError, isAuthorized, resolveIdentity } from "./identity";
-import {
-  EntityConflictError,
-  EntityNotFoundError,
-} from "./persistence";
-import type { ControlModuleDeps } from "./control";
-import { createWorkflowRuntime, type PreparedWorkflowStart, type WaitEvaluator, type WorkflowRuntime } from "./workflow-runtime";
-import type { WorkflowStepCommitFaults } from "./workflow-step-commit";
-import {
-  beginMessageAuthoritySession,
-  type MessageAuthoritySession,
-} from "./message-authority";
-import { AsyncEntityPersistence, type AsyncEntitySession } from "./async-entity-persistence";
-import { AsyncEventLogPersistence, type AsyncEventSession } from "./async-event-log";
-import type { KernelPersistence } from "./kernel-persistence";
-import { recoverIndeterminate } from "./kernel-persistence";
-import { armCompatibilityOpFaults } from "./sqlite-kernel-persistence";
-
-/** The single owning scope on the single-tenant path (§2.0). The kernel injects it; modules
- * never see where it came from, and today it is always `local`. */
-export const LOCAL_SCOPE = "local";
-
-type AnyModuleDefinition = ModuleDefinition<ModuleManifest>;
-
-/** The caller identity for one invocation. The owning scope is kernel-injected (`local`), so
- * callers supply only who they are and what they may do. */
-export interface InvocationIdentity {
-  readonly actor: string;
-  readonly grants: readonly Grant[];
-  /** Opaque server-resolved creator attributes the TRUSTED host binding attaches from the
-   *  authenticated token (scopes/constraints/kind) so a module can freeze a durable effect's
-   *  create-time identity under the creator's REAL reach (P2-7). Rides this identity — NOT the
-   *  client-facing op input — so a client cannot supply or widen it. See {@link ResolvedIdentity}. */
-  readonly resolvedIdentity?: ResolvedIdentity;
-}
-
-/** Transport-owned commit identity for one mutation invocation. Supplying this lets an HTTP/MCP
- * boundary carry its stable request key all the way to Kernel opCommit; callers cannot influence
- * entity versions, only deduplicate an otherwise identical atomic commit. */
-export interface InvocationOptions {
-  readonly requestKey?: string;
-}
-
-/** A capability the K6a in-process host does not yet provide (K6b / workflow-runtime milestones). */
-export class KernelNotAvailableError extends Error {
-  constructor(readonly feature: string) {
-    super(`kernel feature '${feature}' is not available in the K6a in-process host`);
-    this.name = "KernelNotAvailableError";
-  }
-}
-
-/** A module issued `ctx.commands.issue(name, …)` for a command its manifest never declared. Fail
- * closed: an undeclared command has no grant/target/idempotency mapping, so it can never dispatch. */
-export class UnknownHostCommandError extends Error {
-  constructor(readonly moduleId: string, readonly commandName: string) {
-    super(`module '${moduleId}' declares no command '${commandName}'`);
-    this.name = "UnknownHostCommandError";
-  }
-}
-
-/**
- * The single, resolved shape the kernel hands the src side for ONE `ctx.commands.issue(...)` call.
- * The kernel builds it from the module's {@link HostCommandDecl} (the declared `grant`/`timeoutMs`/
- * `target`/`whenDegraded` and the computed `idempotencyKey`) plus the issue call-site (`name`/`input`/
- * `target`). It is intentionally NARROW — everything the src adapter needs to route the issue through
- * `dispatchCommand(...)` and nothing more; the module cannot smuggle extra authority through it.
- */
-export interface HostCommandIssueRequest {
-  /** The declaring module's id — namespaces the idempotency key so two modules cannot collide. */
-  readonly moduleId: string;
-  /** The declared command name (the key in the manifest's `commands` map). */
-  readonly commandName: string;
-  /** The caller's input, ALREADY validated against the decl's `input` schema by the kernel. */
-  readonly input: unknown;
-  /** The call-site target host (`ctx.commands.issue`'s third arg). */
-  readonly target: CommandTarget;
-  /** The decl's target CLASS — whether the command runs on the host-agent or a runner. */
-  readonly targetKind: "host-agent" | "runner";
-  /** The decl's `grant` (e.g. `command:run-command`). The src adapter maps this to — and must never
-   *  widen beyond — the legacy `command:write` + cwd-constrained authz that `dispatchCommand` gates. */
-  readonly grant: Grant;
-  /** `decl.idempotencyKey(input)` — the dedup token a re-drive re-presents so a crash before the
-   *  journal memo dispatches onto the SAME orchestrator command instead of double-dispatching. */
-  readonly idempotencyKey: string;
-  readonly timeoutMs: number;
-  readonly whenDegraded: "queue" | "reject";
-}
-
-/**
- * The narrow host seam backing `ctx.commands`. The kernel declares it; the SRC side implements it by
- * mapping `issue` onto the authz-gated command dispatch (which runs `assertCommandAuthorized` → the
- * #968 cwd gate) and `status` onto a command read. The kernel never imports src: it only ever holds
- * this interface, so a module can reach the command bus ONLY through the authz-gated adapter.
- *
- * These command methods are ASYNC (#1910 K2): the src adapter routes both through the async DB gateway
- * (`issue` atomically find-or-creates the correlation-keyed command off the loop; `status` reads it via
- * the reader pool), so a command-timer firing workflow never touches a raw `Database` on the main loop.
- * `ctx.commands` awaits them under the contract's Promise-returning {@link CommandClient}.
- */
-export interface HostCommandDispatcher {
-  issue(request: HostCommandIssueRequest): Promise<HostCommandRun>;
-  status(commandId: string): Promise<HostCommandRun | undefined>;
-}
-
-/** A {@link HostCommandStatus} is TERMINAL once the orchestrator has settled the command — the only
- *  point a `{kind:"command"}` wait is allowed to fire. `done`/`failed` are the two terminal projections
- *  the src adapter maps every settled orchestrator status onto (succeeded → done; failed/timed_out/
- *  rejected/canceled → failed). */
-const TERMINAL_HOST_COMMAND_STATUSES: ReadonlySet<HostCommandStatus> = new Set<HostCommandStatus>(["done", "failed"]);
-
-function isTerminalHostCommandStatus(status: HostCommandStatus): boolean {
-  return TERMINAL_HOST_COMMAND_STATUSES.has(status);
-}
-
-/** An event-log record matches a `{kind:"event"}` wait's `correlationId` when its payload is an
- *  object carrying a `correlationId` field equal to it. This is the single, documented convention the
- *  automations pilot emits under; a wait with no `correlationId` matches on topic alone. */
-/** Whether the scoped event log holds ANY event matching a `{kind:"event"}` wait — its `topic` (the
- *  event name) and, when present, its `correlationId`. Pages through the whole scope so a match late
- *  in the log is still found; a pure, side-effect-free read the wakeup pass may run more than once. */
-/** The effect providers bound into every ModuleCtx. */
-export interface HostEffects {
-  readonly clock: Clock;
-  readonly rng: Rng;
-  readonly net: Transport;
-  readonly log: Logger;
-}
-
-interface ModuleHostBaseOptions {
-  readonly clock?: Clock;
-  readonly rng?: Rng;
-  readonly net?: Transport;
-  readonly log?: Logger;
-  /** Executor lease TTL in ms for the workflow runtime; defaults to the runtime's own default. */
-  readonly leaseTtlMs?: number;
-  /** The src adapter backing `ctx.commands` — maps a module's `issue`/`status` onto the authz-gated
-   *  `dispatchCommand`/`getCommand` machinery (see {@link HostCommandDispatcher}). Omitted → the
-   *  in-process host has no command bus: `ctx.commands.issue`/`status` reject (fail-closed) and a
-   *  `{kind:"command"}` wait never fires. */
-  readonly commands?: HostCommandDispatcher;
-  /** Overrides the wait evaluator the M3 wakeup pass consults ({@link WorkflowRuntime.wakeup}). When
-   *  omitted the host builds the DEFAULT evaluator: a `{kind:"command"}` wait fires once the wired
-   *  {@link HostCommandDispatcher} reports the command terminal, and a `{kind:"event"}` wait fires once
-   *  the kernel event log holds a matching event. Provide this only to fully override that (tests). */
-  readonly workflowWaitEvaluator?: WaitEvaluator;
-  /** In-process step-commit fault injection (TEST/CHAOS only). The host arms the returned faults on the
-   *  persistence port under the step's internally-generated request key; it is a no-op for a persistence
-   *  backend that does not read the compatibility fault WeakMap (e.g. the async gateway adapter). */
-  readonly workflowCommitFaults?: (instanceId: string, stepName: string) => WorkflowStepCommitFaults | undefined;
-  /** In-process op-commit fault injection (TEST/CHAOS only). Same arming discipline as
-   *  {@link workflowCommitFaults}; a no-op for a non-SqliteKernelPersistence backend. */
-  readonly opCommitFaults?: (moduleId: string, opName: string) => OpCommitFaults | undefined;
-}
-
-/**
- * The kernel host is ALWAYS built on an async {@link KernelPersistence} port (K3, #1910) — no raw
- * `Database` is ever handed to the host. Production builds the gateway-backed adapter
- * (`createGatewayKernelPersistence`); in-process unit tests and kill-9 chaos harnesses compose a
- * `SqliteKernelPersistence` through the `createSqliteModuleHost` test-support helper. The old
- * `{ db }` K0 compatibility branch is removed.
- */
-export interface ModuleHostOptions extends ModuleHostBaseOptions {
-  readonly persistence: KernelPersistence;
-}
-
-/** The armable faults for ONE op invocation (see {@link ModuleHostOptions.opCommitFaults}). */
-export interface OpCommitFaults {
-  /** Awaited between the handler/output-validation and the atomic commit. A throw aborts the op
-   *  pre-commit (sessions discarded, nothing persisted). */
-  readonly beforeCommit?: () => void | Promise<void>;
-  /** Fires in the tx after participant SQL and before the entity flush. */
-  readonly afterParticipantBeforeEntities?: () => void;
-  /** Fires in the tx between entity and event flushes. */
-  readonly betweenEntitiesAndEvents?: () => void;
-  /** Fires in the tx after event flush and before enlisted workflow seeds. */
-  readonly afterEventsBeforeWorkflowSeeds?: () => void;
-  /** Fires after enlisted workflow seed SQL, before COMMIT. */
-  readonly afterWorkflowSeedsBeforeCommit?: () => void;
-  /** Fires after the durable COMMIT and before the invocation ACK is returned. */
-  readonly afterCommit?: () => void;
-}
-
-export interface ModuleRegisterOptions {
-  readonly config?: ConfigResolveOptions;
-}
-
-interface HostedModule {
-  readonly module: AnyModuleDefinition;
-  readonly config: unknown;
-}
-
-function traceFor(rng: Rng): TraceContext {
-  const build = (traceId: string, spanId: string): TraceContext => ({
-    traceId,
-    spanId,
-    child: () => build(traceId, rng.uuid()),
-  });
-  return build(rng.uuid(), rng.uuid());
-}
-
-function errMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-/** One `enlist: "op-commit"` workflow start staged during an op handler: its prepared seed executes
- *  inside the op's atomic commit; `instanceId` records the authoritative id the seed returned so the
- *  post-commit drive targets the deduped instance, not the provisional stub. */
-interface PendingOpWorkflowStart {
-  readonly prepared: PreparedWorkflowStart;
-  instanceId?: string;
-}
-
-interface PendingOpWorkflowControl {
-  readonly operation: "cancel" | "fail" | "reopen";
-  readonly instanceId: string;
-  readonly failure?: JsonValue;
-}
-
-function unavailableCommands(): CommandClient<unknown> {
-  return {
-    issue: () => Promise.reject(new KernelNotAvailableError("commands")),
-    status: () => Promise.reject(new KernelNotAvailableError("commands")),
-  } as unknown as CommandClient<unknown>;
-}
-
-/**
- * The real `ctx.commands` bound to one module + the wired {@link HostCommandDispatcher}. `issue`
- * looks up the named {@link HostCommandDecl}, validates the input against its schema (a parse failure
- * rejects — fail-closed), computes the decl's `idempotencyKey`, and hands the resolved
- * {@link HostCommandIssueRequest} to the dispatcher. The dispatcher is the ONLY path to the command
- * bus, so every issue routes through its authz gate; an undeclared command name rejects before any
- * dispatch. The contract's Promise-returning methods wrap the synchronous dispatcher.
- */
-function commandClientFor(module: AnyModuleDefinition, dispatcher: HostCommandDispatcher): CommandClient<unknown> {
-  const decls = (module.commands ?? {}) as Record<string, HostCommandDecl>;
-  const client = {
-    issue: async (name: string, input: unknown, target: CommandTarget): Promise<HostCommandRun> => {
-      const decl = decls[name];
-      if (!decl) throw new UnknownHostCommandError(module.id, name);
-      // Validate against the decl schema BEFORE computing the idempotency key or dispatching, so the
-      // key is derived from a well-formed input and a malformed issue fails closed (never dispatches).
-      const parsed = decl.input.parse(input) as unknown;
-      const request: HostCommandIssueRequest = {
-        moduleId: module.id,
-        commandName: name,
-        input: parsed,
-        target,
-        targetKind: decl.target,
-        grant: decl.grant,
-        idempotencyKey: decl.idempotencyKey(parsed),
-        timeoutMs: decl.timeoutMs,
-        whenDegraded: decl.whenDegraded ?? "reject",
-      };
-      return dispatcher.issue(request);
-    },
-    status: async (id: string): Promise<HostCommandRun | undefined> => dispatcher.status(id),
-  };
-  return client as unknown as CommandClient<unknown>;
-}
-
-function unavailableSecrets(): SecretsReader<unknown> {
-  return { get: () => Promise.reject(new KernelNotAvailableError("secrets")) } as unknown as SecretsReader<unknown>;
-}
-
-/** No-op reporter: the host has nothing to serve health probes to yet, and no capabilities. */
-function inertHealth(): HealthReporter {
-  return { report: () => {}, capability: () => Promise.resolve(false) };
-}
-
-function fieldsFromZodError(error: z.ZodError): Readonly<Record<string, readonly string[]>> {
-  const fields: Record<string, string[]> = {};
-  for (const issue of error.issues) {
-    const key = issue.path.map(String).join(".") || "(root)";
-    (fields[key] ??= []).push(issue.message);
-  }
-  return fields;
-}
-
-/** Translate the primitives' internal failures into the module-visible typed `OpError`. Unknown
- * handler errors propagate unchanged (the rollback has already happened by the time we get here). */
-function mapInvocationError(error: unknown): unknown {
-  if (error instanceof OpError) return error;
-  if (error instanceof AuthorizationError) return new OpError("unauthorized", 403, error.message);
-  if (error instanceof EntityConflictError) return new OpError("conflict", 409, error.message);
-  if (error instanceof EntityNotFoundError) return new OpError("not_found", 404, error.message);
-  return error;
-}
-
-/**
- * The K6a in-process serving core. Registers `defineModule` manifests, resolves each one's
- * config once (no live-reload), and serves its ops through {@link ModuleHost.invoke}: identity
- * resolution with a kernel-injected `local` scope, default-deny authorization, Zod I/O
- * validation, and an atomic entity+event commit. Transport derivation (HTTP/MCP/CLI) is K6b.
- */
-export class ModuleHost {
-  /**
-   * This host's OPAQUE identity (#1506) — a JS-PRIVATE, set-once field, deliberately NOT a public
-   * `readonly` property. A TS `readonly` field is writable at runtime, so it could be REASSIGNED
-   * (`host.identity = …`) and a module that keyed private state by it would then bind to the replacement:
-   * that is a second seam. `#identity` cannot be reassigned or shadowed from outside the class, and the
-   * ctx below is built from it DIRECTLY, so shadowing the public {@link identity} getter can only produce
-   * an inert binding — never one this host will ever present.
-   *
-   * It is frozen and carries nothing; its only meaningful property is REFERENCE identity, so a look-alike
-   * object is never this host.
-   */
-  readonly #identity: HostIdentity = Object.freeze({ hostIdentity: true as const });
-  readonly #kernelPersistence: KernelPersistence;
-  readonly #effects: HostEffects;
-  readonly #persistence: AsyncEntityPersistence;
-  readonly #eventLog: AsyncEventLogPersistence;
-  readonly #modules = new Map<string, HostedModule>();
-  readonly #leaseTtlMs: number | undefined;
-  readonly #commands: HostCommandDispatcher | undefined;
-  /** The resolved wait evaluator handed to every runtime: the caller's override if given, else the
-   *  DEFAULT composite built from the command dispatcher (`command` waits) + event log (`event` waits). */
-  readonly #waitEvaluator: WaitEvaluator;
-  readonly #workflowCommitFaults: ((instanceId: string, stepName: string) => WorkflowStepCommitFaults | undefined) | undefined;
-  readonly #opCommitFaults: ((moduleId: string, opName: string) => OpCommitFaults | undefined) | undefined;
-  /** Per-module schema-install promises from {@link register}; {@link whenReady} awaits them all. */
-  readonly #registrations: Promise<void>[] = [];
-
-  /** Read-only view of {@link ModuleHost.#identity}, for a module that must bind private state to this
-   *  host (the #1506 admission capability). There is NO setter: the backing field is JS-private, so this
-   *  can be shadowed on an instance but never redirected — anything built from a shadow is inert, because
-   *  every ctx carries the private field's value. */
-  get identity(): HostIdentity {
-    return this.#identity;
-  }
-
-  constructor(options: ModuleHostOptions) {
-    this.#leaseTtlMs = options.leaseTtlMs;
-    this.#commands = options.commands;
-    this.#workflowCommitFaults = options.workflowCommitFaults;
-    this.#opCommitFaults = options.opCommitFaults;
-    this.#effects = {
-      clock: options.clock ?? createRealClock(),
-      rng: options.rng ?? createSystemRng(),
-      net: options.net ?? createNetTransport(),
-      log: options.log ?? createSilentLogger(),
-    };
-    // The host holds ONLY the async persistence port — never a raw Database (K3, #1910). In-process
-    // tests/chaos compose a SqliteKernelPersistence via `createSqliteModuleHost`; production injects the
-    // gateway-backed adapter.
-    this.#kernelPersistence = options.persistence;
-    this.#persistence = new AsyncEntityPersistence(this.#kernelPersistence);
-    this.#eventLog = new AsyncEventLogPersistence(this.#kernelPersistence);
-    this.#waitEvaluator = this.#resolveWaitEvaluator(options.workflowWaitEvaluator);
-  }
-
-  /**
-   * Build the wait evaluator the M3 wakeup pass consults. An explicit override wins verbatim
-   * (tests / bespoke hosts). Otherwise the DEFAULT composite resolves the two ratified
-   * {@link WaitCondition} kinds: a `{kind:"command"}` fires once the wired {@link HostCommandDispatcher}
-   * reports the command terminal (never fires when no dispatcher is wired — fail-closed), and a
-   * `{kind:"event"}` fires once the kernel's own event log holds a matching event. Kept
-   * side-effect-free: the runtime re-invokes it while scanning AND under the acquired lease.
-   */
-  #resolveWaitEvaluator(override: WaitEvaluator | undefined): WaitEvaluator {
-    if (override) return override;
-    const dispatcher = this.#commands;
-    const persistence = this.#kernelPersistence;
-    return async (waitFor: WaitCondition): Promise<boolean> => {
-      if (waitFor.kind === "command") {
-        if (!dispatcher) return false;
-        const run = await dispatcher.status(waitFor.commandId);
-        return run !== undefined && isTerminalHostCommandStatus(run.status);
-      }
-      return persistence.eventHasMatch(LOCAL_SCOPE as unknown as Scope, waitFor.topic, waitFor.correlationId);
-    };
-  }
-
-  /** Install a module: derive its tables (K4) and event schemas (K5) and resolve its config. Schema
-   *  installation is async (it routes through the persistence port's writer); {@link invoke} awaits the
-   *  per-module readiness before touching a table, so callers need not await `register`. A caller that
-   *  observes the installed schema OUT OF BAND (not through an op) awaits {@link whenReady} first. */
-  register<M extends ModuleManifest>(module: ModuleDefinition<M>, options: ModuleRegisterOptions = {}): void {
-    if (this.#modules.has(module.id)) throw new Error(`module '${module.id}' is already registered with the host`);
-    this.#registrations.push(this.#persistence.register(module));
-    this.#eventLog.register(module);
-    const config = resolveConfig(module.config, options.config ?? {});
-    this.#modules.set(module.id, { module: module as AnyModuleDefinition, config });
-  }
-
-  /** Resolve once every registered module's async schema install has committed. Callers that build a
-   *  host and then observe its tables OUT OF BAND (e.g. the control host's cross-module observability,
-   *  or a test asserting the ON-gated schema exists) await this so the sync read cannot race the writer.
-   *  Invocation self-gates on per-module readiness, so the op path does not need this. */
-  async whenReady(): Promise<void> {
-    await Promise.all(this.#registrations);
-  }
-
-  /** The resolved, validated config for a registered module (the value handed to `ctx.config`). */
-  configFor<M extends ModuleManifest>(module: ModuleDefinition<M>): unknown {
-    return this.#require(module.id).config;
-  }
-
-  /**
-   * The kernel-wide read/control capabilities the `control` module (KAPI-1 Wave 2) closes over.
-   * A module's `ctx` only ever sees its OWN entities/events, so cross-module observability +
-   * control cannot ride `ctx`; the control module is built from these injected reader/controller
-   * interfaces instead (KAPI-0 §6.1 decision 1 — "hang off the host"). Exposes the host's own
-   * journal/event/entity persistence narrowed to the read + control-primitive surface; the control
-   * module's ops apply owner-scoping (G-M1) + default-redact (K-C3) on top — these are raw/ungated.
-   */
-  kernelControlDeps(): ControlModuleDeps {
-    const port = this.#kernelPersistence;
-    const control = (operation: "cancel" | "pause" | "resume" | "reopen", id: string): Promise<boolean> => {
-      const requestKey = this.#effects.rng.uuid();
-      const now = this.#effects.clock.now();
-      return recoverIndeterminate(() => port.controlWorkflow(requestKey, operation, id, now));
-    };
-    return {
-      journal: {
-        listInstances: (options) => port.listWorkflowInstances(options),
-        getInstance: (id) => port.getWorkflowInstance(id),
-        listSteps: (id) => port.listWorkflowSteps(id),
-        cancelInstance: (id) => control("cancel", id),
-        pauseInstance: (id) => control("pause", id),
-        resumeInstance: (id) => control("resume", id),
-        reopenInstance: (id) => control("reopen", id),
-      },
-      events: { replay: (scope, since, limit = 500, moduleId) => port.replayEvents(scope, since, limit, moduleId) },
-      entities: this.#persistence,
-    };
-  }
-
-  #require(moduleId: string): HostedModule {
-    const hosted = this.#modules.get(moduleId);
-    if (!hosted) throw new Error(`module '${moduleId}' is not registered with the host`);
-    return hosted;
-  }
-
-  /**
-   * A real {@link WorkflowClient} bound to one module's ctx/db/journal, replacing the K6a
-   * `unavailableWorkflows` stub. Its `beginStepContext` assembles a fresh `ModuleCtx` + K4/K5
-   * sessions per step exactly the way {@link ModuleHost.invoke} builds an op's ctx, so a workflow
-   * step runs with the same principal/scope, config, and effects an op does. Each executed step
-   * commits its effects + journal memo atomically through M0's `commitStepAttempt`.
-   */
-  #buildRuntime<M extends ModuleManifest>(
-    module: ModuleDefinition<M>,
-    principal: Principal,
-    config: unknown,
-  ): WorkflowRuntime {
-    return createWorkflowRuntime({
-      persistence: this.#kernelPersistence,
-      ready: this.#persistence.ready(module.id),
-      clock: this.#effects.clock,
-      rng: this.#effects.rng,
-      moduleName: module.id,
-      // Stamp the generic owner column (KAPI-1 / decision 3) from the invoking principal, so a
-      // `ctx.workflows.start` records who created the instance. A system-driven runtime carries the
-      // system actor here (accepted creator-invisible divergence for migrated/system starts).
-      createdBy: principal.actor,
-      workflows: (module.workflows ?? {}) as Readonly<Record<string, WorkflowDecl>>,
-      ...(this.#leaseTtlMs !== undefined ? { leaseTtlMs: this.#leaseTtlMs } : {}),
-      isWaitSatisfied: this.#waitEvaluator,
-      ...(this.#workflowCommitFaults !== undefined ? { commitFaults: this.#workflowCommitFaults } : {}),
-      beginStepContext: () => {
-        const entitySession = this.#persistence.begin(module, principal.scope);
-        const eventSession = this.#eventLog.begin(module, principal.scope);
-        const messageAuthoritySession = beginMessageAuthoritySession(this.#kernelPersistence.messageAuthorityAvailable);
-        const ctx = this.#assembleCtx(module, principal, config, entitySession, eventSession, messageAuthoritySession);
-        return {
-          ctx,
-          entitySession: entitySession as AsyncEntitySession<unknown>,
-          eventSession: eventSession as AsyncEventSession<unknown>,
-          messageAuthoritySession,
-        };
-      },
-    });
-  }
-
-  #workflowClientFor<M extends ModuleManifest>(
-    module: ModuleDefinition<M>,
-    principal: Principal,
-    config: unknown,
-  ): WorkflowClient<NonNullable<M["workflows"]>> {
-    return this.#buildRuntime(module, principal, config) as unknown as WorkflowClient<NonNullable<M["workflows"]>>;
-  }
-
-  /**
-   * The module's {@link WorkflowClient} for a caller identity, for driving a workflow outside an
-   * op invocation (e.g. a `run-now` trigger or a test). Scope is kernel-injected (`local`) exactly
-   * as in {@link ModuleHost.invoke}; the caller supplies only who they are.
-   */
-  workflows<M extends ModuleManifest>(module: ModuleDefinition<M>, identity: InvocationIdentity): WorkflowClient<NonNullable<M["workflows"]>> {
-    const hosted = this.#require(module.id);
-    const principal = resolveIdentity({ actor: identity.actor, scope: LOCAL_SCOPE, grants: identity.grants, resolvedIdentity: identity.resolvedIdentity });
-    return this.#workflowClientFor(module as ModuleDefinition<M>, principal, hosted.config);
-  }
-
-  /**
-   * A workflow DRIVER handle (the supervisor role): the concrete {@link WorkflowRuntime}, which
-   * adds the M2 recovery entry points ({@link WorkflowRuntime.resume} / {@link WorkflowRuntime.recover})
-   * on top of start/status/cancel. A supervisor calls `recover()` on boot and on a tick to reclaim
-   * instances orphaned by a crashed driver. Each call builds a fresh runtime with its own lease
-   * owner/token, so two driver handles genuinely contend on the single-writer lease.
-   */
-  workflowDriver<M extends ModuleManifest>(module: ModuleDefinition<M>, identity: InvocationIdentity): WorkflowRuntime {
-    const hosted = this.#require(module.id);
-    const principal = resolveIdentity({ actor: identity.actor, scope: LOCAL_SCOPE, grants: identity.grants, resolvedIdentity: identity.resolvedIdentity });
-    return this.#buildRuntime(module as ModuleDefinition<M>, principal, hosted.config);
-  }
-
-  /**
-   * The workflow client an OP invocation sees: identical to the raw runtime, except that a start
-   * carrying `enlist: "op-commit"` is STAGED instead of committed — validated eagerly (so a schema
-   * failure still throws `invalid_input` from the handler), pushed onto the invocation's pending
-   * list for {@link commitAtomically} to seed inside the op's transaction, and driven post-commit.
-   * A start WITHOUT the option keeps the ratified immediate-commit semantics unchanged.
-   */
-  #enlistableClient(
-    runtime: WorkflowRuntime,
-    pendingStarts: PendingOpWorkflowStart[],
-    pendingControls: PendingOpWorkflowControl[],
-  ): WorkflowClient<unknown> {
-    const client = {
-      start: async (name: string, input: unknown, options: WorkflowStartOptions): Promise<WorkflowRun> => {
-        if (options?.enlist !== "op-commit") return runtime.start(name, input, options);
-        const prepared = await runtime.prepareStart(name, input, options);
-        pendingStarts.push({ prepared });
-        return prepared.provisional;
-      },
-      status: (id: string) => runtime.status(id),
-      cancel: async (id: string) => {
-        pendingControls.push({ operation: "cancel", instanceId: id });
-        return true;
-      },
-      control: async (operation: "cancel" | "fail" | "reopen", instanceId: string, failure?: JsonValue) => {
-        pendingControls.push({ operation, instanceId, ...(failure !== undefined ? { failure } : {}) });
-        return true;
-      },
-    };
-    return client as unknown as WorkflowClient<unknown>;
-  }
-
-  #assembleCtx<M extends ModuleManifest>(
-    module: ModuleDefinition<M>,
-    principal: Principal,
-    config: unknown,
-    entitySession: AsyncEntitySession<M["entities"]>,
-    eventSession: AsyncEventSession<NonNullable<M["events"]>>,
-    messageAuthoritySession: MessageAuthoritySession,
-    pendingStarts?: PendingOpWorkflowStart[],
-    pendingControls?: PendingOpWorkflowControl[],
-  ): ModuleCtx<M> {
-    // A step/standalone ctx (no pending list) gets the raw runtime, whose `start` fails closed on
-    // `enlist: "op-commit"` — there is no op commit to join outside an op invocation.
-    const runtime = this.#buildRuntime(module, principal, config);
-    const ctx = {
-      hostIdentity: this.#identity,
-      principal,
-      trace: traceFor(this.#effects.rng),
-      config,
-      entities: entitySession.entities,
-      events: eventSession.events,
-      workflows: pendingStarts
-        ? this.#enlistableClient(runtime, pendingStarts, pendingControls ?? [])
-        : (runtime as unknown as WorkflowClient<NonNullable<M["workflows"]>>),
-      commands: this.#commands ? commandClientFor(module as AnyModuleDefinition, this.#commands) : unavailableCommands(),
-      messageAuthority: messageAuthoritySession.participant,
-      health: inertHealth(),
-      secrets: unavailableSecrets(),
-      clock: this.#effects.clock,
-      rng: this.#effects.rng,
-      net: this.#effects.net,
-      log: this.#effects.log,
-    };
-    return ctx as unknown as ModuleCtx<M>;
-  }
-
-  /**
-   * Serve one op in-process. Order is load-bearing: authorize (default-deny) → validate input →
-   * open sessions → run handler → validate output → atomically commit. A denial, a validation
-   * failure, a handler throw, or a version conflict all leave the store and event log untouched,
-   * and surface as a typed {@link OpError} where the kernel owns the failure mode.
-   */
-  async invoke<M extends ModuleManifest>(
-    module: ModuleDefinition<M>,
-    opName: string,
-    identity: InvocationIdentity,
-    rawInput: unknown,
-    options: InvocationOptions = {},
-  ): Promise<unknown> {
-    const hosted = this.#require(module.id);
-    const op = module.ops?.[opName];
-    if (!op) throw new OpError("unknown_op", 404, `module '${module.id}' declares no op '${opName}'`);
-
-    // Scope is kernel-injected: the caller supplies identity, never ownership.
-    const principal = resolveIdentity({ actor: identity.actor, scope: LOCAL_SCOPE, grants: identity.grants, resolvedIdentity: identity.resolvedIdentity });
-
-    // Default-deny: an op is served only if the principal explicitly holds the op's grant.
-    if (!isAuthorized(principal, { moduleId: module.id, grant: op.grant })) {
-      throw new OpError(
-        "unauthorized",
-        403,
-        `actor '${principal.actor}' is not authorized for '${module.id}.${opName}' (requires '${op.grant}')`,
-      );
-    }
-
-    const input = op.input.safeParse(rawInput);
-    if (!input.success) throw new OpError("invalid_input", 400, `input validation failed for '${module.id}.${opName}'`, fieldsFromZodError(input.error));
-
-    await this.#persistence.ready(module.id);
-
-    const entitySession = this.#persistence.begin(module, principal.scope);
-    const eventSession = this.#eventLog.begin(module, principal.scope);
-    const messageAuthoritySession = beginMessageAuthoritySession(this.#kernelPersistence.messageAuthorityAvailable);
-    const pendingStarts: PendingOpWorkflowStart[] = [];
-    const pendingControls: PendingOpWorkflowControl[] = [];
-    const ctx = this.#assembleCtx(module, principal, hosted.config, entitySession, eventSession, messageAuthoritySession, pendingStarts, pendingControls);
-
-    let committing = false;
-    try {
-      const result = await op.handler(ctx, input.data);
-      const output = op.output.safeParse(result);
-      if (!output.success) {
-        throw new OpError("invalid_output", 500, `output validation failed for '${module.id}.${opName}'`, fieldsFromZodError(output.error));
-      }
-      // The T-0 chaos seam: hold a LIVE op exactly between its reads and its flush, so a concurrent
-      // process can commit first and this op's buffered writes lose their CAS. Test-only; a throw
-      // here aborts pre-commit (sessions + staged seeds all discarded).
-      const opFaults = this.#opCommitFaults?.(module.id, opName);
-      if (opFaults?.beforeCommit) await opFaults.beforeCommit();
-      committing = true;
-      entitySession.seal();
-      eventSession.seal();
-      messageAuthoritySession.seal();
-      const capturedAt = this.#effects.clock.now();
-      const entities = entitySession.mutations();
-      const events = eventSession.appends(capturedAt);
-      const messageAuthority = messageAuthoritySession.operations();
-      // Query/no-op attempts never enter the writer queue and therefore never take SQLite's write lock.
-      if (entities.length || events.length || messageAuthority.length || pendingStarts.length || pendingControls.length) {
-        const requestKey = options.requestKey?.trim() || this.#effects.rng.uuid();
-        if (opFaults) armCompatibilityOpFaults(this.#kernelPersistence, requestKey, opFaults);
-        const envelope = structuredClone({
-          requestKey,
-          capturedAt,
-          entities,
-          events,
-          messageAuthority,
-          workflowSeeds: pendingStarts.map((pending, resultIndex) => ({ seed: pending.prepared.seed, resultIndex })),
-          workflowControls: pendingControls.map((pending) => ({
-            operation: pending.operation,
-            instanceId: pending.instanceId,
-            ...(pending.failure !== undefined ? { failure: pending.failure } : {}),
-          })),
-        });
-        const committed = await recoverIndeterminate(() => this.#kernelPersistence.opCommit(envelope));
-        committed.workflowInstanceIds.forEach((id, index) => {
-          const pending = pendingStarts[index];
-          if (pending) pending.instanceId = id;
-        });
-      }
-      opFaults?.afterCommit?.();
-      // Drive enlisted instances only AFTER their seeds durably committed. A drive failure is a
-      // runtime concern (the instance is durable and `recover()`/`wakeup()` converge it) — never a
-      // false op failure: the op's state HAS committed, and throwing here would tell the caller the
-      // opposite. Per-start isolation mirrors the runtime's drive passes.
-      for (const pending of pendingStarts) {
-        if (pending.instanceId === undefined) continue;
-        try {
-          await pending.prepared.drive(pending.instanceId);
-        } catch (error) {
-          this.#effects.log.warn(`post-commit workflow drive failed for '${module.id}.${opName}'`, {
-            instanceId: pending.instanceId,
-            error: errMessage(error),
-          });
-        }
-      }
-      return output.data;
-    } catch (error) {
-      // Only the pre-commit paths leave sessions open; a commit failure already finalized and
-      // rolled them back inside the transaction, so discarding again would double-finalize.
-      if (!committing) {
-        entitySession.discard();
-        eventSession.discard();
-        messageAuthoritySession.discard();
-      }
-      throw mapInvocationError(error);
-    }
-  }
-}
-
-export function createModuleHost(options: ModuleHostOptions): ModuleHost {
-  return new ModuleHost(options);
-}