okengine 0.15.2 → 0.17.0

package/src/kernel/fx.ts

@@ -20,6 +20,7 @@ import type {
   IndexStoreFxHandle,
   KvStoreDecl,
   KvStoreFxHandle,
+  SelectFromBuilder,
   SelectOrderBuilder,
   SqlStoreDecl,
   StoreDecl,
@@ -36,6 +37,12 @@ import type { VaultActor, VaultAdapter, VaultRuntime } from "../elements/vault.t
 import type { ChannelRuntime } from "../elements/channel.ts";
 import type { AiRuntime } from "../elements/ai.ts";
 import { parseDurationMs } from "../elements/clock/duration.ts";
+import type { ApiKeyStore } from "../auth/api-keys.ts";
+import type { FxAuthIdentity, FxAuthKeyMethods } from "./fx-auth-keys.ts";
+import type { FxAuthTenantMethods } from "./fx-auth-tenants.ts";
+import type { TenantStore } from "../auth/tenants.ts";
+import type { SessionCrypto, SessionStore } from "../auth/sessions.ts";
+import type { Manifest } from "../manifest/types.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
 import { createEffectLedger, recordEffect, reversibilityOf, type EffectLedger } from "./effects.ts";
 import { resolveDurationMs } from "./elapsed.ts";
@@ -73,11 +80,27 @@ async function loadRunsWindow(): Promise<typeof import("../runs/window.ts")> {
   return import("../runs/window.ts");
 }
 
+/**
+ * Sync-load live SSE + Last-Event-ID resume only when `fx.live` runs.
+ * A static import would pin `checkLiveResume` / 410 encoding on every
+ * createFx — including Store-only `oke()` graphs.
+ */
+function loadFxLiveStream(): typeof import("./fx-live-stream.ts") {
+  return lazyRequire(import.meta.dir, ["fx", "live", "stream"].join("-"));
+}
+
 /** 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.
+ * Resource ref Flows declare for {@link Fx.auth} key management.
+ * Same string as `src/auth/api-keys.ts` — defined here so the HMAC / key-store
+ * module stays off the edge and Store-only graphs.
+ */
+export const AUTH_API_KEYS_RESOURCE = "auth:api-keys";
+
+/**
+ * Capability ref for {@link Fx.deadLetters} / {@link Fx.live} — `signal:<name>`, never a store facet.
  *
  * @param name - Signal name
  */
@@ -103,13 +126,10 @@ export function resolveStoreRef(ref: NamedRef | { readonly ref: ResourceRef }):
   return ref.name as ResourceRef;
 }
 
+export type { FxAuthIdentity } from "./fx-auth-keys.ts";
+
 /** Auth principal on the user plane. */
-export interface FxAuth {
-  readonly userId: string | null;
-  readonly scopes: ReadonlySet<string>;
-  /** Whether the identity has completed verification (email / MFA). */
-  readonly verified?: boolean;
-}
+export interface FxAuth extends FxAuthIdentity, FxAuthKeyMethods, FxAuthTenantMethods {}
 
 /** Operator principal on the Console plane. */
 export interface FxOperator {
@@ -359,16 +379,46 @@ export interface JsonResult<T = unknown> {
   readonly kind?: undefined;
 }
 
-/** SSE carrier from {@link FxJson.stream}. */
+/** SSE carrier from {@link FxJson.stream} / {@link Fx.live}. */
 export interface JsonStreamResult {
   readonly [jsonResultBrand]: true;
   readonly kind: "stream";
   readonly status: 200;
-  readonly chunks: AsyncIterable<string>;
+  readonly chunks: AsyncIterable<unknown>;
+  /** Awaited before the 200 SSE body; throws OKE1014 on a missing resume cursor. */
+  ready?: () => Promise<void>;
   /** Set by the kernel to commit journal / Runs after the stream settles. */
   finalize?: () => Promise<void>;
 }
 
+const sseFrameBrand: unique symbol = Symbol.for("oke.sse.frame");
+
+/** One SSE frame — optional `id:` plus JSON `data:`. */
+export interface SseFrame {
+  readonly [sseFrameBrand]: true;
+  readonly data: unknown;
+  readonly id?: string;
+}
+
+/**
+ * Brand a stream chunk so {@link encodeSseStream} can emit `id:`.
+ *
+ * @param data - JSON payload
+ * @param id - Optional SSE id
+ */
+export function sseFrame(data: unknown, id?: string): SseFrame {
+  return id !== undefined ? { [sseFrameBrand]: true, data, id } : { [sseFrameBrand]: true, data };
+}
+
+/**
+ * True when `value` is a branded SSE frame.
+ *
+ * @param value - Unknown
+ */
+export function isSseFrame(value: unknown): value is SseFrame {
+  return typeof value === "object" && value !== null && (value as SseFrame)[sseFrameBrand] === true;
+}
+
 /** True when `value` is an {@link FxJson} JSON-envelope carrier. */
 export function isJsonResult(value: unknown): value is JsonResult {
   return (
@@ -422,9 +472,9 @@ export interface FxJson {
   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.
+   * Pass {@link Fx.stream} or any async iterable of chunks.
    */
-  stream(chunks: AsyncIterable<string>): JsonStreamResult;
+  stream(chunks: AsyncIterable<unknown>): JsonStreamResult;
 }
 
 /**
@@ -638,6 +688,29 @@ export interface Fx {
    */
   deadLetters<T>(signal: SignalDecl<T>): Promise<readonly DeadLetter<T>[]>;
   deadLetters(signal: NamedRef): Promise<readonly DeadLetter[]>;
+  /**
+   * Stream a `delivery: "live"` signal as SSE (records `read` on `signal:<name>`).
+   *
+   * HTTP `Last-Event-ID` is applied when `opts.afterId` is omitted. A missing
+   * cursor throws OKE1014; `JsonStreamResult.ready` turns that into HTTP 410.
+   *
+   * @param signal - Signal name or handle
+   * @param opts - Payload filter and optional resume cursor
+   */
+  live<T>(
+    signal: SignalDecl<T>,
+    opts?: {
+      readonly match?: (payload: T) => boolean;
+      readonly afterId?: string;
+    },
+  ): JsonStreamResult;
+  live(
+    signal: NamedRef,
+    opts?: {
+      readonly match?: (payload: unknown) => boolean;
+      readonly afterId?: string;
+    },
+  ): JsonStreamResult;
   /**
    * Call another flow (records `call`). Stub returns `undefined`.
    *
@@ -837,8 +910,27 @@ export interface CreateFxOptions {
   readonly capability?: CapabilityToken;
   /** Injectable clock for timestamps / `fx.clock.now`. */
   readonly now?: () => number;
-  /** Auth principal. */
-  readonly auth?: FxAuth;
+  /** Auth principal bag (key methods attach at create time). */
+  readonly auth?: FxAuthIdentity;
+  /** Shared API key store for {@link Fx.auth} key methods. */
+  readonly apiKeyStore?: ApiKeyStore;
+  /** Tenant registry (when `gate.auth.tenant` is on). */
+  readonly tenantStore?: TenantStore;
+  /** Session store for {@link Fx.auth.switchTenant}. */
+  readonly sessions?: SessionStore;
+  /** Session crypto for {@link Fx.auth.switchTenant}. */
+  readonly sessionCrypto?: SessionCrypto;
+  /** Manifest for tenant-role catalog validation. */
+  readonly manifest?: Manifest | null;
+  /** When true, tenant-scoped KV / vault defaults apply. */
+  readonly tenantEnabled?: boolean;
+  /**
+   * When false, skip tenant-role scope union (tenant-unaware flow).
+   * Default true when {@link tenantEnabled}.
+   */
+  readonly flowTenantScoped?: boolean;
+  /** Current flow plane (tenant-role union is user-plane only). */
+  readonly flowPlane?: "user" | "operator";
   /** Operator principal. */
   readonly operator?: FxOperator;
   /**
@@ -911,6 +1003,8 @@ export interface CreateFxOptions {
    * as `parentRunId` so consuming Flows can join the trace chain.
    */
   readonly runId?: string;
+  /** HTTP `Last-Event-ID` for {@link Fx.live} resume (tests may pass `opts.afterId`). */
+  readonly lastEventId?: string;
   /** Reveal PII through the store runtime (requires `pii:reveal` upstream). */
   readonly revealPii?: boolean;
   /** Trigger gate names for RLS (`oke.gate` = first policy/public). */
@@ -1001,12 +1095,20 @@ export function createFxContext(options: CreateFxOptions): FxContext {
   }
   const cacheStore = new Map<string, unknown>();
 
-  const auth: FxAuth = options.auth ?? {
-    userId: null,
-    scopes: new Set(),
-  };
+  // Computed stem — a static import would pin HMAC / api-keys on every createFx.
+  const authBag = options.auth ?? { userId: null, scopes: new Set() };
+  const keys = lazyRequire<typeof import("./fx-auth-keys.ts")>(
+    import.meta.dir,
+    ["fx", "auth", "keys"].join("-"),
+  ).attach({
+    auth: authBag,
+    store: options.apiKeyStore,
+    now,
+    gated,
+  });
+  const auth: FxAuth = keys as FxAuth;
   const operator: FxOperator = options.operator ?? { id: null };
-  const tenant: FxTenant = options.tenant ?? { id: null };
+  const tenant: { id: string | null } = options.tenant ?? { id: null };
   const defaultLocale = options.i18n?.defaultLocale ?? "en";
   const locale = options.i18n?.locale ?? defaultLocale;
   const catalogs = options.i18n?.catalogs ?? {};
@@ -1042,6 +1144,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       gateNames: options.rlsGateNames ?? [],
       bypass: false,
       operator: false,
+      ...(options.tenantEnabled === true ? { tenantId: tenant.id } : {}),
     });
     return identity ? { rls: identity } : {};
   }
@@ -1171,9 +1274,9 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       get driverId() {
         return cached?.driverId ?? "memory";
       },
-      select(columns?) {
+      select: ((columns?: unknown) => {
         return {
-          from(table) {
+          from(table: unknown) {
             const run = (plan: {
               where?: unknown;
               orders?: readonly unknown[];
@@ -1182,7 +1285,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
             }): Promise<SqlRow[]> =>
               gatedTable("read", table, async () => {
                 const h = await ensure();
-                const from = h.select(columns).from(table);
+                const from = h.select(columns).from(table) as SelectFromBuilder;
                 const filtered = plan.where === undefined ? from : from.where(plan.where);
                 const ordered =
                   plan.orders === undefined ? filtered : filtered.orderBy(...plan.orders);
@@ -1206,7 +1309,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
             });
 
             return {
-              where(where) {
+              where(where: unknown) {
                 return {
                   ...tail({ where }),
                   orderBy: (...orders: readonly unknown[]) => tail({ where, orders }),
@@ -1219,13 +1322,16 @@ export function createFxContext(options: CreateFxOptions): FxContext {
               offset(n: number) {
                 return run({ offset: n });
               },
-              then(onfulfilled, onrejected) {
+              then(
+                onfulfilled: (value: SqlRow[]) => unknown,
+                onrejected?: (reason: unknown) => unknown,
+              ) {
                 return run({}).then(onfulfilled, onrejected);
               },
             };
           },
         };
-      },
+      }) as SqlStoreHandle["select"],
       insert(table) {
         return {
           values(row) {
@@ -1338,6 +1444,33 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     } as SqlStoreHandle;
   }
 
+  function loadFxTenantStore(): {
+    kv: (
+      mode: "in" | "out",
+      tenantId: string | null,
+      decl: KvStoreDecl,
+      enabled: boolean,
+      prop: string | symbol,
+      payload: unknown,
+    ) => unknown;
+    path: (
+      tenantId: string | null,
+      enabled: boolean,
+      contracts: { get(name: string): { perTenant?: boolean } | undefined } | undefined,
+      name: string,
+    ) => string;
+    missingVault: (storagePath: string) => Error;
+  } {
+    return lazyRequire(import.meta.dir, ["fx", "tenant", "store"].join("-"));
+  }
+
+  const tenantOn = options.tenantEnabled === true;
+
+  function tenantVaultPath(name: string): string {
+    if (!tenantOn) return name;
+    return loadFxTenantStore().path(tenant.id, true, options.vaultRuntime?.contracts, name);
+  }
+
   function storeHandle(ref: SqlStoreDecl): SqlStoreHandle;
   function storeHandle(ref: KvStoreDecl): KvStoreFxHandle;
   function storeHandle(ref: FilesStoreDecl): FilesStoreFxHandle;
@@ -1589,7 +1722,19 @@ export function createFxContext(options: CreateFxOptions): FxContext {
   const vaultSurface: FxVault = {
     get(secret) {
       const name = resolveName(secret);
-      return gatedSecret(name, () => {
+      return gatedSecret(name, async () => {
+        const path = tenantVaultPath(name);
+        if (path !== name) {
+          if (options.vaultAdapter) {
+            const rec = await options.vaultAdapter.get(path);
+            if (!rec) {
+              throw loadFxTenantStore().missingVault(path);
+            }
+            return new Redacted(rec.value);
+          }
+          const value = secrets[path] ?? secrets[name] ?? `[secret:${path}]`;
+          return new Redacted(value);
+        }
         const value = options.vaultRuntime
           ? options.vaultRuntime.read(name)
           : (secrets[name] ?? `[secret:${name}]`);
@@ -1600,7 +1745,8 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       const name = resolveName(path);
       return gatedSecret(name, async () => {
         refuseDryRunVaultWrite("set", name);
-        const written = await vaultAdapterFor("set").set(name, value, {
+        const storage = tenantVaultPath(name);
+        const written = await vaultAdapterFor("set").set(storage, value, {
           ...(setOptions?.ttlMs !== undefined ? { ttlMs: setOptions.ttlMs } : {}),
           ...(setOptions?.metadata !== undefined ? { metadata: setOptions.metadata } : {}),
           actor: vaultActor,
@@ -1612,7 +1758,8 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       const name = resolveName(path);
       return gatedSecret(name, async () => {
         refuseDryRunVaultWrite("rotate", name);
-        const written = await vaultAdapterFor("rotate").rotate(name, value, {
+        const storage = tenantVaultPath(name);
+        const written = await vaultAdapterFor("rotate").rotate(storage, value, {
           actor: vaultActor,
         });
         return { path: written.path, version: written.version };
@@ -1622,7 +1769,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       const name = resolveName(path);
       return gatedSecret(name, async () => {
         refuseDryRunVaultWrite("delete", name);
-        return vaultAdapterFor("delete").delete(name, { actor: vaultActor });
+        return vaultAdapterFor("delete").delete(tenantVaultPath(name), { actor: vaultActor });
       });
     },
     async list(prefix) {
@@ -1705,6 +1852,18 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         return options.signalRuntime.deadLetters(name);
       });
     },
+    live(
+      signal: NamedRef,
+      opts?: { readonly match?: (payload: unknown) => boolean; readonly afterId?: string },
+    ) {
+      return loadFxLiveStream().createLiveStream({
+        name: resolveName(signal),
+        afterId: opts?.afterId ?? options.lastEventId,
+        match: opts?.match,
+        gated,
+        signalRuntime: options.signalRuntime,
+      }) as JsonStreamResult;
+    },
     call(flow, input) {
       const name = resolveName(flow);
       return gated("call", name, async () => {
@@ -1985,5 +2144,24 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     },
   };
 
+  if (options.tenantStore !== undefined || options.tenantEnabled === true) {
+    lazyRequire<{
+      install: (
+        bag: { auth: FxAuthIdentity; store: (ref: never) => object },
+        ctx: {
+          readonly tenantId: string | null;
+          readonly options: typeof options;
+          readonly now: () => number;
+          readonly gated: typeof gated;
+        },
+      ) => void;
+    }>(import.meta.dir, ["fx", "tenant", "store"].join("-")).install(fx, {
+      tenantId: tenant.id,
+      options,
+      now,
+      gated,
+    });
+  }
+
   return { fx, ledger, capability };
 }

package/src/kernel/hooks.ts

@@ -156,7 +156,7 @@ export type PipelineEncoder = (result: {
   readonly failure?: FlowFailure | undefined;
   readonly output?: unknown;
   readonly error?: unknown;
-}) => Response;
+}) => Response | Promise<Response>;
 
 /**
  * Run the seven-stage pipeline around `handler`.
@@ -234,7 +234,7 @@ export async function runPipeline(
   // (short-circuit wins; encoder input mirrors the app layer exactly).
   if (encode !== undefined && ctx.response === undefined) {
     const failure = isFlowFailure(ctx.error) ? ctx.error : undefined;
-    ctx.response = encode({ failure, output: ctx.result, error: ctx.error });
+    ctx.response = await encode({ failure, output: ctx.result, error: ctx.error });
   }
 
   await runStage("onResponse", hooks, ctx, fx);

package/src/kernel/http-resource.ts

@@ -22,37 +22,28 @@ import {
  * @param path - Base path (`/notes`)
  * @param ops - The five FlowDefs (usually `resource.all()`)
  * @param gates - Shared gate chain
- * @param isLive - Live on GET list + get
  */
 export function httpResource<P extends string>(
   path: P,
   ops: ResourceFlowBag,
   gates: readonly GateRef[] = [],
-  isLive = false,
 ): ResourceMount {
   const id = `${path}/:id` as `${P}/:id`;
-  const verb = <M extends HttpMethod>(
-    method: M,
-    p: P | `${P}/:id`,
-    live: boolean,
-  ): HttpTrigger<M> => createHttpTrigger(method, p, gates, live);
+  const verb = <M extends HttpMethod>(method: M, p: P | `${P}/:id`): HttpTrigger<M> =>
+    createHttpTrigger(method, p, gates);
   const mount: ResourceMount = {
     [resourceMountBrand]: true,
     gates,
-    isLive,
     mounts: [
-      { trigger: verb("GET", path, isLive), flow: ops.list },
-      { trigger: verb("POST", path, false), flow: ops.create },
-      { trigger: verb("GET", id, isLive), flow: ops.get },
-      { trigger: verb("PATCH", id, false), flow: ops.update },
-      { trigger: verb("DELETE", id, false), flow: ops.remove },
+      { trigger: verb("GET", path), flow: ops.list },
+      { trigger: verb("POST", path), flow: ops.create },
+      { trigger: verb("GET", id), flow: ops.get },
+      { trigger: verb("PATCH", id), flow: ops.update },
+      { trigger: verb("DELETE", id), flow: ops.remove },
     ],
-    gate: createGateAttach((next) => httpResource(path, ops, next, isLive), gates),
+    gate: createGateAttach((next) => httpResource(path, ops, next), gates),
     public() {
-      return httpResource(path, ops, [...gates, GATE_PUBLIC_NAME], isLive);
-    },
-    live() {
-      return httpResource(path, ops, gates, true);
+      return httpResource(path, ops, [...gates, GATE_PUBLIC_NAME]);
     },
   };
   return mount;

package/src/kernel/index.ts

@@ -78,6 +78,7 @@ export type {
   AppFlowRoute,
   AppRouteMap,
   FlowNamespace,
+  LiveAppFlowRoute,
   RouteFromFlow,
   RoutesFromAdoptArgs,
 } from "./adopt-routes.ts";
@@ -359,6 +360,7 @@ export {
   type HttpMethod,
   type HttpTrigger,
   type InternalTrigger,
+  type LiveHttpTrigger,
   type ResourceFlowBag,
   type ResourceMount,
   type SignalAsTrigger,

package/src/kernel/journal.ts

@@ -104,6 +104,8 @@ export interface JournalRun {
   leaseExpiresAt?: number;
   readonly createdAt: number;
   updatedAt: number;
+  /** Isolation context for resume (`fx.tenant`). */
+  tenant?: string | null;
 }
 
 /**
@@ -366,6 +368,12 @@ export interface JournalSession {
   readonly runId: string;
   /** Underlying run snapshot (mutated as entries append). */
   readonly run: JournalRun;
+  /**
+   * Persist isolation context so resume restamps {@link Fx.tenant}.
+   *
+   * @param id - Tenant id (null clears)
+   */
+  stampTenant(id: string | null): Promise<void>;
   /**
    * Replay or execute a named step. Never re-runs `fn` when already journaled.
    *
@@ -607,6 +615,10 @@ export function createJournal(options: CreateJournalOptions): Journal {
       undoStack() {
         return undos;
       },
+      async stampTenant(id) {
+        run.tenant = id;
+        await persist();
+      },
       beginRegistrationPass() {
         registrationPass = true;
       },

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

@@ -0,0 +1,78 @@
+/**
+ * Live HTTP exposure uniqueness (OKE1013) and GET-only synthesis.
+ */
+
+import { describe, expect, test, beforeEach } from "bun:test";
+import { z } from "zod";
+import { gate } from "../elements/gate.ts";
+import { signal, resetSignals } from "../elements/signal/declare.ts";
+import { oke } from "./app.ts";
+import { resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { stampFlowName } from "./stamp-http.ts";
+import { http } from "./triggers.ts";
+
+const member = gate.policy("member", ({ auth }) => !!auth.verified);
+const admin = gate.policy("admin", ({ auth }) => !!auth.verified);
+const partner = gate.policy("partner", ({ auth }) => !!auth.verified);
+
+const orderStatus = () =>
+  signal("order-status", {
+    delivery: "live",
+    optional: true,
+    schema: z.object({
+      orderId: z.string(),
+      status: z.enum(["placed", "fulfilling", "shipped"]),
+    }),
+  });
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetSignals();
+});
+
+describe("live HTTP uniqueness", () => {
+  test("member :orderId + admin firehose both boot", () => {
+    const sig = orderStatus();
+    const events = on(http.get("/orders/:orderId/events").gate(member).live(sig));
+    const feed = on(http.get("/admin/order-status").gate(admin).live(sig));
+    stampFlowName(events, "orders.events");
+    stampFlowName(feed, "admin.adminFeed");
+    expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
+  });
+
+  test("same match, different gates boot (via disambiguates on the client)", () => {
+    const sig = orderStatus();
+    const a = on(http.get("/orders/:orderId/events").gate(member).live(sig));
+    const b = on(http.get("/partners/:orderId/events").gate(partner).live(sig));
+    stampFlowName(a, "orders.events");
+    stampFlowName(b, "partners.events");
+    expect(() => oke({ name: "t", autoBoot: false })).not.toThrow();
+  });
+
+  test("two member firehoses on different paths fail OKE1013", () => {
+    const sig = orderStatus();
+    const a = on(http.get("/feed-a").gate(member).live(sig));
+    const b = on(http.get("/feed-b").gate(member).live(sig));
+    stampFlowName(a, "orders.feedA");
+    stampFlowName(b, "orders.feedB");
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1013/);
+  });
+
+  test("duplicate GET path still OKE1011", () => {
+    const sig = orderStatus();
+    const a = on(http.get("/orders/:orderId/events").gate(member).live(sig));
+    const b = on(http.get("/orders/:orderId/events").gate(admin).live(sig));
+    stampFlowName(a, "orders.events");
+    stampFlowName(b, "admin.events");
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1011/);
+  });
+
+  test("POST .live(signal) is rejected", () => {
+    const sig = orderStatus();
+    expect(() => on(http.post("/orders").gate(member).live(sig))).toThrow(
+      /live exposure must be GET/,
+    );
+  });
+});