okengine 0.1.4

package/src/runs/shred.ts

@@ -0,0 +1,243 @@
+/**
+ * Crypto-shredding for right-to-erasure on immutable Parquet partitions.
+ *
+ * Personal fields are encrypted with a per-subject key held in the Vault.
+ * `oke privacy erase --subject <id>` deletes the key — archived bytes become
+ * permanently unreadable without rewriting partitions (console §9.11).
+ */
+
+import type { VaultRuntime } from "../elements/vault.ts";
+
+/** Prefix for per-subject shred keys in the Vault. */
+export const SUBJECT_KEY_PREFIX = "oke.subject.";
+
+/** Marker returned when a field cannot be decrypted (key shredded). */
+export const SHREDDED = "[shredded]";
+
+/**
+ * Vault key name for a subject.
+ *
+ * @param subjectId - Subject identifier
+ */
+export function subjectKeyName(subjectId: string): string {
+  return `${SUBJECT_KEY_PREFIX}${subjectId}`;
+}
+
+/** Minimal vault surface needed for subject keys. */
+export interface SubjectKeyVault {
+  /**
+   * Read a secret by name.
+   *
+   * @param name - Secret name
+   */
+  read(name: string): string;
+  /**
+   * Write / overwrite a secret (mutable vault bags only).
+   *
+   * @param name - Secret name
+   * @param value - Cleartext
+   */
+  put(name: string, value: string): void;
+  /**
+   * Delete a secret.
+   *
+   * @param name - Secret name
+   */
+  delete(name: string): boolean;
+  /**
+   * Whether a secret is present.
+   *
+   * @param name - Secret name
+   */
+  has(name: string): boolean;
+}
+
+/**
+ * Adapt a {@link VaultRuntime} that supports put/delete into {@link SubjectKeyVault}.
+ *
+ * @param vault - Booted vault runtime with mutation support
+ */
+export function subjectKeysFromVault(vault: VaultRuntime): SubjectKeyVault {
+  return {
+    read(name) {
+      return vault.read(name);
+    },
+    put(name, value) {
+      if (typeof vault.put !== "function") {
+        throw new Error("vault: put() required for subject keys");
+      }
+      vault.put(name, value);
+    },
+    delete(name) {
+      if (typeof vault.delete !== "function") {
+        throw new Error("vault: delete() required for subject-key erasure");
+      }
+      return vault.delete(name);
+    },
+    has(name) {
+      return vault.names().includes(name);
+    },
+  };
+}
+
+/**
+ * In-memory subject-key vault (tests / when no Vault element is wired).
+ */
+export function createMemorySubjectKeys(
+  seed?: Readonly<Record<string, string>>,
+): SubjectKeyVault {
+  const map = new Map<string, string>(Object.entries(seed ?? {}));
+  return {
+    read(name) {
+      const v = map.get(name);
+      if (v === undefined) throw new Error(`subject key missing: ${name}`);
+      return v;
+    },
+    put(name, value) {
+      map.set(name, value);
+    },
+    delete(name) {
+      return map.delete(name);
+    },
+    has(name) {
+      return map.has(name);
+    },
+  };
+}
+
+/**
+ * Ensure a per-subject AES-256 key exists; return raw key bytes.
+ *
+ * @param keys - Subject key vault
+ * @param subjectId - Subject id
+ */
+export async function ensureSubjectKey(
+  keys: SubjectKeyVault,
+  subjectId: string,
+): Promise<Uint8Array> {
+  const name = subjectKeyName(subjectId);
+  if (!keys.has(name)) {
+    const raw = crypto.getRandomValues(new Uint8Array(32));
+    keys.put(name, Buffer.from(raw).toString("base64"));
+    return raw;
+  }
+  return Buffer.from(keys.read(name), "base64");
+}
+
+/**
+ * Encrypt cleartext fields under the subject's key.
+ *
+ * @param keys - Subject key vault
+ * @param subjectId - Subject id
+ * @param fields - Cleartext field map
+ */
+export async function archiveFields(
+  keys: SubjectKeyVault,
+  subjectId: string,
+  fields: Readonly<Record<string, string>>,
+): Promise<Record<string, string>> {
+  const key = await ensureSubjectKey(keys, subjectId);
+  const out: Record<string, string> = {};
+  for (const [name, value] of Object.entries(fields)) {
+    out[name] = await encryptAesGcm(value, key);
+  }
+  return out;
+}
+
+/**
+ * Decrypt archived fields. Missing / shredded keys yield {@link SHREDDED}.
+ *
+ * @param keys - Subject key vault
+ * @param subjectId - Subject id
+ * @param archived - Ciphertext field map
+ */
+export async function revealArchived(
+  keys: SubjectKeyVault,
+  subjectId: string,
+  archived: Readonly<Record<string, string>>,
+): Promise<Record<string, string>> {
+  const name = subjectKeyName(subjectId);
+  if (!keys.has(name)) {
+    const shredded: Record<string, string> = {};
+    for (const k of Object.keys(archived)) shredded[k] = SHREDDED;
+    return shredded;
+  }
+  const key = Buffer.from(keys.read(name), "base64");
+  const out: Record<string, string> = {};
+  for (const [field, blob] of Object.entries(archived)) {
+    try {
+      out[field] = await decryptAesGcm(blob, key);
+    } catch {
+      out[field] = SHREDDED;
+    }
+  }
+  return out;
+}
+
+/**
+ * Erase a subject by deleting their Vault key (crypto-shred).
+ *
+ * @param keys - Subject key vault
+ * @param subjectId - Subject id
+ * @returns Whether a key was deleted
+ */
+export function eraseSubject(
+  keys: SubjectKeyVault,
+  subjectId: string,
+): boolean {
+  return keys.delete(subjectKeyName(subjectId));
+}
+
+async function encryptAesGcm(
+  plaintext: string,
+  keyBytes: Uint8Array,
+): Promise<string> {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const keyBuf = toArrayBuffer(keyBytes);
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    keyBuf,
+    { name: "AES-GCM" },
+    false,
+    ["encrypt"],
+  );
+  const cipher = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    cryptoKey,
+    new TextEncoder().encode(plaintext),
+  );
+  const packed = new Uint8Array(iv.length + cipher.byteLength);
+  packed.set(iv, 0);
+  packed.set(new Uint8Array(cipher), iv.length);
+  return Buffer.from(packed).toString("base64");
+}
+
+async function decryptAesGcm(
+  blob: string,
+  keyBytes: Uint8Array,
+): Promise<string> {
+  const packed = Buffer.from(blob, "base64");
+  const iv = toArrayBuffer(packed.subarray(0, 12));
+  const data = toArrayBuffer(packed.subarray(12));
+  const keyBuf = toArrayBuffer(keyBytes);
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    keyBuf,
+    { name: "AES-GCM" },
+    false,
+    ["decrypt"],
+  );
+  const plain = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: new Uint8Array(iv) },
+    cryptoKey,
+    data,
+  );
+  return new TextDecoder().decode(plain);
+}
+
+/** Copy into a real ArrayBuffer for Web Crypto BufferSource typing. */
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return copy.buffer;
+}

package/src/runs/telemetry.ts

@@ -0,0 +1,10 @@
+/**
+ * Re-export run telemetry from the kernel (collected through `fx`).
+ */
+
+export {
+  createRunTelemetry,
+  cacheDimensionOf,
+  type RunLogLine,
+  type RunTelemetry,
+} from "../kernel/run-telemetry.ts";

package/src/runs/types.ts

@@ -0,0 +1,179 @@
+/**
+ * Wide-event types for the runs store.
+ *
+ * One flow execution = one wide event = one span. Traces, Overview and Runs
+ * are three views of this single store (console §9.11).
+ */
+
+import type { EffectEntry } from "../kernel/effects.ts";
+import type { RunLogLine } from "../kernel/run-telemetry.ts";
+import type { FlowPlane } from "../manifest/types.ts";
+
+export type { RunLogLine };
+
+/** Protocol ids for runs store drivers. */
+export type RunsDriverId = "files" | "memory" | "postgres" | "clickhouse";
+
+/** Typed error carried on a failed run. */
+export interface RunError {
+  /** Declared or framework error code. */
+  readonly code: string;
+  /** Human-readable message when present. */
+  readonly message?: string;
+}
+
+/**
+ * Declared / observed dimensions available without manual instrumentation.
+ * Extra keys are allowed for outlier analysis.
+ */
+export type RunDimensions = Record<
+  string,
+  string | number | boolean | null | undefined
+>;
+
+/**
+ * One wide event — the atomic observability record.
+ *
+ * Personal fields that must survive erasure go in {@link archived}
+ * (ciphertext under a per-subject Vault key).
+ */
+export interface WideEvent {
+  /** Run id (= span id). */
+  readonly id: string;
+  /** Parent run id when this execution was caused by another (trace chain). */
+  readonly parentId?: string;
+  /** Flow name. */
+  readonly flow: string;
+  /** Optional unit scope. */
+  readonly unit?: string;
+  /** Trigger kind (`http` · `every` · `signal` · `cdc` · `internal`). */
+  readonly trigger: string;
+  /** Auth plane. */
+  readonly plane: FlowPlane;
+  /** Tenant id when multi-tenancy is active. */
+  readonly tenant?: string | null;
+  /** Principal — user id or operator id. */
+  readonly principal?: string | null;
+  /** Subject id for crypto-shredding (defaults to principal / tenant). */
+  readonly subjectId?: string | null;
+  /** Gate names evaluated for this invocation. */
+  readonly gates: readonly string[];
+  /** Cache outcome observed through `fx.cache`. */
+  readonly cache: "hit" | "miss" | "none";
+  /** SQL role when a store runtime routed the flow. */
+  readonly replica?: "primary" | "replica";
+  /** Replica lag in milliseconds when observed. */
+  readonly replicaLagMs?: number;
+  /** AI cost accrued during the run. */
+  readonly cost?: number;
+  /** Prompt version when `fx.ask` was used. */
+  readonly promptVersion?: number;
+  /** Build / release version when known. */
+  readonly buildVersion?: string;
+  /** Typed error when the flow failed. */
+  readonly error?: RunError | null;
+  /** Effect ledger snapshot. */
+  readonly effects: readonly EffectEntry[];
+  /**
+   * `fx.log` lines — a field on the run, not a parallel stream.
+   */
+  readonly logs: readonly RunLogLine[];
+  /** Wall duration in milliseconds. */
+  readonly durationMs: number;
+  /** Epoch-ms start. */
+  readonly startedAt: number;
+  /** Epoch-ms end. */
+  readonly endedAt: number;
+  /**
+   * Crypto-shredded personal fields: field name → ciphertext.
+   * Readable only while the per-subject Vault key exists.
+   */
+  readonly archived?: Readonly<Record<string, string>>;
+  /**
+   * All queryable dimensions (declared + observed).
+   * Outlier explanation compares these across populations.
+   */
+  readonly dimensions: RunDimensions;
+}
+
+/** Retention / redaction policy (lifecycle — not locality). */
+export interface RunsRetention {
+  /**
+   * Keep operational runs for this duration, or `"forever"` (default).
+   * Deletion is a compliance action, not a cleanup job.
+   */
+  readonly keep?: string | "forever";
+  /** Redact personal fields older than these durations. */
+  readonly redact?: Readonly<Record<string, string>>;
+}
+
+/** One SQL result row. */
+export type RunsRow = Record<string, unknown>;
+
+/** Runs store handle — append wide events and query them. */
+export interface RunsStore {
+  /** Protocol driver id. */
+  readonly driverId: RunsDriverId;
+  /**
+   * Append one wide event (buffered; may flush to a partition).
+   *
+   * @param event - Wide event to store
+   */
+  append(event: WideEvent): Promise<void>;
+  /**
+   * Flush buffered events to durable partitions.
+   */
+  flush(): Promise<void>;
+  /**
+   * Run SQL against all visible partitions (local + object storage).
+   *
+   * @param sql - DuckDB / driver SQL
+   */
+  query(sql: string): Promise<RunsRow[]>;
+  /**
+   * Materialise all events (test helper / small stores).
+   */
+  all(): Promise<WideEvent[]>;
+  /** Close underlying resources. */
+  close(): Promise<void>;
+}
+
+/** Driver factory for the runs store. */
+export interface RunsDriver {
+  /** Protocol id. */
+  readonly id: RunsDriverId;
+  /**
+   * Open a store.
+   *
+   * @param options - Driver-specific options
+   */
+  open(options?: RunsOpenOptions): Promise<RunsStore>;
+}
+
+/** Options when opening a runs store. */
+export interface RunsOpenOptions {
+  /** Local root for recent Parquet partitions (`files`). */
+  readonly localRoot?: string;
+  /** Optional object-storage bucket for older partitions (`files`). */
+  readonly remote?: {
+    readonly bucket: import("../drivers/types.ts").FilesBucket;
+    readonly prefix?: string;
+  };
+  /** Injected local files bucket (tests). */
+  readonly localBucket?: import("../drivers/types.ts").FilesBucket;
+  /**
+   * Age after which new writes go to object storage (engine locality detail).
+   * Default: 7 days. User never declares archive tiers.
+   */
+  readonly hotWindowMs?: number;
+  /** Retention policy (compliance). */
+  readonly retention?: RunsRetention;
+  /** Postgres connection URL or injected client. */
+  readonly url?: string;
+  /** Injected client for postgres / clickhouse fakes. */
+  readonly client?: unknown;
+  /** Table / dataset name. */
+  readonly name?: string;
+  /** Build version stamped on every event when not set on the event. */
+  readonly buildVersion?: string;
+}

package/src/runtime/bun.ts

@@ -0,0 +1,140 @@
+/**
+ * Bun runtime adapter — `Bun.serve`, `bun:sqlite`, `Bun.password`.
+ *
+ * Uses Bun native `routes` for HTTP paths the engine can express, with
+ * `fetch` as the fallback. Every request passes Host / Origin validation
+ * before the app pipeline (console §10.1).
+ */
+
+import { Database } from "bun:sqlite";
+import { createBunCrypto, createEnv, createFiles, createTimers } from "./primitives.ts";
+import { secureFetch } from "./security.ts";
+import {
+  APP_PORT,
+  type FetchApp,
+  type Runtime,
+  type ServeOptions,
+  type ServerHandle,
+} from "./types.ts";
+
+/** Bun adapter — extends {@link Runtime} with native sqlite. */
+export interface BunRuntime extends Runtime {
+  readonly name: "bun";
+  /**
+   * Open a `bun:sqlite` database (native binding).
+   *
+   * @param filename - Path, `":memory:"`, or omit for memory
+   * @param options - `bun:sqlite` open options
+   */
+  sqlite(
+    filename?: string,
+    options?: ConstructorParameters<typeof Database>[1],
+  ): Database;
+}
+
+/**
+ * Create the Bun runtime adapter.
+ */
+export function createBunRuntime(): BunRuntime {
+  return {
+    name: "bun",
+    timers: createTimers(),
+    crypto: createBunCrypto(),
+    env: createEnv(),
+    files: createFiles(),
+    sqlite(filename = ":memory:", options) {
+      return options === undefined
+        ? new Database(filename)
+        : new Database(filename, options);
+    },
+    serve(app, options) {
+      return listenBun(app, options);
+    },
+  };
+}
+
+/**
+ * True when a path can be registered on Bun.serve `routes`
+ * (static segments and `:param` only).
+ *
+ * @param path - Route path pattern
+ */
+export function isBunNativePath(path: string): boolean {
+  if (!path.startsWith("/")) return false;
+  // Reject optional params, regex, wildcards Bun's object routes may not mirror 1:1
+  if (/[*?{}()]/.test(path)) return false;
+  if (/\/:[^/]+\?/.test(path)) return false;
+  return true;
+}
+
+type MethodHandlers = Partial<
+  Record<string, (req: Request) => Response | Promise<Response>>
+>;
+
+/**
+ * Build Bun.serve `routes` from app HTTP bindings.
+ * Each handler runs the secured fetch pipeline (identical behaviour).
+ *
+ * @param app - Application
+ * @param fetchHandler - Secured fetch
+ */
+export function buildBunRoutes(
+  app: FetchApp,
+  fetchHandler: (request: Request) => Promise<Response>,
+): Record<string, MethodHandlers> {
+  const routes: Record<string, MethodHandlers> = {};
+  const bindings = app.bindings ?? [];
+  for (const b of bindings) {
+    if (b.trigger.kind !== "http") continue;
+    const path = b.trigger.path;
+    const method = b.trigger.method;
+    if (typeof path !== "string" || typeof method !== "string") continue;
+    if (!isBunNativePath(path)) continue;
+    const methods = routes[path] ?? (routes[path] = {});
+    methods[method] = (req) => fetchHandler(req);
+  }
+  return routes;
+}
+
+function listenBun(app: FetchApp, options?: ServeOptions): ServerHandle {
+  const port = options?.port ?? APP_PORT;
+  const hostname = options?.hostname ?? "127.0.0.1";
+  const fetchHandler = secureFetch(
+    (req) => app.fetch(req),
+    options,
+    hostname,
+  );
+  const routes = buildBunRoutes(app, fetchHandler);
+
+  const server = Bun.serve({
+    port,
+    hostname,
+    ...(options?.id !== undefined ? { id: options.id } : {}),
+    routes: Object.keys(routes).length > 0 ? routes : undefined,
+    fetch: fetchHandler,
+  });
+
+  const boundPort = server.port ?? port;
+  const boundHost = server.hostname ?? hostname;
+  const url = new URL(`http://${formatHostForUrl(boundHost)}:${boundPort}/`);
+
+  return {
+    url,
+    port: boundPort,
+    hostname: boundHost,
+    fetch: fetchHandler,
+    stop(closeActiveConnections = false) {
+      server.stop(closeActiveConnections);
+    },
+  };
+}
+
+/**
+ * Format a hostname for use in a URL (bracket IPv6).
+ *
+ * @param host - Hostname
+ */
+function formatHostForUrl(host: string): string {
+  if (host.includes(":") && !host.startsWith("[")) return `[${host}]`;
+  return host;
+}

package/src/runtime/cold-start.bench.ts

@@ -0,0 +1,20 @@
+/**
+ * Cold-start budget gate — unified-theory §24 / AGENTS.md.
+ * Measured in a fresh Bun subprocess so import cost is real.
+ *
+ * Limit: < 75 ms from process start to server ready.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { COLD_START_BUDGET_MS } from "../release/limits.ts";
+import { measureColdStartMedianMs } from "../release/measure.ts";
+
+describe("cold start budget", () => {
+  test(`Bun adapter ready in < ${COLD_START_BUDGET_MS} ms`, async () => {
+    const median = await measureColdStartMedianMs();
+    console.log(
+      `cold-start median=${median.toFixed(2)} ms budget=${COLD_START_BUDGET_MS}`,
+    );
+    expect(median).toBeLessThan(COLD_START_BUDGET_MS);
+  });
+});

package/src/runtime/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Runtime adapters: Bun (primary) · Web Standards (Node / Deno / edge).
+ */
+
+export {
+  createBunRuntime,
+  buildBunRoutes,
+  isBunNativePath,
+  type BunRuntime,
+} from "./bun.ts";
+
+export {
+  createEnv,
+  createFiles,
+  createTimers,
+  createWebCrypto,
+  createBunCrypto,
+} from "./primitives.ts";
+
+export {
+  checkRequestSecurity,
+  forbiddenResponse,
+  isHostAllowed,
+  normalizeHost,
+  resolveAllowedHosts,
+  secureFetch,
+  type SecurityCheck,
+} from "./security.ts";
+
+export {
+  APP_PORT,
+  CONSOLE_PORT,
+  MCP_PORT,
+  type FetchApp,
+  type PasswordAlgorithm,
+  type Runtime,
+  type RuntimeCrypto,
+  type RuntimeEnv,
+  type RuntimeFiles,
+  type RuntimeName,
+  type RuntimeTimers,
+  type ServeOptions,
+  type ServerHandle,
+} from "./types.ts";
+
+export { createWebStandardRuntime } from "./web-standard.ts";