okengine 0.11.2 → 0.13.0

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) };
+}

package/src/kernel/compensate.test.ts

@@ -10,7 +10,8 @@ import { flow } from "./flow.ts";
 import { oke } from "./app.ts";
 import { createRunsRuntime } from "../runs/runtime.ts";
 import { runDurable } from "../elements/clock/durable.ts";
-import { fail } from "./errors.ts";
+import { fail, OkeError, OKE_ERRORS } from "./errors.ts";
+import { failureCodeOf, failureFromUnknown } from "./compensate.ts";
 
 function memoryJournal(store = createMemoryJournalStore()): JournalRuntime {
   return {
@@ -413,3 +414,35 @@ describe("durable compensate", () => {
     }
   });
 });
+
+describe("failureFromUnknown", () => {
+  test("OkeError keeps OKE#### code and cause text", () => {
+    const err = new OkeError(OKE_ERRORS.UNDECLARED_WRITE, {
+      flow: "drafts.expire",
+      resource: "kv:drafts",
+    });
+    expect(failureCodeOf(err)).toBe("OKE1002");
+    expect(failureFromUnknown(err)).toEqual({
+      data: null,
+      error: {
+        code: "OKE1002",
+        data: { flow: "drafts.expire", resource: "kv:drafts" },
+        message: 'Flow "drafts.expire" writes "kv:drafts" without declaring it.',
+      },
+    });
+  });
+
+  test("plain Error keeps its message", () => {
+    const err = new Error("card_declined");
+    expect(failureFromUnknown(err).error).toEqual({
+      code: "card_declined",
+      data: {},
+      message: "card_declined",
+    });
+  });
+
+  test("FlowFailure passes through", () => {
+    const failure = fail("CycleClosed", { cycleId: "c1" }, { message: "already closed" });
+    expect(failureFromUnknown(failure)).toBe(failure);
+  });
+});

package/src/kernel/compensate.ts

@@ -6,6 +6,7 @@
  */
 
 import type { AnyFlowDef } from "./flow.ts";
+import { fail, OkeError, type FlowFailure } from "./errors.ts";
 import type { Fx } from "./fx.ts";
 import { isFlowFailure } from "./hooks.ts";
 import { JOURNAL_UNDO_PREFIX, type JournalSession, type JournalStepEntry } from "./journal.ts";
@@ -17,11 +18,29 @@ import { JOURNAL_UNDO_PREFIX, type JournalSession, type JournalStepEntry } from
  */
 export function failureCodeOf(err: unknown): string {
   if (isFlowFailure(err)) return err.error.code;
+  if (err instanceof OkeError) return `OKE${err.code}`;
   if (err instanceof Error && err.name && err.name !== "Error") return err.name;
   if (err instanceof Error && err.message) return err.message.slice(0, 120);
   return "Error";
 }
 
+/**
+ * Coerce a thrown value into a {@link FlowFailure} for Runs wide events.
+ *
+ * {@link OkeError} keeps its numeric code and cause so Traces can show
+ * `OKE1002` instead of a bare `OkeError` with no message.
+ *
+ * @param err - Thrown value or {@link FlowFailure}
+ */
+export function failureFromUnknown(err: unknown): FlowFailure {
+  if (isFlowFailure(err)) return err;
+  if (err instanceof OkeError) {
+    return fail(`OKE${err.code}`, { ...err.params }, { message: err.causeText });
+  }
+  const message = err instanceof Error ? err.message : undefined;
+  return fail(failureCodeOf(err), {}, message !== undefined ? { message } : undefined);
+}
+
 /** Forward step names only (excludes journaled `undo:*` entries). */
 export function forwardCompletedSteps(session: JournalSession): readonly string[] {
   return session.run.entries

package/src/kernel/effect-timing.test.ts

@@ -33,6 +33,22 @@ describe("per-effect timing (EffectEntry, not RunTelemetry / hooks)", () => {
     expect(ledger.entries[0]!.duration).toBe(41);
   });
 
+  test("frozen clock still records high-res duration", async () => {
+    const ledger = createEffectLedger();
+    await recordEffect(
+      ledger,
+      "read",
+      "sql:notes",
+      () => 1_000,
+      async () => {
+        await Bun.sleep(2);
+        return "ok";
+      },
+    );
+    expect(ledger.entries[0]!.timestamp).toBe(1_000);
+    expect(ledger.entries[0]!.duration).toBeGreaterThan(1);
+  });
+
   test("gated fx.store / fx.emit / fx.send populate EffectEntry timing", async () => {
     const telemetry = createRunTelemetry();
     let t = 5000;

package/src/kernel/effects-stamping.test.ts

@@ -47,7 +47,7 @@ const CreateOut = z.object({ ok: z.boolean() });
 
 function buildUnannotatedCreateFlow(db: ReturnType<typeof store.sql>) {
   return on(
-    http.post("/notes").gate(gate.public),
+    http.post("/notes").gate.public,
     flow("notes.create", {
       in: CreateIn,
       out: CreateOut,
@@ -140,7 +140,7 @@ describe("boot-level: table-ref resolution stays backward compatible", () => {
     resetFlowSeq();
     const db = store.sql("app", { schema: { notes } });
     const create = on(
-      http.post("/notes").gate(gate.public),
+      http.post("/notes").gate.public,
       flow("notes.create", {
         in: CreateIn,
         out: CreateOut,
@@ -193,7 +193,7 @@ import { on, flow, http, gate } from "okengine";
 const db = {} as any;
 const notes = {} as any;
 export const create = on(
-  http.post("/notes").gate(gate.public),
+  http.post("/notes").gate.public,
   flow("notes.create", {
     do: async (input, fx) => {
       await fx.store(db).insert(notes).values({ id: input.id, title: input.title, createdAt: 1 });

package/src/kernel/effects.test.ts

@@ -3,6 +3,7 @@ import {
   createEffectLedger,
   EFFECT_KIND_TIERS,
   recordEffect,
+  recordObservedEffect,
   reversibilityOf,
   type EffectKind,
   type ReversibilityTier,
@@ -70,6 +71,20 @@ describe("effects — ledger", () => {
     });
   });
 
+  test("recordObservedEffect appends a completed observation without re-entering work", () => {
+    const ledger = createEffectLedger();
+    recordObservedEffect(ledger, "read", "computed:sql:notes/notes.list/-", 1_000, 0.4);
+    expect(ledger.entries).toEqual([
+      {
+        kind: "read",
+        resource: "computed:sql:notes/notes.list/-",
+        timestamp: 1_000,
+        duration: 0.4,
+        reversibility: "none",
+      },
+    ]);
+  });
+
   test("clear empties the ledger", () => {
     const ledger = createEffectLedger();
     ledger.record({

package/src/kernel/effects.ts

@@ -5,6 +5,8 @@
  * the journal, tests, runs store, and capability check all read.
  */
 
+import { resolveDurationMs } from "./elapsed.ts";
+
 /** The seven load-bearing effect kinds (manifest `effects` keys, singular). */
 export type EffectKind = "read" | "write" | "emit" | "send" | "ask" | "secret" | "call";
 
@@ -34,7 +36,7 @@ export interface EffectEntry {
   readonly resource: string;
   /** Epoch-ms when the call started. */
   readonly timestamp: number;
-  /** Wall duration in milliseconds. */
+  /** Duration in milliseconds (high-res; may be fractional). */
   readonly duration: number;
   /** Reversibility tier for {@link kind}. */
   readonly reversibility: ReversibilityTier;
@@ -95,6 +97,9 @@ export function createEffectLedger(): EffectLedger {
 /**
  * Record an effect around an async (or sync) body, measuring duration.
  *
+ * Timestamp comes from `now` (epoch-ms). Duration prefers `performance.now()`
+ * so a frozen / same-millisecond clock does not record 0.
+ *
  * @param ledger - Target ledger
  * @param kind - Effect kind
  * @param resource - Resource ref
@@ -109,19 +114,48 @@ export async function recordEffect<T>(
   body: () => T | Promise<T>,
 ): Promise<T> {
   const timestamp = now();
+  const t0 = performance.now();
   try {
     return await body();
   } finally {
-    ledger.record({
+    recordObservedEffect(
+      ledger,
       kind,
       resource,
       timestamp,
-      duration: Math.max(0, now() - timestamp),
-      reversibility: reversibilityOf(kind),
-    });
+      resolveDurationMs(now() - timestamp, performance.now() - t0),
+    );
   }
 }
 
+/**
+ * Append a completed observation that was already timed.
+ *
+ * Used when the work must not be re-entered (tier-1 cache hit already
+ * called `storeRt.cache.get`) but the ledger still needs an honest entry.
+ *
+ * @param ledger - Target ledger
+ * @param kind - Effect kind
+ * @param resource - Resource ref (or kernel cache key)
+ * @param timestamp - Epoch-ms when the call started
+ * @param duration - Measured duration in milliseconds
+ */
+export function recordObservedEffect(
+  ledger: EffectLedger,
+  kind: EffectKind,
+  resource: string,
+  timestamp: number,
+  duration: number,
+): void {
+  ledger.record({
+    kind,
+    resource,
+    timestamp,
+    duration,
+    reversibility: reversibilityOf(kind),
+  });
+}
+
 /**
  * All seven kinds with their tiers — useful for exhaustive tests.
  */

package/src/kernel/elapsed.test.ts

@@ -0,0 +1,26 @@
+/**
+ * Unit tests for {@link resolveDurationMs}.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { resolveDurationMs } from "./elapsed.ts";
+
+describe("resolveDurationMs", () => {
+  test("prefers high-res when the wall clock did not tick", () => {
+    expect(resolveDurationMs(0, 0.37)).toBe(0.37);
+    expect(resolveDurationMs(0, 0)).toBe(0);
+  });
+
+  test("keeps the app clock when it ticked", () => {
+    expect(resolveDurationMs(2, 2.4)).toBe(2);
+    expect(resolveDurationMs(1, 0.4)).toBe(1);
+    expect(resolveDurationMs(5_000, 3)).toBe(5_000);
+    expect(resolveDurationMs(41, 0.2)).toBe(41);
+  });
+
+  test("non-finite and negative collapse to 0", () => {
+    expect(resolveDurationMs(Number.NaN, 4)).toBe(4);
+    expect(resolveDurationMs(4, Number.NaN)).toBe(4);
+    expect(resolveDurationMs(-12, -3)).toBe(0);
+  });
+});