okengine 0.1.4 → 0.2.1

package/src/console/server/store.ts

@@ -467,6 +467,18 @@ export interface StoreEditInput {
   readonly confirmed?: boolean;
 }
 
+/** Result of a direct store edit (preview or applied). */
+export interface StoreEditResult {
+  readonly ok: true;
+  readonly dryRun: boolean;
+  readonly willNotFire: ConsoleWillNotFire;
+  readonly applied: boolean;
+  readonly wouldHaveFired: ReadonlyArray<{
+    readonly kind: "send" | "ask";
+    readonly resource: string;
+  }>;
+}
+
 /**
  * Preview or apply a direct row/key edit. Direct edit is NOT a flow execution.
  *
@@ -483,16 +495,7 @@ export async function editStore(
     readonly production: boolean;
     readonly dryRun?: boolean;
   },
-): Promise<{
-  readonly ok: true;
-  readonly dryRun: boolean;
-  readonly willNotFire: ConsoleWillNotFire;
-  readonly applied: boolean;
-  readonly wouldHaveFired: ReadonlyArray<{
-    readonly kind: "send" | "ask";
-    readonly resource: string;
-  }>;
-}> {
+): Promise<StoreEditResult> {
   const effectRef = (
     input.child && input.ref.startsWith("sql:")
       ? `sql:${input.child}`

package/src/drivers/index.ts

@@ -2,6 +2,7 @@
  * Protocol-named drivers, tree-shaken by the Manifest.
  *
  * Subpath: `okengine/drivers/*`
+ * @module
  */
 
 export type {
@@ -115,12 +116,7 @@ export {
   createSignalNatsFake,
 } from "./signal-nats.ts";
 
-export {
-  runSqlConformance,
-  runKvConformance,
-  runFilesConformance,
-  runIndexConformance,
-} from "./conformance.ts";
+// Conformance helpers are test-only — import from `okengine/drivers/conformance`.
 
 export type {
   VaultDriverId,

package/src/drivers/vault-sops.ts

@@ -3,15 +3,32 @@
  *
  * Pure TypeScript, in-process. No Go `sops` / `age` binary.
  * Decrypts the SOPS data key with age, then AES-256-GCM value payloads.
+ *
+ * `age-encryption` is an optional peer — loaded only when this driver runs.
  */
 
-import * as age from "age-encryption";
 import type {
   VaultBag,
   VaultDriver,
   VaultOpenOptions,
 } from "./vault-types.ts";
 
+/** Minimal Typage surface used by this driver. */
+type AgeModule = typeof import("age-encryption");
+
+/**
+ * Lazy-load Typage so apps that never open a sops vault skip the dependency.
+ */
+async function loadAge(): Promise<AgeModule> {
+  try {
+    return await import("age-encryption");
+  } catch {
+    throw new Error(
+      "sops vault: install optional peer `age-encryption` (bun add age-encryption)",
+    );
+  }
+}
+
 /** SOPS metadata block. */
 interface SopsMeta {
   readonly age?: ReadonlyArray<{
@@ -109,6 +126,7 @@ async function decryptDataKey(
   identity: string,
   encBlock: string,
 ): Promise<Uint8Array> {
+  const age = await loadAge();
   const d = new age.Decrypter();
   d.addIdentity(identity.trim());
   const trimmed = encBlock.trim();
@@ -182,6 +200,7 @@ export async function buildSopsFixture(
   recipient: string,
   dataKey?: Uint8Array,
 ): Promise<{ json: string; dataKey: Uint8Array }> {
+  const age = await loadAge();
   const key = dataKey ?? crypto.getRandomValues(new Uint8Array(32));
   const e = new age.Encrypter();
   e.addRecipient(recipient);

package/src/elements/ai.ts

@@ -9,6 +9,7 @@
  * (`oke eval` gates CI). Agents' tools are the app's own flows (gates apply).
  * PII fields cannot reach a third-party model without explicit `allowPii`.
  * Nondeterministic ⇒ journaling forced, auto-cache disabled.
+ * @module
  */
 
 export { ai } from "./ai/declare.ts";

package/src/elements/channel.ts

@@ -8,6 +8,7 @@
  * MIME, attachments, retry, and the unified error hierarchy come from sently.
  * OKE adds: declared templates with i18n, consent/opt-out, fallback chains
  * recorded as chains, and delivery receipts.
+ * @module
  */
 
 export { channel } from "./channel/declare.ts";

package/src/elements/clock.ts

@@ -7,6 +7,7 @@
  * Durability lives on the Flow (`durable: true`); the journal records every
  * `fx` call. Crons leader-elect; schedules are reconciled into the Store at
  * boot (console §5).
+ * @module
  */
 
 export { clock } from "./clock/declare.ts";

package/src/elements/gate.ts

@@ -5,6 +5,7 @@
  * Rate strategies are atomic Lua on the kv driver.
  *
  * Drivers: inherits `store.kv` (`memory` · `redis`).
+ * @module
  */
 
 export { gate } from "./gate/declare.ts";

package/src/elements/signal.ts

@@ -3,6 +3,7 @@
  *
  * Delivery physics: `once` · `broadcast` · `live` (mandatory, no default).
  * Drivers: `memory` · `postgres` (default / transactional) · `redis` · `nats`.
+ * @module
  */
 
 export { signal } from "./signal/declare.ts";

package/src/elements/store.ts

@@ -5,6 +5,7 @@
  * Drivers are protocol-named and live under `src/drivers/*`.
  * All world access still goes through `fx`; this module only declares
  * resources and provides runtime helpers (cache, replica routing, PII).
+ * @module
  */
 
 export { store, sql, kv, files, index } from "./store/declare.ts";

package/src/elements/vault.ts

@@ -7,6 +7,7 @@
  * A declaration is a contract, never a value. Boot validates every contract
  * and lists all gaps at once. Logs/traces receive fingerprints and redaction
  * registered at boot — cleartext never appears even when passed to `fx.log`.
+ * @module
  */
 
 export {

package/src/index.ts

@@ -3,6 +3,15 @@
  *
  * Full ten-export surface lands as elements ship; this entry exposes the
  * executable core (oke · on · flow · http · fx · contracts).
+ *
+ * @example
+ * ```ts
+ * import { oke, on, flow, http } from "okengine";
+ *
+ * export const app = oke({ name: "notes" });
+ * ```
+ *
+ * @module
  */
 
 export {

package/src/kernel/app.ts

@@ -22,7 +22,7 @@ import {
 // `./boot.ts` pulls in every element + driver module (vault, store, signal,
 // clock, gate, channel, ai, runs) — a type-only import here keeps that whole
 // graph out of the cold-start path; `doBoot` below loads it lazily, only
-// when an app actually boots (AGENTS.md budget: cold start < 75 ms).
+// when an app actually boots (AGENTS.md / unified-theory budget: cold start < 75 ms).
 import type { BootOptions, BootResult, ElementRuntimes } from "./boot.ts";
 import type { CapabilityToken } from "./capability.ts";
 import {

package/src/kernel/boot-bind/ai.ts

@@ -0,0 +1,31 @@
+/**
+ * Lazy AI binder — loaded only when AI is declared.
+ */
+
+import { mockAiDriver } from "../../drivers/ai-mock.ts";
+import {
+  createAiRuntime,
+  type AiRuntime,
+} from "../../elements/ai.ts";
+import type { GateRuntime } from "../../elements/gate.ts";
+import type { BootOptions } from "../boot.ts";
+
+/**
+ * Construct an AI runtime (mock default; shares gate for agents).
+ *
+ * @param options - Boot options
+ * @param gate - Gate runtime for agent tool checks
+ * @param now - Clock
+ */
+export function bindAi(
+  options: BootOptions,
+  gate: GateRuntime | undefined,
+  now: () => number,
+): AiRuntime {
+  return createAiRuntime({
+    ...(options.ai ?? {}),
+    defaultDriver: options.ai?.defaultDriver ?? mockAiDriver,
+    gates: options.ai?.gates ?? gate,
+    now,
+  });
+}

package/src/kernel/boot-bind/channel.ts

@@ -0,0 +1,27 @@
+/**
+ * Lazy channel binder — loaded only when Channel is declared.
+ */
+
+import { openConsoleChannel } from "../../drivers/channel-console.ts";
+import {
+  createChannelRuntime,
+  type ChannelRuntime,
+} from "../../elements/channel.ts";
+import type { BootOptions } from "../boot.ts";
+
+/**
+ * Construct a Channel runtime (console inbox default).
+ *
+ * @param options - Boot options
+ * @param now - Clock
+ */
+export function bindChannel(
+  options: BootOptions,
+  now: () => number,
+): ChannelRuntime {
+  return createChannelRuntime({
+    ...(options.channel ?? {}),
+    drivers: options.channel?.drivers ?? [openConsoleChannel()],
+    now,
+  });
+}

package/src/kernel/boot-bind/clock.ts

@@ -0,0 +1,74 @@
+/**
+ * Lazy clock binder — loaded only when Clock is declared.
+ */
+
+import {
+  clock as declareClock,
+  createClockRuntime,
+  createTestClockRuntime,
+  type ClockDecl,
+  type ClockRuntime,
+} from "../../elements/clock.ts";
+import {
+  resolveDriverId,
+  type ConfigEnv,
+} from "../../config/index.ts";
+import type { BootOptions } from "../boot.ts";
+
+/** Result of binding a clock runtime. */
+export interface BindClockResult {
+  readonly clock: ClockRuntime;
+  readonly clockDecls: ReadonlyMap<string, ClockDecl>;
+}
+
+/**
+ * Construct / adopt a Clock runtime, register decls, reconcile.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param now - Clock
+ * @param prebuilt - Optional injected runtime
+ */
+export async function bindClock(
+  options: BootOptions,
+  env: ConfigEnv,
+  now: () => number,
+  prebuilt?: ClockRuntime,
+): Promise<BindClockResult> {
+  const clockDriver =
+    resolveDriverId(options.config?.drivers?.clock, env) ??
+    (env === "test" ? "frozen" : "memory");
+  const clock =
+    prebuilt ??
+    (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);
+  }
+  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);
+      });
+    }
+  }
+
+  return { clock, clockDecls };
+}

package/src/kernel/boot-bind/gate.ts

@@ -0,0 +1,28 @@
+/**
+ * Lazy gate binder — loaded only when Gate is declared (or required by AI).
+ */
+
+import { memoryDrivers } from "../../drivers/memory.ts";
+import {
+  createGateRuntime,
+  type GateRuntime,
+} from "../../elements/gate.ts";
+import type { BootOptions } from "../boot.ts";
+
+/**
+ * Construct a Gate runtime backed by a memory kv namespace.
+ *
+ * @param options - Boot options
+ * @param now - Clock
+ */
+export async function bindGate(
+  options: BootOptions,
+  now: () => number,
+): Promise<GateRuntime> {
+  const kvNs = await memoryDrivers.kv.open({ name: "oke:gates" });
+  return createGateRuntime({
+    gates: options.gates ?? [],
+    kv: kvNs,
+    now,
+  });
+}

package/src/kernel/boot-bind/runs.ts

@@ -0,0 +1,28 @@
+/**
+ * Lazy runs binder — loaded only when runs are requested.
+ */
+
+import {
+  createRunsRuntime,
+  memoryRunsDriver,
+  type CreateRunsRuntimeOptions,
+  type RunsRuntime,
+} from "../../runs/index.ts";
+
+/**
+ * Construct and open a runs runtime.
+ *
+ * @param options - Create options (when not already a runtime)
+ */
+export async function bindRuns(
+  options?: CreateRunsRuntimeOptions,
+): Promise<RunsRuntime> {
+  const runs = createRunsRuntime({
+    driver: options?.driver ?? memoryRunsDriver,
+    ...(options ?? {}),
+  });
+  if (!runs.store) {
+    await runs.open();
+  }
+  return runs;
+}

package/src/kernel/boot-bind/signal.ts

@@ -0,0 +1,68 @@
+/**
+ * Lazy signal binder — loaded only when Signal is declared.
+ */
+
+import { memorySignalDriver } from "../../drivers/signal-memory.ts";
+import {
+  createSignalRuntime,
+  type SignalRuntime,
+} from "../../elements/signal.ts";
+import {
+  resolveDriverId,
+  type ConfigEnv,
+} from "../../config/index.ts";
+import type { BootOptions } from "../boot.ts";
+
+/**
+ * Construct a Signal runtime, register decls / binding names, start the bus.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param now - Clock
+ */
+export async function bindSignal(
+  options: BootOptions,
+  env: ConfigEnv,
+  now: () => number,
+): Promise<SignalRuntime> {
+  const signalId =
+    resolveDriverId(options.config?.drivers?.signal, env) ?? "memory";
+  void signalId;
+  const signal = createSignalRuntime({
+    driver: memorySignalDriver,
+    now,
+  });
+  for (const decl of options.signals ?? []) {
+    signal.register(decl);
+  }
+  for (const b of options.bindings ?? []) {
+    if (b.trigger.kind === "signal") {
+      if (!signal.declarations.has(b.trigger.name)) {
+        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);
+      });
+    }
+  }
+
+  return signal;
+}

package/src/kernel/boot-bind/store.ts

@@ -0,0 +1,47 @@
+/**
+ * Lazy store binder — loaded only when Store is declared.
+ */
+
+import { memoryDrivers } from "../../drivers/memory.ts";
+import {
+  createStoreRuntime,
+  type StoreRuntime,
+} from "../../elements/store.ts";
+import {
+  resolveDriverId,
+  type ConfigEnv,
+} from "../../config/index.ts";
+import type { BootOptions } from "../boot.ts"; // type-only — no cycle at runtime
+
+/**
+ * Construct a Store runtime and register facet declarations.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ * @param now - Clock
+ */
+export function bindStore(
+  options: BootOptions,
+  env: ConfigEnv,
+  now: () => number,
+): StoreRuntime {
+  const sqlId =
+    resolveDriverId(options.config?.drivers?.store?.sql, env) ?? "memory";
+  const kvId =
+    resolveDriverId(options.config?.drivers?.store?.kv, env) ?? "memory";
+  void sqlId;
+  void kvId;
+  const 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);
+  }
+  return store;
+}

package/src/kernel/boot-bind/vault.ts

@@ -0,0 +1,36 @@
+/**
+ * Lazy vault binder — loaded only when secrets are declared.
+ */
+
+import { memoryVaultDriver } from "../../drivers/vault-memory.ts";
+import {
+  createVaultRuntime,
+  type VaultRuntime,
+} from "../../elements/vault.ts";
+import type { ConfigEnv } from "../../config/index.ts";
+import type { BootOptions } from "../boot.ts";
+
+/**
+ * Construct and boot a Vault runtime from BootOptions.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export async function bindVault(
+  options: BootOptions,
+  env: ConfigEnv,
+): Promise<VaultRuntime> {
+  const vaultSecrets = options.vault?.secrets ?? options.secrets ?? [];
+  const vault = createVaultRuntime({
+    secrets: vaultSecrets,
+    chain: options.vault?.chain ?? [
+      {
+        driver: memoryVaultDriver,
+        options: { secrets: {} },
+      },
+    ],
+    allowDevFallbacks: options.vault?.allowDevFallbacks ?? env !== "prod",
+  });
+  await vault.boot();
+  return vault;
+}

package/src/kernel/boot.test.ts

@@ -7,10 +7,14 @@
  */
 
 import { afterEach, describe, expect, jest, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { memoryVaultDriver } from "../drivers/index.ts";
 import { clock } from "../elements/clock.ts";
+import { store } from "../elements/store.ts";
 import { vault, VaultBootError } from "../elements/vault.ts";
-import { bootApplication } from "./boot.ts";
+import { bootApplication, resolveElementNeeds } from "./boot.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
 import { every, http } from "./triggers.ts";
 import { oke } from "./app.ts";
@@ -42,6 +46,86 @@ describe("boot — vault gaps", () => {
       expect(boot.message).toContain("DATABASE_URL");
     }
   });
+
+  test("three missing secrets still list every gap at once", async () => {
+    try {
+      await bootApplication({
+        env: "prod",
+        secrets: [
+          vault("A", { description: "one" }),
+          vault("B", { description: "two" }),
+          vault("C", { description: "three" }),
+        ],
+        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(["A", "B", "C"]);
+    }
+  });
+});
+
+describe("boot — lazy element needs", () => {
+  test("Store-only declarations do not require AI/channel/vault", () => {
+    const needs = resolveElementNeeds({
+      stores: [store.sql("notes", { schema: {} as never })],
+    });
+    expect(needs.store).toBe(true);
+    expect(needs.ai).toBe(false);
+    expect(needs.channel).toBe(false);
+    expect(needs.vault).toBe(false);
+    expect(needs.signal).toBe(false);
+  });
+
+  test("oke() Store-only graph stays under the prior 41.4 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");
+    const storePath = join(import.meta.dir, "../elements/store.ts");
+    await Bun.write(
+      entry,
+      `import { oke } from ${JSON.stringify(appPath)};\n` +
+        `import { store } from ${JSON.stringify(storePath)};\n` +
+        `export const app = oke({ name: "notes" });\n` +
+        `export { store };\n`,
+    );
+    try {
+      const result = await Bun.build({
+        entrypoints: [entry],
+        minify: true,
+        target: "bun",
+        format: "esm",
+        external: [
+          "@duckdb/node-api",
+          "@duckdb/*",
+          "age-encryption",
+          "sently",
+          "sently/*",
+          "ajv",
+          "ajv/*",
+          "ajv-formats",
+          "oxc-parser",
+          "zod",
+        ],
+      });
+      expect(result.success).toBe(true);
+      let total = 0;
+      for (const o of result.outputs) {
+        const raw = await o.arrayBuffer();
+        if (raw.byteLength === 0) continue;
+        total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
+      }
+      // Prior eager-bind baseline: ~41.4 kB for oke() alone.
+      expect(total).toBeLessThan(41_400);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("boot — capabilities from Manifest effects", () => {