okengine 0.2.5 → 0.2.8

package/src/kernel/hooks.ts

@@ -40,9 +40,7 @@ export const BEFORE_HANDLER_STAGES: readonly HookStage[] = [
 ] as const;
 
 /** Stages that run after a successful handler (before onResponse). */
-export const AFTER_HANDLER_STAGES: readonly HookStage[] = [
-  "afterHandle",
-] as const;
+export const AFTER_HANDLER_STAGES: readonly HookStage[] = ["afterHandle"] as const;
 
 /** All user-registrable stages in pipeline order. */
 export const HOOK_STAGES: readonly HookStage[] = [
@@ -97,11 +95,7 @@ export type HookFn = (
   ctx: InvocationContext,
   fxOrErr: Fx | unknown,
   fx?: Fx,
-) =>
-  | void
-  | Response
-  | FlowFailure
-  | Promise<void | Response | FlowFailure>;
+) => void | Response | FlowFailure | Promise<void | Response | FlowFailure>;
 
 /** Hook bag keyed by stage. */
 export type HookMap = Partial<Record<HookStage, HookFn[]>>;
@@ -247,10 +241,7 @@ async function runStage(
     const started = pluginId !== undefined ? performance.now() : 0;
     try {
       // Spec apps use `.hook("onError", (ctx, err, fx) => …)`.
-      returned =
-        stage === "onError"
-          ? await fn(ctx, ctx.error, fx)
-          : await fn(ctx, fx);
+      returned = stage === "onError" ? await fn(ctx, ctx.error, fx) : await fn(ctx, fx);
     } catch (err) {
       if (pluginId !== undefined) {
         recordHookCost(pluginId, stage, performance.now() - started);

package/src/kernel/index.ts

@@ -50,11 +50,7 @@ export type {
   RoutesFromAdoptArgs,
 } from "./adopt-routes.ts";
 
-export {
-  createCapabilityToken,
-  effectsFieldOf,
-  type CapabilityToken,
-} from "./capability.ts";
+export { createCapabilityToken, effectsFieldOf, type CapabilityToken } from "./capability.ts";
 
 export {
   createEffectLedger,
@@ -181,12 +177,7 @@ export {
   type HookCostSummary,
 } from "./hook-timing.ts";
 
-export {
-  listBindings,
-  on,
-  resetBindings,
-  type Binding,
-} from "./on.ts";
+export { listBindings, on, resetBindings, type Binding } from "./on.ts";
 
 export {
   isPlugin,
@@ -205,6 +196,7 @@ export {
   type PluginOptions,
   type PluginRegistration,
   type TableContribution,
+  type PluginTableOptions,
 } from "./plugin.ts";
 
 export {
@@ -270,11 +262,6 @@ export {
   type JourneySlo,
 } from "./journey.ts";
 
-export {
-  unit,
-  consumeUnitPlugins,
-  resetUnitPlugins,
-  type UnitBag,
-} from "./unit.ts";
+export { unit, consumeUnitPlugins, resetUnitPlugins, type UnitBag } from "./unit.ts";
 
 export { rateLimit, type RateLimitPluginOptions } from "./rate-limit.ts";

package/src/kernel/journal.ts

@@ -11,11 +11,7 @@ import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 
 /** Status of a durable run. */
-export type JournalRunStatus =
-  | "running"
-  | "sleeping"
-  | "completed"
-  | "failed";
+export type JournalRunStatus = "running" | "sleeping" | "completed" | "failed";
 
 /** A completed named step. */
 export interface JournalStepEntry {
@@ -44,10 +40,7 @@ export interface JournalEffectEntry {
 }
 
 /** One journaled event in call order. */
-export type JournalEntry =
-  | JournalStepEntry
-  | JournalSleepEntry
-  | JournalEffectEntry;
+export type JournalEntry = JournalStepEntry | JournalSleepEntry | JournalEffectEntry;
 
 /** Persisted durable run. */
 export interface JournalRun {
@@ -103,9 +96,7 @@ export interface JournalStore {
 }
 
 /** In-memory journal store. */
-export function createMemoryJournalStore(
-  seed?: readonly JournalRun[],
-): JournalStore {
+export function createMemoryJournalStore(seed?: readonly JournalRun[]): JournalStore {
   const runs = new Map<string, JournalRun>();
   for (const r of seed ?? []) {
     runs.set(r.id, cloneRun(r));
@@ -147,10 +138,7 @@ export function createFileJournalStore(path: string): JournalStore {
 
   async function flush(map: Map<string, JournalRun>): Promise<void> {
     await mkdir(dirname(path), { recursive: true });
-    await Bun.write(
-      path,
-      JSON.stringify({ runs: [...map.values()] }, null, 2),
-    );
+    await Bun.write(path, JSON.stringify({ runs: [...map.values()] }, null, 2));
   }
 
   return {
@@ -204,11 +192,7 @@ export interface JournalSession {
    * @param duration - Duration string (`7d`, `2m`, …)
    * @param parseMs - Duration → milliseconds
    */
-  sleep(
-    label: string,
-    duration: string,
-    parseMs: (duration: string) => number,
-  ): Promise<void>;
+  sleep(label: string, duration: string, parseMs: (duration: string) => number): Promise<void>;
   /**
    * Journal an arbitrary fx effect (replay returns recorded value).
    *
@@ -216,11 +200,7 @@ export interface JournalSession {
    * @param resource - Resource ref
    * @param execute - Side-effecting body
    */
-  effect<T>(
-    effectKind: string,
-    resource: string,
-    execute: () => T | Promise<T>,
-  ): Promise<T>;
+  effect<T>(effectKind: string, resource: string, execute: () => T | Promise<T>): Promise<T>;
   /** Persist current run status / output. */
   commit(
     status: JournalRunStatus,
@@ -327,11 +307,7 @@ export function createJournal(options: CreateJournalOptions): Journal {
       ): Promise<T> {
         for (let i = cursor; i < run.entries.length; i++) {
           const e = run.entries[i]!;
-          if (
-            e.kind === "effect" &&
-            e.effectKind === effectKind &&
-            e.resource === resource
-          ) {
+          if (e.kind === "effect" && e.effectKind === effectKind && e.resource === resource) {
             cursor = i + 1;
             return e.value as T;
           }

package/src/kernel/on.ts

@@ -6,12 +6,7 @@
  * The return type carries the bound trigger so `typeof app` can derive REST.
  */
 
-import {
-  isFlow,
-  type AnyFlowDef,
-  type FlowDef,
-  type FlowErrorMap,
-} from "./flow.ts";
+import { isFlow, type AnyFlowDef, type FlowDef, type FlowErrorMap } from "./flow.ts";
 import {
   normalizeTrigger,
   type BoundTriggerOf,

package/src/kernel/pipeline.test.ts

@@ -9,10 +9,7 @@
 
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
-import {
-  createSessionStore,
-  issueSessionWithScopes,
-} from "../auth/sessions.ts";
+import { createSessionStore, issueSessionWithScopes } from "../auth/sessions.ts";
 import { createClockRuntime } from "../elements/clock.ts";
 import { gate } from "../elements/gate.ts";
 import { createRunsRuntime, memoryRunsDriver } from "../runs/index.ts";
@@ -20,16 +17,11 @@ import { oke } from "./app.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
 import { on, resetBindings } from "./on.ts";
 import { http } from "./triggers.ts";
-import {
-  gateDenialFailure,
-  recordGateEvaluations,
-} from "./pipeline.ts";
+import { gateDenialFailure, recordGateEvaluations } from "./pipeline.ts";
 import { createRunTelemetry } from "./run-telemetry.ts";
 
 const member = gate.policy("member", ({ auth }) => !!auth.verified);
-const canOrder = gate.policy("order:create", ({ auth }) =>
-  auth.scopes.has("order:create"),
-);
+const canOrder = gate.policy("order:create", ({ auth }) => auth.scopes.has("order:create"));
 
 describe("gateDenialFailure", () => {
   test("anonymous → Unauthorized; authed → Forbidden; rate → RateLimited", () => {
@@ -217,18 +209,17 @@ describe("pipeline — Bearer cryptographic verification", () => {
     const app = oke({
       name: "auth-forge",
       gates: [member],
-      env: "dev",
+      env: "local",
       auth: { secret: "hmac-secret-for-tests", sessions },
       startScheduler: false,
     });
-    await app.boot({ env: "dev", gates: [member], startScheduler: false });
+    await app.boot({ env: "local", gates: [member], startScheduler: false });
 
     const res = await app.fetch(
       new Request("http://localhost/secure", {
         method: "GET",
         headers: {
-          authorization:
-            "Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJoYWNrZXIifQ.forgedsignature",
+          authorization: "Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJoYWNrZXIifQ.forgedsignature",
         },
       }),
     );
@@ -272,13 +263,13 @@ describe("pipeline — Bearer cryptographic verification", () => {
     const app = oke({
       name: "auth-expired",
       gates: [member],
-      env: "dev",
+      env: "local",
       auth: { secret, sessions, now: () => nowMs },
       elements: { clock: clockRt },
       startScheduler: false,
     });
     await app.boot({
-      env: "dev",
+      env: "local",
       gates: [member],
       startScheduler: false,
       elements: { clock: clockRt },
@@ -324,10 +315,10 @@ describe("pipeline — Bearer cryptographic verification", () => {
     const app = oke({
       name: "no-inject",
       gates: [member],
-      env: "dev",
+      env: "local",
       startScheduler: false,
     });
-    await app.boot({ env: "dev", gates: [member], startScheduler: false });
+    await app.boot({ env: "local", gates: [member], startScheduler: false });
 
     const result = await app.execute(
       app.flow("orders.inject")!,

package/src/kernel/pipeline.ts

@@ -74,18 +74,14 @@ export type GateDenialCode = "Unauthorized" | "Forbidden" | "RateLimited";
  * @param evaluation - First denying evaluation
  * @param ctx - Policy context at denial time
  */
-export function gateDenialFailure(
-  evaluation: GateEvaluation,
-  ctx: GatePolicyContext,
-): FlowFailure {
+export function gateDenialFailure(evaluation: GateEvaluation, ctx: GatePolicyContext): FlowFailure {
   if (evaluation.kind === "rate" || evaluation.reason === "rate limited") {
     return fail("RateLimited", {
       retryAfterMs: evaluation.retryAfterMs ?? 0,
     });
   }
 
-  const authenticated =
-    ctx.auth.userId !== null && ctx.auth.userId !== undefined;
+  const authenticated = ctx.auth.userId !== null && ctx.auth.userId !== undefined;
   if (!authenticated) {
     return fail("Unauthorized", {});
   }
@@ -102,9 +98,7 @@ export function gateDenialFailure(
  */
 export function gateNamesOf(trigger: Trigger): string[] {
   if (trigger.kind !== "http") return [];
-  return (trigger as HttpTrigger).gates.map((g) =>
-    typeof g === "string" ? g : g.name,
-  );
+  return (trigger as HttpTrigger).gates.map((g) => (typeof g === "string" ? g : g.name));
 }
 
 /**
@@ -129,10 +123,7 @@ export function recordGateEvaluations(
  * @param bag - Mutable principal bag
  * @param resolved - Identity
  */
-export function applyPrincipal(
-  bag: PrincipalBag,
-  resolved: ResolvedPrincipal | undefined,
-): void {
+export function applyPrincipal(bag: PrincipalBag, resolved: ResolvedPrincipal | undefined): void {
   if (!resolved) return;
   if (resolved.plane === "operator" || resolved.operatorId !== undefined) {
     bag.operator.id = resolved.operatorId ?? null;
@@ -217,10 +208,7 @@ export function createElementPipelineHooks(deps: PipelineDeps): {
  * @param fx - Fx door
  * @param ctx - Invocation context (for IP / meta)
  */
-export function policyContextOf(
-  fx: Fx,
-  ctx: InvocationContext,
-): GatePolicyContext {
+export function policyContextOf(fx: Fx, ctx: InvocationContext): GatePolicyContext {
   const auth = fx.auth as FxAuth;
   const operator = fx.operator as FxOperator;
   const ip =

package/src/kernel/plug.ts

@@ -14,10 +14,7 @@
 
 import type { AnyFlowDef } from "./flow.ts";
 import { isPlugin, type DecorationsOf, type PluginDef } from "./plugin.ts";
-import {
-  type PluginRegistry,
-  type PluginScope,
-} from "./registry.ts";
+import { type PluginRegistry, type PluginScope } from "./registry.ts";
 
 /**
  * Apply a plugin to a registry at the given scope.
@@ -43,10 +40,8 @@ export function applyPlugin(
  * @typeParam Base - Existing decorations
  * @typeParam P - Plugin being plugged
  */
-export type AccumulateDecorations<
-  Base extends Record<string, unknown>,
-  P,
-> = Base & DecorationsOf<P>;
+export type AccumulateDecorations<Base extends Record<string, unknown>, P> = Base &
+  DecorationsOf<P>;
 
 /** Something that can receive `.plug()` with type accumulation. */
 export interface Pluggable<D extends Record<string, unknown> = {}> {
@@ -55,9 +50,7 @@ export interface Pluggable<D extends Record<string, unknown> = {}> {
    *
    * @param pluginDef - Plugin from {@link plugin}
    */
-  plug<P extends PluginDef>(
-    pluginDef: P,
-  ): Pluggable<AccumulateDecorations<D, P>>;
+  plug<P extends PluginDef>(pluginDef: P): Pluggable<AccumulateDecorations<D, P>>;
 }
 
 /**

package/src/kernel/plugin/conflicts.test.ts

@@ -10,19 +10,11 @@ describe("plugin conflict detection", () => {
   test("table-name collision fails the boot with both plugin names", () => {
     const registry = createPluginRegistry();
 
-    registry.plug(
-      plugin("audit", { version: "1.0.0" }).table("events"),
-      { kind: "app" },
-    );
+    registry.plug(plugin("audit", { version: "1.0.0" }).table("events"), { kind: "app" });
 
     expect(() =>
-      registry.plug(
-        plugin("billing", { version: "1.0.0" }).table("events"),
-        { kind: "app" },
-      ),
-    ).toThrow(
-      'Plugin conflict: table "events" claimed by "audit" and "billing"',
-    );
+      registry.plug(plugin("billing", { version: "1.0.0" }).table("events"), { kind: "app" }),
+    ).toThrow('Plugin conflict: table "events" claimed by "audit" and "billing"');
   });
 
   test("panel-id collision names both sides", () => {
@@ -79,28 +71,24 @@ describe("plugin conflict detection", () => {
       config: { max: 30 },
     }).hook("onRequest", () => {});
 
-    expect(
-      registry.plug(p, { kind: "unit", name: "orders" }),
-    ).toBeDefined();
-    expect(
-      registry.plug(p, { kind: "unit", name: "payments" }),
-    ).toBeDefined();
+    expect(registry.plug(p, { kind: "unit", name: "orders" })).toBeDefined();
+    expect(registry.plug(p, { kind: "unit", name: "payments" })).toBeDefined();
     expect(registry.installed).toHaveLength(2);
   });
 
   test("same plugin twice with conflicting config is a boot error", () => {
     const registry = createPluginRegistry();
 
-    registry.plug(
-      plugin("rate-limit", { version: "1.0.0", config: { max: 30 } }),
-      { kind: "unit", name: "orders" },
-    );
+    registry.plug(plugin("rate-limit", { version: "1.0.0", config: { max: 30 } }), {
+      kind: "unit",
+      name: "orders",
+    });
 
     expect(() =>
-      registry.plug(
-        plugin("rate-limit", { version: "1.0.0", config: { max: 60 } }),
-        { kind: "unit", name: "payments" },
-      ),
+      registry.plug(plugin("rate-limit", { version: "1.0.0", config: { max: 60 } }), {
+        kind: "unit",
+        name: "payments",
+      }),
     ).toThrow(/conflicting config/);
   });
 });

package/src/kernel/plugin/decorate.test.ts

@@ -15,8 +15,7 @@ beforeEach(() => {
 });
 
 /** Compile-time assert: `Actual` extends `Expected`. */
-type ExpectExtends<Actual, Expected> =
-  Actual extends Expected ? true : false;
+type ExpectExtends<Actual, Expected> = Actual extends Expected ? true : false;
 
 describe("plugin decorate — types and runtime", () => {
   test("decoration is visible in downstream handlers", async () => {
@@ -45,14 +44,12 @@ describe("plugin decorate — types and runtime", () => {
   });
 
   test("types accumulate through .plug()", () => {
-    const withAudit = plugin("audit", { version: "1.0.0" }).decorate(
-      "audit",
-      { enabled: true as const },
-    );
-    const withBilling = plugin("billing", { version: "1.0.0" }).decorate(
-      "billing",
-      { currency: "SAR" as const },
-    );
+    const withAudit = plugin("audit", { version: "1.0.0" }).decorate("audit", {
+      enabled: true as const,
+    });
+    const withBilling = plugin("billing", { version: "1.0.0" }).decorate("billing", {
+      currency: "SAR" as const,
+    });
 
     const app = oke({ name: "types" }).plug(withAudit).plug(withBilling);
 
@@ -98,9 +95,7 @@ describe("plugin decorate — types and runtime", () => {
     );
 
     const app = oke({ name: "deco-scope" });
-    app.unit("orders").plug(
-      plugin("flag", { version: "1.0.0" }).decorate("flag", "orders-only"),
-    );
+    app.unit("orders").plug(plugin("flag", { version: "1.0.0" }).decorate("flag", "orders-only"));
 
     await app.fetch(new Request("http://localhost/orders"));
     await app.fetch(new Request("http://localhost/payments"));

package/src/kernel/plugin/scoping.test.ts

@@ -54,11 +54,7 @@ describe("plugin scoping — attachment point is the scope", () => {
     await app.fetch(new Request("http://localhost/orders"));
     await app.fetch(new Request("http://localhost/payments"));
 
-    expect(fired).toEqual([
-      "rate-limit",
-      "orders:handler",
-      "payments:handler",
-    ]);
+    expect(fired).toEqual(["rate-limit", "orders:handler", "payments:handler"]);
   });
 
   test("app-scoped plugin hook fires for every unit", async () => {
@@ -87,12 +83,9 @@ describe("plugin scoping — attachment point is the scope", () => {
       }),
     );
 
-    const audit = plugin("audit", { version: "1.0.0" }).hook(
-      "afterHandle",
-      () => {
-        fired.push("audit");
-      },
-    );
+    const audit = plugin("audit", { version: "1.0.0" }).hook("afterHandle", () => {
+      fired.push("audit");
+    });
 
     const app = oke({ name: "app-scope" }).plug(audit);
 

package/src/kernel/plugin.ts

@@ -91,10 +91,30 @@ export interface ImageRecipeContribution {
 export interface TableContribution {
   /** Table name — conflict namespace shared across plugins. */
   readonly name: string;
-  /** Opaque schema descriptor. */
+  /**
+   * Abstract column map from `field.*` builders (merged into domain schema emit).
+   * Omit when the plugin only claims a name (DDL stays hand-written).
+   */
+  readonly columns?: Readonly<Record<string, unknown>>;
+  /**
+   * Non-column metadata (e.g. data plane). Prefer this over stuffing `plane`
+   * into the column map.
+   */
+  readonly options?: {
+    readonly plane?: "operator" | "user" | "shared" | string;
+  };
+  /**
+   * Opaque schema descriptor (legacy). Prefer {@link columns} + {@link options}.
+   * Still set for plane-only contributions so older readers keep working.
+   */
   readonly schema?: unknown;
 }
 
+/** Options for {@link PluginApi.table} / {@link PluginDef.table}. */
+export interface PluginTableOptions {
+  readonly plane?: "operator" | "user" | "shared" | string;
+}
+
 /** Driver contribution. */
 export interface DriverContribution {
   /** Driver id (protocol-named) — conflict namespace shared across plugins. */
@@ -152,10 +172,7 @@ export interface PluginApi {
    * @param name - Command name
    * @param handler - Command handler
    */
-  cli(
-    name: string,
-    handler: CliContribution["handler"],
-  ): PluginApi;
+  cli(name: string, handler: CliContribution["handler"]): PluginApi;
   /**
    * Contribute a driver.
    *
@@ -173,10 +190,19 @@ export interface PluginApi {
   /**
    * Contribute a DB table / schema fragment.
    *
+   * Plugins may declare **whole tables** (with optional `field.*` columns)
+   * merged into the generated domain schema. Extending an existing app-owned
+   * table with plugin columns is not supported — contribute a separate table.
+   *
    * @param name - Table name
-   * @param schema - Opaque schema
+   * @param columns - Abstract column map, or legacy `{ plane }` options
+   * @param options - Plane / metadata (preferred over embedding `plane` in columns)
    */
-  table(name: string, schema?: unknown): PluginApi;
+  table(
+    name: string,
+    columns?: Readonly<Record<string, unknown>>,
+    options?: PluginTableOptions,
+  ): PluginApi;
   /**
    * Contribute a flow.
    *
@@ -265,10 +291,7 @@ export interface PluginDef<D extends Record<string, unknown> = {}> {
    * @param key - Decoration key
    * @param value - Value
    */
-  decorate<K extends string, V>(
-    key: K,
-    value: V,
-  ): PluginDef<D & { [P in K]: V }>;
+  decorate<K extends string, V>(key: K, value: V): PluginDef<D & { [P in K]: V }>;
   /**
    * Queue an element contribution.
    *
@@ -317,10 +340,17 @@ export interface PluginDef<D extends Record<string, unknown> = {}> {
   /**
    * Queue a table / schema contribution.
    *
+   * Whole tables only — no column injection into app-owned tables (v1).
+   *
    * @param name - Table name
-   * @param schema - Schema
+   * @param columns - Abstract column map, or legacy `{ plane }` options
+   * @param options - Plane / metadata
    */
-  table(name: string, schema?: unknown): PluginDef<D>;
+  table(
+    name: string,
+    columns?: Readonly<Record<string, unknown>>,
+    options?: PluginTableOptions,
+  ): PluginDef<D>;
   /**
    * Queue a flow contribution.
    *
@@ -343,8 +373,7 @@ export interface PluginDef<D extends Record<string, unknown> = {}> {
 }
 
 /** Extract accumulated decoration types from a {@link PluginDef}. */
-export type DecorationsOf<P> =
-  P extends PluginDef<infer D> ? D : Record<string, never>;
+export type DecorationsOf<P> = P extends PluginDef<infer D> ? D : Record<string, never>;
 
 /**
  * Define a plugin. Fluent methods queue a registration plan; the registry
@@ -353,10 +382,7 @@ export type DecorationsOf<P> =
  * @param name - Stable plugin id
  * @param options - Version and optional config snapshot
  */
-export function plugin(
-  name: string,
-  options: PluginOptions,
-): PluginDef {
+export function plugin(name: string, options: PluginOptions): PluginDef {
   const steps: Array<(api: PluginApi) => void> = [];
 
   const def: PluginDef = {
@@ -390,9 +416,7 @@ export function plugin(
           api.element(el);
         } else if (typeof el.facet === "string" && typeof el.name === "string") {
           api.element({
-            kind: el.facet.startsWith("store.")
-              ? el.facet
-              : `store.${el.facet}`,
+            kind: el.facet.startsWith("store.") ? el.facet : `store.${el.facet}`,
             name: el.name,
           });
         } else {
@@ -437,9 +461,9 @@ export function plugin(
       });
       return def;
     },
-    table(tableName, schema) {
+    table(tableName, columns, options) {
       steps.push((api) => {
-        api.table(tableName, schema);
+        api.table(tableName, columns, options);
       });
       return def;
     },