okengine 0.14.1 → 0.16.0

package/src/kernel/auto-cache.test.ts

@@ -44,7 +44,7 @@ describe("automatic tier-1 cache from effects", () => {
     const db = store.sql("app", { schema: { notes } });
     let lists = 0;
     const list = on(
-      http.get("/notes").gate.public,
+      http.get("/notes").public(),
       flow("notes.list", {
         out: z.array(NoteOut),
         effects: { reads: ["sql:notes"] },
@@ -80,7 +80,7 @@ describe("automatic tier-1 cache from effects", () => {
     resetFlowSeq();
     const db = store.sql("app", { schema: { notes } });
     const list = on(
-      http.get("/notes").gate.public,
+      http.get("/notes").public(),
       flow("notes.list", {
         out: z.array(NoteOut),
         effects: { reads: ["sql:notes"] },
@@ -115,7 +115,7 @@ describe("automatic tier-1 cache from effects", () => {
     const db = store.sql("app", { schema: { notes } });
     let lists = 0;
     const list = on(
-      http.get("/notes").gate.public,
+      http.get("/notes").public(),
       flow("notes.list", {
         cache: false,
         effects: { reads: ["sql:notes"] },
@@ -146,7 +146,7 @@ describe("automatic tier-1 cache from effects", () => {
     const db = store.sql("app", { schema: { notes } });
     let lists = 0;
     const list = on(
-      http.get("/notes").gate.public,
+      http.get("/notes").public(),
       flow("notes.list", {
         out: z.array(NoteOut),
         do: async (_input, fx) => {
@@ -191,7 +191,7 @@ describe("automatic tier-1 cache from effects", () => {
     const db = store.sql("app", { schema: { notes } });
     let lists = 0;
     const list = on(
-      http.get("/notes").gate.public,
+      http.get("/notes").public(),
       flow("notes.list", {
         effects: { reads: ["sql:notes"] },
         do: () => {
@@ -201,7 +201,7 @@ describe("automatic tier-1 cache from effects", () => {
       }),
     );
     const create = on(
-      http.post("/notes").gate.public,
+      http.post("/notes").public(),
       flow("notes.create", {
         in: z.object({ title: z.string() }),
         effects: { writes: ["sql:notes"] },
@@ -231,7 +231,7 @@ describe("automatic tier-1 cache from effects", () => {
     const db = store.sql("app", { schema: { notes } });
     let lists = 0;
     const list = on(
-      http.get("/notes").gate.public,
+      http.get("/notes").public(),
       flow("notes.list", {
         out: z.array(NoteOut),
         do: async (_input, fx) => {
@@ -242,7 +242,7 @@ describe("automatic tier-1 cache from effects", () => {
       }),
     );
     const create = on(
-      http.post("/notes").gate.public,
+      http.post("/notes").public(),
       flow("notes.create", {
         in: z.object({ title: z.string() }),
         do: async (input, fx) => {

package/src/kernel/auto-registry.test.ts

@@ -1,17 +1,21 @@
 /**
- * `oke({...})` auto-populates `stores` / `secrets` / `signals` /
- * `channel.templates` from the same kind of module-evaluation registry
- * already proven for `on()`'s trigger drain (`registry-isolation.test.ts`).
+ * `oke({...})` auto-populates `stores` / `secrets` / `signals` / `clocks` /
+ * `gate.policies` / `channel.templates` from the same kind of
+ * module-evaluation registry already proven for `on()`'s trigger drain
+ * (`registry-isolation.test.ts`).
  *
- * `store.sql` / `store.files`, `vault.secret`, `signal()`, and medium-binder
- * `.template()` push into a shared registry (`src/kernel/element-registries.ts`)
- * at call time — zero change to how developers call them. `oke()` drains it
- * at construction under the same `registry: "consume" | "keep" | "ignore"`
- * switch that already governs bindings.
+ * `store.*`, `vault.secret`, `signal()`, `clock()`, `gate.policy` / `.scope`
+ * / `.rate`, and medium-binder `.template()` push into a shared registry
+ * (`src/kernel/element-registries.ts`) at call time — zero change to how
+ * developers call them. `oke()` drains it at construction under the same
+ * `registry: "consume" | "keep" | "ignore"` switch that already governs
+ * bindings.
  */
 
 import { describe, expect, test } from "bun:test";
 import { channel } from "../elements/channel/declare.ts";
+import { clock } from "../elements/clock/declare.ts";
+import { gate } from "../elements/gate/declare.ts";
 import { signal } from "../elements/signal/declare.ts";
 import { store } from "../elements/store/declare.ts";
 import { vault } from "../elements/vault/declare.ts";
@@ -20,7 +24,7 @@ import { flow } from "./flow.ts";
 import { on, resetBindings } from "./on.ts";
 import { http } from "./triggers.ts";
 
-describe("oke() auto-registry — stores/secrets/signals/channel.templates/ai", () => {
+describe("oke() auto-registry — stores/secrets/signals/clocks/gates/channel.templates/ai", () => {
   test("before/after: zero explicit arrays boots identically to the explicit-array form", async () => {
     resetBindings();
 
@@ -161,6 +165,42 @@ describe("oke() auto-registry — stores/secrets/signals/channel.templates/ai",
     expect(app.bootResult?.vault?.contracts.has("IGNORED_SECRET")).toBeFalsy();
   });
 
+  test("store.kv / store.index / clock() / gate.policy auto-drain — no explicit oke() arrays", async () => {
+    resetBindings();
+    store.kv("drafts", { description: "Compose drafts" });
+    store.index("tasks", { description: "Task search" });
+    clock("daily-digest", { cron: "0 8 * * *", every: "1d", timezone: "UTC" });
+    const member = gate.policy("member", ({ auth }) => !!auth.verified);
+    gate.scope("task:write");
+    gate.rate({ max: 60, per: "1m", keyBy: "user" });
+
+    const ping = flow("auto.ping", {
+      do: () => ({ ok: true as const }),
+    });
+    on(http.get("/auto-ping").gate(member), ping);
+
+    const app = oke({
+      name: "auto-kv-clock-gate",
+      autoBoot: false,
+      startScheduler: false,
+    });
+
+    expect(app.$options.stores?.some((s) => s.ref === "kv:drafts")).toBe(true);
+    expect(app.$options.stores?.some((s) => s.ref === "index:tasks")).toBe(true);
+    expect(app.$options.clocks?.some((c) => c.name === "daily-digest")).toBe(true);
+    expect(app.$options.gate?.policies?.some((g) => "name" in g && g.name === "member")).toBe(true);
+    expect(app.$options.gate?.policies?.some((g) => "name" in g && g.name === "task:write")).toBe(
+      true,
+    );
+
+    await app.boot({ env: "test" });
+    expect(app.bootResult?.store?.declarations.has("kv:drafts")).toBe(true);
+    expect(app.bootResult?.store?.declarations.has("index:tasks")).toBe(true);
+    expect(app.bootResult?.clock?.declarations.has("daily-digest")).toBe(true);
+    expect(app.bootResult?.gate?.gates.has("member")).toBe(true);
+    expect(app.bootResult?.gate?.gates.has("task:write")).toBe(true);
+  });
+
   test('registry: "consume" (default) drains stores/secrets/signals/channel.templates — a later app does not inherit them', async () => {
     store.sql("leak-app", { schema: {} });
     vault.secret("LEAK_SECRET", { dev: "dev-leak" });

package/src/kernel/boot.test.ts

@@ -79,7 +79,7 @@ describe("boot — lazy element needs", () => {
     expect(needs.signal).toBe(false);
   });
 
-  test("oke() Store-only graph stays under the prior 48 kB baseline", async () => {
+  test("oke() Store-only graph stays under the prior 50 kB baseline", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-store-only-"));
     const entry = join(dir, "entry.ts");
     const appPath = join(import.meta.dir, "app.ts");
@@ -116,9 +116,9 @@ describe("boot — lazy element needs", () => {
         if (raw.byteLength === 0) continue;
         total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
       }
-      // Rebased after 0.12.0 store/http graph growth
-      // (~47.6 kB gzip with export externals).
-      expect(total).toBeLessThan(48_000);
+      // Rebased after host API-key persist + allowlist on `oke()`.
+      // (~50.3 kB gzip with export externals).
+      expect(total).toBeLessThan(51_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
@@ -227,7 +227,7 @@ describe("boot — HTTP gate wiring on the default path", () => {
     resetBindings();
     resetFlowSeq();
     on(
-      http.get("/ping").gate.public,
+      http.get("/ping").public(),
       flow("ping-public", {
         do: () => ({ ok: true }),
       }),

package/src/kernel/boot.ts

@@ -101,10 +101,10 @@ export interface BootOptions {
   readonly gates?: readonly GateDecl[];
   /**
    * HTTP auth-posture enforcement at boot.
-   * - `"deny"` (default) — every HTTP trigger must carry a gate or `.gate.public`
+   * - `"deny"` (default) — every HTTP trigger must carry a gate or `.public()`
    * - `"allow"` — skips the audit **only** when {@link env} is `"test"`;
    *   ignored in local/prod/docker (never a production-wide bypass).
-   *   Migrate real apps with per-trigger `.gate.public`.
+   *   Migrate real apps with per-trigger `.public()`.
    */
   readonly unguardedHttp?: "deny" | "allow";
   /** Signal declarations. */

package/src/kernel/effects-stamping.test.ts

@@ -47,7 +47,7 @@ const CreateOut = z.object({ ok: z.boolean() });
 
 function buildUnannotatedCreateFlow(db: ReturnType<typeof store.sql>) {
   return on(
-    http.post("/notes").gate.public,
+    http.post("/notes").public(),
     flow("notes.create", {
       in: CreateIn,
       out: CreateOut,
@@ -140,7 +140,7 @@ describe("boot-level: table-ref resolution stays backward compatible", () => {
     resetFlowSeq();
     const db = store.sql("app", { schema: { notes } });
     const create = on(
-      http.post("/notes").gate.public,
+      http.post("/notes").public(),
       flow("notes.create", {
         in: CreateIn,
         out: CreateOut,
@@ -193,7 +193,7 @@ import { on, flow, http, gate } from "okengine";
 const db = {} as any;
 const notes = {} as any;
 export const create = on(
-  http.post("/notes").gate.public,
+  http.post("/notes").public(),
   flow("notes.create", {
     do: async (input, fx) => {
       await fx.store(db).insert(notes).values({ id: input.id, title: input.title, createdAt: 1 });

package/src/kernel/element-registries.ts

@@ -1,8 +1,9 @@
 /**
- * Module-evaluation registries for `store.sql` / `store.files`, `vault.secret`,
- * `vault.env.required`, `signal()`, `channel.<medium>().template()`, and
- * `ai.model` / `.prompt` / `ai.embed` / `ai.agent` / `ai.mcpServer` — the plain arrays behind
- * each declare module's `listX()` / `resetX()` pair (mirrors `on.ts`'s
+ * Module-evaluation registries for `store.*`, `vault.secret`,
+ * `vault.env.required`, `signal()`, `clock()`, `gate.policy` / `.scope` /
+ * `.rate`, `channel.<medium>().template()`, and `ai.model` / `.prompt` /
+ * `ai.embed` / `ai.agent` / `ai.mcpServer` — the plain arrays behind each
+ * declare module's `listX()` / `resetX()` pair (mirrors `on.ts`'s
  * trigger-drain `bindings` array).
  *
  * Lives here, not in the declare modules themselves, so {@link oke} can read
@@ -24,8 +25,10 @@ import type { StoreDecl } from "../elements/store/declare.ts";
 import type { VaultSecretDecl } from "../elements/vault/declare.ts";
 import type { SignalDecl } from "../elements/signal/declare.ts";
 import type { ChannelTemplateDecl } from "../elements/channel/declare.ts";
+import type { ClockDecl } from "../elements/clock/declare.ts";
+import type { GateDecl } from "../elements/gate/declare.ts";
 
-/** `store.sql` / `store.files` declarations since the last reset. */
+/** `store.sql` / `store.kv` / `store.files` / `store.index` declarations since the last reset. */
 export const storeRegistry: StoreDecl[] = [];
 /** `vault.secret` declarations since the last reset. */
 export const secretRegistry: VaultSecretDecl[] = [];
@@ -33,6 +36,10 @@ export const secretRegistry: VaultSecretDecl[] = [];
 export const requiredEnvRegistry: string[] = [];
 /** `signal()` declarations since the last reset. */
 export const signalRegistry: SignalDecl[] = [];
+/** `clock()` declarations since the last reset. */
+export const clockRegistry: ClockDecl[] = [];
+/** `gate.policy` / `gate.scope` / `gate.rate` declarations since the last reset. */
+export const gateRegistry: GateDecl[] = [];
 /** Medium-binder `.template()` declarations since the last reset. */
 export const channelTemplateRegistry: ChannelTemplateDecl[] = [];
 /** `ai.model` declarations since the last reset. */

package/src/kernel/errors.ts

@@ -183,6 +183,30 @@ export const OKE_ERRORS = {
     cause: "src/flows/{unit} exists on disk but adopted no flows — the .adopt() barrel is stale.",
     fix: "Run `oke dev` or `oke build` to regenerate `src/flows/generated.ts`.",
   },
+  /**
+   * `http.get()` was never stamped from the file tree — refuse a silent `/`.
+   */
+  HTTP_PATH_UNRESOLVED: {
+    code: 1010,
+    cause: 'Flow "{flow}" bound {method} with no path — the file-tree stamp never ran.',
+    fix: 'Put the file under `src/flows/<unit>/` and import `@/flows/generated`, or pass an explicit path to `http.{method}("/…")`.',
+  },
+  /**
+   * Two HTTP bindings share method + path — last-add-wins is the opposite of this DX.
+   */
+  HTTP_ROUTE_DUPLICATE: {
+    code: 1011,
+    cause: '{method} {path} is bound twice (flow "{flow}").',
+    fix: "Give each HTTP flow a unique method + path.",
+  },
+  /**
+   * Adopted HTTP flow still has no name (`flow({ do })` outside a unit).
+   */
+  HTTP_FLOW_UNNAMED: {
+    code: 1012,
+    cause: "An HTTP flow on {method} {path} has no name.",
+    fix: 'Use `flow("unit.export", {…})` or export it from a `src/flows/<unit>/` file so the tree can stamp `unit.export`.',
+  },
   /**
    * Emit target has no subscriber (unified-theory §21).
    * Thrown at emit when `optional` is false and nobody is subscribed.

package/src/kernel/flow-units.ts

@@ -0,0 +1,64 @@
+/**
+ * Module-evaluation registry for `src/flows/generated.ts`.
+ *
+ * Same consume/ignore posture as `on()` / `listBindings()`: generated.ts
+ * calls {@link registerFlowUnits}; {@link oke} drains the bag into `$routes`
+ * unless `registry: "ignore"`.
+ */
+
+import type { AnyFlowDef } from "./flow.ts";
+import { isFlow } from "./flow.ts";
+
+/** Unit name → export name → Flow. */
+export type FlowUnitBag = {
+  readonly [exportName: string]: unknown;
+};
+
+const pending: Record<string, FlowUnitBag> = {};
+
+/**
+ * Record generated flow units for the next {@link oke} construction.
+ *
+ * @param units - `{ notes, main, … }` from `generated.ts`
+ */
+export function registerFlowUnits(units: Record<string, FlowUnitBag>): void {
+  Object.assign(pending, units);
+}
+
+/**
+ * Drain registered units (consume). Clears the registry.
+ */
+export function consumeRegisteredFlowUnits(): Record<string, FlowUnitBag> {
+  const snap: Record<string, FlowUnitBag> = { ...pending };
+  resetRegisteredFlowUnits();
+  return snap;
+}
+
+/**
+ * Snapshot without clearing (keep / tests).
+ */
+export function peekRegisteredFlowUnits(): Record<string, FlowUnitBag> {
+  return { ...pending };
+}
+
+/**
+ * Clear the unit registry (tests / `registry: "consume"` after drain).
+ */
+export function resetRegisteredFlowUnits(): void {
+  for (const key of Object.keys(pending)) {
+    delete pending[key];
+  }
+}
+
+/**
+ * Collect FlowDefs from a unit bag (skip non-flow exports).
+ *
+ * @param bag - Namespace object
+ */
+export function flowsInUnitBag(bag: FlowUnitBag): AnyFlowDef[] {
+  const found: AnyFlowDef[] = [];
+  for (const value of Object.values(bag)) {
+    if (isFlow(value)) found.push(value);
+  }
+  return found;
+}

package/src/kernel/flow.ts

@@ -239,13 +239,34 @@ export const flowBrand: unique symbol = Symbol("oke.flow");
  * Input / output types are inferred from Standard Schema `in` / `out` when
  * present; otherwise from the `do` handler signature.
  *
+ * A nameless `flow({ do })` is stamped `unit.export` by the file-tree
+ * generator, {@link unit}, or `.adopt()`. Explicit `flow("notes.get", {…})`
+ * still wins.
+ *
+ * @param options - Contract and handler (name stamped later)
+ */
+export function flow<Opts extends FlowOptions<any, any, any>>(
+  options: Opts,
+): FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>>;
+/**
  * @param name - Stable name (used by `fx.call` and the Manifest)
  * @param options - Contract and handler
  */
 export function flow<Opts extends FlowOptions<any, any, any>>(
   name: string,
   options: Opts & { readonly name?: never },
-): FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>> {
+): FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>>;
+export function flow(
+  nameOrOptions: string | FlowOptions<any, any, any>,
+  maybeOptions?: FlowOptions<any, any, any> & { readonly name?: never },
+): FlowDef {
+  const named = typeof nameOrOptions === "string";
+  const name = named ? nameOrOptions : "";
+  const options = (named ? maybeOptions : nameOrOptions) as FlowOptions<any, any, any> | undefined;
+  if (!options || typeof options.do !== "function") {
+    throw new TypeError("flow() expected an options bag with a do handler");
+  }
+
   const triggers: Trigger[] = [];
   const hooks: Partial<Record<HookStage, HookFn[]>> = {};
   const pendingPlugins: PluginDef[] = [];
@@ -253,13 +274,13 @@ export function flow<Opts extends FlowOptions<any, any, any>>(
   const dot = name.indexOf(".");
   const unit = dot > 0 ? name.slice(0, dot) : undefined;
 
-  const def: FlowDef<InferFlowIn<Opts>, InferFlowOut<Opts>, InferFlowErrors<Opts>> = {
+  const def: FlowDef = {
     [flowBrand]: true,
     name,
     unit,
     in: options.in,
     out: options.out,
-    errors: (options.errors ?? undefined) as InferFlowErrors<Opts> | undefined,
+    errors: (options.errors ?? undefined) as FlowErrorMap | undefined,
     effects: options.effects,
     durable: options.durable ?? false,
     retry: options.retry,
@@ -268,17 +289,8 @@ export function flow<Opts extends FlowOptions<any, any, any>>(
     slo: options.slo,
     plane: options.plane,
     breaking: options.breaking ?? false,
-    compensate: options.compensate as
-      | ((
-          ctx: {
-            readonly input: InferFlowIn<Opts>;
-            readonly error: unknown;
-            readonly completedSteps: readonly string[];
-          },
-          fx: import("./fx.ts").Fx,
-        ) => unknown | Promise<unknown>)
-      | undefined,
-    do: options.do as FlowHandler<InferFlowIn<Opts>, InferFlowOut<Opts>>,
+    compensate: options.compensate as FlowDef["compensate"],
+    do: options.do as FlowHandler,
     triggers,
     $trigger: undefined,
     hooks,
@@ -320,9 +332,9 @@ export function isFlow(value: unknown): value is AnyFlowDef {
 }
 
 /**
- * No-op. `name` is a required positional argument now, so there is no
- * auto-name sequence left to reset — kept so existing test `beforeEach`
- * blocks don't need touching.
+ * No-op. Nameless flows start as `""` and are stamped by unit / adopt /
+ * the file-tree generator — kept so existing test `beforeEach` blocks
+ * don't need touching.
  *
  * @internal
  */

package/src/kernel/fx-auth-keys.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Session-only `fx.auth` key methods — issuer derived, never from flow input.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { AttenuationError } from "../auth/attenuation.ts";
+import { createApiKey, createApiKeyStore } from "../auth/api-keys.ts";
+import { isFlowFailure } from "./hooks.ts";
+import { createFx } from "./fx.ts";
+
+describe("fx.auth key methods", () => {
+  test("createApiKey derives creator from the live session and rejects broader scopes", async () => {
+    const store = createApiKeyStore();
+    const fx = createFx({
+      flow: "keys.create",
+      effects: { writes: ["auth:api-keys"] },
+      apiKeyStore: store,
+      auth: { userId: "u1", scopes: new Set(["member"]), apiKeyId: null },
+    });
+    const created = await fx.auth.createApiKey({ name: "mine", scopes: ["member"] });
+    expect(created.key.scopes).toEqual(["member"]);
+    expect(created.secret.startsWith("oke_")).toBe(true);
+    expect(store.keys.get(created.key.id)?.creatorId).toBe("u1");
+
+    await expect(fx.auth.createApiKey({ name: "wide", scopes: ["admin"] })).rejects.toBeInstanceOf(
+      AttenuationError,
+    );
+  });
+
+  test("key-authenticated caller cannot create / list / revoke / rotate / update", async () => {
+    const store = createApiKeyStore();
+    await createApiKey(store, {
+      plane: "user",
+      name: "existing",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      id: "key_existing",
+    });
+    const fx = createFx({
+      flow: "keys.as-key",
+      effects: { reads: ["auth:api-keys"], writes: ["auth:api-keys"] },
+      apiKeyStore: store,
+      auth: { userId: "u1", scopes: new Set(["member"]), apiKeyId: "key_existing" },
+    });
+    for (const call of [
+      () => fx.auth.createApiKey({ name: "nested", scopes: ["member"] }),
+      () => fx.auth.listApiKeys(),
+      () => fx.auth.revokeApiKey("key_existing"),
+      () => fx.auth.rotateApiKey("key_existing"),
+      () => fx.auth.updateApiKey("key_existing", { name: "nope" }),
+    ]) {
+      try {
+        await call();
+        throw new Error("expected Forbidden");
+      } catch (err) {
+        expect(isFlowFailure(err)).toBe(true);
+        if (isFlowFailure(err)) expect(err.error.code).toBe("Forbidden");
+      }
+    }
+  });
+
+  test("list is self-only; cross-user revoke is Forbidden", async () => {
+    const store = createApiKeyStore();
+    await createApiKey(store, {
+      plane: "user",
+      name: "theirs",
+      scopes: ["member"],
+      creatorId: "u2",
+      creatorScopes: ["member"],
+      id: "key_theirs",
+    });
+    const fx = createFx({
+      flow: "keys.list",
+      effects: { reads: ["auth:api-keys"], writes: ["auth:api-keys"] },
+      apiKeyStore: store,
+      auth: { userId: "u1", scopes: new Set(["member"]), apiKeyId: null },
+    });
+    expect(await fx.auth.listApiKeys()).toEqual([]);
+    try {
+      await fx.auth.revokeApiKey("key_theirs");
+      throw new Error("expected Forbidden");
+    } catch (err) {
+      expect(isFlowFailure(err)).toBe(true);
+      if (isFlowFailure(err)) expect(err.error.code).toBe("Forbidden");
+    }
+  });
+});