okengine 0.1.4

package/src/kernel/auth-resolve.ts

@@ -0,0 +1,93 @@
+/**
+ * Bearer → principal resolution via the builtin hybrid session path.
+ *
+ * Production HTTP requests must call {@link verifyAccess} (HMAC signature,
+ * expiry, session not revoked). Test-harness principal injection is gated
+ * separately in the pipeline (`allowTestPrincipals`).
+ */
+
+import {
+  createSessionStore,
+  verifyAccess,
+  type AccessClaims,
+  type SessionStore,
+} from "../auth/sessions.ts";
+import type { ResolvedPrincipal } from "./pipeline.ts";
+
+/** Auth binding for the request pipeline. */
+export interface AppAuthBinding {
+  /** HMAC secret for access tokens. */
+  readonly secret: string;
+  /** Session store (revocation checks). Created when omitted. */
+  readonly sessions: SessionStore;
+  /** Injectable clock (tests / frozen harness). */
+  readonly now: () => number;
+}
+
+/** Options for {@link createAppAuthBinding}. */
+export interface CreateAppAuthBindingOptions {
+  readonly secret: string;
+  readonly sessions?: SessionStore;
+  readonly now?: () => number;
+}
+
+/**
+ * Create an auth binding that verifies Bearer tokens cryptographically.
+ *
+ * @param options - Secret + optional session store / clock
+ */
+export function createAppAuthBinding(
+  options: CreateAppAuthBindingOptions,
+): AppAuthBinding {
+  return {
+    secret: options.secret,
+    sessions: options.sessions ?? createSessionStore(),
+    now: options.now ?? (() => Date.now()),
+  };
+}
+
+/**
+ * Verify a Bearer access token and map claims to a {@link ResolvedPrincipal}.
+ * Throws {@link import("../auth/sessions.ts").SessionError} on forge / expiry / revoke.
+ *
+ * @param auth - App auth binding
+ * @param token - Raw Bearer token (no `Bearer ` prefix)
+ */
+export async function verifyBearerToken(
+  auth: AppAuthBinding,
+  token: string,
+): Promise<ResolvedPrincipal> {
+  const claims = await verifyAccess(
+    auth.sessions,
+    auth.secret,
+    token,
+    auth.now,
+  );
+  return claimsToPrincipal(claims);
+}
+
+/**
+ * Map access-token claims to the pipeline principal shape.
+ *
+ * A cryptographically valid access token implies an authenticated principal;
+ * `verified` is set so policy gates like `member` accept the session.
+ *
+ * @param claims - Verified claims
+ */
+export function claimsToPrincipal(claims: AccessClaims): ResolvedPrincipal {
+  if (claims.plane === "operator") {
+    return {
+      plane: "operator",
+      operatorId: claims.sub,
+      userId: null,
+      scopes: claims.scopes,
+      verified: true,
+    };
+  }
+  return {
+    plane: "user",
+    userId: claims.sub,
+    scopes: claims.scopes,
+    verified: true,
+  };
+}

package/src/kernel/boot.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Boot sequence acceptance:
+ * - missing secrets fail naming every gap at once
+ * - capability tokens minted from flow effects (Manifest)
+ * - declared cron fires on a running app without manual dispatch
+ * - real timer loop starts by default outside test env (fake wall-clock)
+ */
+
+import { afterEach, describe, expect, jest, test } from "bun:test";
+import { memoryVaultDriver } from "../drivers/index.ts";
+import { clock } from "../elements/clock.ts";
+import { vault, VaultBootError } from "../elements/vault.ts";
+import { bootApplication } from "./boot.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { every, http } from "./triggers.ts";
+import { oke } from "./app.ts";
+import { on, resetBindings } from "./on.ts";
+
+describe("boot — vault gaps", () => {
+  test("two missing secrets fail naming both at once", async () => {
+    try {
+      await bootApplication({
+        env: "prod",
+        secrets: [
+          vault("STRIPE_KEY", { description: "Payments gateway key" }),
+          vault("DATABASE_URL", { description: "Primary SQL URL" }),
+        ],
+        vault: {
+          allowDevFallbacks: false,
+          chain: [{ driver: memoryVaultDriver, options: { secrets: {} } }],
+        },
+      });
+      expect.unreachable("boot should fail");
+    } catch (err) {
+      expect(err).toBeInstanceOf(VaultBootError);
+      const boot = err as VaultBootError;
+      expect(boot.gaps.map((g) => g.name).sort()).toEqual([
+        "DATABASE_URL",
+        "STRIPE_KEY",
+      ]);
+      expect(boot.message).toContain("STRIPE_KEY");
+      expect(boot.message).toContain("DATABASE_URL");
+    }
+  });
+});
+
+describe("boot — capabilities from Manifest effects", () => {
+  test("tokens cover declared effects only", async () => {
+    const charge = flow({
+      name: "payments.charge",
+      effects: { secrets: ["STRIPE_KEY"], writes: ["sql:orders"] },
+      do: () => ({ ok: true }),
+    });
+    const result = await bootApplication({
+      env: "test",
+      secrets: [vault("STRIPE_KEY", { dev: "sk_test" })],
+      vault: { allowDevFallbacks: true, chain: [] },
+      flows: [charge],
+    });
+    const cap = result.capabilities.get("payments.charge");
+    expect(cap).toBeDefined();
+    expect(cap!.allows("secret", "STRIPE_KEY")).toBe(true);
+    expect(cap!.allows("write", "sql:orders")).toBe(true);
+    expect(cap!.allows("secret", "OTHER")).toBe(false);
+    await result.close();
+  });
+});
+
+describe("boot — cron fires without manual dispatch", () => {
+  test("scheduler tick runs a due every-binding", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    let ran = 0;
+    on(
+      every("1h"),
+      flow({
+        name: "cleanup.expire",
+        do: () => {
+          ran += 1;
+        },
+      }),
+    );
+
+    const app = oke({
+      name: "cron-boot",
+      clocks: [clock("expire-stale", { every: "1h" })],
+      env: "test",
+    });
+
+    await app.boot({
+      env: "test",
+      startScheduler: false,
+      clocks: [clock("expire-stale", { every: "1h" })],
+    });
+
+    const rt = app.bootResult!.clock!;
+    // First tick — due (never ran).
+    const { ran: names } = await rt.tick();
+    expect(names.length).toBeGreaterThan(0);
+    expect(ran).toBeGreaterThanOrEqual(1);
+
+    // Advance past the effective every; tick again without dispatchEvery.
+    rt.advance("1h");
+    const before = ran;
+    await rt.tick();
+    expect(ran).toBeGreaterThan(before);
+
+    await app.bootResult?.close();
+  });
+});
+
+describe("boot — HTTP gate wiring lives behind boot", () => {
+  test("unbooted app still serves without gates (legacy)", async () => {
+    resetBindings();
+    resetFlowSeq();
+    on(
+      http.get("/ping"),
+      flow({
+        name: "ping",
+        do: () => ({ ok: true }),
+      }),
+    );
+    const app = oke({ name: "legacy" });
+    const res = await app.fetch(
+      new Request("http://localhost/ping", { method: "GET" }),
+    );
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("boot — cron autostart via real timer loop", () => {
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  test("booted app (non-test) fires every() with no manual tick/runNow", async () => {
+    resetBindings();
+    resetFlowSeq();
+    jest.useFakeTimers({ now: 1_000_000 });
+
+    let ran = 0;
+    on(
+      every("10m"),
+      flow({
+        name: "cleanup.autostart",
+        do: () => {
+          ran += 1;
+        },
+      }),
+    );
+
+    // env: "dev" → startScheduler defaults ON. No createTestApp / advance.
+    const app = oke({
+      name: "cron-autostart",
+      env: "dev",
+      schedulerIntervalMs: 1000,
+    });
+    await app.boot();
+
+    expect(ran).toBe(0);
+
+    // Drive the wall-clock interval that boot installed — not clock.advance /
+    // runNow / dispatchEvery (those prove the harness, not autostart).
+    jest.advanceTimersByTime(1000);
+    // Interval callback does `void clock.tick()`; drain the async store walk.
+    for (let i = 0; i < 50; i++) await Promise.resolve();
+
+    expect(ran).toBeGreaterThanOrEqual(1);
+
+    await app.stop();
+  });
+});

package/src/kernel/boot.ts

@@ -0,0 +1,439 @@
+/**
+ * Ordered application boot — fail fast before a single request is served.
+ *
+ * ```
+ * 1. Vault     — resolve every declared secret (list all gaps at once)
+ * 2. Store     — bind drivers per environment; open connections
+ * 3. Signals   — register declarations; start consumers
+ * 4. Clocks    — reconcile into the Store; start scheduler (leader election)
+ * 5. Channel   — bind channel runtime
+ * 6. AI        — bind AI runtime
+ * 7. Runs      — open the runs store
+ * 8. Caps      — mint per-flow capability tokens from the Manifest / effects
+ * ```
+ *
+ * The scheduler reads the effective state from the Store after reconciliation,
+ * never the code directly (console §5).
+ */
+
+import {
+  createAiRuntime,
+  type AiRuntime,
+  type CreateAiRuntimeOptions,
+} from "../elements/ai.ts";
+import {
+  createChannelRuntime,
+  type ChannelRuntime,
+  type CreateChannelRuntimeOptions,
+} from "../elements/channel.ts";
+import {
+  clock as declareClock,
+  createClockRuntime,
+  createTestClockRuntime,
+  type ClockDecl,
+  type ClockRuntime,
+} from "../elements/clock.ts";
+import {
+  createGateRuntime,
+  type GateDecl,
+  type GateRuntime,
+} from "../elements/gate.ts";
+import {
+  createSignalRuntime,
+  type SignalDecl,
+  type SignalRuntime,
+} from "../elements/signal.ts";
+import {
+  createStoreRuntime,
+  type StoreDecl,
+  type StoreRuntime,
+} from "../elements/store.ts";
+import {
+  createVaultRuntime,
+  type CreateVaultRuntimeOptions,
+  type VaultRuntime,
+  type VaultSecretDecl,
+} from "../elements/vault.ts";
+import {
+  memoryDrivers,
+  memorySignalDriver,
+  memoryVaultDriver,
+  openConsoleChannel,
+  mockAiDriver,
+} from "../drivers/index.ts";
+import {
+  resolveDriverId,
+  type ConfigEnv,
+  type OkeConfig,
+} from "../config/index.ts";
+import {
+  createRunsRuntime,
+  memoryRunsDriver,
+  type CreateRunsRuntimeOptions,
+  type RunsRuntime,
+} from "../runs/index.ts";
+import {
+  createCapabilityToken,
+  type CapabilityToken,
+} from "./capability.ts";
+import type { AnyFlowDef } from "./flow.ts";
+import type { Binding } from "./on.ts";
+
+/** Pre-built or partially-built element runtimes. */
+export interface ElementRuntimes {
+  readonly vault?: VaultRuntime;
+  readonly store?: StoreRuntime;
+  readonly signal?: SignalRuntime;
+  readonly clock?: ClockRuntime;
+  readonly gate?: GateRuntime;
+  readonly channel?: ChannelRuntime;
+  readonly ai?: AiRuntime;
+  readonly runs?: RunsRuntime;
+}
+
+/** Declarations + options consumed by {@link bootApplication}. */
+export interface BootOptions {
+  /** Active environment (defaults to `dev`). */
+  readonly env?: ConfigEnv;
+  /** Optional `oke.config.ts` document. */
+  readonly config?: OkeConfig;
+  /** Pre-built runtimes (skip construction when present). */
+  readonly elements?: ElementRuntimes;
+  /** Vault secret contracts. */
+  readonly secrets?: readonly VaultSecretDecl[];
+  /** Vault create options (chain / allowDevFallbacks). */
+  readonly vault?: Omit<CreateVaultRuntimeOptions, "secrets"> & {
+    readonly secrets?: readonly VaultSecretDecl[];
+  };
+  /** Gate declarations for the runtime. */
+  readonly gates?: readonly GateDecl[];
+  /** Signal declarations. */
+  readonly signals?: readonly SignalDecl[];
+  /** Named clock declarations. */
+  readonly clocks?: readonly ClockDecl[];
+  /** Store facet declarations to register. */
+  readonly stores?: readonly StoreDecl[];
+  /** Channel runtime options. */
+  readonly channel?: CreateChannelRuntimeOptions;
+  /** AI runtime options. */
+  readonly ai?: CreateAiRuntimeOptions;
+  /** Runs runtime or create options. */
+  readonly runs?: RunsRuntime | CreateRunsRuntimeOptions;
+  /** Adopted bindings (for every→cron + signal consumers). */
+  readonly bindings?: readonly Binding[];
+  /** Flows known to the app (for capability minting). */
+  readonly flows?: readonly AnyFlowDef[];
+  /**
+   * Dispatch a cron / every interval when the scheduler fires.
+   *
+   * @param name - Cron name or every-interval
+   */
+  readonly onCronFire?: (name: string) => void | Promise<void>;
+  /**
+   * Dispatch a signal message to bound flows.
+   *
+   * @param signal - Signal name
+   * @param payload - Payload
+   */
+  readonly onSignal?: (
+    signal: string,
+    payload: unknown,
+  ) => void | Promise<void>;
+  /** Injectable clock for test / frozen harnesses. */
+  readonly now?: () => number;
+  /** Instance id for leader election. */
+  readonly instanceId?: string;
+  /**
+   * Start a background scheduler tick loop.
+   * Default: `true` when `env !== "test"`; `false` in test (opt in explicitly).
+   * Opt out in production with `startScheduler: false`.
+   */
+  readonly startScheduler?: boolean;
+  /** Scheduler tick period ms (default 1000). */
+  readonly schedulerIntervalMs?: number;
+}
+
+/** Result of a successful boot. */
+export interface BootResult {
+  readonly vault?: VaultRuntime;
+  readonly store?: StoreRuntime;
+  readonly signal?: SignalRuntime;
+  readonly clock?: ClockRuntime;
+  readonly gate?: GateRuntime;
+  readonly channel?: ChannelRuntime;
+  readonly ai?: AiRuntime;
+  readonly runs?: RunsRuntime;
+  /** Per-flow capability tokens minted from declared effects. */
+  readonly capabilities: ReadonlyMap<string, CapabilityToken>;
+  /** Stop the background scheduler (if started). */
+  stopScheduler(): void;
+  /** Close element runtimes. */
+  close(): Promise<void>;
+}
+
+/**
+ * Run the ordered boot sequence. Fails fast — a missing secret throws
+ * before store/signal/… open, so no request can be served.
+ *
+ * @param options - Declarations, config, pre-built runtimes
+ */
+export async function bootApplication(
+  options: BootOptions = {},
+): Promise<BootResult> {
+  const env: ConfigEnv = options.env ?? "dev";
+  const pre = options.elements ?? {};
+  const now = options.now ?? (() => Date.now());
+
+  // 1. Vault boot — resolve every declared secret; list all gaps at once.
+  const vaultSecrets =
+    options.vault?.secrets ?? options.secrets ?? [];
+  let vault = pre.vault;
+  if (!vault && vaultSecrets.length > 0) {
+    vault = createVaultRuntime({
+      secrets: vaultSecrets,
+      chain: options.vault?.chain ?? [
+        {
+          driver: memoryVaultDriver,
+          options: { secrets: {} },
+        },
+      ],
+      allowDevFallbacks:
+        options.vault?.allowDevFallbacks ?? env !== "prod",
+    });
+  }
+  if (vault && !vault.booted) {
+    await vault.boot();
+  }
+
+  // 2. Bind store drivers per environment; open connections.
+  let store = pre.store;
+  if (!store) {
+    const sqlId =
+      resolveDriverId(options.config?.drivers?.store?.sql, env) ?? "memory";
+    const kvId =
+      resolveDriverId(options.config?.drivers?.store?.kv, env) ?? "memory";
+    // Protocol ids → memory bundle for test/dev when not otherwise injected.
+    void sqlId;
+    void kvId;
+    store = createStoreRuntime({
+      drivers: {
+        sql: memoryDrivers.sql,
+        kv: memoryDrivers.kv,
+        files: memoryDrivers.files,
+        index: memoryDrivers.index,
+      },
+      now,
+    });
+  }
+  for (const decl of options.stores ?? []) {
+    store.register?.(decl);
+  }
+
+  // 3. Register signals; start consumers.
+  let signal = pre.signal;
+  if (!signal) {
+    const signalId =
+      resolveDriverId(options.config?.drivers?.signal, env) ?? "memory";
+    void signalId;
+    signal = createSignalRuntime({
+      driver: memorySignalDriver,
+      now,
+    });
+  }
+  for (const decl of options.signals ?? []) {
+    signal.register(decl);
+  }
+  // Also register signal-as-trigger names from bindings.
+  for (const b of options.bindings ?? []) {
+    if (b.trigger.kind === "signal") {
+      if (!signal.declarations.has(b.trigger.name)) {
+        // Minimal decl so the bus knows the name; optional to avoid orphan fail.
+        signal.register({
+          name: b.trigger.name,
+          delivery: "once",
+          retries: 3,
+          deadLetter: true,
+          optional: true,
+        });
+      }
+    }
+  }
+  const bus = await signal.start();
+
+  if (options.onSignal) {
+    const handler = options.onSignal;
+    const seen = new Set<string>();
+    for (const b of options.bindings ?? []) {
+      if (b.trigger.kind !== "signal") continue;
+      const name = b.trigger.name;
+      if (seen.has(name)) continue;
+      seen.add(name);
+      await bus.subscribe(name, `oke:${name}`, async (msg) => {
+        await handler(name, msg.payload);
+      });
+    }
+  }
+
+  // 4. Reconcile clocks into the store; start scheduler with leader election.
+  const clockDriver =
+    resolveDriverId(options.config?.drivers?.clock, env) ??
+    (env === "test" ? "frozen" : "memory");
+  let clock = pre.clock;
+  if (!clock) {
+    clock =
+      clockDriver === "frozen" || env === "test"
+        ? createTestClockRuntime(now(), { instanceId: options.instanceId })
+        : createClockRuntime({ instanceId: options.instanceId, now });
+  }
+
+  const clockDecls = new Map<string, ClockDecl>();
+  for (const c of options.clocks ?? []) {
+    clockDecls.set(c.name, c);
+  }
+  // every("1h") bindings → named clocks the scheduler can fire.
+  for (const b of options.bindings ?? []) {
+    if (b.trigger.kind === "every" && !clockDecls.has(b.trigger.interval)) {
+      clockDecls.set(
+        b.trigger.interval,
+        declareClock(b.trigger.interval, { every: b.trigger.interval }),
+      );
+    }
+  }
+  for (const decl of clockDecls.values()) {
+    clock.register(decl);
+  }
+  await clock.reconcile();
+
+  if (options.onCronFire) {
+    const fire = options.onCronFire;
+    for (const name of clockDecls.keys()) {
+      clock.onCron(name, async () => {
+        await fire(name);
+      });
+    }
+  }
+
+  // Default ON outside test — a declared every()/cron must fire with zero
+  // further application calls (Clock element's core promise).
+  const startScheduler =
+    options.startScheduler ?? (env !== "test");
+  let schedulerTimer: ReturnType<typeof setInterval> | undefined;
+  if (startScheduler) {
+    const period = options.schedulerIntervalMs ?? 1000;
+    schedulerTimer = setInterval(() => {
+      void clock!.tick();
+    }, period);
+    // Don't keep the process alive solely for the scheduler in tests.
+    schedulerTimer.unref?.();
+  }
+
+  // Gate runtime (needs kv from store drivers) — used by the request
+  // pipeline and AI agents. Constructed before channel/AI bind.
+  let gate = pre.gate;
+  if (!gate) {
+    const kvNs = await memoryDrivers.kv.open({ name: "oke:gates" });
+    gate = createGateRuntime({
+      gates: options.gates ?? [],
+      kv: kvNs,
+      now,
+    });
+  }
+
+  // 5. Bind channel runtime.
+  let channel = pre.channel;
+  if (!channel) {
+    channel = createChannelRuntime({
+      ...(options.channel ?? {}),
+      drivers: options.channel?.drivers ?? [openConsoleChannel()],
+      now,
+    });
+  }
+
+  // 6. Bind AI runtime (shares the gate runtime for agent tool checks).
+  let ai = pre.ai;
+  if (!ai) {
+    ai = createAiRuntime({
+      ...(options.ai ?? {}),
+      defaultDriver: options.ai?.defaultDriver ?? mockAiDriver,
+      gates: options.ai?.gates ?? gate,
+      now,
+    });
+  }
+
+  // 7. Open the runs store.
+  let runs = pre.runs;
+  if (!runs) {
+    if (options.runs && isRunsRuntime(options.runs)) {
+      runs = options.runs;
+    } else {
+      const runsOpts =
+        options.runs && !isRunsRuntime(options.runs)
+          ? options.runs
+          : undefined;
+      runs = createRunsRuntime({
+        driver: runsOpts?.driver ?? memoryRunsDriver,
+        ...(runsOpts ?? {}),
+      });
+    }
+  }
+  if (runs && !runs.store) {
+    await runs.open();
+  }
+
+  // 8. Mint per-flow capability tokens from declared effects (Manifest).
+  const capabilities = mintCapabilities(options.flows ?? []);
+
+  return {
+    vault,
+    store,
+    signal,
+    clock,
+    gate,
+    channel,
+    ai,
+    runs,
+    capabilities,
+    stopScheduler() {
+      if (schedulerTimer !== undefined) {
+        clearInterval(schedulerTimer);
+        schedulerTimer = undefined;
+      }
+    },
+    async close() {
+      if (schedulerTimer !== undefined) {
+        clearInterval(schedulerTimer);
+        schedulerTimer = undefined;
+      }
+      await signal?.close();
+      await vault?.close();
+      await runs?.flush();
+    },
+  };
+}
+
+/**
+ * Mint capability tokens from each flow's declared effects.
+ * Tokens come from the Manifest / flow contract — never hand-passed sets.
+ *
+ * @param flows - Adopted flows
+ */
+export function mintCapabilities(
+  flows: readonly AnyFlowDef[],
+): Map<string, CapabilityToken> {
+  const map = new Map<string, CapabilityToken>();
+  for (const f of flows) {
+    map.set(f.name, createCapabilityToken(f.name, f.effects));
+  }
+  return map;
+}
+
+function isRunsRuntime(
+  value: RunsRuntime | CreateRunsRuntimeOptions,
+): value is RunsRuntime {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "record" in value &&
+    typeof (value as RunsRuntime).record === "function"
+  );
+}