okengine 0.1.4

package/src/kernel/budget-entry.ts

@@ -0,0 +1,55 @@
+/**
+ * Bundle entry for the kernel edge size budget (AGENTS.md / unified-theory §24).
+ *
+ * Anchors the tree-shaken edge profile — router, flow binding, fx, hooks,
+ * capability, contracts — without optional elements (runs, boot, drivers).
+ * Live bindings keep minify from dropping the runtime graph.
+ */
+
+import { compileRoute, encodeExecuteResult } from "../compiler/index.ts";
+import { validate } from "../validation/standard-schema.ts";
+import { createCapabilityToken } from "./capability.ts";
+import { fail, OKE_ERRORS } from "./errors.ts";
+import { flow } from "./flow.ts";
+import { createFx } from "./fx.ts";
+import { mergeHooks, runPipeline } from "./hooks.ts";
+import { on, resetBindings } from "./on.ts";
+import { createRouter } from "./router.ts";
+import { http } from "./triggers.ts";
+
+/**
+ * Anchor for the size check — must reference the edge-profile surface.
+ */
+export function __okeKernelBudgetAnchor(): {
+  createRouter: typeof createRouter;
+  flow: typeof flow;
+  on: typeof on;
+  resetBindings: typeof resetBindings;
+  http: typeof http;
+  createFx: typeof createFx;
+  fail: typeof fail;
+  OKE_ERRORS: typeof OKE_ERRORS;
+  runPipeline: typeof runPipeline;
+  mergeHooks: typeof mergeHooks;
+  createCapabilityToken: typeof createCapabilityToken;
+  compileRoute: typeof compileRoute;
+  encodeExecuteResult: typeof encodeExecuteResult;
+  validate: typeof validate;
+} {
+  return {
+    createRouter,
+    flow,
+    on,
+    resetBindings,
+    http,
+    createFx,
+    fail,
+    OKE_ERRORS,
+    runPipeline,
+    mergeHooks,
+    createCapabilityToken,
+    compileRoute,
+    encodeExecuteResult,
+    validate,
+  };
+}

package/src/kernel/budget.test.ts

@@ -0,0 +1,19 @@
+/**
+ * Kernel edge profile budget — AGENTS.md / unified-theory §24.
+ * Limit: < 15 kB gzipped (minified bundle).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { KERNEL_EDGE_BUDGET_BYTES } from "../release/limits.ts";
+import { measureKernelEdgeGzipBytes } from "../release/measure.ts";
+
+describe("kernel edge bundle budget", () => {
+  test(`edge profile < ${KERNEL_EDGE_BUDGET_BYTES} bytes gzipped`, async () => {
+    const size = await measureKernelEdgeGzipBytes();
+    console.log(
+      `kernel edge gzip=${size} budget=${KERNEL_EDGE_BUDGET_BYTES}`,
+    );
+    expect(size).toBeGreaterThan(0);
+    expect(size).toBeLessThan(KERNEL_EDGE_BUDGET_BYTES);
+  });
+});

package/src/kernel/call.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test, beforeEach } from "bun:test";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("fx.call — untriggered flows", () => {
+  test("untriggered flow is callable via app.call and fx.call", async () => {
+    const stats = flow({
+      name: "links.stats",
+      do: ({ code }: { code: string }) => ({ code, clicks: 7 }),
+    });
+
+    const parent = on(
+      http.post("/run"),
+      flow({
+        name: "links.run",
+        effects: { calls: ["links.stats"] },
+        do: async ({ code }: { code: string }, fx) => {
+          const result = await fx.call("links.stats", { code });
+          return result;
+        },
+      }),
+    );
+
+    const app = oke({ name: "call" }).adopt(stats);
+
+    // Direct call (Linkly ⑤)
+    await expect(app.call(stats, { code: "sa" })).resolves.toEqual({
+      code: "sa",
+      clicks: 7,
+    });
+
+    // Same path through fx.call from a triggered flow
+    const res = await app.fetch(
+      new Request("http://localhost/run", {
+        method: "POST",
+        body: JSON.stringify({ code: "sa" }),
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      data: { code: "sa", clicks: 7 },
+      error: null,
+    });
+    expect(parent.triggers).toHaveLength(1);
+    expect(stats.triggers).toHaveLength(0);
+  });
+
+  test("http and signal invocations of the same flow execute identically", async () => {
+    let runs = 0;
+    const work = flow({
+      name: "work",
+      do: (input: { v: number }) => {
+        runs += 1;
+        return { out: input.v + 1 };
+      },
+    });
+
+    on(http.post("/work"), work);
+    on({ name: "tick", delivery: "broadcast" }, work);
+
+    const app = oke({ name: "identical" });
+
+    const a = await app.fetch(
+      new Request("http://localhost/work", {
+        method: "POST",
+        body: JSON.stringify({ v: 10 }),
+      }),
+    );
+    const b = await app.dispatchSignal("tick", { v: 10 });
+
+    expect(await a.json()).toEqual({ data: { out: 11 }, error: null });
+    expect(b[0]?.output).toEqual({ out: 11 });
+    expect(runs).toBe(2);
+  });
+});

package/src/kernel/capability.ts

@@ -0,0 +1,113 @@
+/**
+ * Per-flow capability tokens — least privilege by construction (§7.4).
+ *
+ * A flow receives a token covering only its declared effects. An undeclared
+ * access throws OKE1xxx with the flow name, the attempted resource, and the fix.
+ * Enforced at runtime, not merely documented.
+ */
+
+import type { Effects } from "../manifest/types.ts";
+import type { EffectKind } from "./effects.ts";
+import { OKE_ERRORS, throwOke } from "./errors.ts";
+
+/** Maps effect kind → the undeclared-access registry key. */
+const UNDECLARED_KEY: Readonly<
+  Record<EffectKind, keyof typeof OKE_ERRORS>
+> = {
+  read: "UNDECLARED_READ",
+  write: "UNDECLARED_WRITE",
+  emit: "UNDECLARED_EMIT",
+  send: "UNDECLARED_SEND",
+  ask: "UNDECLARED_ASK",
+  secret: "UNDECLARED_SECRET",
+  call: "UNDECLARED_CALL",
+};
+
+/** Maps effect kind → the corresponding `Effects` field. */
+const EFFECTS_FIELD: Readonly<
+  Record<EffectKind, keyof Effects>
+> = {
+  read: "reads",
+  write: "writes",
+  emit: "emits",
+  send: "sends",
+  ask: "asks",
+  secret: "secrets",
+  call: "calls",
+};
+
+/**
+ * Capability token for one flow invocation.
+ * Allows only the resources listed in the flow's declared effects.
+ */
+export interface CapabilityToken {
+  /** Flow id this token was issued for. */
+  readonly flow: string;
+  /** Declared effects that minted this token. */
+  readonly declared: Effects;
+  /**
+   * Assert that `kind` on `resource` is allowed.
+   * Throws {@link OkeError} (OKE1xxx) on violation.
+   *
+   * @param kind - Effect kind being attempted
+   * @param resource - Resource / signal / template / … ref
+   */
+  assert(kind: EffectKind, resource: string): void;
+  /**
+   * Whether `kind` on `resource` is allowed (no throw).
+   *
+   * @param kind - Effect kind
+   * @param resource - Resource ref
+   */
+  allows(kind: EffectKind, resource: string): boolean;
+}
+
+/**
+ * Mint a capability token from a flow's declared effects.
+ *
+ * When `declared` is `undefined` (compiler has not yet stamped effects),
+ * the token is open — every access is allowed and ledgered. An explicit
+ * `{}` or partial declaration is least-privilege (missing keys = deny).
+ *
+ * @param flow - Flow id (used in error messages)
+ * @param declared - Declared effect surface, or `undefined` for open
+ */
+export function createCapabilityToken(
+  flow: string,
+  declared?: Effects,
+): CapabilityToken {
+  const open = declared === undefined;
+  const effects = declared ?? {};
+  const sets: Record<EffectKind, ReadonlySet<string>> = {
+    read: new Set(effects.reads ?? []),
+    write: new Set(effects.writes ?? []),
+    emit: new Set(effects.emits ?? []),
+    send: new Set(effects.sends ?? []),
+    ask: new Set(effects.asks ?? []),
+    secret: new Set(effects.secrets ?? []),
+    call: new Set(effects.calls ?? []),
+  };
+
+  return {
+    flow,
+    declared: effects,
+    allows(kind: EffectKind, resource: string): boolean {
+      if (open) return true;
+      return sets[kind].has(resource);
+    },
+    assert(kind: EffectKind, resource: string): void {
+      if (open) return;
+      if (sets[kind].has(resource)) return;
+      throwOke(UNDECLARED_KEY[kind], { flow, resource });
+    },
+  };
+}
+
+/**
+ * Effects-field name for a kind (e.g. `read` → `"reads"`).
+ *
+ * @param kind - Effect kind
+ */
+export function effectsFieldOf(kind: EffectKind): keyof Effects {
+  return EFFECTS_FIELD[kind];
+}

package/src/kernel/dry-run.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import type { ChannelRuntime } from "../elements/channel/runtime.ts";
+import {
+  isDryRun,
+  withDryRun,
+} from "./dry-run.ts";
+import { createFx, type FxStubStoreHandle } from "./fx.ts";
+
+describe("fx dry-run stubbing", () => {
+  test("send/ask are intercepted; writes still execute then roll back", async () => {
+    let realSends = 0;
+    let realAsks = 0;
+    const channelRuntime = {
+      async send() {
+        realSends += 1;
+        return { ok: true as const, receiptId: "r" };
+      },
+    } as unknown as ChannelRuntime;
+    const aiRuntime = {
+      async ask() {
+        realAsks += 1;
+        return { answer: "nope" };
+      },
+    };
+
+    const stockRow = { qty: 100 };
+    const fx = createFx({
+      flow: "test.dry",
+      effects: {
+        reads: ["sql:t"],
+        writes: ["sql:t"],
+        sends: ["mail"],
+        asks: ["p@1"],
+      },
+      channelRuntime,
+      aiRuntime: aiRuntime as never,
+      storeData: { "sql:t": { sku: stockRow } },
+    });
+
+    const stubbed = await withDryRun(async () => {
+      expect(isDryRun()).toBe(true);
+      const store = fx.store("sql:t") as FxStubStoreHandle;
+      const row = (await store.get("sku")) as { qty: number };
+      row.qty -= 1;
+      await store.set("sku", row);
+      expect(((await store.get("sku")) as { qty: number }).qty).toBe(99);
+      await fx.send("mail", { to: "a@b.c" });
+      await fx.ask("p@1", {});
+      return store.get("sku");
+    });
+
+    expect(await stubbed.result).toEqual({ qty: 99 });
+    expect(realSends).toBe(0);
+    expect(realAsks).toBe(0);
+    expect(stubbed.wouldHaveFired).toEqual([
+      { kind: "send", resource: "mail" },
+      { kind: "ask", resource: "p@1" },
+    ]);
+    // Rolled back — store is byte-for-byte restored.
+    const store = fx.store("sql:t") as FxStubStoreHandle;
+    expect(await store.get("sku")).toEqual({ qty: 100 });
+    expect(stockRow.qty).toBe(100);
+  });
+});

package/src/kernel/dry-run.ts

@@ -0,0 +1,171 @@
+/**
+ * Dry-run effect stubbing + write isolation (console §9.1 · §9.3 · §9.4).
+ *
+ * - Irreversible effects (`send` / `ask`) are intercepted and recorded as
+ *   "would have fired" — never contact a real channel or model.
+ * - Store writes run against real data for an honest pass/fail verdict, then
+ *   are always rolled back (snapshot / restore) when the dry-run scope exits.
+ * - Drivers that cannot isolate writes throw {@link DryRunWriteIsolationError};
+ *   the operator plane refuses rather than silently risk a double-write.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** One intercepted irreversible effect during a dry run. */
+export interface DryRunWouldHaveFired {
+  /** Irreversible kind. */
+  readonly kind: "send" | "ask";
+  /** Template / prompt name. */
+  readonly resource: string;
+  /** Optional correlating message id (signal dry-run). */
+  readonly messageId?: string;
+}
+
+/** Active dry-run bag. */
+export interface DryRunContext {
+  /** Intercepted send/ask calls in order. */
+  readonly wouldHaveFired: DryRunWouldHaveFired[];
+  /** Optional message id stamped onto subsequent intercepts. */
+  messageId?: string;
+  /**
+   * Deep-cloned table snapshots taken before the first touch of each stub store.
+   * Restored in `finally` so dry-run writes never persist.
+   */
+  readonly storeSnapshots: Map<string, Map<string, unknown>>;
+  /** Live stub-store Maps to restore from {@link storeSnapshots}. */
+  readonly storeRefs: Map<string, Map<string, unknown>>;
+}
+
+/**
+ * Thrown when a dry-run write cannot be transactionally isolated.
+ *
+ * The Console / signal bus must refuse the dry-run for that signal rather
+ * than risk a committed double-write.
+ */
+export class DryRunWriteIsolationError extends Error {
+  /** Stable machine code. */
+  readonly code = "dry_run_write_isolation" as const;
+
+  /**
+   * @param reason - Human-readable refusal reason
+   */
+  constructor(reason: string) {
+    super(reason);
+    this.name = "DryRunWriteIsolationError";
+  }
+}
+
+const storage = new AsyncLocalStorage<DryRunContext>();
+
+/**
+ * Whether the current async chain is inside a dry-run scope.
+ */
+export function isDryRun(): boolean {
+  return storage.getStore() !== undefined;
+}
+
+/**
+ * Active dry-run context, or `undefined` outside a dry-run.
+ */
+export function getDryRunContext(): DryRunContext | undefined {
+  return storage.getStore();
+}
+
+/**
+ * Snapshot of intercepted irreversible effects for the current dry-run.
+ */
+export function dryRunWouldHaveFired(): readonly DryRunWouldHaveFired[] {
+  return storage.getStore()?.wouldHaveFired ?? [];
+}
+
+/**
+ * Stamp the active dry-run with a signal message id (for correlating stubs).
+ *
+ * @param messageId - Dead-letter / message id
+ */
+export function setDryRunMessageId(messageId: string): void {
+  const ctx = storage.getStore();
+  if (ctx) ctx.messageId = messageId;
+}
+
+/**
+ * Record that a send/ask would have fired. No-op outside dry-run.
+ *
+ * @param kind - Irreversible kind
+ * @param resource - Template / prompt name
+ */
+export function recordWouldHaveFired(
+  kind: "send" | "ask",
+  resource: string,
+): void {
+  const ctx = storage.getStore();
+  if (!ctx) return;
+  ctx.wouldHaveFired.push({
+    kind,
+    resource,
+    ...(ctx.messageId !== undefined ? { messageId: ctx.messageId } : {}),
+  });
+}
+
+/**
+ * Ensure a stub store table is snapshotted before dry-run mutation.
+ *
+ * First touch deep-clones the table; {@link withDryRun} restores it in `finally`.
+ *
+ * @param ref - Store resource ref (`sql:inventory`, …)
+ * @param table - Live in-memory table Map
+ */
+export function touchDryRunStore(
+  ref: string,
+  table: Map<string, unknown>,
+): void {
+  const ctx = storage.getStore();
+  if (!ctx) return;
+  if (ctx.storeSnapshots.has(ref)) return;
+  ctx.storeRefs.set(ref, table);
+  ctx.storeSnapshots.set(
+    ref,
+    new Map(
+      [...table.entries()].map(([k, v]) => [k, structuredClone(v)]),
+    ),
+  );
+}
+
+/**
+ * Roll back every stub store touched during this dry-run scope.
+ *
+ * @param ctx - Dry-run bag
+ */
+function rollbackStores(ctx: DryRunContext): void {
+  for (const [ref, live] of ctx.storeRefs) {
+    const snap = ctx.storeSnapshots.get(ref);
+    if (!snap) continue;
+    live.clear();
+    for (const [k, v] of snap) {
+      live.set(k, structuredClone(v));
+    }
+  }
+}
+
+/**
+ * Run `fn` with irreversible effects stubbed and stub-store writes rolled back.
+ *
+ * @param fn - Work that may call `fx.send` / `fx.ask` / `fx.store`
+ */
+export async function withDryRun<T>(fn: () => T | Promise<T>): Promise<{
+  readonly result: T;
+  readonly wouldHaveFired: readonly DryRunWouldHaveFired[];
+}> {
+  const ctx: DryRunContext = {
+    wouldHaveFired: [],
+    storeSnapshots: new Map(),
+    storeRefs: new Map(),
+  };
+  try {
+    const result = await storage.run(ctx, fn);
+    return { result, wouldHaveFired: ctx.wouldHaveFired };
+  } finally {
+    // Always roll back — success or failure. Pass/fail was observed before this.
+    rollbackStores(ctx);
+  }
+}

package/src/kernel/effects.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createEffectLedger,
+  EFFECT_KIND_TIERS,
+  recordEffect,
+  reversibilityOf,
+  type EffectKind,
+  type ReversibilityTier,
+} from "./effects.ts";
+
+describe("effects — reversibility tiers", () => {
+  test("all seven effect kinds have the correct reversibility tier", () => {
+    const expected: Record<EffectKind, ReversibilityTier> = {
+      read: "none",
+      write: "reversible",
+      emit: "deferred",
+      send: "irreversible",
+      ask: "irreversible",
+      secret: "capability",
+      call: "portal",
+    };
+
+    expect(EFFECT_KIND_TIERS).toHaveLength(7);
+    for (const { kind, reversibility } of EFFECT_KIND_TIERS) {
+      expect(reversibility).toBe(expected[kind]);
+      expect(reversibilityOf(kind)).toBe(expected[kind]);
+    }
+  });
+});
+
+describe("effects — ledger", () => {
+  test("records kind, resource, timestamp, duration, reversibility in order", async () => {
+    const ledger = createEffectLedger();
+    let t = 1_000;
+    const now = () => t;
+
+    await recordEffect(ledger, "read", "sql:bookings", now, () => {
+      t += 5;
+      return "ok";
+    });
+    await recordEffect(ledger, "write", "sql:bookings", now, async () => {
+      t += 10;
+    });
+    await recordEffect(ledger, "emit", "order-placed", now, async () => {
+      t += 1;
+    });
+
+    expect(ledger.entries).toHaveLength(3);
+    expect(ledger.entries.map((e) => e.kind)).toEqual([
+      "read",
+      "write",
+      "emit",
+    ]);
+    expect(ledger.entries[0]).toMatchObject({
+      kind: "read",
+      resource: "sql:bookings",
+      timestamp: 1_000,
+      duration: 5,
+      reversibility: "none",
+    });
+    expect(ledger.entries[1]).toMatchObject({
+      kind: "write",
+      resource: "sql:bookings",
+      timestamp: 1_005,
+      duration: 10,
+      reversibility: "reversible",
+    });
+    expect(ledger.entries[2]).toMatchObject({
+      kind: "emit",
+      resource: "order-placed",
+      timestamp: 1_015,
+      duration: 1,
+      reversibility: "deferred",
+    });
+  });
+
+  test("clear empties the ledger", () => {
+    const ledger = createEffectLedger();
+    ledger.record({
+      kind: "read",
+      resource: "sql:x",
+      timestamp: 0,
+      duration: 0,
+      reversibility: "none",
+    });
+    ledger.clear();
+    expect(ledger.entries).toEqual([]);
+  });
+});