okengine 0.13.0 → 0.15.2

package/src/kernel/fx.ts

@@ -9,7 +9,8 @@
  * for deterministic tests (§7.6).
  */
 
-import type { Effects, ResourceRef } from "../manifest/types.ts";
+import type { Effects, ResourceRef, SignalResourceRef } from "../manifest/types.ts";
+import { isMcpToolRef } from "../manifest/mcp-ref.ts";
 import type { QueryPageSpec } from "./list-page.ts";
 import { schemaTableName, sqlTableRef } from "../manifest/sql-resource.ts";
 import type {
@@ -26,9 +27,11 @@ import type {
   StoreRuntime,
   SqlStoreHandle,
 } from "../elements/store.ts";
+import { rlsIdentityFromAuth } from "../elements/store.ts";
+import type { RlsIdentity } from "../drivers/pg-rls.ts";
 import type { SqlRow } from "../drivers/types.ts";
-import type { SignalRuntime } from "../elements/signal.ts";
-import type { SignalEmitOptions } from "../drivers/signal-types.ts";
+import type { SignalDecl, SignalRuntime } from "../elements/signal.ts";
+import type { DeadLetter, SignalEmitOptions } from "../drivers/signal-types.ts";
 import type { VaultActor, VaultAdapter, VaultRuntime } from "../elements/vault.ts";
 import type { ChannelRuntime } from "../elements/channel.ts";
 import type { AiRuntime } from "../elements/ai.ts";
@@ -73,6 +76,15 @@ async function loadRunsWindow(): Promise<typeof import("../runs/window.ts")> {
 /** Resource ref Flows declare to read the Runs store via {@link Fx.runs}. */
 export const RUNS_RESOURCE = "runs";
 
+/**
+ * Capability ref for {@link Fx.deadLetters} — `signal:<name>`, never a store facet.
+ *
+ * @param name - Signal name
+ */
+export function signalReadRef(name: string): SignalResourceRef {
+  return `signal:${name}`;
+}
+
 export type { FxRetryOptions, FxThunk } from "./concurrency.ts";
 
 /** Named ref: plain string or `{ name }` element handle (optional pin). */
@@ -140,6 +152,27 @@ export interface FxTenant {
 export interface FxClock {
   /** Current epoch-ms (injectable via {@link CreateFxOptions.now}). */
   now(): number;
+  /**
+   * Instant `duration` before {@link FxClock.now} (`"30d"` → now − 30 days).
+   * Uses the same duration strings as {@link FxClock.sleep} / `every()`.
+   *
+   * @param duration - Duration string (e.g. `"30d"`, `"2h"`)
+   */
+  ago(duration: string): number;
+  /**
+   * Instant `duration` after {@link FxClock.now} (`"14d"` → now + 14 days).
+   * Uses the same duration strings as {@link FxClock.sleep} / `every()`.
+   *
+   * @param duration - Duration string (e.g. `"14d"`, `"15m"`)
+   */
+  fromNow(duration: string): number;
+  /**
+   * Span in milliseconds (`"30d"` → `2_592_000_000`). Compose with a stored
+   * instant: `createdAt + fx.clock.duration("7d")`. Unknown strings are `0`.
+   *
+   * @param duration - Duration string (e.g. `"30d"`, `"200ms"`)
+   */
+  duration(duration: string): number;
   /**
    * Durable sleep — when the flow is `durable`, journals the wake time and
    * survives restart / deploy. Without a journal, resolves immediately
@@ -323,12 +356,36 @@ export interface JsonResult<T = unknown> {
   readonly status: number;
   readonly value?: T;
   readonly meta?: Record<string, unknown>;
+  readonly kind?: undefined;
+}
+
+/** SSE carrier from {@link FxJson.stream}. */
+export interface JsonStreamResult {
+  readonly [jsonResultBrand]: true;
+  readonly kind: "stream";
+  readonly status: 200;
+  readonly chunks: AsyncIterable<string>;
+  /** Set by the kernel to commit journal / Runs after the stream settles. */
+  finalize?: () => Promise<void>;
 }
 
-/** True when `value` is an {@link FxJson} carrier. */
+/** True when `value` is an {@link FxJson} JSON-envelope carrier. */
 export function isJsonResult(value: unknown): value is JsonResult {
   return (
-    typeof value === "object" && value !== null && (value as JsonResult)[jsonResultBrand] === true
+    typeof value === "object" &&
+    value !== null &&
+    (value as JsonResult)[jsonResultBrand] === true &&
+    (value as JsonStreamResult).kind !== "stream"
+  );
+}
+
+/** True when `value` is an SSE stream carrier from {@link FxJson.stream}. */
+export function isJsonStreamResult(value: unknown): value is JsonStreamResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as JsonStreamResult)[jsonResultBrand] === true &&
+    (value as JsonStreamResult).kind === "stream"
   );
 }
 
@@ -363,6 +420,11 @@ export interface FxJson {
    * every string field; extra keys auto-eq except `id`.
    */
   withQuery<T>(rows: readonly T[], input: unknown, spec?: QueryPageSpec<T>): JsonResult<T[]>;
+  /**
+   * 200 — `text/event-stream` of JSON `data:` frames, then `data: [DONE]`.
+   * Pass {@link Fx.stream} or any async iterable of token strings.
+   */
+  stream(chunks: AsyncIterable<string>): JsonStreamResult;
 }
 
 /**
@@ -567,6 +629,15 @@ export interface Fx {
    * @param options - Optional emit options (`key` for per-key once ordering)
    */
   emit(signal: NamedRef, payload?: unknown, options?: SignalEmitOptions): Promise<void>;
+  /**
+   * Query dead-lettered messages for one signal (records `read` on `signal:<name>`).
+   *
+   * Requires a bound signal runtime and `effects.reads` including `signal:<name>`.
+   *
+   * @param signal - Signal name or handle
+   */
+  deadLetters<T>(signal: SignalDecl<T>): Promise<readonly DeadLetter<T>[]>;
+  deadLetters(signal: NamedRef): Promise<readonly DeadLetter[]>;
   /**
    * Call another flow (records `call`). Stub returns `undefined`.
    *
@@ -651,7 +722,11 @@ export interface Fx {
    */
   stream(
     model: NamedRef,
-    opts?: { readonly prompt?: string; readonly data?: unknown },
+    opts?: {
+      readonly prompt?: string;
+      readonly data?: unknown;
+      readonly via?: readonly NamedRef[];
+    },
   ): AsyncIterable<string>;
   /** Logger. */
   readonly log: FxLog;
@@ -838,6 +913,12 @@ export interface CreateFxOptions {
   readonly runId?: string;
   /** Reveal PII through the store runtime (requires `pii:reveal` upstream). */
   readonly revealPii?: boolean;
+  /** Trigger gate names for RLS (`oke.gate` = first policy/public). */
+  readonly rlsGateNames?: readonly string[];
+  /** Skip RLS stamp (Operator / `bypassGates` / operator-plane flows). */
+  readonly rlsBypass?: boolean;
+  /** Forced bag (Console / Call API). Wins over {@link rlsGateNames}. */
+  readonly rls?: import("../drivers/pg-rls.ts").RlsIdentity;
   /**
    * Active journal session when the flow is durable. Every `fx` call is
    * recorded; `step` / `sleep` replay from the journal on resume.
@@ -952,6 +1033,19 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     } satisfies FxPrincipal);
   const journal = options.journal;
 
+  function rlsInvokeContext(): { rls?: RlsIdentity } {
+    if (options.rlsBypass === true) return {};
+    if (options.rls) return { rls: options.rls };
+    const identity = rlsIdentityFromAuth({
+      userId: auth.userId,
+      scopes: auth.scopes,
+      gateNames: options.rlsGateNames ?? [],
+      bypass: false,
+      operator: false,
+    });
+    return identity ? { rls: identity } : {};
+  }
+
   async function gated<T>(
     kind: Parameters<CapabilityToken["assert"]>[0],
     resource: string,
@@ -1269,6 +1363,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           cache.handle = await runtime.open(decl, {
             effects: options.effects ?? {},
             revealPii: options.revealPii,
+            ...rlsInvokeContext(),
           });
         }
         return cache.handle;
@@ -1288,6 +1383,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           {
             effects: options.effects ?? {},
             revealPii: options.revealPii,
+            ...rlsInvokeContext(),
           },
           {
             gate: gated,
@@ -1336,6 +1432,15 @@ export function createFxContext(options: CreateFxOptions): FxContext {
 
   const clock: FxClock = {
     now,
+    ago(duration: string): number {
+      return now() - parseDurationMs(duration);
+    },
+    fromNow(duration: string): number {
+      return now() + parseDurationMs(duration);
+    },
+    duration(duration: string): number {
+      return parseDurationMs(duration);
+    },
     async sleep(label: string, duration: string): Promise<void> {
       if (journal) {
         await journal.sleep(label, duration, parseDurationMs);
@@ -1591,9 +1696,24 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         }
       });
     },
+    deadLetters(signal: NamedRef) {
+      const name = resolveName(signal);
+      return gated("read", signalReadRef(name), async () => {
+        if (!options.signalRuntime) {
+          throw new Error("fx.deadLetters requires a bound signal runtime");
+        }
+        return options.signalRuntime.deadLetters(name);
+      });
+    },
     call(flow, input) {
       const name = resolveName(flow);
       return gated("call", name, async () => {
+        if (isMcpToolRef(name)) {
+          if (!options.aiRuntime) {
+            throw new Error(`fx.call: AI runtime is not configured for MCP tool "${name}"`);
+          }
+          return options.aiRuntime.callMcp(name, input, currentAbortSignal());
+        }
         if (options.callHandler) {
           return options.callHandler(name, input);
         }
@@ -1785,6 +1905,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
             prompt: opts?.prompt,
             data: opts?.data,
             signal: local.signal,
+            via: opts?.via?.map(resolveName),
           })) {
             if (local.signal.aborted) break;
             yield text;
@@ -1832,6 +1953,14 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       },
       with: jsonWith,
       withQuery: jsonWithQuery,
+      stream(chunks) {
+        return {
+          [jsonResultBrand]: true,
+          kind: "stream" as const,
+          status: 200 as const,
+          chunks,
+        };
+      },
     },
     async step<T>(name: string, fn: () => T | Promise<T>, opts?: StepOptions<T>): Promise<T> {
       if (journal) {

package/src/kernel/horizontal-child.ts

@@ -190,11 +190,11 @@ const charge = flow("horizontal.charge", {
 });
 
 const bindings: Binding[] = [
-  { trigger: http.get("/ping").gate.public, flow: ping as AnyFlowDef },
+  { trigger: http.get("/ping").public(), flow: ping as AnyFlowDef },
   { trigger: http.get("/rate").gate(rateGate), flow: rate as AnyFlowDef },
-  { trigger: http.post("/write").gate.public, flow: write as AnyFlowDef },
-  { trigger: http.post("/emit").gate.public, flow: emit as AnyFlowDef },
-  { trigger: http.post("/charge").gate.public, flow: charge as AnyFlowDef },
+  { trigger: http.post("/write").public(), flow: write as AnyFlowDef },
+  { trigger: http.post("/emit").public(), flow: emit as AnyFlowDef },
+  { trigger: http.post("/charge").public(), flow: charge as AnyFlowDef },
 ];
 
 const app = oke({

package/src/kernel/http-path-pending.ts

@@ -0,0 +1,20 @@
+/**
+ * Branded sentinel for `http.get()` with no path — never `"/"`.
+ * Lives in a leaf module so `oke()` can refuse leftovers without pulling
+ * the HTTP trigger constructors onto a Store-only graph.
+ */
+
+/** Unresolved path token. {@link stampHttpPath} replaces it from the file tree. */
+export const HTTP_PATH_PENDING = "__oke_http_path_pending__" as const;
+
+/** Type of {@link HTTP_PATH_PENDING}. */
+export type HttpPathPending = typeof HTTP_PATH_PENDING;
+
+/**
+ * True when an HTTP trigger still carries the unresolved path sentinel.
+ *
+ * @param path - Trigger path
+ */
+export function isPendingHttpPath(path: string): boolean {
+  return path === HTTP_PATH_PENDING;
+}

package/src/kernel/http-resource.ts

@@ -3,6 +3,7 @@
  * apps do not pay for the five-verb CRUD helper.
  */
 
+import { GATE_PUBLIC_NAME } from "../elements/gate/flatten.ts";
 import {
   createGateAttach,
   createHttpTrigger,
@@ -47,6 +48,9 @@ export function httpResource<P extends string>(
       { trigger: verb("DELETE", id, false), flow: ops.remove },
     ],
     gate: createGateAttach((next) => httpResource(path, ops, next, isLive), gates),
+    public() {
+      return httpResource(path, ops, [...gates, GATE_PUBLIC_NAME], isLive);
+    },
     live() {
       return httpResource(path, ops, gates, true);
     },

package/src/kernel/http-stream.test.ts

@@ -0,0 +1,174 @@
+/**
+ * HTTP SSE via `fx.json.stream` + client-disconnect abort of the provider fetch.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { ai } from "../elements/ai.ts";
+import type { AiDriver } from "../drivers/ai-types.ts";
+import { createRunsRuntime } from "../runs/runtime.ts";
+import { createBunRuntime } from "../runtime/bun.ts";
+import type { ServerHandle } from "../runtime/types.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+function tokenDriver(chunks: readonly string[], delayMs = 0): AiDriver {
+  return {
+    id: "mock",
+    async open() {
+      return {
+        driverId: "mock" as const,
+        model: "smart",
+        async complete() {
+          return { text: "", model: "smart", driverId: "mock" as const };
+        },
+        async *stream() {
+          for (const text of chunks) {
+            if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+            yield { text };
+          }
+        },
+      };
+    },
+  };
+}
+
+function hangingDriver(onAbort: () => void): AiDriver {
+  return {
+    id: "mock",
+    async open() {
+      return {
+        driverId: "mock" as const,
+        model: "smart",
+        async complete() {
+          return { text: "", model: "smart", driverId: "mock" as const };
+        },
+        async *stream(opts) {
+          yield { text: "start" };
+          await new Promise<void>((resolve, reject) => {
+            const t = setTimeout(resolve, 8_000);
+            opts.signal?.addEventListener(
+              "abort",
+              () => {
+                onAbort();
+                clearTimeout(t);
+                const err = new Error("aborted");
+                err.name = "AbortError";
+                reject(err);
+              },
+              { once: true },
+            );
+          });
+          yield { text: "never" };
+        },
+      };
+    },
+  };
+}
+
+describe("fx.json.stream HTTP SSE", () => {
+  let handle: ServerHandle | undefined;
+
+  afterEach(() => {
+    handle?.stop(true);
+    handle = undefined;
+  });
+
+  test("encodes token chunks as SSE and leaves JSON flows buffered", async () => {
+    const smart = ai.model("smart");
+    on(
+      http.get("/chat").public(),
+      flow("chat.stream", {
+        do: (_input, fx) => fx.json.stream(fx.stream(smart, { prompt: "hi" })),
+      }),
+    );
+    on(http.get("/ping").public(), flow("ping", { do: () => ({ ok: true as const }) }));
+
+    const app = oke({
+      name: "http-stream",
+      ai: { models: [smart], defaultDriver: tokenDriver(["Hel", "lo"]) },
+    });
+
+    const streamed = await app.fetch(new Request("http://localhost/chat"));
+    expect(streamed.headers.get("content-type")).toMatch(/text\/event-stream/);
+    const body = await streamed.text();
+    expect(body).toContain('data: "Hel"');
+    expect(body).toContain('data: "lo"');
+    expect(body).toContain("data: [DONE]");
+
+    const json = await app.fetch(new Request("http://localhost/ping"));
+    expect(json.headers.get("content-type")).toMatch(/application\/json/);
+    expect(await json.json()).toEqual({ data: { ok: true }, error: null });
+  });
+
+  test("client abort mid-stream aborts the upstream provider fetch", async () => {
+    let providerAborted = false;
+    const smart = ai.model("smart");
+    on(
+      http.get("/slow").public(),
+      flow("chat.slow", {
+        do: (_input, fx) => fx.json.stream(fx.stream(smart, { prompt: "long" })),
+      }),
+    );
+
+    const app = oke({
+      name: "http-stream-abort",
+      ai: { models: [smart], defaultDriver: hangingDriver(() => (providerAborted = true)) },
+    });
+
+    handle = createBunRuntime().serve(app, { port: 0, hostname: "127.0.0.1" });
+    const ac = new AbortController();
+    const res = await fetch(`http://127.0.0.1:${handle.port}/slow`, { signal: ac.signal });
+    expect(res.headers.get("content-type")).toMatch(/text\/event-stream/);
+    const reader = res.body!.getReader();
+    const first = await reader.read();
+    expect(first.done).toBe(false);
+    ac.abort();
+    await new Promise((r) => setTimeout(r, 80));
+    expect(providerAborted).toBe(true);
+  });
+
+  test("Traces stay empty until stream close; duration covers the open stream", async () => {
+    const runs = createRunsRuntime({ driver: "memory" });
+    await runs.open();
+    const smart = ai.model("smart");
+    on(
+      http.get("/chat").public(),
+      flow("chat.stream", {
+        do: (_input, fx) => fx.json.stream(fx.stream(smart, { prompt: "hi" })),
+      }),
+    );
+
+    const app = oke({
+      name: "http-stream-traces",
+      ai: { models: [smart], defaultDriver: tokenDriver(["Hel", "lo"], 25) },
+      runs,
+      env: "test",
+    });
+    await app.boot({ env: "test", runs, startScheduler: false });
+
+    const streamed = await app.fetch(new Request("http://localhost/chat"));
+    expect(streamed.headers.get("content-type")).toMatch(/text\/event-stream/);
+    await runs.flush();
+    expect(await runs.all()).toHaveLength(0);
+
+    const body = await streamed.text();
+    expect(body).toContain("data: [DONE]");
+
+    await runs.flush();
+    const events = await runs.all();
+    expect(events).toHaveLength(1);
+    expect(events[0]!.error ?? null).toBeNull();
+    expect(events[0]!.output).toEqual({ streamed: true });
+    expect(events[0]!.durationMs).toBeGreaterThanOrEqual(40);
+
+    await app.stop();
+    await runs.close();
+  });
+});

package/src/kernel/index.ts

@@ -137,6 +137,7 @@ export {
   createFxContext,
   freezePrincipal,
   isJsonResult,
+  isJsonStreamResult,
   jsonResultBrand,
   resolveName,
   resolveStoreRef,
@@ -160,6 +161,7 @@ export {
   type FxThunk,
   type JsonPage,
   type JsonResult,
+  type JsonStreamResult,
   type NamedRef,
   type StepOptions,
 } from "./fx.ts";

package/src/kernel/pipeline.test.ts

@@ -65,9 +65,9 @@ describe("gateDenialFailure", () => {
   });
 });
 
-describe("http trigger — .gate.public", () => {
+describe("http trigger — .public()", () => {
   test("attaches the public sentinel without calling gate()", () => {
-    const trigger = http.get("/health").gate.public;
+    const trigger = http.get("/health").public();
     expect(trigger.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(["public"]);
     expect(trigger.live().isLive).toBe(true);
   });

package/src/kernel/plugin-elements.test.ts

@@ -32,7 +32,7 @@ describe("plugin element contributions", () => {
       .table("otp_codes")
       .needs("store.sql");
 
-    on(http.get("/ok").gate.public, flow("ok", { do: () => ({ ok: true }) }));
+    on(http.get("/ok").public(), flow("ok", { do: () => ({ ok: true }) }));
 
     const app = oke({
       name: "plugin-elements",

package/src/kernel/plugin-needs.test.ts

@@ -75,7 +75,7 @@ describe("plugin .needs() resolution", () => {
   test("boot fails when plugin needs missing peer plugin", async () => {
     resetBindings();
     resetFlowSeq();
-    on(http.get("/x").gate.public, flow("x", { do: () => ({ ok: true }) }));
+    on(http.get("/x").public(), flow("x", { do: () => ({ ok: true }) }));
     const dependent = plugin("needs-auth", { version: "0.0.1" }).needs("auth");
     const app = oke({ name: "needs-boot", gate: { policies: [gate.public] } }).plug(dependent);
     await expect(app.boot({ env: "test" })).rejects.toThrow(PluginNeedsError);

package/src/kernel/ready.test.ts

@@ -38,7 +38,7 @@ describe("GET /_/ready", () => {
     });
     const bindings: Binding[] = [
       {
-        trigger: http.post("/charge").gate.public,
+        trigger: http.post("/charge").public(),
         flow: charge as AnyFlowDef,
       },
     ];
@@ -82,7 +82,7 @@ describe("GET /_oke/client.json", () => {
       startScheduler: false,
       env: "test",
       gate: { unguardedHttp: "allow" },
-      bindings: [{ trigger: http.get("/ping").gate.public, flow: ping as AnyFlowDef }],
+      bindings: [{ trigger: http.get("/ping").public(), flow: ping as AnyFlowDef }],
     });
     await app.boot();
     const res = await app.fetch(new Request("http://127.0.0.1/_oke/client.json"));

package/src/kernel/resource-mount.test.ts

@@ -63,6 +63,20 @@ describe("http.resource — gate / live", () => {
     expect(remove?.isLive).toBe(false);
   });
 
+  test(".public().live() stamps the sentinel on every verb", () => {
+    resetBindings();
+    resetFlowSeq();
+    on(http.resource("/notes", bag()).public().live());
+    expect(httpOf("/notes", "GET")?.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(
+      ["public"],
+    );
+    expect(
+      httpOf("/notes", "POST")?.gates.map((g) => (typeof g === "string" ? g : g.name)),
+    ).toEqual(["public"]);
+    expect(httpOf("/notes", "GET")?.isLive).toBe(true);
+    expect(httpOf("/notes", "POST")?.isLive).toBe(false);
+  });
+
   test(".live().gate(member) order does not matter", () => {
     resetBindings();
     resetFlowSeq();

package/src/kernel/run-duration.test.ts

@@ -23,7 +23,7 @@ describe("execute run duration", () => {
     await runs.open();
 
     on(
-      http.get("/ping").gate.public,
+      http.get("/ping").public(),
       flow("demo.ping", {
         do: () => ({ ok: true }),
       }),
@@ -68,7 +68,7 @@ describe("execute run duration", () => {
     await runs.open();
     try {
       on(
-        http.get("/ping").gate.public,
+        http.get("/ping").public(),
         flow("demo.ping", {
           do: () => ({ ok: true }),
         }),

package/src/kernel/stamp-http.test.ts

@@ -0,0 +1,79 @@
+/**
+ * In-place path / name stamps and fail-loud HTTP boot.
+ */
+
+import { describe, expect, test, beforeEach } from "bun:test";
+import type { RuntimeRouteMap } from "./adopt-routes.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { resetRegisteredFlowUnits, registerFlowUnits } from "./flow-units.ts";
+import { listBindings, on, resetBindings } from "./on.ts";
+import { stampFlowName, stampHttpPath } from "./stamp-http.ts";
+import { HTTP_PATH_PENDING } from "./http-path-pending.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetRegisteredFlowUnits();
+});
+
+describe("stampHttpPath", () => {
+  test("mutates the on() binding in place — listBindings sees the stamped path", () => {
+    const f = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
+    expect(f.$trigger && f.$trigger.kind === "http" && f.$trigger.path).toBe(HTTP_PATH_PENDING);
+    stampHttpPath(f, "/notes/:id");
+    expect(f.$trigger && f.$trigger.kind === "http" && f.$trigger.path).toBe("/notes/:id");
+    const bound = listBindings()[0];
+    expect(bound?.trigger.kind === "http" && bound.trigger.path).toBe("/notes/:id");
+  });
+
+  test("explicit http.get('/x') wins — stamp does not overwrite", () => {
+    const f = on(http.get("/me/tasks").public(), flow("notes.get", { do: () => 1 }));
+    stampHttpPath(f, "/notes/:id");
+    expect(f.$trigger && f.$trigger.kind === "http" && f.$trigger.path).toBe("/me/tasks");
+  });
+});
+
+describe("stampFlowName", () => {
+  test("fills a nameless flow as unit.export", () => {
+    const f = flow({ do: () => 1 });
+    expect(f.name).toBe("");
+    stampFlowName(f, "notes.get");
+    expect(f.name).toBe("notes.get");
+    expect(f.unit).toBe("notes");
+  });
+
+  test("explicit flow('notes.get') wins", () => {
+    const f = flow("notes.get", { do: () => 1 });
+    stampFlowName(f, "notes.list");
+    expect(f.name).toBe("notes.get");
+  });
+});
+
+describe("oke — unresolved sentinel and duplicate routes", () => {
+  test("unresolved http.get() fails construction", () => {
+    on(http.get().public(), flow("notes.get", { do: () => 1 }));
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1010/);
+  });
+
+  test("duplicate GET /notes fails construction", () => {
+    on(http.get("/notes").public(), flow("notes.list", { do: () => 1 }));
+    on(http.get("/notes").public(), flow("notes.also", { do: () => 1 }));
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1011/);
+  });
+
+  test("nameless HTTP flow fails construction", () => {
+    on(http.get("/notes").public(), flow({ do: () => 1 }));
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1012/);
+  });
+
+  test("registerFlowUnits drains into $routes; registry ignore does not", () => {
+    const get = on(http.get("/notes/:id").public(), flow("notes.get", { do: () => 1 }));
+    registerFlowUnits({ notes: { get } });
+    const ignored = oke({ name: "t", autoBoot: false, registry: "ignore" });
+    expect(ignored.$routes).toEqual({});
+    const app = oke({ name: "t", autoBoot: false });
+    expect((app.$routes as RuntimeRouteMap).notes?.get?.path).toBe("/notes/:id");
+  });
+});