okengine 0.16.0 → 0.17.0

package/src/elements/gate/permissions.ts

@@ -91,6 +91,18 @@ function collectEffects(manifest: Manifest, kind: "reads" | "writes"): string[]
   return out;
 }
 
+/**
+ * Whether a Module:Action is an application (user-plane) scope.
+ *
+ * Console / operator scopes are `console:*` (Access · API-key plane split).
+ * Tenant roles may only grant application scopes.
+ *
+ * @param action - Module:Action pair
+ */
+export function isApplicationScope(action: string): boolean {
+  return !action.startsWith("console:");
+}
+
 /**
  * Format pairs for `oke gates list` stdout.
  *

package/src/elements/gate.ts

@@ -63,4 +63,9 @@ export {
   type TakeRateOptions,
 } from "./gate/strategies.ts";
 
-export { deriveModuleActions, flowIdToAction, formatGatesList } from "./gate/permissions.ts";
+export {
+  deriveModuleActions,
+  flowIdToAction,
+  formatGatesList,
+  isApplicationScope,
+} from "./gate/permissions.ts";

package/src/elements/signal/declare.ts

@@ -7,17 +7,18 @@
 
 import type { SignalDelivery } from "../../manifest/types.ts";
 import { signalRegistry } from "../../kernel/element-registries.ts";
+import { parseDurationMs } from "../clock/duration.ts";
 
-/** Options for {@link signal}. */
-export interface SignalOptions {
-  /**
-   * Delivery physics — required, no default.
-   *
-   * - `once` — competing consumers, retries, DLQ
-   * - `broadcast` — every subscriber receives a copy
-   * - `live` — client-subscribable stream (replayable)
-   */
-  readonly delivery: SignalDelivery;
+/** Live-tape cap. Omit both fields (or omit `retention`) for an unbounded tape. */
+export interface SignalRetention {
+  /** Drop events older than this duration (`"7d"`, `"1h"`, `"30s"`, …). */
+  readonly maxAge?: string;
+  /** Keep only the newest N live events. */
+  readonly maxCount?: number;
+}
+
+/** Shared options for every {@link signal} delivery mode. */
+interface SignalOptionsBase {
   /** Optional human description for Console / docs (falls back to the signal name). */
   readonly description?: string;
   /** Max delivery attempts before dead-letter (once). */
@@ -33,6 +34,21 @@ export interface SignalOptions {
   readonly optional?: boolean;
 }
 
+/**
+ * Options for {@link signal}.
+ *
+ * `retention` is live-only — a type error on `once` / `broadcast`.
+ */
+export type SignalOptions =
+  | (SignalOptionsBase & {
+      readonly delivery: "once" | "broadcast";
+      readonly retention?: never;
+    })
+  | (SignalOptionsBase & {
+      readonly delivery: "live";
+      readonly retention?: SignalRetention;
+    });
+
 /**
  * Declared signal handle — usable as `on(signal, flow)`, `fx.emit(signal, …)`,
  * and `fx.deadLetters(signal)`.
@@ -52,6 +68,8 @@ export interface SignalDecl<T = unknown> {
   readonly schema?: unknown;
   /** Optional orphan-emit allowance. */
   readonly optional: boolean;
+  /** Live-tape cap (`delivery: "live"` only). Omitted = unbounded. */
+  readonly retention?: SignalRetention;
   /** Phantom payload type for typed emits. */
   readonly _payload?: T;
 }
@@ -91,6 +109,21 @@ export function signal<T = unknown>(name: string, options: SignalOptions): Signa
   ) {
     throw new TypeError(`signal("${name}"): delivery is mandatory (once | broadcast | live)`);
   }
+  const retention = "retention" in options ? options.retention : undefined;
+  if (retention !== undefined && options.delivery !== "live") {
+    throw new TypeError(`signal("${name}"): retention is only valid with delivery: "live"`);
+  }
+  if (retention?.maxAge !== undefined && parseDurationMs(retention.maxAge) <= 0) {
+    throw new TypeError(
+      `signal("${name}"): retention.maxAge must be a duration like "24h" or "30s"`,
+    );
+  }
+  if (
+    retention?.maxCount !== undefined &&
+    (!Number.isInteger(retention.maxCount) || retention.maxCount < 1)
+  ) {
+    throw new TypeError(`signal("${name}"): retention.maxCount must be an integer ≥ 1`);
+  }
   const decl: SignalDecl<T> = {
     name,
     delivery: options.delivery,
@@ -99,6 +132,7 @@ export function signal<T = unknown>(name: string, options: SignalOptions): Signa
     deadLetter: options.deadLetter ?? true,
     schema: options.schema,
     optional: options.optional ?? false,
+    ...(options.delivery === "live" && retention !== undefined ? { retention } : {}),
   };
   signalRegistry.push(decl as SignalDecl);
   return decl;

package/src/elements/signal/delivery-modes.test.ts

@@ -20,6 +20,26 @@ import {
   type SignalDriver,
 } from "../../drivers/index.ts";
 import { signal, type SignalDecl } from "./declare.ts";
+import type { LiveEvent } from "../../drivers/signal-types.ts";
+
+async function takeLivePayloads(iter: AsyncIterable<LiveEvent>, n: number): Promise<unknown[]> {
+  return (await takeLiveEvents(iter, n)).map((e) => e.payload);
+}
+
+async function takeLiveEvents(iter: AsyncIterable<LiveEvent>, n: number): Promise<LiveEvent[]> {
+  const out: LiveEvent[] = [];
+  const it = iter[Symbol.asyncIterator]();
+  try {
+    while (out.length < n) {
+      const step = await it.next();
+      if (step.done) break;
+      out.push(step.value);
+    }
+  } finally {
+    await it.return?.();
+  }
+  return out;
+}
 
 const drivers: Array<{
   label: string;
@@ -167,13 +187,79 @@ for (const { label, driver, setup } of drivers) {
       await bus.emit("seat-feed", { seat: "12C" });
       await bus.drain();
 
-      const late: unknown[] = [];
-      await bus.live("seat-feed", (payload) => {
-        late.push(payload);
-      });
+      const late = await takeLivePayloads(bus.live("seat-feed"), 3);
 
       // All retained live messages replay — not the Console recentLive cap of 50.
       expect(late).toEqual([{ seat: "12A" }, { seat: "12B" }, { seat: "12C" }]);
     });
+
+    test("live: maxCount keeps the newest N", async () => {
+      const live = signal("seat-feed", {
+        delivery: "live",
+        optional: true,
+        retention: { maxCount: 2 },
+      });
+      const bus = await openBus(driver, [live], setup?.() ?? {});
+
+      for (const seat of ["12A", "12B", "12C", "12D", "12E"]) {
+        await bus.emit("seat-feed", { seat });
+      }
+      await bus.drain();
+
+      const late = await takeLivePayloads(bus.live("seat-feed"), 2);
+      expect(late).toEqual([{ seat: "12D" }, { seat: "12E" }]);
+    });
+
+    test("live: maxAge prunes on emit and on live() open", async () => {
+      let t = 1_000;
+      const live = signal("seat-feed", {
+        delivery: "live",
+        optional: true,
+        retention: { maxAge: "1s" },
+      });
+      const bus = await openBus(driver, [live], { now: () => t, ...(setup?.() ?? {}) });
+
+      await bus.emit("seat-feed", { seat: "old" });
+      await bus.drain();
+      t += 2_000;
+      await bus.emit("seat-feed", { seat: "new" });
+      await bus.drain();
+
+      const late = await takeLivePayloads(bus.live("seat-feed"), 1);
+      expect(late).toEqual([{ seat: "new" }]);
+    });
+
+    test("live: afterId skips already-delivered events", async () => {
+      const live = signal("seat-feed", { delivery: "live", optional: true });
+      const bus = await openBus(driver, [live], setup?.() ?? {});
+
+      await bus.emit("seat-feed", { seat: "12A" });
+      await bus.emit("seat-feed", { seat: "12B" });
+      await bus.emit("seat-feed", { seat: "12C" });
+      await bus.drain();
+
+      const first = await takeLiveEvents(bus.live("seat-feed"), 3);
+      expect(first.map((e) => e.payload)).toEqual([
+        { seat: "12A" },
+        { seat: "12B" },
+        { seat: "12C" },
+      ]);
+      const rest = await takeLiveEvents(bus.live("seat-feed", { afterId: first[0]!.id }), 2);
+      expect(rest.map((e) => e.payload)).toEqual([{ seat: "12B" }, { seat: "12C" }]);
+    });
+
+    test("live: unknown afterId throws OKE1014", async () => {
+      const live = signal("seat-feed", { delivery: "live", optional: true });
+      const bus = await openBus(driver, [live], setup?.() ?? {});
+      await bus.emit("seat-feed", { seat: "12A" });
+      await bus.drain();
+
+      const it = bus.live("seat-feed", { afterId: "missing" })[Symbol.asyncIterator]();
+      try {
+        await expect(it.next()).rejects.toMatchObject({ code: 1014 });
+      } finally {
+        await it.return?.();
+      }
+    });
   });
 }

package/src/elements/signal/order-lifecycle.test.ts

@@ -13,8 +13,24 @@
 import { afterEach, describe, expect, test } from "bun:test";
 
 import { memorySignalDriver, type SignalBus } from "../../drivers/index.ts";
+import type { LiveEvent } from "../../drivers/signal-types.ts";
 import { signal } from "./declare.ts";
 
+async function takeLivePayloads(iter: AsyncIterable<LiveEvent>, n: number): Promise<unknown[]> {
+  const out: unknown[] = [];
+  const it = iter[Symbol.asyncIterator]();
+  try {
+    while (out.length < n) {
+      const step = await it.next();
+      if (step.done) break;
+      out.push(step.value.payload);
+    }
+  } finally {
+    await it.return?.();
+  }
+  return out;
+}
+
 const openBuses: SignalBus[] = [];
 
 afterEach(async () => {
@@ -89,10 +105,10 @@ describe("signal order lifecycle · once + broadcast + live", () => {
     expect(notifyHits).toEqual(["ord_42"]);
 
     // live: late subscriber replays the full retained status history
-    const feed: Array<{ orderId: string; status: string }> = [];
-    await bus.live("order-status", (payload) => {
-      feed.push(payload as { orderId: string; status: string });
-    });
+    const feed = (await takeLivePayloads(bus.live("order-status"), 3)) as Array<{
+      orderId: string;
+      status: string;
+    }>;
     expect(feed).toEqual([
       { orderId: "ord_42", status: "placed" },
       { orderId: "ord_42", status: "fulfilling" },

package/src/elements/signal/runtime.ts

@@ -5,6 +5,7 @@
 
 import type {
   DeadLetter,
+  LiveEvent,
   SignalBus,
   SignalDriver,
   SignalEmitOptions,
@@ -59,6 +60,20 @@ export interface SignalRuntime {
    * @param name - Signal name
    */
   deadLetters(name: string): Promise<readonly DeadLetter[]>;
+  /**
+   * Live feed (auto-starts). Replays history then new events.
+   *
+   * @param name - Signal name
+   * @param opts - Optional resume cursor
+   */
+  live(name: string, opts?: { readonly afterId?: string }): AsyncIterable<LiveEvent>;
+  /**
+   * Validate a live resume cursor (auto-starts). Throws OKE1014 when missing.
+   *
+   * @param name - Signal name
+   * @param afterId - SSE cursor
+   */
+  checkLiveResume(name: string, afterId: string): Promise<void>;
   /** Close the bus. */
   close(): Promise<void>;
 }
@@ -102,6 +117,33 @@ export function createSignalRuntime(options: CreateSignalRuntimeOptions): Signal
       const b = await this.start();
       return b.deadLetters(name);
     },
+    live(name, opts) {
+      return {
+        [Symbol.asyncIterator]() {
+          let inner: AsyncIterator<LiveEvent> | undefined;
+          return {
+            async next() {
+              if (!inner) {
+                const b = await runtime.start();
+                inner = b.live(name, opts)[Symbol.asyncIterator]();
+              }
+              return inner.next();
+            },
+            async return() {
+              if (!inner) {
+                const b = await runtime.start();
+                inner = b.live(name, opts)[Symbol.asyncIterator]();
+              }
+              return inner.return?.() ?? { done: true, value: undefined };
+            },
+          };
+        },
+      };
+    },
+    async checkLiveResume(name, afterId) {
+      const b = await runtime.start();
+      await b.checkLiveResume(name, afterId);
+    },
     async close() {
       if (bus) {
         await bus.close();

package/src/elements/signal.test.ts

@@ -86,6 +86,20 @@ describe("signal declaration", () => {
     expect(s.delivery).toBe("once");
     expect(s.name).toBe("order-placed");
   });
+
+  test("retention is live-only", () => {
+    expect(() =>
+      // @ts-expect-error retention is live-only
+      signal("order-placed", { delivery: "once", retention: { maxCount: 2 } }),
+    ).toThrow(/retention is only valid/);
+
+    const live = signal("order-status", {
+      delivery: "live",
+      optional: true,
+      retention: { maxAge: "24h", maxCount: 500 },
+    });
+    expect(live.retention).toEqual({ maxAge: "24h", maxCount: 500 });
+  });
 });
 
 for (const { label, driver, setup } of drivers) {
@@ -184,17 +198,16 @@ for (const { label, driver, setup } of drivers) {
     });
 
     test("live is client-subscribable", async () => {
-      const live = signal("seat-feed", { delivery: "live" });
+      const live = signal("seat-feed", { delivery: "live", optional: true });
       const bus = await openBus(driver, [live], setup?.() ?? {});
-      const frames: unknown[] = [];
-      await bus.live("seat-feed", (payload) => {
-        frames.push(payload);
-      });
-
+      const it = bus.live("seat-feed")[Symbol.asyncIterator]();
+      const pending = it.next();
       await bus.emit("seat-feed", { seat: "12A" });
       await bus.drain();
-
-      expect(frames).toEqual([{ seat: "12A" }]);
+      const step = await pending;
+      expect(step.done).toBe(false);
+      expect(step.value?.payload).toEqual({ seat: "12A" });
+      await it.return?.();
     });
 
     test("DLQ preserves typed failure reasons per attempt", async () => {

package/src/elements/signal.ts

@@ -7,7 +7,7 @@
  */
 
 export { signal } from "./signal/declare.ts";
-export type { SignalDecl, SignalOptions } from "./signal/declare.ts";
+export type { SignalDecl, SignalOptions, SignalRetention } from "./signal/declare.ts";
 export type { DeadLetter, SignalFailureReason } from "../drivers/signal-types.ts";
 
 export { createSignalRuntime } from "./signal/runtime.ts";

package/src/elements/store/declare.ts

@@ -79,6 +79,11 @@ export interface KvStoreOptions {
    * not the cache Redis (`REDIS_URL`). Distinct from Flow `durable`.
    */
   readonly durable?: boolean;
+  /**
+   * Prefix keys with `{tenantId}:` when `gate.auth.tenant` is on.
+   * Default `true` then; set `false` for genuinely global namespaces.
+   */
+  readonly tenantScoped?: boolean;
 }
 
 /** KV store declaration. */
@@ -87,6 +92,7 @@ export interface KvStoreDecl extends StoreDeclBase {
   readonly ref: `kv:${string}`;
   readonly description?: string;
   readonly durable?: boolean;
+  readonly tenantScoped?: boolean;
 }
 
 /** Options for {@link store.files}. */
@@ -185,6 +191,7 @@ export function kv(name: string, options: KvStoreOptions = {}): KvStoreDecl {
     ref: `kv:${name}`,
     ...(options.description !== undefined ? { description: options.description } : {}),
     ...(options.durable === true ? { durable: true } : {}),
+    ...(options.tenantScoped !== undefined ? { tenantScoped: options.tenantScoped } : {}),
   };
   storeRegistry.push(decl);
   return decl;

package/src/elements/store/rls-identity.test.ts

@@ -93,3 +93,32 @@ describe("firstPolicyOrPublic", () => {
     expect(firstPolicyOrPublic(["public"])).toBe("public");
   });
 });
+
+describe("rlsIdentityFromAuth — tenant GUC", () => {
+  test("stamps tenantId only when the field is provided", () => {
+    expect(
+      rlsIdentityFromAuth({
+        userId: "u1",
+        scopes: new Set(["member"]),
+        gateNames: ["member"],
+        tenantId: "acme",
+      }),
+    ).toEqual({
+      gate: "member",
+      userId: "u1",
+      scopes: ["member"],
+      tenantId: "acme",
+    });
+    expect(
+      rlsIdentityFromAuth({
+        userId: "u1",
+        scopes: new Set(["member"]),
+        gateNames: ["member"],
+      }),
+    ).toEqual({
+      gate: "member",
+      userId: "u1",
+      scopes: ["member"],
+    });
+  });
+});

package/src/elements/store/rls-identity.ts

@@ -66,6 +66,8 @@ export function rlsIdentityFromAuth(input: {
   readonly gateNames: readonly string[];
   readonly bypass?: boolean;
   readonly operator?: boolean;
+  /** When set (tenancy on), stamp `oke.tenant` — empty string if unresolved. */
+  readonly tenantId?: string | null;
 }): RlsIdentity | null {
   if (input.bypass === true || input.operator === true) return null;
   const gate = firstPolicyOrPublic(input.gateNames);
@@ -75,6 +77,7 @@ export function rlsIdentityFromAuth(input: {
     gate,
     userId: input.userId ?? "",
     scopes,
+    ...(input.tenantId !== undefined ? { tenantId: input.tenantId ?? "" } : {}),
   };
 }
 

package/src/elements/store/schema-decl.ts

@@ -6,6 +6,7 @@
  */
 
 import type { ColumnClassification } from "../../manifest/types.ts";
+import { lazyRequire } from "../../kernel/lazy-require.ts";
 import type { ColumnDef, TableHandle } from "./table.ts";
 import { id as idHelper, now as nowHelper } from "./table.ts";
 
@@ -104,8 +105,14 @@ export interface SchemaRlsEnableDecl {
   readonly kind: "schema-rls";
 }
 
+/** Opt out of tenant isolation for a schema table when tenancy is on. */
+export interface SchemaTenantScopedDecl {
+  readonly kind: "schema-tenant-scoped";
+  readonly tenantScoped: false;
+}
+
 /** Third-arg extra for {@link schemaTable}. */
-export type SchemaTableExtra = SchemaPolicyDecl | SchemaRlsEnableDecl;
+export type SchemaTableExtra = SchemaPolicyDecl | SchemaRlsEnableDecl | SchemaTenantScopedDecl;
 
 /** Options for {@link schemaPolicy} / Gate helpers. */
 export interface SchemaPolicyOptions {
@@ -129,6 +136,8 @@ export interface SchemaTableDecl extends TableHandle {
   readonly rls?: boolean;
   /** Declared policies (emit + Manifest). */
   readonly policies?: readonly SchemaPolicyDecl[];
+  /** When `false`, skip fail-loud tenant-policy requirement. */
+  readonly tenantScoped?: boolean;
 }
 
 /**
@@ -424,12 +433,16 @@ export function schemaTable<C extends Record<string, SchemaColumnInput>>(
     (extra): extra is SchemaPolicyDecl => extra.kind === "schema-policy",
   );
   const rls = extras.some((extra) => extra.kind === "schema-rls") || policies.length > 0;
+  const unscoped = extras.some(
+    (extra) => extra.kind === "schema-tenant-scoped" && extra.tenantScoped === false,
+  );
   const table = {
     name,
     columns: stamped,
     ...stamped,
     ...(rls ? { rls: true } : {}),
     ...(policies.length > 0 ? { policies } : {}),
+    ...(unscoped ? { tenantScoped: false } : {}),
   };
   // Survive columns named `name` or `kind` (they would otherwise shadow
   // the table discriminant / SQL name).
@@ -467,12 +480,25 @@ function sqlStringLiteral(value: string): string {
   return `'${value.replaceAll("'", "''")}'`;
 }
 
-function helperPolicyName(prefix: string, key: string, command: SchemaPolicyFor): string {
+/**
+ * Policy name `prefix_key_command`.
+ *
+ * @param prefix - Helper kind
+ * @param key - Gate / column / scope
+ * @param command - SQL command
+ */
+export function helperPolicyName(prefix: string, key: string, command: SchemaPolicyFor): string {
   const slug = key.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "");
   return `${prefix}_${slug}_${command}`;
 }
 
-function policyPredicates(
+/**
+ * USING / WITH CHECK split for a helper expression.
+ *
+ * @param command - SQL command
+ * @param expr - Predicate
+ */
+export function policyPredicates(
   command: SchemaPolicyFor,
   expr: string,
 ): { readonly using?: string; readonly withCheck?: string } {
@@ -540,13 +566,46 @@ export type SchemaPolicyApi = typeof schemaPolicy & {
   readonly gate: typeof schemaPolicyGate;
   readonly owner: typeof schemaPolicyOwner;
   readonly scope: typeof schemaPolicyScope;
+  readonly tenant: (
+    column: string,
+    options?: Pick<SchemaPolicyOptions, "for" | "as" | "to">,
+  ) => SchemaPolicyDecl;
 };
 
+function loadSchemaTenant(): {
+  tenant: SchemaPolicyApi["tenant"];
+  unscoped: () => SchemaTenantScopedDecl;
+} {
+  return lazyRequire(import.meta.dir, ["schema", "tenant"].join("-"));
+}
+
+/**
+ * Tenant-column policy — `tenant_id = oke.tenant()`.
+ *
+ * @param column - SQL / JS column name
+ * @param options - Command (default `all`)
+ */
+export function schemaPolicyTenant(
+  column: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  return loadSchemaTenant().tenant(column, options);
+}
+
+/**
+ * Mark a table as globally shared (`tenantScoped: false`).
+ * Required when `gate.auth.tenant` is on and the table has no tenant policy.
+ */
+export function schemaUnscoped(): SchemaTenantScopedDecl {
+  return loadSchemaTenant().unscoped();
+}
+
 /** `store.schema.policy` — raw + Gate helpers. */
 export const schemaPolicyApi: SchemaPolicyApi = Object.assign(schemaPolicy, {
   gate: schemaPolicyGate,
   owner: schemaPolicyOwner,
   scope: schemaPolicyScope,
+  tenant: schemaPolicyTenant,
 });
 
 // ─── Relations (mirrors drizzle-orm `defineRelations`) ───────────────────────
@@ -746,6 +805,7 @@ export const schema = {
   relations: schemaRelations,
   rls: schemaRls,
   policy: schemaPolicyApi,
+  unscoped: schemaUnscoped,
 } as const;
 
 /**

package/src/elements/store/schema-tenant.ts

@@ -0,0 +1,41 @@
+/**
+ * Tenant schema helpers — lazy chunk off Store-only `oke()` graphs.
+ *
+ * `store.schema.policy.tenant` / `store.schema.unscoped` stay on the public
+ * API via getters; this module is loaded on first access.
+ */
+
+import {
+  schemaPolicy,
+  helperPolicyName,
+  policyPredicates,
+  type SchemaPolicyDecl,
+  type SchemaPolicyOptions,
+  type SchemaTenantScopedDecl,
+} from "./schema-decl.ts";
+
+/**
+ * Tenant-column policy — `tenant_id = oke.tenant()`.
+ *
+ * @param column - SQL / JS column name
+ * @param options - Command (default `all`)
+ */
+export function tenant(
+  column: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  const command = options.for ?? "all";
+  return schemaPolicy(helperPolicyName("tenant", column, command), {
+    ...options,
+    for: command,
+    ...policyPredicates(command, `${column} = oke.tenant()`),
+  });
+}
+
+/**
+ * Mark a table as globally shared (`tenantScoped: false`).
+ * Required when `gate.auth.tenant` is on and the table has no tenant policy.
+ */
+export function unscoped(): SchemaTenantScopedDecl {
+  return { kind: "schema-tenant-scoped", tenantScoped: false };
+}