okengine 0.11.1 → 0.12.0

package/src/kernel/boot-bind/instances.ts

@@ -0,0 +1,58 @@
+/**
+ * Lazy instance-registry binder — loaded only when the fleet is active.
+ */
+
+import type { ConfigEnv } from "../../config/index.ts";
+import { createPostgresInstanceStore } from "../../drivers/instances-postgres.ts";
+import { createInstanceRuntime, type InstanceRuntime, type InstanceStore } from "../instances.ts";
+import type { BootOptions } from "../boot.ts";
+
+/** Result of binding the fleet registry. */
+export interface BindInstancesResult {
+  readonly instances: InstanceRuntime;
+}
+
+/**
+ * Shared SQL URL used by Clock / Journal / the fleet registry.
+ *
+ * @returns DATABASE_URL or OKE_STORE_SQL_URL
+ */
+export function sharedSqlUrl(): string | undefined {
+  return process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL ?? undefined;
+}
+
+/**
+ * Construct a heartbeat runtime. Supported stores: injected · postgres.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param instanceId - Unified process id
+ * @param now - Clock
+ */
+export async function bindInstances(
+  options: BootOptions,
+  env: ConfigEnv,
+  instanceId: string,
+  now: () => number,
+): Promise<BindInstancesResult | undefined> {
+  const prebuilt = options.elements?.instances;
+  if (prebuilt) return { instances: prebuilt };
+
+  let store: InstanceStore | undefined = options.instanceStore;
+  if (!store) {
+    const url = sharedSqlUrl();
+    if (!url || env === "test") return undefined;
+    store = await createPostgresInstanceStore({ url });
+  }
+
+  const instances = createInstanceRuntime({
+    instanceId,
+    store,
+    env,
+    now,
+    heartbeatMs: options.instanceHeartbeatMs,
+    leaseMs: options.instanceLeaseMs,
+  });
+  await instances.heartbeat();
+  return { instances };
+}

package/src/kernel/boot-bind/journal.ts

@@ -14,6 +14,7 @@ import { createPostgresJournalStore } from "../../drivers/journal-postgres.ts";
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { JOURNAL_DEFAULTS } from "../../config/driver-defaults.ts";
 import type { BootOptions } from "../boot.ts";
+import { resolveInstanceId } from "../instance-id.ts";
 
 /** Bound journal runtime — store + this instance's lease identity. */
 export interface JournalRuntime {
@@ -53,7 +54,7 @@ export async function bindJournal(
   env: ConfigEnv,
 ): Promise<BindJournalResult> {
   const driver = resolveJournalDriverId(options, env);
-  const instanceId = options.instanceId ?? `inst-${crypto.randomUUID()}`;
+  const instanceId = resolveInstanceId(options.instanceId);
 
   let store: JournalStore;
   if (driver === "memory") {
@@ -67,7 +68,7 @@ export async function bindJournal(
     if (!url) {
       throw new Error(
         env === "dev"
-          ? 'oke boot: journal driver "postgres" needs DATABASE_URL (did `oke dev` write docker/.env.docker?)'
+          ? 'oke boot: journal driver "postgres" needs DATABASE_URL (did `oke dev` write .env.local?)'
           : 'oke boot: journal driver "postgres" needs DATABASE_URL',
       );
     }

package/src/kernel/boot-bind/runs.ts

@@ -2,22 +2,80 @@
  * Lazy runs binder — loaded only when runs are requested.
  */
 
+import { resolve } from "node:path";
+import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
+import { RUNS_DEFAULTS } from "../../config/driver-defaults.ts";
 import {
   createRunsRuntime,
-  memoryRunsDriver,
   type CreateRunsRuntimeOptions,
+  type RunsDriverId,
   type RunsRuntime,
 } from "../../runs/index.ts";
+import { DEFAULT_RUNS_LOCAL_ROOT } from "../../runs/types.ts";
+import type { BootOptions } from "../boot.ts";
+
+/**
+ * Narrow a config driver id to a known runs protocol.
+ *
+ * @param id - Resolved driver id
+ */
+function asRunsDriverId(id: string): RunsDriverId {
+  if (id === "files" || id === "memory" || id === "postgres" || id === "clickhouse") {
+    return id;
+  }
+  throw new Error(
+    `oke boot: unknown runs driver "${id}" (expected files · memory · postgres · clickhouse)`,
+  );
+}
+
+/**
+ * Resolve `drivers.runs` for the active env.
+ *
+ * @param options - Boot options
+ * @param env - Active {@link ConfigEnv}
+ */
+export function resolveRunsDriverId(options: BootOptions, env: ConfigEnv): RunsDriverId {
+  return asRunsDriverId(resolveDriverId(options.config?.drivers?.runs, env, RUNS_DEFAULTS)!);
+}
+
+/**
+ * Default Parquet keep window when `runs.keep` is unset.
+ *
+ * @param env - Active {@link ConfigEnv}
+ */
+export function defaultRunsKeep(env: ConfigEnv): string {
+  if (env === "prod") return "30d";
+  if (env === "dev") return "7d";
+  return "forever";
+}
 
 /**
  * Construct and open a runs runtime.
  *
- * @param options - Create options (when not already a runtime)
+ * Explicit `oke({ runs: { driver } })` wins. Otherwise `drivers.runs` merges
+ * onto {@link RUNS_DEFAULTS} (`files` in `dev`/`prod`, `memory` in `test`).
+ *
+ * @param options - Boot options (config + rootDir)
+ * @param env - Active {@link ConfigEnv}
+ * @param createOpts - Create options when `oke({ runs: { … } })` is not a runtime
  */
-export async function bindRuns(options?: CreateRunsRuntimeOptions): Promise<RunsRuntime> {
+export async function bindRuns(
+  options: BootOptions,
+  env: ConfigEnv,
+  createOpts?: CreateRunsRuntimeOptions,
+): Promise<RunsRuntime> {
+  const driver = createOpts?.driver ?? resolveRunsDriverId(options, env);
+  const root = options.rootDir ?? process.cwd();
+  const localRoot = createOpts?.localRoot ?? resolve(root, DEFAULT_RUNS_LOCAL_ROOT);
+  const keep = createOpts?.retention?.keep ?? options.config?.runs?.keep ?? defaultRunsKeep(env);
   const runs = createRunsRuntime({
-    driver: options?.driver ?? memoryRunsDriver,
-    ...(options ?? {}),
+    ...createOpts,
+    driver,
+    localRoot,
+    retention: {
+      ...createOpts?.retention,
+      keep,
+    },
   });
   if (!runs.store) {
     await runs.open();

package/src/kernel/boot-bind/signal.ts

@@ -26,7 +26,7 @@ function redisUrlFor(docker: boolean): string | undefined {
   const url = process.env.REDIS_URL ?? process.env.OKE_STORE_KV_URL ?? undefined;
   if (!url && docker) {
     throw new Error(
-      "oke boot: signal redis driver needs REDIS_URL (did `oke dev -d` write docker/.env.docker?)",
+      "oke boot: signal redis driver needs REDIS_URL (did `oke dev -d` write .env.local?)",
     );
   }
   return url;

package/src/kernel/boot-bind/store.ts

@@ -26,7 +26,7 @@ import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runt
  * Construct a Store runtime and register facet declarations.
  *
  * With compose infra (`OKE_DOCKER=1` / `oke dev`), SQL/KV URLs come from
- * `docker/.env.docker`. `env: "test"` uses PGLite (`memory://` by default).
+ * `.env.local`. `env: "test"` uses PGLite (`memory://` by default).
  *
  * @param options - Boot options
  * @param env - Active environment
@@ -254,7 +254,7 @@ function sqlUrlFor(sqlId: string, docker: boolean, env: ConfigEnv): string {
     if (!url) {
       throw new Error(
         docker
-          ? "oke boot: postgres driver needs DATABASE_URL (did `oke dev` write docker/.env.docker?)"
+          ? "oke boot: postgres driver needs DATABASE_URL (did `oke dev` write .env.local?)"
           : "oke boot: postgres driver needs DATABASE_URL",
       );
     }
@@ -274,7 +274,7 @@ function kvUrlFor(kvId: string, docker: boolean): string | undefined {
   if (!url) {
     throw new Error(
       docker
-        ? "oke boot: redis driver needs REDIS_URL (did `oke dev` write docker/.env.docker?)"
+        ? "oke boot: redis driver needs REDIS_URL (did `oke dev` write .env.local?)"
         : "oke boot: redis driver needs REDIS_URL",
     );
   }
@@ -292,7 +292,7 @@ function indexUrlFor(docker: boolean): string {
   if (!url) {
     throw new Error(
       docker
-        ? "oke boot: meilisearch index needs OKE_STORE_INDEX_URL (did `oke dev` write docker/.env.docker?)"
+        ? "oke boot: meilisearch index needs OKE_STORE_INDEX_URL (did `oke dev` write .env.local?)"
         : "oke boot: meilisearch index needs OKE_STORE_INDEX_URL",
     );
   }

package/src/kernel/boot.test.ts

@@ -79,7 +79,7 @@ describe("boot — lazy element needs", () => {
     expect(needs.signal).toBe(false);
   });
 
-  test("oke() Store-only graph stays under the prior 39 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 48 kB baseline", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-store-only-"));
     const entry = join(dir, "entry.ts");
     const appPath = join(import.meta.dir, "app.ts");
@@ -116,9 +116,9 @@ describe("boot — lazy element needs", () => {
         if (raw.byteLength === 0) continue;
         total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
       }
-      // Rebased after lazy `gate.auth` / auth-config chunks + `gate.public`
-      // decoupling from kv-lua strategies (~38.9 kB gzip with export externals).
-      expect(total).toBeLessThan(40_000);
+      // Rebased after 0.12.0 store/http graph growth
+      // (~47.6 kB gzip with export externals).
+      expect(total).toBeLessThan(48_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
@@ -174,10 +174,11 @@ describe("boot — cron fires without manual dispatch", () => {
     });
 
     const rt = app.bootResult!.clock!;
-    // First tick — due (never ran).
+    expect((await rt.store.list()).map((r) => r.name)).toEqual(["expire-stale"]);
+    // First tick — due (never ran). Named clock covers `every("1h")` — no twin `1h` row.
     const { ran: names } = await rt.tick();
-    expect(names.length).toBeGreaterThan(0);
-    expect(ran).toBeGreaterThanOrEqual(1);
+    expect(names).toEqual(["expire-stale"]);
+    expect(ran).toBe(1);
 
     // Advance past the effective every; tick again without dispatchEvery.
     rt.advance("1h");
@@ -225,9 +226,8 @@ describe("boot — HTTP gate wiring on the default path", () => {
   test("bare oke().fetch() with gate.public boots and serves", async () => {
     resetBindings();
     resetFlowSeq();
-    const { gate } = await import("../elements/gate.ts");
     on(
-      http.get("/ping").gate(gate.public),
+      http.get("/ping").gate.public,
       flow("ping-public", {
         do: () => ({ ok: true }),
       }),

package/src/kernel/boot.ts

@@ -7,7 +7,8 @@
  * 3. Signals   — register declarations; start consumers
  * 4. Clocks    — reconcile into the Store
  * 4b. Journal  — bind the durable-run store (SKIP LOCKED + lease when shared)
- * 4c. Scheduler — tick clocks + resume due durable runs (leader election)
+ * 4c. Instances — fleet registry heartbeat (TTL liveness; off in test)
+ * 4d. Scheduler — tick clocks + resume due durable runs + fleet heartbeat
  * 5. Channel   — bind channel runtime
  * 6. AI        — bind AI runtime
  * 7. Runs      — open the runs store
@@ -26,7 +27,8 @@
  * never the code directly (console §5).
  */
 
-import type { ConfigEnv, OkeConfig } from "../config/index.ts";
+import { resolveDriverId, type ConfigEnv, type OkeConfig } from "../config/index.ts";
+import { CLOCK_DEFAULTS, JOURNAL_DEFAULTS } from "../config/driver-defaults.ts";
 import type { AiRuntime, CreateAiRuntimeOptions } from "../elements/ai.ts";
 import type { ChannelRuntime, CreateChannelRuntimeOptions } from "../elements/channel.ts";
 import type { ClockDecl, ClockRuntime } from "../elements/clock.ts";
@@ -39,7 +41,15 @@ import type {
   VaultSecretDecl,
 } from "../elements/vault.ts";
 import type { JournalRuntime } from "./boot-bind/journal.ts";
-import type { CreateRunsRuntimeOptions, RunsRuntime } from "../runs/index.ts";
+import type { InstanceRuntime, InstanceStore } from "./instances.ts";
+import { resolveInstanceId } from "./instance-id.ts";
+import {
+  resolveRunsConsoleBridge,
+  wrapRunsForConsoleIngest,
+  type CreateRunsRuntimeOptions,
+  type RunsConsoleBridgeTarget,
+  type RunsRuntime,
+} from "../runs/index.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
 import { throwOke } from "./errors.ts";
 import type { AnyFlowDef } from "./flow.ts";
@@ -59,18 +69,21 @@ export interface ElementRuntimes {
   readonly runs?: RunsRuntime;
   /** Pre-bound durable-run journal (skips driver resolution). */
   readonly journal?: JournalRuntime;
+  /** Pre-bound fleet registry (skips driver resolution). */
+  readonly instances?: InstanceRuntime;
 }
 
 /** Declarations + options consumed by {@link bootApplication}. */
 export interface BootOptions {
   /**
-   * Active environment (defaults to `local`, or `docker` when
-   * {@link docker} / `OKE_DOCKER=1`).
+   * Active {@link ConfigEnv} (`dev` · `test` · `prod`).
+   * Default: `prod` when `NODE_ENV=production`; `dev` when Compose is up
+   * ({@link docker} / `OKE_DOCKER=1`); otherwise `test`.
    */
   readonly env?: ConfigEnv;
   /**
-   * Docker mode (`oke dev -d` / `OKE_DOCKER=1`): force driver maps to the
-   * `docker` profile and prefer compose URLs (`docker/.env.docker`).
+   * Compose infra is up (`oke dev` / `OKE_DOCKER=1`): prefer compose URLs
+   * (`.env.local`) and resolve {@link env} to `dev` when unset.
    * When unset, derived from `process.env.OKE_DOCKER`.
    */
   readonly docker?: boolean;
@@ -88,10 +101,10 @@ export interface BootOptions {
   readonly gates?: readonly GateDecl[];
   /**
    * HTTP auth-posture enforcement at boot.
-   * - `"deny"` (default) — every HTTP trigger must carry a gate or `gate.public`
+   * - `"deny"` (default) — every HTTP trigger must carry a gate or `.gate.public`
    * - `"allow"` — skips the audit **only** when {@link env} is `"test"`;
    *   ignored in local/prod/docker (never a production-wide bypass).
-   *   Migrate real apps with per-trigger `gate.public`.
+   *   Migrate real apps with per-trigger `.gate.public`.
    */
   readonly unguardedHttp?: "deny" | "allow";
   /** Signal declarations. */
@@ -106,6 +119,14 @@ export interface BootOptions {
   readonly ai?: CreateAiRuntimeOptions;
   /** Runs runtime or create options. */
   readonly runs?: RunsRuntime | CreateRunsRuntimeOptions;
+  /**
+   * Push recorded WideEvents to Console ingest (`oke dev` live Traces bridge).
+   * When set (or via `OKE_RUNS_INGEST_*` env), boot enables a runs store
+   * automatically (`files` in `dev`/`prod`, `memory` in `test`). `false`
+   * disables env lookup. Prod recording stays opt-in — only `oke dev`
+   * sets the env.
+   */
+  readonly runsBridge?: RunsConsoleBridgeTarget | false;
   /** Adopted bindings (for every→cron + signal consumers). */
   readonly bindings?: readonly Binding[];
   /** Flows known to the app (for capability minting). */
@@ -160,8 +181,17 @@ export interface BootOptions {
     readonly kv?: import("../drivers/types.ts").KvClientLike;
     readonly signalRedis?: import("../drivers/signal-types.ts").SignalRedisClientLike;
   };
-  /** Instance id for leader election. */
+  /**
+   * Process instance id for Clock / Journal / fleet registry.
+   * When unset, boot mints one `inst-<uuid>` and passes it to every binder.
+   */
   readonly instanceId?: string;
+  /** Injected fleet store (chaos / tests — activates the registry in `test`). */
+  readonly instanceStore?: InstanceStore;
+  /** Fleet heartbeat write interval ms (default 5_000). */
+  readonly instanceHeartbeatMs?: number;
+  /** Fleet presence TTL ms (default 30_000 — matches Clock / Journal). */
+  readonly instanceLeaseMs?: number;
   /**
    * Start a background scheduler tick loop.
    * Default: `true` when `env !== "test"`; `false` in test (opt in explicitly).
@@ -184,6 +214,13 @@ export interface BootResult {
   readonly runs?: RunsRuntime;
   /** Durable-run journal (present when any flow declares `durable: true`). */
   readonly journal?: JournalRuntime;
+  /**
+   * Unified process instance id (Clock, Journal, and the fleet registry
+   * share this value).
+   */
+  readonly instanceId: string;
+  /** Fleet registry (absent in `test` unless a store is injected). */
+  readonly instances?: InstanceRuntime;
   /** Per-flow capability tokens minted from declared effects. */
   readonly capabilities: ReadonlyMap<string, CapabilityToken>;
   /** Stop the background scheduler (if started). */
@@ -225,7 +262,10 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
   let gate = pre.gate !== undefined || (options.gates?.length ?? 0) > 0;
   let channel = pre.channel !== undefined || options.channel !== undefined;
   let ai = pre.ai !== undefined || options.ai !== undefined;
-  let runs = pre.runs !== undefined || options.runs !== undefined;
+  let runs =
+    pre.runs !== undefined ||
+    options.runs !== undefined ||
+    resolveRunsConsoleBridge(options.runsBridge) !== null;
   let journal = pre.journal !== undefined;
 
   const considerFlow = (f: AnyFlowDef): void => {
@@ -265,6 +305,34 @@ export function resolveElementNeeds(options: BootOptions): ElementNeeds {
   return { vault, store, signal, clock, gate, channel, ai, runs, journal };
 }
 
+/**
+ * Whether boot should open the fleet registry.
+ *
+ * `test` stays off unless a store is injected. `dev`/`prod` activate when
+ * a shared SQL URL exists and Clock or Journal is actually postgres — or
+ * when the app has neither (HTTP-only replicas still census on Postgres).
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param needs - Resolved element needs
+ */
+function shouldBindFleetRegistry(
+  options: BootOptions,
+  env: ConfigEnv,
+  needs: ElementNeeds,
+): boolean {
+  if (options.elements?.instances !== undefined) return true;
+  if (options.instanceStore !== undefined) return true;
+  if (env === "test") return false;
+  const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL;
+  if (!url) return false;
+  const clockDriver = resolveDriverId(options.config?.drivers?.clock, env, CLOCK_DEFAULTS);
+  const journalDriver = resolveDriverId(options.config?.drivers?.journal, env, JOURNAL_DEFAULTS);
+  if (needs.clock && clockDriver === "postgres") return true;
+  if (needs.journal && journalDriver === "postgres") return true;
+  return !needs.clock && !needs.journal;
+}
+
 /**
  * Dynamically load a boot-bind module without pulling it into the bundler
  * graph (expression `new URL` — Bun resolves at runtime).
@@ -298,7 +366,8 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       config = undefined;
     }
   }
-  const options: BootOptions = { ...input, config, env, docker };
+  const instanceId = resolveInstanceId(input.instanceId);
+  const options: BootOptions = { ...input, config, env, docker, instanceId };
   const pre = options.elements ?? {};
   const now = options.now ?? (() => Date.now());
   const needs = resolveElementNeeds(options);
@@ -324,6 +393,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   type ChannelBind = typeof import("./boot-bind/channel.ts");
   type AiBind = typeof import("./boot-bind/ai.ts");
   type RunsBind = typeof import("./boot-bind/runs.ts");
+  type InstancesBind = typeof import("./boot-bind/instances.ts");
 
   let storeBind: StoreBind | undefined;
   let signalBind: SignalBind | undefined;
@@ -333,6 +403,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   let channelBind: ChannelBind | undefined;
   let aiBind: AiBind | undefined;
   let runsBind: RunsBind | undefined;
+  let instancesBind: InstancesBind | undefined;
 
   if (needs.store && !pre.store) {
     binderLoads.push(
@@ -362,6 +433,14 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       }),
     );
   }
+  const wantInstances = shouldBindFleetRegistry(options, env, needs);
+  if (wantInstances && !pre.instances) {
+    binderLoads.push(
+      loadBind<InstancesBind>("instances").then((m) => {
+        instancesBind = m;
+      }),
+    );
+  }
   if (needs.gate && !pre.gate) {
     binderLoads.push(
       loadBind<GateBind>("gate").then((m) => {
@@ -433,16 +512,25 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     journal = (await journalBind!.bindJournal(options, env)).journal;
   }
 
-  // 4c. Scheduler — one timer drives clock ticks and durable-run resume.
+  // 4c. Fleet registry — one row per process (TTL liveness). Off in `test`
+  // unless a store is injected. Shares the 1s scheduler timer; writes every 5s.
+  let instances = pre.instances;
+  if (!instances && instancesBind) {
+    instances = (await instancesBind.bindInstances(options, env, instanceId, now))?.instances;
+  }
+
+  // 4d. Scheduler — one timer drives clock ticks, durable-run resume, heartbeat.
   let schedulerTimer: ReturnType<typeof setInterval> | undefined;
   const startScheduler = options.startScheduler ?? env !== "test";
-  if (startScheduler && (clock !== undefined || journal !== undefined)) {
+  if (startScheduler && (clock !== undefined || journal !== undefined || instances !== undefined)) {
     const period = options.schedulerIntervalMs ?? 1000;
     const clockRt = clock;
     const durableResume = options.onDurableResume;
+    const fleet = instances;
     schedulerTimer = setInterval(() => {
       if (clockRt) void clockRt.tick();
       if (journal && durableResume) void durableResume();
+      if (fleet) void fleet.maybeHeartbeat();
     }, period);
     schedulerTimer.unref?.();
   }
@@ -467,18 +555,26 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
 
   // 7. Runs
   let runs = pre.runs;
-  if (needs.runs) {
+  const runsBridge = resolveRunsConsoleBridge(options.runsBridge);
+  if (needs.runs || runsBridge) {
     if (!runs) {
       if (options.runs && isRunsRuntime(options.runs)) {
         runs = options.runs;
         if (!runs.store) await runs.open();
       } else {
         const runsOpts = options.runs && !isRunsRuntime(options.runs) ? options.runs : undefined;
-        runs = await runsBind!.bindRuns(runsOpts);
+        if (!runsBind) {
+          const m = await loadBind<RunsBind>("runs");
+          runsBind = m;
+        }
+        runs = await runsBind!.bindRuns(options, env, runsOpts);
       }
     } else if (!runs.store) {
       await runs.open();
     }
+    if (runs && runsBridge) {
+      runs = wrapRunsForConsoleIngest(runs, runsBridge);
+    }
   }
 
   // 8. Caps — effect refs only; no element modules (unless a lazy extract is needed).
@@ -503,6 +599,8 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     ai,
     runs,
     journal,
+    instanceId,
+    instances,
     capabilities,
     stopScheduler() {
       if (schedulerTimer !== undefined) {
@@ -520,6 +618,7 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
       await runs?.flush();
       const journalStore = journal?.store as { close?: () => Promise<void> } | undefined;
       await journalStore?.close?.();
+      await instances?.close();
     },
   };
 }

package/src/kernel/capability.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { createCapabilityToken } from "./capability.ts";
+import { OkeError } from "./errors.ts";
+
+describe("capability — prompt pin matching", () => {
+  test("declared name@version allows asking the bare prompt name", () => {
+    const token = createCapabilityToken("documents.summarize", {
+      asks: ["document-summary@1"],
+    });
+    expect(token.allows("ask", "document-summary")).toBe(true);
+    expect(() => token.assert("ask", "document-summary")).not.toThrow();
+  });
+
+  test("declared bare name allows asking a pinned PromptRef", () => {
+    const token = createCapabilityToken("documents.summarize", {
+      asks: ["document-summary"],
+    });
+    expect(token.allows("ask", "document-summary@1")).toBe(true);
+  });
+
+  test("distinct pins of the same prompt do not match", () => {
+    const token = createCapabilityToken("documents.summarize", {
+      asks: ["document-summary@1"],
+    });
+    expect(token.allows("ask", "document-summary@2")).toBe(false);
+    expect(() => token.assert("ask", "document-summary@2")).toThrow(OkeError);
+  });
+
+  test("a different prompt name is still denied", () => {
+    const token = createCapabilityToken("documents.summarize", {
+      asks: ["document-summary@1"],
+    });
+    expect(token.allows("ask", "form-classify")).toBe(false);
+  });
+
+  test("pin matching does not apply to other effect kinds", () => {
+    const token = createCapabilityToken("mail.send", {
+      sends: ["welcome@1"],
+    });
+    expect(token.allows("send", "welcome")).toBe(false);
+  });
+});

package/src/kernel/capability.ts

@@ -39,6 +39,12 @@ const EFFECTS_FIELD: Readonly<Record<EffectKind, keyof Effects>> = {
 export interface CapabilityToken {
   /** Flow id this token was issued for. */
   readonly flow: string;
+  /**
+   * `true` when the compiler has not stamped effects (`declared` was
+   * `undefined` at mint). Open tokens allow every access; empty
+   * `declared` is then "unknown", not least-privilege deny.
+   */
+  readonly open: boolean;
   /** Declared effects that minted this token. */
   readonly declared: Effects;
   /**
@@ -83,14 +89,15 @@ export function createCapabilityToken(flow: string, declared?: Effects): Capabil
 
   return {
     flow,
+    open,
     declared: effects,
     allows(kind: EffectKind, resource: string): boolean {
       if (open) return true;
-      return sets[kind].has(resource);
+      return allowsResource(kind, sets[kind], resource);
     },
     assert(kind: EffectKind, resource: string): void {
       if (open) return;
-      if (sets[kind].has(resource)) return;
+      if (allowsResource(kind, sets[kind], resource)) return;
       throwOke(UNDECLARED_KEY[kind], { flow, resource });
     },
   };
@@ -104,3 +111,38 @@ export function createCapabilityToken(flow: string, declared?: Effects): Capabil
 export function effectsFieldOf(kind: EffectKind): keyof Effects {
   return EFFECTS_FIELD[kind];
 }
+
+/**
+ * Exact match for every kind. `ask` also treats PromptRef pins as
+ * interchangeable: declared `name@version` allows asking `name`, and
+ * declared `name` allows asking `name@version`. Distinct pins do not match.
+ */
+function allowsResource(
+  kind: EffectKind,
+  declared: ReadonlySet<string>,
+  resource: string,
+): boolean {
+  if (declared.has(resource)) return true;
+  return kind === "ask" && promptPinAllows(declared, resource);
+}
+
+/** Prompt refs are `name` or `name@version` — either side may omit the pin. */
+function promptPinAllows(declared: ReadonlySet<string>, resource: string): boolean {
+  const asked = parsePromptPin(resource);
+  for (const entry of declared) {
+    const pin = parsePromptPin(entry);
+    if (pin.name !== asked.name) continue;
+    if (pin.version === undefined || asked.version === undefined || pin.version === asked.version) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function parsePromptPin(ref: string): { readonly name: string; readonly version?: number } {
+  const at = ref.lastIndexOf("@");
+  if (at <= 0) return { name: ref };
+  const tail = ref.slice(at + 1);
+  if (!/^\d+$/.test(tail)) return { name: ref };
+  return { name: ref.slice(0, at), version: Number(tail) };
+}