okengine 0.9.1 → 0.10.1

package/src/manifest/sql-resource.ts

@@ -0,0 +1,41 @@
+/**
+ * SQL resource-ref naming — the one place both the compiler's AST-based
+ * effect inference ({@link "../compiler/effects-infer.ts"}) and the
+ * kernel's capability gate ({@link "../kernel/fx.ts"} `gatedSqlHandle`)
+ * compute a per-table `sql:<table>` ref, so the two cannot silently
+ * drift apart again.
+ *
+ * Table-name *resolution* differs by nature — the compiler reads a static
+ * AST identifier (or, better, the declared name behind a
+ * `store.schema.table(name, …)` binding); the kernel reads the declared
+ * name straight off the live table object at call time. Only the
+ * naming/formatting step is shared here; that is the part a second,
+ * independently-written implementation could get wrong.
+ */
+
+import type { ResourceRef } from "./types.ts";
+
+/**
+ * The declared name a real `store.schema.table(name, columns)` object
+ * carries at runtime — the same string that was the first argument to
+ * `store.schema.table(...)` in source, regardless of what the JS binding
+ * is called. `undefined` for anything else (raw ORM tables, plain
+ * objects, missing/optional table arguments).
+ *
+ * @param value - Value passed where a table argument is expected
+ */
+export function schemaTableName(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const v = value as { kind?: unknown; name?: unknown };
+  if (v.kind !== "schema-table") return undefined;
+  return typeof v.name === "string" ? v.name : undefined;
+}
+
+/**
+ * `sql:<table>` resource ref for a declared table name.
+ *
+ * @param table - Declared table name
+ */
+export function sqlTableRef(table: string): ResourceRef {
+  return `sql:${table}` as ResourceRef;
+}

package/src/manifest/types.ts

@@ -40,6 +40,12 @@ export type ChannelMedium = "email" | "sms" | "whatsapp" | "push" | "any";
 /** Resource ref: `sql:table`, `kv:namespace`, `files:bucket`, `index:name`. */
 export type ResourceRef = `${StoreFacet}:${string}`;
 
+/**
+ * Observability read capability for `fx.runs` — not a store facet.
+ * Declare on `effects.reads` (never `writes`).
+ */
+export type RunsResourceRef = "runs";
+
 /** Signal name reference. */
 export type SignalRef = string;
 
@@ -68,8 +74,8 @@ export type JsonSchema = string | Record<string, unknown>;
  * `sends` / `asks` are irreversible (asks also nondeterministic + cost).
  */
 export interface Effects {
-  /** Store reads. */
-  reads?: ResourceRef[];
+  /** Store reads, plus optional `"runs"` for `fx.runs`. */
+  reads?: Array<ResourceRef | RunsResourceRef>;
   /** Store writes. */
   writes?: ResourceRef[];
   /** Emitted signals. */

package/src/runs/collect.ts

@@ -32,6 +32,8 @@ export interface CollectWideEventInput {
   readonly endedAt: number;
   /** Pipeline failure when present. */
   readonly failure?: FlowFailure | null;
+  /** Validated flow input (for local replay). */
+  readonly input?: unknown;
   /** Optional parent run id (causal chain). */
   readonly parentId?: string;
   /** Optional run id (generated when omitted). */
@@ -104,6 +106,7 @@ export function collectWideEvent(input: CollectWideEventInput): WideEvent {
       : {}),
     ...(input.buildVersion !== undefined ? { buildVersion: input.buildVersion } : {}),
     error,
+    ...(input.input !== undefined ? { input: input.input } : {}),
     effects: [...input.ledger.entries],
     logs: [...input.telemetry.logs],
     durationMs,

package/src/runs/export-otlp.ts

@@ -0,0 +1,64 @@
+/**
+ * Optional OTLP metrics export shape — additive sink for WideEvents.
+ *
+ * Not a prerequisite for native alerting (Runs + Clock + Channel).
+ * Protocol-named (`otlp`); vendor choice stays in config / images.
+ */
+
+import type { WideEvent } from "./types.ts";
+
+/** One OTLP-shaped metric datapoint derived from a wide event. */
+export interface OtlpRunMetric {
+  readonly name: "oke.runs" | "oke.run.duration_ms";
+  readonly kind: "counter" | "histogram";
+  readonly value: number;
+  readonly attributes: Readonly<Record<string, string>>;
+  readonly timeUnixMs: number;
+}
+
+/**
+ * Map a WideEvent onto OTLP-friendly metric datapoints.
+ *
+ * @param event - Appended run
+ */
+export function wideEventToOtlpMetrics(event: WideEvent): readonly OtlpRunMetric[] {
+  const attributes = {
+    flow: event.flow,
+    trigger: event.trigger,
+    outcome: event.error ? "error" : "ok",
+    ...(event.error ? { error_code: event.error.code } : {}),
+  };
+  return [
+    {
+      name: "oke.runs",
+      kind: "counter",
+      value: 1,
+      attributes,
+      timeUnixMs: event.endedAt,
+    },
+    {
+      name: "oke.run.duration_ms",
+      kind: "histogram",
+      value: event.durationMs,
+      attributes: { flow: event.flow, trigger: event.trigger },
+      timeUnixMs: event.endedAt,
+    },
+  ];
+}
+
+/** Pluggable sink for teams with an existing Grafana / Datadog stack. */
+export type OtlpMetricsSink = (metrics: readonly OtlpRunMetric[]) => void | Promise<void>;
+
+/**
+ * Fan-out helper: call after `runs.record` when an OTLP sink is configured.
+ *
+ * @param event - Just-recorded wide event
+ * @param sink - Optional exporter
+ */
+export async function exportRunMetrics(
+  event: WideEvent,
+  sink: OtlpMetricsSink | undefined,
+): Promise<void> {
+  if (!sink) return;
+  await sink(wideEventToOtlpMetrics(event));
+}

package/src/runs/index.ts

@@ -68,5 +68,21 @@ export {
 
 export { privacyErase, type PrivacyEraseOptions, type PrivacyEraseResult } from "./privacy.ts";
 
+export {
+  evaluateSloBreaches,
+  parseLatencyMs,
+  percentile,
+  windowStatsForFlow,
+  type RunWindowStats,
+  type SloBreach,
+} from "./window.ts";
+
+export {
+  exportRunMetrics,
+  wideEventToOtlpMetrics,
+  type OtlpMetricsSink,
+  type OtlpRunMetric,
+} from "./export-otlp.ts";
+
 export { createRunsPostgresFake } from "./drivers/postgres.ts";
 export { createRunsClickHouseFake } from "./drivers/clickhouse.ts";

package/src/runs/parquet.ts

@@ -42,6 +42,7 @@ export function wideEventToRow(event: WideEvent): ParquetRow {
     build_version: event.buildVersion ?? null,
     error_code: event.error?.code ?? null,
     error_message: event.error?.message ?? null,
+    input: event.input === undefined ? null : JSON.stringify(event.input),
     effects: JSON.stringify(event.effects),
     logs: JSON.stringify(event.logs),
     duration_ms: event.durationMs,
@@ -103,6 +104,14 @@ export function rowToWideEvent(row: Record<string, unknown>): WideEvent {
             ...(row.error_message != null ? { message: String(row.error_message) } : {}),
           }
         : null,
+    ...(row.input != null && row.input !== ""
+      ? {
+          input:
+            typeof row.input === "string"
+              ? (JSON.parse(row.input) as unknown)
+              : (row.input as unknown),
+        }
+      : {}),
     effects: parseJsonArray(row.effects) as WideEvent["effects"],
     logs: parseJsonArray(row.logs) as WideEvent["logs"],
     durationMs: Number(row.duration_ms ?? 0),

package/src/runs/types.ts

@@ -69,6 +69,11 @@ export interface WideEvent {
   readonly buildVersion?: string;
   /** Typed error when the flow failed. */
   readonly error?: RunError | null;
+  /**
+   * Validated flow input snapshot for local replay (`oke replay`).
+   * Declared personal fields may be crypto-shredded into {@link archived}.
+   */
+  readonly input?: unknown;
   /** Effect ledger snapshot. */
   readonly effects: readonly EffectEntry[];
   /**

package/src/runs/window.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import type { WideEvent } from "./types.ts";
+import { evaluateSloBreaches, parseLatencyMs, windowStatsForFlow } from "./window.ts";
+
+function ev(
+  partial: Partial<WideEvent> & Pick<WideEvent, "id" | "durationMs" | "startedAt">,
+): WideEvent {
+  return {
+    flow: "checkout.create",
+    trigger: "http",
+    plane: "user",
+    gates: [],
+    cache: "none",
+    error: null,
+    effects: [],
+    logs: [],
+    endedAt: partial.startedAt + partial.durationMs,
+    dimensions: {},
+    ...partial,
+  };
+}
+
+describe("runs window stats", () => {
+  test("parseLatencyMs", () => {
+    expect(parseLatencyMs("200ms")).toBe(200);
+    expect(parseLatencyMs("1s")).toBe(1000);
+    expect(parseLatencyMs("bad")).toBeNull();
+  });
+
+  test("computes p95 and error rate", () => {
+    const now = 10_000;
+    const events = [
+      ev({ id: "1", durationMs: 10, startedAt: now - 1000 }),
+      ev({ id: "2", durationMs: 20, startedAt: now - 900 }),
+      ev({ id: "3", durationMs: 30, startedAt: now - 800 }),
+      ev({ id: "4", durationMs: 40, startedAt: now - 700 }),
+      ev({
+        id: "5",
+        durationMs: 200,
+        startedAt: now - 600,
+        error: { code: "Timeout" },
+      }),
+    ];
+    const stats = windowStatsForFlow(events, "checkout.create", now, 5 * 60_000);
+    expect(stats.total).toBe(5);
+    expect(stats.errors).toBe(1);
+    expect(stats.errorRate).toBeCloseTo(0.2);
+    expect(stats.p95Ms).toBe(200);
+  });
+
+  test("evaluateSloBreaches flags latency and availability", () => {
+    const stats = windowStatsForFlow(
+      [
+        ev({ id: "1", durationMs: 500, startedAt: 9000, error: { code: "X" } }),
+        ev({ id: "2", durationMs: 500, startedAt: 9100 }),
+      ],
+      "checkout.create",
+      10_000,
+      5_000,
+    );
+    const breaches = evaluateSloBreaches(stats, {
+      availability: "99.9%",
+      latency: { p95: "100ms" },
+    });
+    expect(breaches.some((b) => b.kind === "availability")).toBe(true);
+    expect(breaches.some((b) => b.kind === "latency_p95")).toBe(true);
+  });
+});

package/src/runs/window.ts

@@ -0,0 +1,148 @@
+/**
+ * Rolling window metrics over WideEvents — shared by Console Overview and
+ * Flow-facing `fx.runs` checkers (native alerting without `fx.metric`).
+ */
+
+import type { WideEvent } from "./types.ts";
+
+/** One flow's rolling stats over a time window. */
+export interface RunWindowStats {
+  readonly flow: string;
+  readonly total: number;
+  readonly errors: number;
+  readonly errorRate: number;
+  readonly p50Ms: number;
+  readonly p95Ms: number;
+  readonly p99Ms: number;
+  readonly from: number;
+  readonly to: number;
+}
+
+/**
+ * Percentile of a sorted numeric array.
+ *
+ * @param sorted - Ascending durations
+ * @param p - Percentile in (0, 1]
+ */
+export function percentile(sorted: readonly number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0]!;
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1));
+  return sorted[idx]!;
+}
+
+/**
+ * Parse a Manifest latency string like `200ms` / `1s` into milliseconds.
+ *
+ * @param raw - Latency threshold
+ */
+export function parseLatencyMs(raw: string | undefined): number | null {
+  if (!raw) return null;
+  const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m)?$/i.exec(raw.trim());
+  if (!match) return null;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n) || n < 0) return null;
+  const unit = (match[2] ?? "ms").toLowerCase();
+  if (unit === "s") return Math.round(n * 1000);
+  if (unit === "m") return Math.round(n * 60_000);
+  return Math.round(n);
+}
+
+/**
+ * Compute rolling stats for one flow over `[to - windowMs, to]`.
+ *
+ * @param events - Wide events
+ * @param flow - Flow name filter
+ * @param to - Window end (epoch-ms)
+ * @param windowMs - Window length
+ */
+export function windowStatsForFlow(
+  events: readonly WideEvent[],
+  flow: string,
+  to: number,
+  windowMs: number,
+): RunWindowStats {
+  const from = to - Math.max(0, windowMs);
+  const mine = events.filter((e) => e.flow === flow && e.startedAt >= from && e.startedAt <= to);
+  const durations = mine.map((e) => e.durationMs).sort((a, b) => a - b);
+  const errors = mine.filter((e) => e.error != null).length;
+  const total = mine.length;
+  return {
+    flow,
+    total,
+    errors,
+    errorRate: total === 0 ? 0 : errors / total,
+    p50Ms: percentile(durations, 0.5),
+    p95Ms: percentile(durations, 0.95),
+    p99Ms: percentile(durations, 0.99),
+    from,
+    to,
+  };
+}
+
+/** Breach report for a declared latency / availability SLO. */
+export interface SloBreach {
+  readonly flow: string;
+  readonly kind: "availability" | "latency_p95" | "latency_p99";
+  readonly threshold: number;
+  readonly observed: number;
+  readonly sampleCount: number;
+}
+
+/**
+ * Evaluate Manifest-style SLO thresholds against window stats.
+ *
+ * @param stats - Window stats
+ * @param slo - Declared availability + latency
+ */
+export function evaluateSloBreaches(
+  stats: RunWindowStats,
+  slo: {
+    readonly availability?: string;
+    readonly latency?: { readonly p95?: string; readonly p99?: string };
+  },
+): SloBreach[] {
+  const out: SloBreach[] = [];
+  if (stats.total === 0) return out;
+
+  if (slo.availability) {
+    const match = /^(\d+(?:\.\d+)?)\s*%?$/.exec(slo.availability.trim());
+    if (match) {
+      const pct = Number(match[1]);
+      const tolerable = Math.max(0, 1 - pct / 100);
+      if (stats.errorRate > tolerable) {
+        out.push({
+          flow: stats.flow,
+          kind: "availability",
+          threshold: tolerable,
+          observed: stats.errorRate,
+          sampleCount: stats.total,
+        });
+      }
+    }
+  }
+
+  const p95 = parseLatencyMs(slo.latency?.p95);
+  if (p95 != null && stats.p95Ms > p95) {
+    out.push({
+      flow: stats.flow,
+      kind: "latency_p95",
+      threshold: p95,
+      observed: stats.p95Ms,
+      sampleCount: stats.total,
+    });
+  }
+
+  const p99 = parseLatencyMs(slo.latency?.p99);
+  if (p99 != null && stats.p99Ms > p99) {
+    out.push({
+      flow: stats.flow,
+      kind: "latency_p99",
+      threshold: p99,
+      observed: stats.p99Ms,
+      sampleCount: stats.total,
+    });
+  }
+
+  return out;
+}

package/src/runtime/boot-warn.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Boot honesty suppress flag for the `oke dev` Backend child.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { emitBootWarn } from "./boot-warn.ts";
+
+describe("emitBootWarn", () => {
+  const prev = process.env["OKE_SUPPRESS_BOOT_WARN"];
+
+  afterEach(() => {
+    if (prev === undefined) delete process.env["OKE_SUPPRESS_BOOT_WARN"];
+    else process.env["OKE_SUPPRESS_BOOT_WARN"] = prev;
+  });
+
+  test("forwards to console.warn by default", () => {
+    delete process.env["OKE_SUPPRESS_BOOT_WARN"];
+    const lines: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => {
+      lines.push(args.map(String).join(" "));
+    };
+    try {
+      emitBootWarn("oke boot: test notice");
+      expect(lines).toEqual(["oke boot: test notice"]);
+    } finally {
+      console.warn = original;
+    }
+  });
+
+  test("no-ops when OKE_SUPPRESS_BOOT_WARN=1", () => {
+    process.env["OKE_SUPPRESS_BOOT_WARN"] = "1";
+    const lines: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => {
+      lines.push(args.map(String).join(" "));
+    };
+    try {
+      emitBootWarn("oke boot: hidden");
+      expect(lines).toEqual([]);
+    } finally {
+      console.warn = original;
+    }
+  });
+});

package/src/runtime/boot-warn.ts

@@ -0,0 +1,17 @@
+/**
+ * Boot honesty lines (`oke boot: …`) — once per process, suppressible in
+ * the `oke dev` Backend child so the parent Console owns the notice.
+ */
+
+/**
+ * Emit a boot warning unless suppressed for this process.
+ *
+ * Set `OKE_SUPPRESS_BOOT_WARN=1` on the Backend child during `oke dev` so
+ * Signal / Channel / files process-local notices print once (parent only).
+ *
+ * @param message - Full warning text (usually prefixed `oke boot:`)
+ */
+export function emitBootWarn(message: string): void {
+  if (process.env["OKE_SUPPRESS_BOOT_WARN"] === "1") return;
+  console.warn(message);
+}

package/src/runtime/dev-request-log.ts

@@ -1,5 +1,5 @@
 /**
- * Dev-only request lines for `oke dev` (App / Console / MCP).
+ * Dev-only request lines for `oke dev` (Backend / Console / MCP).
  *
  * Gated by `OKE_DEV_REQUEST_LOG=1`. Surfaces share one TTY; label + color
  * keep streams readable without a multiplexer.
@@ -18,22 +18,22 @@ export function shouldLogDevRequests(): boolean {
 }
 
 /**
- * Active surface for this async context, or `OKE_DEV_SURFACE`, or `App`.
+ * Active surface for this async context, or `OKE_DEV_SURFACE`, or `Backend`.
  */
 export function currentDevSurface(): DevLogSurface {
   const fromAls = surfaceAls.getStore();
   if (fromAls) return fromAls;
   const fromEnv = process.env.OKE_DEV_SURFACE;
-  if (fromEnv === "App" || fromEnv === "Console" || fromEnv === "MCP") {
+  if (fromEnv === "Backend" || fromEnv === "Console" || fromEnv === "MCP") {
     return fromEnv;
   }
-  return "App";
+  return "Backend";
 }
 
 /**
  * Run a handler tagged with a surface (Console wrap around `app.fetch`).
  *
- * @param surface - App · Console · MCP
+ * @param surface - Backend · Console · MCP
  * @param fn - Async work
  */
 export function runWithDevSurface<T>(