@humwick/server 0.130.1 → 0.130.3

package/node_modules/@humwick/kernel/control.ts

@@ -1,645 +0,0 @@
-// Ensure zod carries `.openapi()` before {@link jsonValueSchema} is built below — a named component
-// ref is what stops the recursive schema from stack-overflowing OpenAPI generation (see that schema).
-// Idempotent (module-cached); `index.ts` also imports it first, this covers a direct `./control` import.
-import "./openapi-init";
-import { z } from "zod";
-import {
-  type Grant,
-  type JsonValue,
-  type ModuleCtx,
-  type ModuleDefinition,
-  type Scope,
-  type WorkflowStatusName,
-  OpError,
-  defineModule,
-} from "./contract";
-import type {
-  ListInstancesOptions,
-  WorkflowInstancePage,
-  WorkflowInstanceRow,
-  WorkflowStepJournalRow,
-} from "./workflow-journal";
-import type { EmittedEvent, EventReplaySlice } from "./event-log";
-import { WorkflowHistoryExpiredError } from "./workflow-journal";
-import type { EntityRawListOptions, EntityRawPage, EntityRawRow } from "./persistence";
-
-/**
- * KAPI-1 Wave 2 — the kernel **Control** module (`id: "control"`): merged read ops (K1-3) + control
- * ops (K1-5) over the Kernel's generic `workflow_instances` / `kernel_events` / `kernel_entity__*`
- * tables (KAPI-0 design `docs/kernel-control-api.md`; epic #1415). It is the authz + projection
- * layer: the raw accessors it wraps (Wave 1) and the control primitives it maps onto (base) are
- * deliberately ungated — G-M1 owner-scoping and G-M5 fail-closed redaction live HERE.
- *
- * Because a module's `ctx` only ever sees its OWN entities/events, the cross-module reader/controller
- * capabilities are INJECTED (via {@link createControlModule}), not reached through `ctx` — see
- * {@link ControlModuleDeps} and `ModuleHost.kernelControlDeps`.
- *
- * ── Security posture (the crux of the review) ──────────────────────────────────────────────────
- * G-M1 (grant model): the single in-handler `.has(CONTROL_ADMIN_GRANT)` check ({@link isControlAdmin})
- *   is the cross-creator flag. A non-admin `control:read`/`control:write` principal sees/controls only
- *   rows whose `created_by` equals its own actor ({@link canSeeInstance} / the keyed `createdBy` list
- *   filter); an admin crosses creators. The `*System` twins are the reconciler seam — grant
- *   `control:admin`, `expose:{http:false,mcp:false,cli:false}`, cross-creator by construction, never
- *   surfaced to a normal caller (the `cancelMirror` precedent generalized).
- * G-M5 (fail-closed): every default is deny/redact. A NULL/unresolvable owner NEVER matches a
- *   non-admin (SQL equality + {@link canSeeInstance}), so an unknown owner hides the row rather than
- *   exposing it (#1410 R1). Sensitive DTO fields (`input`/`state`/`output`/`error`/`owner`/entity
- *   `fields`/event `payload`/lease token) are OMITTED unless admin ({@link project*} builders).
- *   `listEvents`/`listEntities`/`getEntity` read tables with NO generic owner column, so per-creator
- *   scoping is impossible — they are admin-only in-handler (a non-admin is denied), the strict
- *   fail-closed reading pending the deferred per-module allowlist (KAPI-0 decision 5).
- */
-
-// ── Grant vocabulary (KAPI-0 §3.1) ────────────────────────────────────────────────────────────────
-export const CONTROL_MODULE_ID = "control";
-/** Read the observability surface (metadata; own instances only for a non-admin). */
-export const CONTROL_READ_GRANT = "control:read" satisfies Grant;
-/** Cancel / pause / resume / retry OWN instances. */
-export const CONTROL_WRITE_GRANT = "control:write" satisfies Grant;
-/** Module-matched admin: cross-creator read + control, the ungated (payload/state/fields) view, and
- *  the OP-LEVEL grant the `*System` twins require. */
-export const CONTROL_ADMIN_GRANT = "control:admin" satisfies Grant;
-/** The GLOBAL admin grant. Mirrors the timers `canAdministerTimers` seam (`TIMERS_ADMIN_GRANT =
- *  "system:admin"`): a global admin crosses creators on the exposed read/control ops (KAPI-0 §3.1
- *  "control:admin (or system:admin)"). It does NOT reach the `*System` twins — those require the
- *  module-matched {@link CONTROL_ADMIN_GRANT} exactly, so a global admin can observe/control across
- *  creators through the normal surface but cannot invoke the narrow reconciler seam without the
- *  module-scoped grant. */
-export const SYSTEM_ADMIN_GRANT = "system:admin" satisfies Grant;
-
-// ── Injected kernel-wide capabilities (a module's ctx cannot reach cross-module state) ─────────────
-
-/** Read side of the workflow journal the control module needs (Wave-1 G-A accessor + base reads). */
-export interface InstanceReader {
-  listInstances(options?: ListInstancesOptions): Promise<WorkflowInstancePage>;
-  getInstance(id: string): Promise<WorkflowInstanceRow | undefined>;
-  listSteps(instanceId: string): Promise<WorkflowStepJournalRow[]>;
-}
-
-/** Control-primitive side (base T912): the module maps cancel/pause/resume/retry onto these — it
- *  does NOT re-implement them. Every primitive is OPEN-guarded, idempotent, and authz-free (the
- *  owner check is the module's job), mirroring the timers `cancel`/`cancelMirror` split. */
-export interface InstanceController {
-  cancelInstance(id: string): Promise<boolean>;
-  pauseInstance(id: string): Promise<boolean>;
-  resumeInstance(id: string): Promise<boolean>;
-  reopenInstance(id: string): Promise<boolean>;
-}
-
-/** Read side of the event log (Wave-1 G-D `moduleId` replay filter). */
-export interface EventReader {
-  replay(scope: Scope, since: number, limit?: number, moduleId?: string): Promise<EventReplaySlice>;
-}
-
-/** Generic `(module, entity)` entity reads (Wave-1 G-C accessors). */
-export interface EntityReader {
-  readEntity(moduleId: string, entityName: string, scope: Scope, key: unknown): Promise<EntityRawRow | undefined>;
-  listEntity(moduleId: string, entityName: string, scope: Scope, options?: EntityRawListOptions): Promise<EntityRawPage>;
-}
-
-/** The capabilities {@link createControlModule} closes over. The concrete kernel persistence classes
- *  (`WorkflowJournalPersistence`, `EventLogPersistence`, `EntityPersistence`) satisfy these
- *  structurally, so `ModuleHost.kernelControlDeps()` hands them straight through. */
-export interface ControlModuleDeps {
-  readonly journal: InstanceReader & InstanceController;
-  readonly events: EventReader;
-  readonly entities: EntityReader;
-}
-
-// ── DTO schemas (metadata-first; gated fields `.optional()` and populated only for admin) ──────────
-
-const statusSchema = z.enum([
-  "pending", "running", "sleeping", "waiting", "done", "failed", "canceled",
-]);
-
-const waitKindSchema = z.object({ kind: z.enum(["event", "command"]) });
-
-// A recursive JSON value. The `.openapi("JsonValue")` refId is load-bearing, NOT cosmetic: OpenAPI
-// generation expands schemas inline, and a bare `z.lazy` self-reference recurses without bound —
-// `GET /openapi.json` on a registered control module stack-overflows (RangeError) → 500. Naming the
-// component makes each self-reference emit a `$ref: "#/components/schemas/JsonValue"` instead of
-// re-expanding, so doc generation terminates while the runtime parse behaviour is unchanged.
-const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
-  z.union([
-    z.string(), z.number(), z.boolean(), z.null(),
-    z.array(jsonValueSchema),
-    z.record(z.string(), jsonValueSchema),
-  ]),
-).openapi("JsonValue") as z.ZodType<JsonValue>;
-
-const instanceSummarySchema = z.object({
-  id: z.string(),
-  module: z.string(),
-  workflow: z.string(),
-  status: statusSchema,
-  pausedAt: z.number().optional(),
-  owner: z.string().optional(),           // GATED (admin)
-  createdAt: z.number(),
-  updatedAt: z.number(),
-  closedAt: z.number().optional(),
-  sleepUntil: z.number().optional(),
-  waiting: waitKindSchema.optional(),
-  hasError: z.boolean(),
-});
-
-const instanceDetailSchema = instanceSummarySchema.extend({
-  idempotencyKey: z.string(),
-  attempts: z.number(),
-  input: jsonValueSchema.optional(),        // GATED
-  currentState: jsonValueSchema.optional(), // GATED
-  output: jsonValueSchema.optional(),       // GATED
-  error: z.string().optional(),             // GATED
-  lease: z.object({ held: z.boolean(), expiresAt: z.number().optional() }).optional(),
-});
-
-const journalEntrySchema = z.object({
-  seq: z.number(),
-  stepIndex: z.number(),
-  stepName: z.string(),
-  attempt: z.number(),
-  outcome: z.enum(["completed", "failed"]),
-  startedAt: z.number(),
-  completedAt: z.number(),
-  sleepUntil: z.number().optional(),
-  waitFor: waitKindSchema.optional(),
-  state: jsonValueSchema.optional(),        // GATED
-  result: jsonValueSchema.optional(),       // GATED
-});
-
-const eventSchema = z.object({
-  seq: z.number(),
-  module: z.string(),
-  name: z.string(),
-  createdAt: z.number(),
-  payload: jsonValueSchema.optional(),      // GATED
-});
-
-const entityRowSchema = z.object({
-  module: z.string(),
-  entity: z.string(),
-  key: z.string(),
-  scope: z.string(),
-  version: z.number(),
-  createdAt: z.number(),
-  updatedAt: z.number(),
-  fields: jsonValueSchema.optional(),       // GATED
-});
-
-const changedSchema = z.object({ changed: z.boolean() });
-
-export type KernelInstanceSummary = z.output<typeof instanceSummarySchema>;
-export type KernelInstanceDetail = z.output<typeof instanceDetailSchema>;
-export type KernelJournalEntry = z.output<typeof journalEntrySchema>;
-export type KernelEvent = z.output<typeof eventSchema>;
-export type KernelEntityRow = z.output<typeof entityRowSchema>;
-
-// ── Authz + projection helpers (G-M1 / G-M5) ──────────────────────────────────────────────────────
-
-/** G-M1: the cross-creator flag. Holding the module-matched `control:admin` OR the global
- *  `system:admin` is the ONLY way to cross creators (read or control) or to see gated fields. This is
- *  the in-handler `.has()` check the threat model mandates — default-deny: absent the flag, a
- *  principal is pinned to its own `created_by`. */
-function isControlAdmin(ctx: ModuleCtx): boolean {
-  return ctx.principal.grants.has(CONTROL_ADMIN_GRANT) || ctx.principal.grants.has(SYSTEM_ADMIN_GRANT);
-}
-
-/** G-M1 / G-M5: may this principal SEE this instance row at all? An admin sees every row; a non-admin
- *  sees only its own `created_by`. Fail-closed: a NULL/absent owner never matches a non-admin, so an
- *  unresolvable owner HIDES the row (never falls open — the #1410 R1 lesson). */
-function canSeeInstance(ctx: ModuleCtx, row: WorkflowInstanceRow): boolean {
-  if (isControlAdmin(ctx)) return true;
-  return row.created_by !== null && row.created_by === ctx.principal.actor;
-}
-
-/** The 404 a non-owner / missing id both yield — no existence oracle (mirrors `timers.get`). */
-function notFound(id: string): OpError {
-  return new OpError("not_found", 404, `instance '${id}' was not found`);
-}
-
-/** The 403 the generic (owner-less) entity/event surface returns to a non-admin: those tables carry
- *  no owner column, so per-creator scoping is impossible → admin-only until the allowlist lands. */
-function adminOnly(op: string): OpError {
-  return new OpError("forbidden", 403, `'${op}' requires the '${CONTROL_ADMIN_GRANT}' grant`);
-}
-
-/** Parse the JSON `wait_for` blob into its KIND ONLY — never the correlationId/commandId (K-C3). */
-function projectWaitKind(waitFor: string | null): { kind: "event" | "command" } | undefined {
-  if (waitFor === null) return undefined;
-  try {
-    const parsed = JSON.parse(waitFor) as { kind?: unknown };
-    if (parsed.kind === "event" || parsed.kind === "command") return { kind: parsed.kind };
-  } catch {
-    // Fail-closed: an unparseable wait blob discloses nothing (shape omitted, never the raw string).
-  }
-  return undefined;
-}
-
-/** Best-effort JSON decode of a stored column; returns undefined on null/parse failure (never the
- *  raw string, so a malformed blob cannot leak). */
-function decodeJson(raw: string | null): JsonValue | undefined {
-  if (raw === null) return undefined;
-  try {
-    return JSON.parse(raw) as JsonValue;
-  } catch {
-    return undefined;
-  }
-}
-
-function toStatus(raw: string): WorkflowStatusName {
-  return raw as WorkflowStatusName;
-}
-
-/** Metadata-first instance summary. `owner` is GATED — populated only for an admin (G-M5). */
-function projectSummary(row: WorkflowInstanceRow, admin: boolean): KernelInstanceSummary {
-  return {
-    id: row.id,
-    module: row.module_name,
-    workflow: row.workflow_name,
-    status: toStatus(row.status),
-    ...(row.paused_at !== null ? { pausedAt: row.paused_at } : {}),
-    ...(admin && row.created_by !== null ? { owner: row.created_by } : {}),
-    createdAt: row.created_at,
-    updatedAt: row.updated_at,
-    ...(row.closed_at !== null ? { closedAt: row.closed_at } : {}),
-    ...(row.sleep_until !== null ? { sleepUntil: row.sleep_until } : {}),
-    ...(projectWaitKind(row.wait_for) ? { waiting: projectWaitKind(row.wait_for) } : {}),
-    hasError: row.failure !== null,
-  };
-}
-
-/** Instance detail. `input`/`currentState`/`output`/`error` are GATED (admin only, G-M5); the lease
- *  is liveness-only and NEVER carries the token (K-C3). */
-function projectDetail(row: WorkflowInstanceRow, steps: readonly WorkflowStepJournalRow[], admin: boolean): KernelInstanceDetail {
-  const latest = steps.at(-1);
-  const held = row.executor_lease_token !== null;
-  return {
-    ...projectSummary(row, admin),
-    idempotencyKey: row.idempotency_key,
-    attempts: row.journal_cursor,
-    ...(admin && decodeJson(row.input) !== undefined ? { input: decodeJson(row.input) } : {}),
-    ...(admin && latest && decodeJson(latest.state_snapshot) !== undefined
-      ? { currentState: decodeJson(latest.state_snapshot) } : {}),
-    ...(admin && decodeJson(row.output) !== undefined ? { output: decodeJson(row.output) } : {}),
-    ...(admin && row.failure !== null ? { error: failureMessage(row.failure) } : {}),
-    lease: {
-      held,
-      ...(row.executor_lease_expires_at !== null ? { expiresAt: row.executor_lease_expires_at } : {}),
-    },
-  };
-}
-
-/** A human-ish message from the JSON failure blob without leaking the whole structure to a non-admin
- *  (this is only ever called under an admin guard, but stays defensive). */
-function failureMessage(failure: string): string {
-  const decoded = decodeJson(failure);
-  if (decoded !== null && typeof decoded === "object" && !Array.isArray(decoded)) {
-    const message = (decoded as Record<string, JsonValue>).message;
-    if (typeof message === "string") return message;
-  }
-  return typeof decoded === "string" ? decoded : failure;
-}
-
-/** Journal entry. `state`/`result` are GATED (admin only); `waitFor` is shape-only (K-C3). */
-function projectJournalEntry(row: WorkflowStepJournalRow, admin: boolean): KernelJournalEntry {
-  return {
-    seq: row.seq,
-    stepIndex: row.step_index,
-    stepName: row.step_name,
-    attempt: row.attempt,
-    outcome: row.outcome === "failed" ? "failed" : "completed",
-    startedAt: row.started_at,
-    completedAt: row.completed_at,
-    ...(row.sleep_until !== null ? { sleepUntil: row.sleep_until } : {}),
-    ...(projectWaitKind(row.wait_for) ? { waitFor: projectWaitKind(row.wait_for) } : {}),
-    ...(admin && decodeJson(row.state_snapshot) !== undefined ? { state: decodeJson(row.state_snapshot) } : {}),
-    ...(admin && decodeJson(row.result) !== undefined ? { result: decodeJson(row.result) } : {}),
-  };
-}
-
-/** Event DTO. `payload` is GATED (admin only, K-C3). Reached only under an admin guard today. */
-function projectEvent(event: EmittedEvent, admin: boolean): KernelEvent {
-  return {
-    seq: event.seq,
-    module: event.moduleId,
-    name: event.name,
-    createdAt: event.createdAt,
-    ...(admin && event.payload !== undefined ? { payload: event.payload as JsonValue } : {}),
-  };
-}
-
-/** Entity DTO. `fields` is GATED (admin only, K-C3 — the timers `relaySend` outbox holds the frozen
- *  create-time identity, so its columns are NEVER returned to a non-admin). Reached only under an
- *  admin guard today. */
-function projectEntity(row: EntityRawRow, admin: boolean): KernelEntityRow {
-  return {
-    module: row.module,
-    entity: row.entity,
-    key: String(row.key),
-    scope: row.scope,
-    version: row.version,
-    createdAt: row.createdAt,
-    updatedAt: row.updatedAt,
-    ...(admin && row.fields !== undefined ? { fields: row.fields as JsonValue } : {}),
-  };
-}
-
-// ── Control-op body (shared by the creator-facing op and its `*System` twin) ───────────────────────
-
-/** Run one control PRIMITIVE against an instance after the owner gate. The creator-facing path passes
- *  `enforceOwner: true` (a non-admin may act only on its own instance; a non-owner/absent id yields the
- *  same 404 → no existence oracle, K-C2). The `*System` twin passes `enforceOwner: false` — it crosses
- *  creators by construction and is `control:admin`-gated at the op level, so it never reaches a
- *  non-admin. The primitive itself is idempotent + terminal-safe, so a repeat/no-op cannot corrupt
- *  state. Returns whether the primitive changed anything. */
-async function runControl(
-  ctx: ModuleCtx,
-  deps: ControlModuleDeps,
-  id: string,
-  primitive: (id: string) => Promise<boolean>,
-  enforceOwner: boolean,
-): Promise<boolean> {
-  if (enforceOwner) {
-    const row = await deps.journal.getInstance(id);
-    if (!row || !canSeeInstance(ctx, row)) throw notFound(id);
-  }
-  try {
-    return await primitive(id);
-  } catch (error) {
-    // A retry whose journal retention already pruned is a 409, not a silent "pending" (#3018).
-    if (error instanceof WorkflowHistoryExpiredError) throw new OpError("history_expired", 409, error.message);
-    throw error;
-  }
-}
-
-/** Re-fetch and project the post-control summary for a creator-facing op (the row is guaranteed to
- *  exist — the owner gate already read it). */
-async function controlResult(ctx: ModuleCtx, deps: ControlModuleDeps, id: string): Promise<KernelInstanceSummary> {
-  const row = await deps.journal.getInstance(id);
-  if (!row) throw notFound(id);
-  return projectSummary(row, isControlAdmin(ctx));
-}
-
-const idInput = z.object({ id: z.string().min(1) });
-const listInstancesInput = z.object({
-  module: z.string().optional(),
-  workflow: z.string().optional(),
-  status: statusSchema.optional(),
-  cursor: z.string().optional(),
-  limit: z.coerce.number().int().min(1).max(200).optional(),
-});
-const pageOutput = <T extends z.ZodType>(item: T) => z.object({ items: z.array(item), cursor: z.string().optional() });
-
-/**
- * Build the `control` module bound to the injected kernel-wide capabilities. A FACTORY (not a static
- * `defineModule` const) because the op handlers must close over `deps` — a module's `ctx` cannot reach
- * cross-module journal/event/entity state. The returned manifest is a normal validated
- * {@link ModuleDefinition}; `ModuleHost.register` installs it and serves its ops through the same
- * default-deny invoker every other module uses.
- */
-export function createControlModule(deps: ControlModuleDeps) {
-  return defineModule({
-    id: CONTROL_MODULE_ID,
-    title: "Kernel control & observability",
-    description: "Module-agnostic read + control surface over the Kernel's generic instance/event/entity tables (KAPI-1).",
-    ops: {
-      // ── 6 read ops (K1-3) ──────────────────────────────────────────────────────────────────────
-      // Instance reads ARE creator-scoped via the landed `created_by` column (G-M1).
-      listInstances: {
-        kind: "query",
-        grant: CONTROL_READ_GRANT,
-        summary: "List workflow instances (own only for a non-admin), filtered by module/workflow/status.",
-        http: { method: "GET", path: "/instances" },
-        input: listInstancesInput,
-        output: pageOutput(instanceSummarySchema),
-        handler: async (ctx, input) => {
-          const admin = isControlAdmin(ctx);
-          // G-M1: a non-admin is pinned to its own actor via the keyed `createdBy` filter (which also
-          // excludes NULL-owner rows); an admin omits it and crosses creators.
-          const page = await deps.journal.listInstances({
-            ...(input.module !== undefined ? { module: input.module } : {}),
-            ...(input.workflow !== undefined ? { workflow: input.workflow } : {}),
-            ...(input.status !== undefined ? { status: input.status } : {}),
-            ...(admin ? {} : { createdBy: ctx.principal.actor }),
-            ...(input.cursor !== undefined ? { cursor: input.cursor } : {}),
-            ...(input.limit !== undefined ? { limit: input.limit } : {}),
-          });
-          return {
-            items: page.items.map((row) => projectSummary(row, admin)),
-            ...(page.cursor !== undefined ? { cursor: page.cursor } : {}),
-          };
-        },
-      },
-      getInstance: {
-        kind: "query",
-        grant: CONTROL_READ_GRANT,
-        summary: "Fetch one workflow instance's detail (own only for a non-admin).",
-        http: { method: "GET", path: "/instances/{id}" },
-        input: idInput,
-        output: instanceDetailSchema,
-        handler: async (ctx, input) => {
-          const row = await deps.journal.getInstance(input.id);
-          // G-M1 / G-M5: a non-owner gets the SAME 404 a missing id yields (no existence oracle).
-          if (!row || !canSeeInstance(ctx, row)) throw notFound(input.id);
-          const admin = isControlAdmin(ctx);
-          const steps = admin ? await deps.journal.listSteps(input.id) : [];
-          return projectDetail(row, steps, admin);
-        },
-      },
-      getJournal: {
-        kind: "query",
-        grant: CONTROL_READ_GRANT,
-        summary: "The step-journal ledger for one instance (own only for a non-admin).",
-        http: { method: "GET", path: "/instances/{id}/journal" },
-        input: idInput,
-        output: pageOutput(journalEntrySchema),
-        handler: async (ctx, input) => {
-          // Fail-closed: prove instance ownership BEFORE returning any journal row.
-          const row = await deps.journal.getInstance(input.id);
-          if (!row || !canSeeInstance(ctx, row)) throw notFound(input.id);
-          const admin = isControlAdmin(ctx);
-          const steps = await deps.journal.listSteps(input.id);
-          return { items: steps.map((s) => projectJournalEntry(s, admin)) };
-        },
-      },
-      // Event + entity reads have NO generic owner column → admin-only (fail-closed, G-M5).
-      listEvents: {
-        kind: "query",
-        grant: CONTROL_READ_GRANT,
-        // O3: entry-gated on control:read, but admin-only in-handler (owner-less table). Advertise the
-        // REAL requirement so the derived MCP/OpenAPI surface never names a scope that always 403s.
-        advertiseScopes: [CONTROL_ADMIN_GRANT],
-        summary: "List kernel events for a module (admin-only: events carry no creator column).",
-        http: { method: "GET", path: "/events" },
-        input: z.object({
-          module: z.string().optional(),
-          since: z.coerce.number().int().min(0).optional(),
-          limit: z.coerce.number().int().min(1).max(200).optional(),
-        }),
-        output: z.object({ items: z.array(eventSchema), lastSeq: z.number(), truncated: z.boolean() }),
-        handler: async (ctx, input) => {
-          if (!isControlAdmin(ctx)) throw adminOnly("listEvents");
-          const slice = await deps.events.replay(
-            ctx.principal.scope,
-            input.since ?? 0,
-            input.limit ?? 50,
-            input.module,
-          );
-          return {
-            items: slice.events.map((e) => projectEvent(e, true)),
-            lastSeq: slice.lastSeq,
-            truncated: slice.truncated,
-          };
-        },
-      },
-      listEntities: {
-        kind: "query",
-        grant: CONTROL_READ_GRANT,
-        advertiseScopes: [CONTROL_ADMIN_GRANT], // O3: admin-only in-handler — advertise admin, not control:read.
-        summary: "List a module entity's rows (admin-only: entity rows carry no generic creator column).",
-        http: { method: "GET", path: "/entities/{module}/{entity}" },
-        input: z.object({
-          module: z.string().min(1),
-          entity: z.string().min(1),
-          cursor: z.string().optional(),
-          limit: z.coerce.number().int().min(1).max(200).optional(),
-        }),
-        output: pageOutput(entityRowSchema),
-        handler: async (ctx, input) => {
-          if (!isControlAdmin(ctx)) throw adminOnly("listEntities");
-          const page = await deps.entities.listEntity(input.module, input.entity, ctx.principal.scope, {
-            ...(input.cursor !== undefined ? { cursor: input.cursor } : {}),
-            ...(input.limit !== undefined ? { limit: input.limit } : {}),
-          });
-          return {
-            items: page.items.map((row) => projectEntity(row, true)),
-            ...(page.cursor !== undefined ? { cursor: page.cursor } : {}),
-          };
-        },
-      },
-      getEntity: {
-        kind: "query",
-        grant: CONTROL_READ_GRANT,
-        advertiseScopes: [CONTROL_ADMIN_GRANT], // O3: admin-only in-handler — advertise admin, not control:read.
-        summary: "Fetch one module entity row by key (admin-only).",
-        http: { method: "GET", path: "/entities/{module}/{entity}/{key}" },
-        input: z.object({ module: z.string().min(1), entity: z.string().min(1), key: z.string() }),
-        output: entityRowSchema,
-        handler: async (ctx, input) => {
-          if (!isControlAdmin(ctx)) throw adminOnly("getEntity");
-          const row = await deps.entities.readEntity(input.module, input.entity, ctx.principal.scope, input.key);
-          if (!row) throw new OpError("not_found", 404, `entity '${input.module}/${input.entity}/${input.key}' was not found`);
-          return projectEntity(row, true);
-        },
-      },
-
-      // ── Control ops (K1-5) — creator-facing (control:write, owner-scoped) ────────────────────────
-      cancel: {
-        kind: "mutation",
-        idempotent: true,
-        grant: CONTROL_WRITE_GRANT,
-        summary: "Cancel an OPEN instance you own (terminal-safe, idempotent).",
-        http: { method: "POST", path: "/instances/{id}/cancel" },
-        input: idInput,
-        output: instanceSummarySchema,
-        handler: async (ctx, input) => {
-          await runControl(ctx, deps, input.id, (id) => deps.journal.cancelInstance(id), true);
-          return controlResult(ctx, deps, input.id);
-        },
-      },
-      pause: {
-        kind: "mutation",
-        idempotent: true,
-        grant: CONTROL_WRITE_GRANT,
-        summary: "Pause an OPEN instance you own (gates the driver work-lists; deadline-preserving).",
-        http: { method: "POST", path: "/instances/{id}/pause" },
-        input: idInput,
-        output: instanceSummarySchema,
-        handler: async (ctx, input) => {
-          await runControl(ctx, deps, input.id, (id) => deps.journal.pauseInstance(id), true);
-          return controlResult(ctx, deps, input.id);
-        },
-      },
-      resume: {
-        kind: "mutation",
-        idempotent: true,
-        grant: CONTROL_WRITE_GRANT,
-        summary: "Resume a paused instance you own.",
-        http: { method: "POST", path: "/instances/{id}/resume" },
-        input: idInput,
-        output: instanceSummarySchema,
-        handler: async (ctx, input) => {
-          await runControl(ctx, deps, input.id, (id) => deps.journal.resumeInstance(id), true);
-          return controlResult(ctx, deps, input.id);
-        },
-      },
-      retry: {
-        kind: "mutation",
-        idempotent: true,
-        grant: CONTROL_WRITE_GRANT,
-        summary: "Re-open a failed instance you own so the runtime re-drives it (idempotent no-op otherwise).",
-        http: { method: "POST", path: "/instances/{id}/retry" },
-        input: idInput,
-        output: instanceSummarySchema,
-        handler: async (ctx, input) => {
-          await runControl(ctx, deps, input.id, (id) => deps.journal.reopenInstance(id), true);
-          return controlResult(ctx, deps, input.id);
-        },
-      },
-
-      // ── `*System` twins (control:admin, expose:false) — the reconciler seam (K1-5 / K-C2) ────────
-      // Cross-creator by construction; never surfaced over HTTP/MCP/CLI. K-C2 requires that no
-      // transport authors a tool/command for these AND that `deriveHttpRoutes` excludes them (the
-      // explicit `expose.http:false` below). Best-effort: they return `{changed}` and never 404 on an
-      // absent id (a reconciler may sweep ids that were already reaped) — the `cancelMirror` posture.
-      cancelSystem: {
-        kind: "mutation",
-        idempotent: true,
-        grant: CONTROL_ADMIN_GRANT,
-        summary: "System twin of cancel: cancel ANY instance (reconciler-only; unexposed).",
-        expose: { http: false, mcp: false, cli: false },
-        input: idInput,
-        output: changedSchema,
-        handler: async (ctx, input) => ({ changed: await runControl(ctx, deps, input.id, (id) => deps.journal.cancelInstance(id), false) }),
-      },
-      pauseSystem: {
-        kind: "mutation",
-        idempotent: true,
-        grant: CONTROL_ADMIN_GRANT,
-        summary: "System twin of pause: pause ANY instance (reconciler-only; unexposed).",
-        expose: { http: false, mcp: false, cli: false },
-        input: idInput,
-        output: changedSchema,
-        handler: async (ctx, input) => ({ changed: await runControl(ctx, deps, input.id, (id) => deps.journal.pauseInstance(id), false) }),
-      },
-      resumeSystem: {
-        kind: "mutation",
-        idempotent: true,
-        grant: CONTROL_ADMIN_GRANT,
-        summary: "System twin of resume: resume ANY instance (reconciler-only; unexposed).",
-        expose: { http: false, mcp: false, cli: false },
-        input: idInput,
-        output: changedSchema,
-        handler: async (ctx, input) => ({ changed: await runControl(ctx, deps, input.id, (id) => deps.journal.resumeInstance(id), false) }),
-      },
-      retrySystem: {
-        kind: "mutation",
-        idempotent: true,
-        grant: CONTROL_ADMIN_GRANT,
-        summary: "System twin of retry: re-open ANY failed instance (reconciler-only; unexposed).",
-        expose: { http: false, mcp: false, cli: false },
-        input: idInput,
-        output: changedSchema,
-        handler: async (ctx, input) => ({ changed: await runControl(ctx, deps, input.id, (id) => deps.journal.reopenInstance(id), false) }),
-      },
-    },
-  });
-}
-
-/** The set of op names that are `*System` twins — never exposed over any transport (K-C2). Wave 3's
- *  MCP/CLI binding MUST exclude these; the HTTP surface excludes them via `expose.http:false`. */
-export const CONTROL_SYSTEM_OPS = Object.freeze([
-  "cancelSystem", "pauseSystem", "resumeSystem", "retrySystem",
-] as const);
-
-/** The concrete module definition type {@link createControlModule} returns. */
-export type ControlModule = ReturnType<typeof createControlModule>;