okengine 0.15.2 → 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/cache.ts

@@ -63,7 +63,7 @@ export function tier1KeysForReads(
  * @param effects - Write flow effects
  */
 export function resourcesTouchedByWrites(effects: Effects): ResourceRef[] {
-  return [...(effects.writes ?? [])];
+  return (effects.writes ?? []).filter((r): r is ResourceRef => isStoreResourceRef(r));
 }
 
 /**

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/runtime.ts

@@ -239,6 +239,13 @@ export interface StoreRuntime {
    * @param ref - `kv:name`
    */
   kvNamespace(ref: ResourceRef): Promise<KvNamespace>;
+  /**
+   * Shared primary SQL connection (`sharedSqlConn`).
+   *
+   * Host auth persist (`oke_api_keys`) and durable KV borrow this same
+   * connection — never a second open against `store.sql()` / `DATABASE_URL`.
+   */
+  primarySql(): Promise<SqlConnection | undefined>;
   /**
    * Register a declaration (usually done at module load).
    *
@@ -545,6 +552,13 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
       if (!ns) throw new Error(`Unknown kv ref: ${ref}`);
       return ns;
     },
+    async primarySql() {
+      const sqlDriver = options.drivers.sql;
+      if (!sqlDriver) return undefined;
+      const firstSql = Object.values(options.sql ?? [])[0];
+      const url = options.sqlUrl ?? firstSql?.primary.url;
+      return sharedSqlConn(sqlDriver, "primary", { url });
+    },
     onWriteEffects(effects) {
       return cache.invalidateFromEffects(effects);
     },