okengine 0.1.4

package/src/elements/vault.test.ts

@@ -0,0 +1,296 @@
+/**
+ * Vault element acceptance:
+ * - a missing secret fails boot listing every gap
+ * - a secret value never appears in a log or trace even when passed to fx.log
+ * - fingerprints instead of values
+ * - resolution chain (first hit wins)
+ * - sops/age via Typage (in-process, no Go binary)
+ */
+
+import { describe, expect, test } from "bun:test";
+import * as age from "age-encryption";
+import {
+  buildSopsFixture,
+  envVaultDriver,
+  memoryVaultDriver,
+  sopsVaultDriver,
+} from "../drivers/index.ts";
+import { createFx } from "../kernel/fx.ts";
+import {
+  createVaultRuntime,
+  fingerprintSecretSync,
+  SECRET_MASK,
+  vault,
+  VaultBootError,
+} from "./vault.ts";
+
+describe("vault declaration", () => {
+  test("vault() and vault.secret() shapes", () => {
+    const a = vault("STRIPE_KEY", {
+      description: "Payments gateway key",
+      rotate: "90d",
+    });
+    expect(a.kind).toBe("secret");
+    expect(a.sensitive).toBe(true);
+    expect(a.name).toBe("STRIPE_KEY");
+    expect(a.description).toBe("Payments gateway key");
+
+    const b = vault.secret("DATABASE_URL", { dev: "postgres://local" });
+    expect(b.name).toBe("DATABASE_URL");
+    expect(b.dev).toBe("postgres://local");
+
+    const cfg = vault.config("PUBLIC_APP_URL", { dev: "http://localhost" });
+    expect(cfg.kind).toBe("config");
+    expect(cfg.sensitive).toBe(false);
+
+    const fromStack = vault.fromStack("store.sql");
+    expect(fromStack).toStartWith("__oke_from_stack__:");
+    const c = vault.secret("DATABASE_URL", { dev: fromStack });
+    expect(c.dev).toBe(fromStack);
+  });
+
+  test("fromStack resolves via OKE_<ROLE>_URL without env-var names in the kernel", async () => {
+    const prev = process.env.OKE_STORE_SQL_URL;
+    process.env.OKE_STORE_SQL_URL = "postgres://oke:x@127.0.0.1:5432/oke";
+    try {
+      const runtime = createVaultRuntime({
+        secrets: [
+          vault.secret("DATABASE_URL", { dev: vault.fromStack("store.sql") }),
+        ],
+        chain: [],
+        allowDevFallbacks: true,
+      });
+      await runtime.boot();
+      expect(runtime.read("DATABASE_URL")).toBe(
+        "postgres://oke:x@127.0.0.1:5432/oke",
+      );
+    } finally {
+      if (prev === undefined) delete process.env.OKE_STORE_SQL_URL;
+      else process.env.OKE_STORE_SQL_URL = prev;
+    }
+  });
+});
+
+describe("boot lists every missing secret", () => {
+  test("VaultBootError enumerates all gaps at once", async () => {
+    const runtime = createVaultRuntime({
+      secrets: [
+        vault("STRIPE_KEY", { description: "Payments gateway key" }),
+        vault("DATABASE_URL", { description: "Primary SQL URL" }),
+        vault("PRESENT"),
+      ],
+      chain: [
+        {
+          driver: memoryVaultDriver,
+          options: { secrets: { PRESENT: "yes" } },
+        },
+      ],
+    });
+
+    try {
+      await runtime.boot();
+      expect.unreachable("boot should fail");
+    } catch (err) {
+      expect(err).toBeInstanceOf(VaultBootError);
+      const boot = err as VaultBootError;
+      expect(boot.gaps).toHaveLength(2);
+      expect(boot.gaps.map((g) => g.name).sort()).toEqual([
+        "DATABASE_URL",
+        "STRIPE_KEY",
+      ]);
+      expect(boot.message).toContain("STRIPE_KEY");
+      expect(boot.message).toContain("Payments gateway key");
+      expect(boot.message).toContain("DATABASE_URL");
+      expect(boot.message).toContain("2 missing");
+    }
+  });
+
+  test("dev fallbacks fill gaps when allowDevFallbacks", async () => {
+    const runtime = createVaultRuntime({
+      secrets: [vault("STRIPE_KEY", { dev: "sk_test_local" })],
+      chain: [],
+      allowDevFallbacks: true,
+    });
+    await runtime.boot();
+    expect(runtime.read("STRIPE_KEY")).toBe("sk_test_local");
+  });
+});
+
+describe("resolution chain", () => {
+  test("first layer wins", async () => {
+    const runtime = createVaultRuntime({
+      secrets: [vault("KEY")],
+      chain: [
+        {
+          driver: memoryVaultDriver,
+          source: "process.env",
+          options: { secrets: { KEY: "from-a" } },
+        },
+        {
+          driver: memoryVaultDriver,
+          source: "driver",
+          options: { secrets: { KEY: "from-b" } },
+        },
+      ],
+    });
+    await runtime.boot();
+    expect(runtime.read("KEY")).toBe("from-a");
+    expect(runtime.resolution("KEY")).toBe("process.env");
+    const chain = runtime.resolutionChain("KEY");
+    expect(chain.find((s) => s.source === "process.env")?.won).toBe(true);
+    expect(chain.find((s) => s.source === "driver")?.present).toBe(true);
+    expect(chain.find((s) => s.source === "driver")?.won).toBe(false);
+  });
+
+  test("env layer resolves process env", async () => {
+    const runtime = createVaultRuntime({
+      secrets: [vault("OKE_TEST_SECRET")],
+      chain: [
+        {
+          driver: envVaultDriver,
+          source: "process.env",
+          options: { env: { OKE_TEST_SECRET: "from-env" } },
+        },
+      ],
+    });
+    await runtime.boot();
+    expect(runtime.read("OKE_TEST_SECRET")).toBe("from-env");
+    expect(runtime.resolution("OKE_TEST_SECRET")).toBe("process.env");
+  });
+
+  test("last-read timestamp updates on read", async () => {
+    let now = 1000;
+    const runtime = createVaultRuntime({
+      secrets: [vault("KEY")],
+      chain: [
+        {
+          driver: memoryVaultDriver,
+          options: { secrets: { KEY: "v" } },
+        },
+      ],
+      now: () => now,
+    });
+    await runtime.boot();
+    expect(runtime.lastReadAt("KEY")).toBeUndefined();
+    runtime.read("KEY");
+    expect(runtime.lastReadAt("KEY")).toBe(1000);
+    now = 2000;
+    runtime.read("KEY");
+    expect(runtime.lastReadAt("KEY")).toBe(2000);
+  });
+
+  test("config cleartext is exposed; secrets are not", async () => {
+    const runtime = createVaultRuntime({
+      secrets: [
+        vault.secret("STRIPE_KEY"),
+        vault.config("PUBLIC_URL"),
+      ],
+      chain: [
+        {
+          driver: memoryVaultDriver,
+          options: {
+            secrets: {
+              STRIPE_KEY: "sk_secret",
+              PUBLIC_URL: "https://example.com",
+            },
+          },
+        },
+      ],
+    });
+    await runtime.boot();
+    expect(runtime.cleartext("STRIPE_KEY")).toBeUndefined();
+    expect(runtime.cleartext("PUBLIC_URL")).toBe("https://example.com");
+    expect(runtime.fingerprint("STRIPE_KEY")).toBeDefined();
+    expect(runtime.fingerprint("PUBLIC_URL")).toBeUndefined();
+  });
+});
+
+describe("redaction + fingerprints", () => {
+  test("secret value never appears in fx.log even when passed explicitly", async () => {
+    const secret = "sk_live_super_secret_value_do_not_leak";
+    const runtime = createVaultRuntime({
+      secrets: [vault("STRIPE_KEY")],
+      chain: [
+        { driver: memoryVaultDriver, options: { secrets: { STRIPE_KEY: secret } } },
+      ],
+    });
+    await runtime.boot();
+
+    const lines: Array<{ message: string; data?: Record<string, unknown> }> =
+      [];
+    const { fx } = createFxContextWithVault(runtime, lines);
+
+    const value = fx.vault("STRIPE_KEY");
+    expect(value).toBe(secret);
+
+    fx.log.info(`charging with ${value}`, { key: value, nested: { k: value } });
+    fx.log.error(secret, { stripe: secret });
+
+    for (const line of lines) {
+      expect(line.message).not.toContain(secret);
+      expect(JSON.stringify(line.data ?? {})).not.toContain(secret);
+      expect(line.message).toContain(SECRET_MASK);
+    }
+  });
+
+  test("fingerprint is stable and not the value", async () => {
+    const secret = "sk_test_abc";
+    const runtime = createVaultRuntime({
+      secrets: [vault("STRIPE_KEY")],
+      chain: [
+        {
+          driver: memoryVaultDriver,
+          options: { secrets: { STRIPE_KEY: secret } },
+        },
+      ],
+    });
+    await runtime.boot();
+    const fp = runtime.fingerprint("STRIPE_KEY");
+    expect(fp).toBe(fingerprintSecretSync(secret));
+    expect(fp).not.toContain(secret);
+    expect(fp?.startsWith("sha256:")).toBe(true);
+  });
+});
+
+describe("sops / age (Typage)", () => {
+  test("decrypts SOPS JSON in-process with age-encryption", async () => {
+    const identity = await age.generateIdentity();
+    const recipient = await age.identityToRecipient(identity);
+    const { json } = await buildSopsFixture(
+      { STRIPE_KEY: "sk_sops_decrypted" },
+      recipient,
+    );
+
+    const runtime = createVaultRuntime({
+      secrets: [vault("STRIPE_KEY")],
+      chain: [
+        {
+          driver: sopsVaultDriver,
+          options: { ciphertext: json, ageIdentity: identity },
+        },
+      ],
+    });
+    await runtime.boot();
+    expect(runtime.read("STRIPE_KEY")).toBe("sk_sops_decrypted");
+  });
+});
+
+/**
+ * Helper — createFx with vault runtime + log sink.
+ */
+function createFxContextWithVault(
+  vaultRuntime: Awaited<ReturnType<typeof createVaultRuntime>>,
+  lines: Array<{ message: string; data?: Record<string, unknown> }>,
+) {
+  return {
+    fx: createFx({
+      flow: "payments.charge",
+      effects: { secrets: ["STRIPE_KEY"] },
+      vaultRuntime,
+      onLog(level, message, data) {
+        void level;
+        lines.push({ message, data });
+      },
+    }),
+  };
+}

package/src/elements/vault.ts

@@ -0,0 +1,44 @@
+/**
+ * Vault element — protected knowledge.
+ *
+ * Physics: secrets · config · environment.
+ * Drivers: `sops` (Typage/age) · `env` · `openbao` · `infisical` · `managed`.
+ *
+ * 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`.
+ */
+
+export {
+  vault,
+  fromStack,
+  FROM_STACK_PREFIX,
+  isFromStack,
+  fromStackRole,
+} from "./vault/declare.ts";
+export type {
+  VaultSecretDecl,
+  VaultSecretOptions,
+} from "./vault/declare.ts";
+
+export {
+  createVaultRuntime,
+  VaultBootError,
+  SECRET_MASK,
+  resolveLayerSource,
+} from "./vault/runtime.ts";
+export type {
+  CreateVaultRuntimeOptions,
+  VaultChainLayer,
+  VaultGap,
+  VaultResolutionSource,
+  VaultResolutionStep,
+  VaultRuntime,
+} from "./vault/runtime.ts";
+
+export {
+  fingerprintSecret,
+  fingerprintSecretSync,
+} from "./vault/fingerprint.ts";
+
+export { createSecretRedactor } from "./vault/redact.ts";

package/src/index.ts

@@ -0,0 +1,183 @@
+/**
+ * `okengine` public entry — kernel surface used by apps and examples.
+ *
+ * Full ten-export surface lands as elements ship; this entry exposes the
+ * executable core (oke · on · flow · http · fx · contracts).
+ */
+
+export {
+  oke,
+  on,
+  flow,
+  http,
+  every,
+  internal,
+  table,
+  fail,
+  createFx,
+  isFlow,
+  isFlowFailure,
+  plugin,
+  isPlugin,
+  bootApplication,
+  mintCapabilities,
+  gateDenialFailure,
+  journey,
+  unit,
+  rateLimit,
+  type OkeApp,
+  type OkeOptions,
+  type FlowDef,
+  type FlowFailure,
+  type FlowErrorValue,
+  type Fx,
+  type Binding,
+  type PluginDef,
+  type PluginCapabilities,
+  type BootOptions,
+  type BootResult,
+  type ElementRuntimes,
+  type JourneyDecl,
+  type UnitBag,
+} from "./kernel/index.ts";
+
+export {
+  store,
+  classify,
+  id,
+  now,
+  defineTable,
+  createStoreRuntime,
+  type StoreDecl,
+  type StoreRuntime,
+  type SqlStoreHandle,
+  type TableHandle,
+} from "./elements/store.ts";
+
+export {
+  signal,
+  createSignalRuntime,
+  type SignalDecl,
+  type SignalOptions,
+  type SignalRuntime,
+} from "./elements/signal.ts";
+
+export {
+  clock,
+  createClockRuntime,
+  createTestClockRuntime,
+  createTimeTravel,
+  runDurable,
+  reconcileClocks,
+  detectDstAmbiguity,
+  type ClockDecl,
+  type ClockRuntime,
+  type TimeTravel,
+  type DurableResult,
+} from "./elements/clock.ts";
+
+export {
+  gate,
+  createGateRuntime,
+  takeRate,
+  deriveModuleActions,
+  ALL_RATE_STRATEGIES,
+  type GateDecl,
+  type GateRuntime,
+  type RateOptions,
+} from "./elements/gate.ts";
+
+export {
+  vault,
+  fromStack,
+  FROM_STACK_PREFIX,
+  createVaultRuntime,
+  VaultBootError,
+  SECRET_MASK,
+  type VaultSecretDecl,
+  type VaultRuntime,
+} from "./elements/vault.ts";
+
+export {
+  channel,
+  createChannelRuntime,
+  createConsentStore,
+  createReceiptLedger,
+  type ChannelTemplateDecl,
+  type ChannelRuntime,
+} from "./elements/channel.ts";
+
+export {
+  ai,
+  createAiRuntime,
+  assertAllowPiiForAsk,
+  AiPiiBuildError,
+  AiSchemaValidationError,
+  runPromptEvals,
+  parseEvalJsonl,
+  type AiModelDecl,
+  type AiPromptDecl,
+  type AiAgentDecl,
+  type AiRuntime,
+} from "./elements/ai.ts";
+
+export {
+  createJournal,
+  createMemoryJournalStore,
+  createFileJournalStore,
+  type Journal,
+  type JournalStore,
+  type JournalRun,
+} from "./kernel/journal.ts";
+
+export {
+  validate,
+  isStandardSchema,
+  fromTypeBox,
+  VALIDATION_ERROR_CODE,
+  type StandardSchemaV1,
+  type SchemaInput,
+  type ValidationErrorData,
+} from "./validation/index.ts";
+
+export {
+  compileAot,
+  compileDynamic,
+  compileRoute,
+  sucrose,
+  type CompiledRoute,
+  type ContextInference,
+} from "./compiler/index.ts";
+
+export {
+  createBunRuntime,
+  createWebStandardRuntime,
+  APP_PORT,
+  CONSOLE_PORT,
+  MCP_PORT,
+  type Runtime,
+  type ServeOptions,
+} from "./runtime/index.ts";
+export {
+  createRunsRuntime,
+  collectWideEvent,
+  createRunTelemetry,
+  explainOutliers,
+  seedOutlierDataset,
+  privacyErase,
+  createMemorySubjectKeys,
+  subjectKeysFromVault,
+  archiveFields,
+  revealArchived,
+  eraseSubject,
+  SHREDDED,
+  filesRunsDriver,
+  memoryRunsDriver,
+  postgresRunsDriver,
+  clickhouseRunsDriver,
+  type RunsRuntime,
+  type WideEvent,
+  type CreateRunsRuntimeOptions,
+  type OutlierFinding,
+  type SubjectKeyVault,
+} from "./runs/index.ts";

package/src/kernel/adopt-routes.ts

@@ -0,0 +1,194 @@
+/**
+ * Type-level (and runtime) route accumulation for `.adopt({ notes })`.
+ *
+ * Registration still happens in {@link on}; adopt makes the composition root
+ * honest and stamps `$routes` so `typeof app` carries every flow contract.
+ */
+
+import type { InferSchemaOutput } from "../validation/standard-schema.ts";
+import type { AnyFlowDef, FlowDef, FlowErrorMap } from "./flow.ts";
+import { isFlow } from "./flow.ts";
+import type { HttpTrigger, Trigger } from "./triggers.ts";
+
+/**
+ * One flow's route contract on `app.$routes` (compatible with client
+ * {@link import("../client/types.ts").FlowContract}).
+ *
+ * `in` / `out` / `errors` are type-level phantoms (absent at runtime).
+ * `method` / `path` are present at runtime for HTTP triggers.
+ */
+export type AppFlowRoute<
+  I = unknown,
+  O = unknown,
+  E extends Record<string, unknown> = Record<string, unknown>,
+  M extends string | undefined = undefined,
+  P extends string | undefined = undefined,
+> = [M, P] extends [string, string]
+  ? {
+      readonly in?: I;
+      readonly out?: O;
+      readonly errors?: E;
+      readonly method: M;
+      readonly path: P;
+    }
+  : {
+      readonly in?: I;
+      readonly out?: O;
+      readonly errors?: E;
+      readonly method?: undefined;
+      readonly path?: undefined;
+    };
+
+/** Unit → flow → contract. */
+export type AppRouteMap = {
+  readonly [unit: string]: {
+    readonly [flow: string]: AppFlowRoute<any, any, any, any, any>;
+  };
+};
+
+/** Namespace object: export name → FlowDef (e.g. `import * as notes`). */
+export type FlowNamespace = {
+  readonly [flow: string]: AnyFlowDef;
+};
+
+/** One `.adopt(...)` argument — a namespace bag or a single untriggered flow. */
+export type AdoptArg = FlowNamespace | Record<string, FlowNamespace> | AnyFlowDef;
+
+/**
+ * Map error schemas to their validated output shapes for the client.
+ *
+ * @typeParam E - Flow error schema map
+ */
+export type ErrorDataOf<E extends FlowErrorMap> = {
+  [K in keyof E]: InferSchemaOutput<E[K]>;
+};
+
+/**
+ * Derive a client route contract from a {@link FlowDef} (trigger → REST).
+ *
+ * @typeParam F - Flow definition
+ */
+export type RouteFromFlow<F> = F extends FlowDef<
+  infer I,
+  infer O,
+  infer E,
+  any,
+  infer T
+>
+  ? [T] extends [HttpTrigger<infer M, infer P>]
+    ? AppFlowRoute<I, O, ErrorDataOf<E>, M, P>
+    : AppFlowRoute<I, O, ErrorDataOf<E>>
+  : never;
+
+/**
+ * Map a flow namespace (`{ create, get, … }`) to a unit route table.
+ *
+ * @typeParam N - Namespace of flows
+ */
+export type RoutesFromNamespace<N> = {
+  [F in keyof N]: N[F] extends AnyFlowDef ? RouteFromFlow<N[F]> : never;
+};
+
+/**
+ * Routes contributed by one `.adopt` argument.
+ *
+ * - `{ notes }` where `notes` is a flow namespace → `{ notes: { create, get, … } }`
+ * - A bare {@link FlowDef} → `{}` (fx.call only; no client unit)
+ *
+ * @typeParam A - Adopt argument
+ */
+export type RoutesFromAdoptArg<A> = A extends AnyFlowDef
+  ? {}
+  : A extends FlowNamespace
+    ? // Bare namespace without a unit key — not used; adopt always wraps `{ unit: ns }`
+      {}
+    : {
+        [U in keyof A]: A[U] extends AnyFlowDef
+          ? never
+          : A[U] extends Record<string, AnyFlowDef>
+            ? RoutesFromNamespace<A[U]>
+            : never;
+      };
+
+/**
+ * Merge route maps from a variadic `.adopt(...)` argument list.
+ *
+ * @typeParam Args - Adopt argument tuple
+ */
+export type RoutesFromAdoptArgs<Args extends readonly unknown[]> =
+  Args extends readonly []
+    ? {}
+    : Args extends readonly [infer H, ...infer T]
+      ? RoutesFromAdoptArg<H> & RoutesFromAdoptArgs<T>
+      : {};
+
+/** Runtime leaf: method/path when the flow has an HTTP trigger. */
+export interface RuntimeFlowRoute {
+  readonly method?: string;
+  readonly path?: string;
+}
+
+/** Runtime `$routes` table (values; types live on {@link OkeApp}). */
+export type RuntimeRouteMap = {
+  [unit: string]: {
+    [flow: string]: RuntimeFlowRoute;
+  };
+};
+
+/**
+ * Build a runtime route leaf from a flow's bound HTTP trigger.
+ *
+ * @param flowDef - Flow definition
+ */
+export function runtimeRouteFromFlow(flowDef: AnyFlowDef): RuntimeFlowRoute {
+  const trigger: Trigger | undefined =
+    flowDef.$trigger ?? flowDef.triggers[0];
+  if (trigger?.kind === "http") {
+    return { method: trigger.method, path: trigger.path };
+  }
+  return {};
+}
+
+/**
+ * Merge namespace objects into a runtime `$routes` map and collect flows.
+ *
+ * @param args - `.adopt` arguments
+ * @param into - Mutable route map to extend
+ * @returns Flows discovered (for `fx.call` registration)
+ */
+export function accumulateAdoptArgs(
+  args: readonly unknown[],
+  into: RuntimeRouteMap,
+): AnyFlowDef[] {
+  const found: AnyFlowDef[] = [];
+
+  for (const arg of args) {
+    if (isFlow(arg)) {
+      found.push(arg);
+      continue;
+    }
+    if (typeof arg !== "object" || arg === null) continue;
+
+    for (const [unit, value] of Object.entries(
+      arg as Record<string, unknown>,
+    )) {
+      if (isFlow(value)) {
+        // Flat `{ create: flow }` without a unit wrapper — skip client map
+        found.push(value);
+        continue;
+      }
+      if (typeof value !== "object" || value === null) continue;
+
+      const unitBag = into[unit] ?? (into[unit] = {});
+      for (const [flowName, flowDef] of Object.entries(
+        value as Record<string, unknown>,
+      )) {
+        if (!isFlow(flowDef)) continue;
+        found.push(flowDef);
+        unitBag[flowName] = runtimeRouteFromFlow(flowDef);
+      }
+    }
+  }
+
+  return found;
+}