okengine 0.9.0 → 0.10.0

package/src/plugins/index.ts

@@ -30,9 +30,9 @@ export {
   otpEmailTemplate,
   otpSmsTemplate,
   otpWhatsappTemplate,
+  type OtpAppModeOptions,
   type OtpOptions,
-  type OtpTier1Options,
-  type OtpTier2Options,
+  type OtpProviderModeOptions,
   type PhoneStore,
 } from "./otp.ts";
 export {

package/src/plugins/otp.test.ts

@@ -1,5 +1,5 @@
 /**
- * otp() plugin — plug-time fail-loud, Tier 2 resend / sealed lifetime, Tier 1 boot.
+ * otp() plugin — plug-time fail-loud, app-mode resend / sealed lifetime, provider-mode boot.
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
@@ -71,44 +71,46 @@ function mockOtpSmsDriver(): ChannelDriver {
 }
 
 describe("otp() plug-time fail-loud", () => {
-  test("missing tier throws", () => {
-    expect(() => otp({} as never)).toThrow(/tier is required/);
+  test("missing mode throws", () => {
+    expect(() => otp({} as never)).toThrow(/mode is required/);
   });
 
-  test("tier 1 with channels throws", () => {
-    expect(() => otp({ tier: 1, channels: ["sms"] } as never)).toThrow(/channels are forbidden/);
+  test('mode "provider" with channels throws', () => {
+    expect(() => otp({ mode: "provider", channels: ["sms"] } as never)).toThrow(
+      /channels are forbidden/,
+    );
   });
 
-  test("tier 1 with exposeDevOtp throws", () => {
-    expect(() => otp({ tier: 1, exposeDevOtp: true } as never)).toThrow(
+  test('mode "provider" with exposeDevOtp throws', () => {
+    expect(() => otp({ mode: "provider", exposeDevOtp: true } as never)).toThrow(
       /exposeDevOtp is forbidden/,
     );
   });
 
-  test("tier 2 without channels throws", () => {
-    expect(() => otp({ tier: 2 } as never)).toThrow(/channels is required/);
+  test('mode "app" without channels throws', () => {
+    expect(() => otp({ mode: "app" } as never)).toThrow(/channels is required/);
   });
 });
 
-describe("otp() Tier 1 boot", () => {
+describe("otp() provider mode boot", () => {
   test("fails loud without Verify-capable SMS driver", async () => {
     const app = oke({
-      name: `otp-t1-${crypto.randomUUID()}`,
+      name: `otp-provider-${crypto.randomUUID()}`,
       env: "test",
       registry: "ignore",
       gate: { auth: { secret: SECRET } },
-    }).plug(otp({ tier: 1 }));
-    await expect(app.boot({ env: "test" })).rejects.toThrow(/tier: 1/);
+    }).plug(otp({ mode: "provider" }));
+    await expect(app.boot({ env: "test" })).rejects.toThrow(/mode: "provider"/);
   });
 
   test("boots when Verify-capable SMS driver is bound", async () => {
     const app = oke({
-      name: `otp-t1-ok-${crypto.randomUUID()}`,
+      name: `otp-provider-ok-${crypto.randomUUID()}`,
       env: "test",
       registry: "ignore",
       gate: { auth: { secret: SECRET } },
       channel: { drivers: [mockOtpSmsDriver()] },
-    }).plug(otp({ tier: 1 }));
+    }).plug(otp({ mode: "provider" }));
     await app.boot({ env: "test" });
     const res = await app.fetch(jsonPost("/auth/otp/request", { phone: "+15551234567" }));
     expect(res.status).toBe(200);
@@ -120,12 +122,12 @@ describe("otp() Tier 1 boot", () => {
   });
 });
 
-describe("otp() Tier 2 resend + sealed lifetime", () => {
+describe("otp() app mode resend + sealed lifetime", () => {
   test("cross-channel resend keeps same code; cooldown then verify wipes seal", async () => {
     let now = 1_000_000;
     const verifications: VerificationStore = createVerificationStore();
     const app = oke({
-      name: `otp-t2-${crypto.randomUUID()}`,
+      name: `otp-app-${crypto.randomUUID()}`,
       env: "test",
       registry: "ignore",
       gate: { auth: { secret: SECRET } },
@@ -133,7 +135,7 @@ describe("otp() Tier 2 resend + sealed lifetime", () => {
       fx: { now: () => now },
     }).plug(
       otp({
-        tier: 2,
+        mode: "app",
         channels: ["sms", "email"],
         exposeDevOtp: true,
         resendCooldownMs: 60_000,
@@ -209,7 +211,7 @@ describe("otp() Tier 2 resend + sealed lifetime", () => {
       fx: { now: () => now },
     }).plug(
       otp({
-        tier: 2,
+        mode: "app",
         channels: ["email"],
         exposeDevOtp: true,
         ttlMs: 1_000,

package/src/plugins/otp.ts

@@ -1,6 +1,6 @@
 /**
- * Unified OTP Gate auth method plugin — Tier 1 (provider-owned) or Tier 2
- * (app-owned multi-channel). Replaces emailOtp() + phoneNumber().
+ * Unified OTP Gate auth method plugin — provider mode (Verify) or app mode
+ * (multi-channel). Replaces emailOtp() + phoneNumber().
  */
 
 import { constantTimeEqual } from "../auth/constant-time.ts";
@@ -66,20 +66,20 @@ interface OtpBaseOptions extends AuthMethodOptions {
   readonly identities?: IdentityStore;
 }
 
-/** Tier 1 — provider-owned OTP via fx.sendOtp / fx.verifyOtp. */
-export interface OtpTier1Options extends OtpBaseOptions {
-  readonly tier: 1;
-  /** Forbidden on Tier 1 — fail loud if set. */
+/** Provider mode — provider-owned OTP via fx.sendOtp / fx.verifyOtp. */
+export interface OtpProviderModeOptions extends OtpBaseOptions {
+  readonly mode: "provider";
+  /** Forbidden in provider mode — fail loud if set. */
   readonly channels?: never;
-  /** Forbidden on Tier 1 — code never exists server-side. */
+  /** Forbidden in provider mode — code never exists server-side. */
   readonly exposeDevOtp?: never;
   readonly resendCooldownMs?: never;
   readonly from?: never;
 }
 
-/** Tier 2 — app-owned OTP with multi-channel delivery. */
-export interface OtpTier2Options extends OtpBaseOptions {
-  readonly tier: 2;
+/** App mode — app-owned OTP with multi-channel delivery. */
+export interface OtpAppModeOptions extends OtpBaseOptions {
+  readonly mode: "app";
   /** Build-time preferred channel order (required). */
   readonly channels: readonly OtpChannel[];
   readonly resendCooldownMs?: number;
@@ -87,24 +87,24 @@ export interface OtpTier2Options extends OtpBaseOptions {
   readonly from?: string;
 }
 
-/** Options for {@link otp}. `tier` is mandatory — no auto-detect. */
-export type OtpOptions = OtpTier1Options | OtpTier2Options;
+/** Options for {@link otp}. `mode` is mandatory — no auto-detect. */
+export type OtpOptions = OtpProviderModeOptions | OtpAppModeOptions;
 
-/** Email OTP template (Tier 2). */
+/** Email OTP template (app mode). */
 export const otpEmailTemplate = channel.email({ from: DEFAULT_FROM }).template("auth-otp-email", {
   description: "OTP sign-in code (email)",
   schema: z.object({ email: z.string(), otp: z.string() }),
   locales: ["en", "ar"],
 });
 
-/** SMS OTP template (Tier 2 — plain message, not provider Verify). */
+/** SMS OTP template (app mode — plain message, not provider Verify). */
 export const otpSmsTemplate = channel.sms().template("auth-otp-sms", {
   description: "OTP sign-in code (SMS)",
   schema: z.object({ phone: z.string(), otp: z.string() }),
   locales: ["en", "ar"],
 });
 
-/** WhatsApp OTP template (Tier 2). */
+/** WhatsApp OTP template (app mode). */
 export const otpWhatsappTemplate = channel.whatsapp().template("auth-otp-whatsapp", {
   description: "OTP sign-in code (WhatsApp)",
   schema: z.object({ phone: z.string(), otp: z.string() }),
@@ -136,18 +136,20 @@ export const otpCatalog = {
 } as const;
 
 function assertOtpOptions(opts: OtpOptions): void {
-  if (opts.tier !== 1 && opts.tier !== 2) {
-    throw new Error("otp(): tier is required — set tier: 1 or tier: 2 (no auto-detect)");
+  if (opts.mode !== "provider" && opts.mode !== "app") {
+    throw new Error(
+      'otp(): mode is required — set mode: "provider" or mode: "app" (no auto-detect)',
+    );
   }
-  if (opts.tier === 1) {
+  if (opts.mode === "provider") {
     if ("channels" in opts && opts.channels !== undefined) {
       throw new Error(
-        "otp({ tier: 1 }): channels are forbidden — provider-owned OTP cannot resend via a different channel; use tier: 2 for multi-channel",
+        'otp({ mode: "provider" }): channels are forbidden — provider-owned OTP cannot resend via a different channel; use mode: "app" for multi-channel',
       );
     }
     if ("exposeDevOtp" in opts && (opts as { exposeDevOtp?: boolean }).exposeDevOtp === true) {
       throw new Error(
-        "otp({ tier: 1 }): exposeDevOtp is forbidden — the code never exists server-side",
+        'otp({ mode: "provider" }): exposeDevOtp is forbidden — the code never exists server-side',
       );
     }
     return;
@@ -155,12 +157,12 @@ function assertOtpOptions(opts: OtpOptions): void {
   const channels = opts.channels;
   if (!channels || channels.length === 0) {
     throw new Error(
-      'otp({ tier: 2 }): channels is required — declare at least one of "sms" | "whatsapp" | "email"',
+      'otp({ mode: "app" }): channels is required — declare at least one of "sms" | "whatsapp" | "email"',
     );
   }
   for (const ch of channels) {
     if (!(OTP_CHANNELS as readonly string[]).includes(ch)) {
-      throw new Error(`otp({ tier: 2 }): unknown channel "${String(ch)}"`);
+      throw new Error(`otp({ mode: "app" }): unknown channel "${String(ch)}"`);
     }
   }
 }
@@ -186,9 +188,9 @@ function pickRequestChannel(
 }
 
 /**
- * Unified OTP request + verify (+ Tier-2 resend).
+ * Unified OTP request + verify (+ app-mode resend).
  *
- * @param opts - Must include `tier: 1` or `tier: 2`
+ * @param opts - Must include `mode: "provider"` or `mode: "app"`
  */
 export function otp(opts: OtpOptions): PluginDef {
   assertOtpOptions(opts);
@@ -200,12 +202,12 @@ export function otp(opts: OtpOptions): PluginDef {
   const verifications = opts.verifications ?? createVerificationStore();
   const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
   const resendCooldownMs =
-    opts.tier === 2
+    opts.mode === "app"
       ? (opts.resendCooldownMs ?? DEFAULT_RESEND_COOLDOWN_MS)
       : DEFAULT_RESEND_COOLDOWN_MS;
-  const channels = opts.tier === 2 ? opts.channels : ([] as const);
-  const exposeDevOtp = opts.tier === 2 && opts.exposeDevOtp === true;
-  const from = opts.tier === 2 ? opts.from : undefined;
+  const channels = opts.mode === "app" ? opts.channels : ([] as const);
+  const exposeDevOtp = opts.mode === "app" && opts.exposeDevOtp === true;
+  const from = opts.mode === "app" ? opts.from : undefined;
 
   const emailTmpl =
     from !== undefined
@@ -223,9 +225,9 @@ export function otp(opts: OtpOptions): PluginDef {
   } as const;
 
   const configSnapshot: OtpPluginConfig =
-    opts.tier === 1
-      ? { method: "otp", tier: 1 }
-      : { method: "otp", tier: 2, channels: [...channels] };
+    opts.mode === "provider"
+      ? { method: "otp", mode: "provider" }
+      : { method: "otp", mode: "app", channels: [...channels] };
 
   const requestOut = z.object({
     ok: z.literal(true),
@@ -233,7 +235,7 @@ export function otp(opts: OtpOptions): PluginDef {
     channel: z.enum(["sms", "whatsapp", "email"]).optional(),
   });
 
-  if (opts.tier === 1) {
+  if (opts.mode === "provider") {
     const request = flow({
       name: "auth.requestOtp",
       unit: "auth",
@@ -270,7 +272,7 @@ export function otp(opts: OtpOptions): PluginDef {
           phone,
           sealedOtp: null,
         });
-        // Tier 1: resend-via-different-channel is impossible — provider owns the code.
+        // Provider mode: resend-via-different-channel is impossible — provider owns the code.
         return { ok: true as const, channel: "sms" as const };
       },
     });
@@ -344,7 +346,7 @@ export function otp(opts: OtpOptions): PluginDef {
       .binding(bindPublicAuth("/otp/verify", verify, "otp"));
   }
 
-  // ── Tier 2 ────────────────────────────────────────────────────────────
+  // ── App mode ───────────────────────────────────────────────────────────
   const request = flow({
     name: "auth.requestOtp",
     unit: "auth",

package/src/plugins/taqnyat.live.test.ts

@@ -1,5 +1,5 @@
 /**
- * Real Taqnyat end-to-end: otp({ tier: 1 }) via Verify API + magic-link via Taqnyat Mail.
+ * Real Taqnyat end-to-end: otp({ mode: "provider" }) via Verify API + magic-link via Taqnyat Mail.
  *
  * Double-gated — runs ONLY when BOTH:
  *   1. The global per-medium opt-in flag is set explicitly
@@ -82,7 +82,7 @@ if (!LIVE_MAIL) {
 const liveSms = LIVE_SMS ? test : test.skip;
 const liveMail = LIVE_MAIL ? test : test.skip;
 
-describe("taqnyat live — provider-managed OTP (Taqnyat Verify)", () => {
+describe("taqnyat live — provider OTP (Taqnyat Verify)", () => {
   liveSms(
     "phone OTP request → real sendOtp → Taqnyat success code 5",
     async () => {
@@ -94,7 +94,7 @@ describe("taqnyat live — provider-managed OTP (Taqnyat Verify)", () => {
         config: {
           drivers: { channel: { sms: { test: "taqnyat" } } },
         },
-      }).plug(otp({ tier: 1 }));
+      }).plug(otp({ mode: "provider" }));
       await app.boot({ env: "test" });
 
       // Wrap the live transport so the plugin's single real send also proves

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;
+}