okengine 0.11.2 → 0.13.0

package/src/kernel/elapsed.ts

@@ -0,0 +1,23 @@
+/**
+ * High-res duration vs injectable wall clock.
+ *
+ * `clock.now()` / `Date.now()` stay epoch-ms for timestamps, leases, and
+ * time-travel. Duration is measured with `performance.now()` so a handler
+ * that finishes in the same millisecond is not recorded as 0.
+ */
+
+/**
+ * Combine a wall-clock delta with a high-res elapsed measurement.
+ *
+ * Use the app clock when it ticked (real ms, time-travel, injected tests).
+ * Use high-res only when the wall clock recorded 0 — the case that used
+ * to show `0μs` for a handler that finished in the same millisecond.
+ *
+ * @param wallMs - `endedAt - startedAt` from the injectable clock
+ * @param elapsedMs - `performance.now()` delta over the same span
+ */
+export function resolveDurationMs(wallMs: number, elapsedMs: number): number {
+  const wall = Number.isFinite(wallMs) ? Math.max(0, wallMs) : 0;
+  const elapsed = Number.isFinite(elapsedMs) ? Math.max(0, elapsedMs) : 0;
+  return wall > 0 ? wall : elapsed;
+}

package/src/kernel/errors.ts

@@ -8,8 +8,27 @@
 
 import { docsUrl as absoluteDocsUrl } from "../docs-origin.ts";
 import { getActiveDefaultLocale, getActiveLocale } from "../i18n/locale-context.ts";
-import { getMessageCatalogs, translate } from "../i18n/messages.ts";
-import { resolveFailureMessage } from "../i18n/failure-message.ts";
+import { lazyRequire } from "./lazy-require.ts";
+
+/** Catalogs — kept off the edge `fail` / `OKE_ERRORS` static graph. */
+function loadMessages(): typeof import("../i18n/messages.ts") {
+  const stem = ["mes", "sages"].join("");
+  try {
+    return lazyRequire(`${import.meta.dir}/../i18n`, stem);
+  } catch {
+    return lazyRequire(import.meta.dir, stem);
+  }
+}
+
+/** Failure-message helper — same lazy boundary as {@link loadMessages}. */
+function loadFailureMessage(): typeof import("../i18n/failure-message.ts") {
+  const stem = ["failure", "message"].join("-");
+  try {
+    return lazyRequire(`${import.meta.dir}/../i18n`, stem);
+  } catch {
+    return lazyRequire(import.meta.dir, stem);
+  }
+}
 
 /** Numeric OKE error code (permanent once published). */
 export type OkeErrorCode = number;
@@ -226,7 +245,10 @@ export function lookupOkeError(code: OkeErrorCode): OkeErrorDefinition | undefin
  * @param opts - Optional message override
  */
 export function fail<E>(code: string, data: E, opts?: FailOptions): FlowFailure<E> {
-  const message = opts?.message !== undefined ? opts.message : resolveFailureMessage(code, data);
+  const message =
+    opts?.message !== undefined
+      ? opts.message
+      : loadFailureMessage().resolveFailureMessage(code, data);
   const error: FlowErrorValue<E> = message !== undefined ? { code, data, message } : { code, data };
   return { data: null, error };
 }
@@ -272,6 +294,7 @@ function localizeOkePart(
   locale?: string,
 ): string {
   const key = `oke.${code}.${part}`;
+  const { getMessageCatalogs, translate } = loadMessages();
   const catalogs = getMessageCatalogs();
   const active = locale ?? getActiveLocale("en");
   const defaultLocale = getActiveDefaultLocale("en");

package/src/kernel/flow.ts

@@ -55,7 +55,11 @@ export interface FlowOptions<I = unknown, O = unknown, E extends FlowErrorMap =
   readonly retry?: FxRetryOptions;
   /** Live-query / push result. */
   readonly live?: boolean;
-  /** Cache TTL (`true` = default policy, or a duration string). */
+  /**
+   * Cache policy. Read-only flows cache automatically from inferred
+   * effects (`true` / omitted). `false` opts out; a duration string
+   * (`"30s"`) adds a TTL on top of write invalidation.
+   */
   readonly cache?: boolean | string;
   /** Declared service-level objective. */
   readonly slo?: Slo;

package/src/kernel/fx-ask-telemetry.test.ts

@@ -0,0 +1,114 @@
+/**
+ * fx.ask stamps RunTelemetry.promptVersion and driver-supplied cost.
+ * Token-only drivers must not invent a $0 WideEvent.cost.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { ai, createAiRuntime } from "../elements/ai.ts";
+import { collectWideEvent } from "../runs/collect.ts";
+import { createEffectLedger } from "./effects.ts";
+import { flow } from "./flow.ts";
+import { createFx } from "./fx.ts";
+import { createRunTelemetry } from "./run-telemetry.ts";
+import { internal } from "./triggers.ts";
+
+const triageFlow = flow("support.triage", {
+  in: z.object({}),
+  do: () => ({ ok: true }),
+});
+
+describe("fx.ask RunTelemetry", () => {
+  test("stamps promptVersion and leaves cost 0 when the driver omits cost", async () => {
+    const smart = ai.model("smart", { provider: "openai-compatible" });
+    const triage = smart.prompt("ticket-triage", { version: 3 });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [triage],
+      clients: {
+        smart: {
+          driverId: "openai-compatible",
+          model: "gpt-test",
+          async complete() {
+            return {
+              text: JSON.stringify({ ok: true }),
+              raw: { ok: true },
+              model: "gpt-test",
+              driverId: "openai-compatible",
+              usage: { inputTokens: 12, outputTokens: 7 },
+            };
+          },
+        },
+      },
+    });
+    const telemetry = createRunTelemetry();
+    const ledger = createEffectLedger();
+    const fx = createFx({
+      flow: "support.triage",
+      effects: { asks: ["ticket-triage"] },
+      aiRuntime: runtime,
+      runTelemetry: telemetry,
+      ledger,
+    });
+
+    await fx.ask("ticket-triage", { subject: "x" });
+    expect(telemetry.promptVersion).toBe(3);
+    expect(telemetry.cost).toBe(0);
+    expect(telemetry.inputTokens).toBe(12);
+    expect(telemetry.outputTokens).toBe(7);
+
+    const event = collectWideEvent({
+      flow: triageFlow,
+      trigger: internal,
+      fx,
+      ledger,
+      telemetry,
+      startedAt: 1_000,
+      endedAt: 1_010,
+    });
+    expect(event.promptVersion).toBe(3);
+    expect(event.cost).toBeUndefined();
+    expect(event.dimensions.cost).toBeNull();
+    expect(event.inputTokens).toBe(12);
+    expect(event.outputTokens).toBe(7);
+    expect(event.dimensions.input_tokens).toBe(12);
+    expect(event.dimensions.output_tokens).toBe(7);
+  });
+
+  test("adds journaled cost only when the driver supplies a value greater than zero", async () => {
+    const smart = ai.model("smart", { provider: "mock" });
+    const triage = smart.prompt("ticket-triage", { version: 1 });
+    const runtime = createAiRuntime({
+      models: [smart],
+      prompts: [triage],
+      clients: {
+        smart: {
+          driverId: "mock",
+          model: "mock",
+          async complete() {
+            return {
+              text: JSON.stringify({ ok: true }),
+              raw: { ok: true },
+              model: "mock",
+              driverId: "mock",
+              usage: { inputTokens: 4, outputTokens: 2, cost: 0.42 },
+            };
+          },
+        },
+      },
+    });
+    const telemetry = createRunTelemetry();
+    const fx = createFx({
+      flow: "support.triage",
+      effects: { asks: ["ticket-triage"] },
+      aiRuntime: runtime,
+      runTelemetry: telemetry,
+    });
+
+    await fx.ask("ticket-triage", { subject: "x" });
+    expect(telemetry.promptVersion).toBe(1);
+    expect(telemetry.cost).toBe(0.42);
+    expect(telemetry.inputTokens).toBe(4);
+    expect(telemetry.outputTokens).toBe(2);
+  });
+});

package/src/kernel/fx.test.ts

@@ -39,6 +39,70 @@ describe("fx — capability enforcement", () => {
     expect(oke.message).toBe(formatOkeMessage(1001, oke.causeText, oke.fix, oke.docsUrl));
   });
 
+  test("SQL table with a name column gates as sql:<table>, not sql:<store>", async () => {
+    const { createStoreRuntime, field, store } = await import("../elements/store.ts");
+    const { memorySqlDriver } = await import("../drivers/index.ts");
+    const teams = store.schema.table("teams", {
+      id: field.text().primaryKey(),
+      name: field.text().notNull(),
+    });
+    const decl = store.sql("db", { schema: { teams } });
+    const rt = createStoreRuntime({
+      drivers: { sql: memorySqlDriver },
+      sql: { db: { name: "db", primary: {} } },
+    });
+    rt.register(decl);
+    const fx = createFx({
+      flow: "teams.list",
+      effects: { reads: ["sql:teams"], writes: ["sql:teams"] },
+      storeRuntime: rt,
+    });
+    await fx.store(decl).insert(teams).values({ id: "t1", name: "Eng" });
+    const rows = await fx.store(decl).select().from(teams);
+    expect(rows).toEqual([{ id: "t1", name: "Eng" }]);
+  });
+
+  test("kv ttlMs is a read of kv:<namespace>", async () => {
+    const { createStoreRuntime, store } = await import("../elements/store.ts");
+    const { memoryKvDriver } = await import("../drivers/index.ts");
+    const decl = store.kv("drafts");
+    const rt = createStoreRuntime({
+      drivers: { kv: memoryKvDriver },
+      kv: { drafts: {} },
+    });
+    rt.register(decl);
+    const writer = createFx({
+      flow: "drafts.save",
+      effects: { writes: ["kv:drafts"] },
+      storeRuntime: rt,
+    });
+    await writer.store(decl).set("ENG-1", { title: "Draft" }, "7d");
+    const reader = createFx({
+      flow: "drafts.expire",
+      effects: { reads: ["kv:drafts"] },
+      storeRuntime: rt,
+    });
+    const ttl = await reader.store(decl).ttlMs("ENG-1");
+    expect(ttl).toBeGreaterThan(0);
+  });
+
+  test("index driverId is meilisearch before first I/O (not a function, not memory)", async () => {
+    const { createStoreRuntime, store } = await import("../elements/store.ts");
+    const { meilisearchDriver } = await import("../drivers/index.ts");
+    const decl = store.index("tasks");
+    const rt = createStoreRuntime({
+      drivers: { index: meilisearchDriver },
+      index: { tasks: { url: "http://127.0.0.1:7700" } },
+    });
+    rt.register(decl);
+    const fx = createFx({
+      flow: "search.seed",
+      effects: { writes: ["index:tasks"] },
+      storeRuntime: rt,
+    });
+    expect(fx.store(decl).driverId).toBe("meilisearch");
+  });
+
   test("declared store read succeeds", async () => {
     const fx = createFx({
       flow: "bookings.create",
@@ -135,6 +199,42 @@ describe("fx — effect ledger", () => {
       expect(entry.reversibility).toBe(reversibilityOf(entry.kind));
     }
   });
+
+  test("fx.ask with a prompt handle matches effects.asks name@version", async () => {
+    const fx = createFx({
+      flow: "documents.summarize",
+      effects: { asks: ["document-summary@1"] },
+      aiRuntime: {
+        prompts: new Map(),
+        agents: new Map(),
+        embeds: new Map(),
+        autoCacheDisabled: true,
+        journalingForced: false,
+        denials: [],
+        agentRuns: [],
+        journal: [],
+        async ask() {
+          return { summary: "ok" };
+        },
+        async runAgent() {
+          return { ok: true, steps: 0, denials: [], output: {} };
+        },
+        async *stream() {
+          /* no tokens */
+        },
+        async search() {
+          return [];
+        },
+        async embed() {
+          return { vectors: [] };
+        },
+      } as never,
+    });
+
+    await expect(fx.ask({ name: "document-summary", version: 1 }, {})).resolves.toEqual({
+      summary: "ok",
+    });
+  });
 });
 
 describe("fx.vault — object surface", () => {
@@ -341,8 +441,15 @@ describe("fx — wholesale swap", () => {
         empty() {
           return { [jsonResultBrand]: true, status: 204 };
         },
-        with(data, meta) {
-          return { [jsonResultBrand]: true, status: 200, value: data, meta };
+        with(dataOrPage: unknown, meta?: Record<string, unknown>) {
+          if (meta !== undefined) {
+            return { [jsonResultBrand]: true, status: 200, value: dataOrPage, meta };
+          }
+          const page = dataOrPage as { data: unknown; meta: Record<string, unknown> };
+          return { [jsonResultBrand]: true, status: 200, value: page.data, meta: page.meta };
+        },
+        withQuery(rows) {
+          return { [jsonResultBrand]: true, status: 200, value: [...rows], meta: {} };
         },
       },
       async step(_name, fn) {
@@ -407,6 +514,40 @@ describe("fx.t — catalogs", () => {
   });
 });
 
+describe("fx.json", () => {
+  test("with accepts a page or (data, meta)", () => {
+    const fx = createFx({ flow: "x", effects: {} });
+    const items = [{ id: "n_1" }];
+    const meta = { mode: "offset", total: 1, limit: 1, offset: 0 };
+    const fromPage = fx.json.with({ data: items, meta });
+    const fromArgs = fx.json.with(items, meta);
+    expect(fromPage).toMatchObject({ status: 200, value: items, meta });
+    expect(fromArgs).toMatchObject({ status: 200, value: items, meta });
+    expect(() => fx.json.with(items as never)).toThrow(/pass \(data, meta\)/);
+  });
+
+  test("withQuery pages rows and skips auto-eq on id", () => {
+    const fx = createFx({ flow: "x", effects: {} });
+    const rows = [
+      { id: "c_1", issueId: "iss_1", title: "Ship" },
+      { id: "c_2", issueId: "iss_1", title: "Later" },
+      { id: "c_3", issueId: "iss_2", title: "Ship docs" },
+    ];
+    const page = fx.json.withQuery(rows, { id: "c_1", q: "ship", limit: 10 });
+    expect(page).toMatchObject({
+      status: 200,
+      value: [
+        { id: "c_1", issueId: "iss_1", title: "Ship" },
+        { id: "c_3", issueId: "iss_2", title: "Ship docs" },
+      ],
+    });
+    expect(page.meta).toMatchObject({ mode: "offset", total: 2, next: null });
+
+    const filtered = fx.json.withQuery(rows, { issueId: "iss_1", limit: 10 });
+    expect(filtered.value).toEqual(rows.slice(0, 2));
+  });
+});
+
 describe("errors — registry", () => {
   test("OKE1042 is reserved with the §21 shape", () => {
     const def = OKE_ERRORS.ORPHAN_EMIT;

package/src/kernel/fx.ts

@@ -10,6 +10,7 @@
  */
 
 import type { Effects, ResourceRef } from "../manifest/types.ts";
+import type { QueryPageSpec } from "./list-page.ts";
 import { schemaTableName, sqlTableRef } from "../manifest/sql-resource.ts";
 import type {
   FilesStoreDecl,
@@ -34,6 +35,7 @@ import type { AiRuntime } from "../elements/ai.ts";
 import { parseDurationMs } from "../elements/clock/duration.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
 import { createEffectLedger, recordEffect, reversibilityOf, type EffectLedger } from "./effects.ts";
+import { resolveDurationMs } from "./elapsed.ts";
 import {
   DryRunWriteIsolationError,
   isDryRun,
@@ -59,7 +61,8 @@ import type { RunTelemetry } from "./run-telemetry.ts";
 import type { RunsRuntime } from "../runs/runtime.ts";
 import type { RunsRow, WideEvent } from "../runs/types.ts";
 import type { RunWindowStats, SloBreach } from "../runs/window.ts";
-import { translate, type MessageCatalogs } from "../i18n/messages.ts";
+import type { MessageCatalogs } from "../i18n/messages.ts";
+import { lazyRequire } from "./lazy-require.ts";
 import type { AppMessageKey, MessageValues } from "../i18n/types.ts";
 
 /** Lazy runs/window helpers — kept off the cold `oke` static graph. */
@@ -72,12 +75,13 @@ export const RUNS_RESOURCE = "runs";
 
 export type { FxRetryOptions, FxThunk } from "./concurrency.ts";
 
-/** Named ref: plain string or `{ name }` element handle. */
-export type NamedRef = string | { readonly name: string };
+/** Named ref: plain string or `{ name }` element handle (optional pin). */
+export type NamedRef = string | { readonly name: string; readonly version?: number };
 
-/** Resolve a {@link NamedRef} to its string id. */
+/** Resolve a {@link NamedRef} to its string id (`name@version` when pinned). */
 export function resolveName(ref: NamedRef): string {
-  return typeof ref === "string" ? ref : ref.name;
+  if (typeof ref === "string") return ref;
+  return ref.version !== undefined ? `${ref.name}@${ref.version}` : ref.name;
 }
 
 /** Resolve a store argument to a `facet:name` resource ref. */
@@ -328,6 +332,16 @@ export function isJsonResult(value: unknown): value is JsonResult {
   );
 }
 
+/**
+ * Paginated JSON page — `data` is Flow `out`; `meta` is the HTTP pager.
+ *
+ * Pass this to {@link FxJson.with} instead of splitting the fields.
+ */
+export type JsonPage<T> = {
+  readonly data: T;
+  readonly meta: Record<string, unknown>;
+};
+
 /**
  * JSON response helpers. `fx.json.create` answers 201; `fx.json.ok` can carry
  * a top-level `meta` (Stripe-style `{ data, meta?, error }`);
@@ -340,8 +354,73 @@ export interface FxJson {
   create<T>(value: T): JsonResult<T>;
   /** 204 — no body. */
   empty(): JsonResult<never>;
+  /** 200 — body `{ data, meta, error: null }` from a {@link JsonPage}. */
+  with<T>(page: JsonPage<T>): JsonResult<T>;
   /** 200 — body `{ data, meta, error: null }` (paginated lists). */
   with<T>(data: T, meta: Record<string, unknown>): JsonResult<T>;
+  /**
+   * 200 — page an in-memory list from `input`. Zero-config: `q` searches
+   * every string field; extra keys auto-eq except `id`.
+   */
+  withQuery<T>(rows: readonly T[], input: unknown, spec?: QueryPageSpec<T>): JsonResult<T[]>;
+}
+
+/**
+ * Build a branded 200 result with required `meta`.
+ *
+ * @param dataOrPage - Item array, or `{ data, meta }`
+ * @param meta - Pager when using the two-arg form
+ */
+function jsonWith<T>(dataOrPage: T | JsonPage<T>, meta?: Record<string, unknown>): JsonResult<T> {
+  if (meta !== undefined) {
+    return { [jsonResultBrand]: true, status: 200, value: dataOrPage as T, meta } as JsonResult<T>;
+  }
+  if (
+    typeof dataOrPage !== "object" ||
+    dataOrPage === null ||
+    !("data" in dataOrPage) ||
+    !("meta" in dataOrPage)
+  ) {
+    throw new TypeError("fx.json.with: pass (data, meta) or ({ data, meta })");
+  }
+  const page = dataOrPage as JsonPage<T>;
+  return {
+    [jsonResultBrand]: true,
+    status: 200,
+    value: page.data,
+    meta: page.meta,
+  } as JsonResult<T>;
+}
+
+/**
+ * Sync-load the PostgREST list grammar only when `fx.json.withQuery` runs.
+ * A static import would pin ~4 kB gzip on every `createFx` — including the
+ * edge profile and Store-only `oke()` graphs that never page a list.
+ */
+function loadListPage(): typeof import("./list-page.ts") {
+  return lazyRequire(import.meta.dir, ["list", "page"].join("-"));
+}
+
+/**
+ * Sync-load i18n catalogs only when `fx.t` runs.
+ */
+function loadMessages(): typeof import("../i18n/messages.ts") {
+  return lazyRequire(`${import.meta.dir}/../i18n`, ["mes", "sages"].join(""));
+}
+
+/**
+ * Page rows from a list query and wrap them as {@link FxJson.with}.
+ *
+ * @param rows - Already-loaded items
+ * @param input - List query / path fields
+ * @param spec - Optional mode, keyset, or column lock
+ */
+function jsonWithQuery<T>(
+  rows: readonly T[],
+  input: unknown,
+  spec?: QueryPageSpec<T>,
+): JsonResult<T[]> {
+  return jsonWith(loadListPage().listPage(rows, input, spec));
 }
 
 /** Options for {@link FxVault.set}. */
@@ -787,6 +866,33 @@ export interface FxContext {
   readonly capability: CapabilityToken;
 }
 
+/**
+ * Stamp prompt version, cost, and driver-supplied tokens onto run telemetry.
+ * Cost and tokens are added only when the journal recorded a value greater
+ * than zero — token-only drivers must not invent a $0 WideEvent field.
+ *
+ * @param telemetry - Per-run collector
+ * @param runtime - AI runtime that just ran the ask
+ * @param prompt - Resolved prompt name
+ */
+function stampAskTelemetry(
+  telemetry: RunTelemetry | undefined,
+  runtime: AiRuntime,
+  prompt: string,
+): void {
+  if (!telemetry) return;
+  const last = runtime.journal[runtime.journal.length - 1];
+  const fromJournal = last?.prompt === prompt ? last : undefined;
+  const version = fromJournal?.version ?? runtime.prompts.get(prompt)?.version;
+  if (typeof version === "number") telemetry.promptVersion = version;
+  const cost = fromJournal?.cost ?? 0;
+  if (cost > 0) telemetry.cost += cost;
+  const inputTokens = fromJournal?.inputTokens ?? 0;
+  if (inputTokens > 0) telemetry.inputTokens += inputTokens;
+  const outputTokens = fromJournal?.outputTokens ?? 0;
+  if (outputTokens > 0) telemetry.outputTokens += outputTokens;
+}
+
 /**
  * Create an in-memory `fx` context (v1 stubs, full surface).
  *
@@ -1202,7 +1308,14 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         get(_t, prop) {
           if (prop === "ref") return baseRef;
           if (prop === "then") return undefined;
-          const isRead = prop === "get" || prop === "search" || prop === "list";
+          if (prop === "driverId") {
+            const opened = cache.handle;
+            if (opened && "driverId" in opened) return opened.driverId;
+            if (decl.facet === "index") return runtime.indexDriverId ?? "memory";
+            if (decl.facet === "kv") return runtime.kvDriverId ?? "memory";
+            return "memory";
+          }
+          const isRead = prop === "get" || prop === "search" || prop === "list" || prop === "ttlMs";
           return (...args: unknown[]) =>
             gated(isRead ? "read" : "write", baseRef, async () => {
               if (!isRead && isDryRun()) {
@@ -1329,6 +1442,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
   async function gatedSecret<T>(name: string, body: () => T | Promise<T>): Promise<T> {
     capability.assert("secret", name);
     const timestamp = now();
+    const t0 = performance.now();
     try {
       return await body();
     } finally {
@@ -1336,7 +1450,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         kind: "secret",
         resource: name,
         timestamp,
-        duration: Math.max(0, now() - timestamp),
+        duration: resolveDurationMs(now() - timestamp, performance.now() - t0),
         reversibility: reversibilityOf("secret"),
       });
     }
@@ -1587,14 +1701,18 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           return {};
         }
         if (options.aiRuntime) {
-          return options.aiRuntime.ask(name, input, {
-            via: opts?.via?.map(resolveName),
-            ...(opts?.timeout !== undefined ? { timeout: opts.timeout } : {}),
-            tools: opts?.tools?.map(resolveName),
-            maxSteps: opts?.maxSteps,
-            // Host fx.call — same capability / ledger / Runs path as any call.
-            callTool: (tool, toolInput) => fx.call(tool, toolInput),
-          });
+          try {
+            return await options.aiRuntime.ask(name, input, {
+              via: opts?.via?.map(resolveName),
+              ...(opts?.timeout !== undefined ? { timeout: opts.timeout } : {}),
+              tools: opts?.tools?.map(resolveName),
+              maxSteps: opts?.maxSteps,
+              // Host fx.call — same capability / ledger / Runs path as any call.
+              callTool: (tool, toolInput) => fx.call(tool, toolInput),
+            });
+          } finally {
+            stampAskTelemetry(telemetry, options.aiRuntime, name);
+          }
         }
         throw new Error(`fx.ask: AI runtime is not configured for prompt "${name}"`);
       });
@@ -1680,7 +1798,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     },
     log,
     t(key, values) {
-      return translate({
+      return loadMessages().translate({
         locale,
         defaultLocale,
         catalogs,
@@ -1712,9 +1830,8 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       empty(): JsonResult<never> {
         return { [jsonResultBrand]: true, status: 204 } as JsonResult<never>;
       },
-      with<T>(data: T, meta: Record<string, unknown>): JsonResult<T> {
-        return { [jsonResultBrand]: true, status: 200, value: data, meta } as JsonResult<T>;
-      },
+      with: jsonWith,
+      withQuery: jsonWithQuery,
     },
     async step<T>(name: string, fn: () => T | Promise<T>, opts?: StepOptions<T>): Promise<T> {
       if (journal) {

package/src/kernel/graceful-shutdown.test.ts

@@ -8,6 +8,7 @@ import { createClockRuntime, createMemoryCronStore } from "../elements/clock.ts"
 import { tryAcquireLease } from "../elements/clock/leader.ts";
 import { createMemoryJournalStore, hasJournalLease, JOURNAL_DEFAULT_LEASE_MS } from "./journal.ts";
 import { releaseInstanceLeases } from "./graceful-shutdown.ts";
+import { createInstanceRuntime, createMemoryInstanceStore } from "./instances.ts";
 
 describe("releaseInstanceLeases", () => {
   test("releases Clock cron leases held by this instance", async () => {
@@ -73,4 +74,23 @@ describe("releaseInstanceLeases", () => {
 
     expect((await store.get(runId))!.lockedBy).toBeUndefined();
   });
+
+  test("releases this process's fleet registry row", async () => {
+    const store = createMemoryInstanceStore();
+    const instances = createInstanceRuntime({
+      instanceId: "inst-a",
+      store,
+      env: "dev",
+      now: () => 1_000,
+    });
+    await instances.heartbeat(1_000);
+    expect(await store.get("inst-a")).toBeDefined();
+
+    await releaseInstanceLeases({
+      bootResult: { instances },
+      stop: async () => {},
+    });
+
+    expect(await store.get("inst-a")).toBeUndefined();
+  });
 });

package/src/kernel/graceful-shutdown.ts

@@ -1,6 +1,7 @@
 /**
- * Graceful shutdown — release Clock / Journal leases held by this instance,
- * then stop the HTTP server and close element runtimes.
+ * Graceful shutdown — release Clock / Journal leases and the fleet registry
+ * row held by this instance, then stop the HTTP server and close element
+ * runtimes.
  *
  * Reuses existing `releaseLease` APIs. Signal message leases have no release
  * surface today — survivors reclaim after TTL (lazy claim).
@@ -23,12 +24,15 @@ export interface GracefulShutdownApp {
       readonly instanceId: string;
       readonly store: JournalStore;
     };
+    readonly instances?: {
+      release(): Promise<void>;
+    };
   };
   stop(): Promise<void>;
 }
 
 /**
- * Release Clock cron leases and Journal run leases held by this instance.
+ * Release Clock cron leases, Journal run leases, and this process's fleet row.
  *
  * @param app - Booted app
  */
@@ -54,6 +58,8 @@ export async function releaseInstanceLeases(app: GracefulShutdownApp): Promise<v
       }
     }
   }
+
+  await boot.instances?.release();
 }
 
 /** Options for {@link installGracefulShutdown}. */