okengine 0.1.4

package/src/console/ui/overview/compose.ts

@@ -0,0 +1,133 @@
+/**
+ * Compose the Overview view from every panel's outputs (console §9.16).
+ *
+ * Pure aggregator — no finding detection lives here.
+ */
+
+import type { Manifest } from "../../../manifest/types.ts";
+import type { AiListResponse } from "../ai/types.ts";
+import { buildCausalityGraph } from "../flows/graph.ts";
+import type { CausalityGraph } from "../flows/graph.ts";
+import type { DiffListResponse } from "../diff/types.ts";
+import { whatChangedSummary } from "../diff/summary.ts";
+import type { GatesListResponse } from "../gates/types.ts";
+import type { ClockListResponse } from "../clock/types.ts";
+import type { SignalRecord } from "../signals/types.ts";
+import type { VaultListResponse } from "../vault/types.ts";
+import type { ChannelsListResponse } from "../channels/types.ts";
+import type { AccessListResponse } from "../access/types.ts";
+import type { RunRecord } from "../runs/types.ts";
+import { firstSloInvite } from "./busiest.ts";
+import { computeCostBudgets } from "./cost.ts";
+import { computeGoldenSignals } from "./golden.ts";
+import { rankedFindings } from "./rank.ts";
+import { computeSloBurns, hasDeclaredSlos } from "./slo.ts";
+import type { OverviewView } from "./types.ts";
+import { composeVerdict } from "./verdict.ts";
+
+/** Panel snapshots Overview aggregates. */
+export interface OverviewInputs {
+  readonly manifest: Manifest | null;
+  readonly runs: readonly RunRecord[];
+  readonly gates: GatesListResponse | null;
+  readonly signals: readonly SignalRecord[];
+  readonly clock: ClockListResponse | null;
+  readonly vault: VaultListResponse | null;
+  readonly channels: ChannelsListResponse | null;
+  readonly ai: AiListResponse | null;
+  readonly diff: DiffListResponse | null;
+  readonly access: AccessListResponse | null;
+  readonly now: number;
+  /** Optional prebuilt graph (tests); otherwise built from Manifest. */
+  readonly architectureGraph?: CausalityGraph | null;
+}
+
+/**
+ * Compose Overview from real panel projections.
+ *
+ * @param inputs - Aggregated panel data
+ */
+export function composeOverview(inputs: OverviewInputs): OverviewView {
+  const {
+    manifest,
+    runs,
+    gates,
+    signals,
+    clock,
+    vault,
+    channels,
+    ai,
+    diff,
+    access,
+    now,
+  } = inputs;
+
+  const graph =
+    inputs.architectureGraph !== undefined
+      ? inputs.architectureGraph
+      : manifest
+        ? buildCausalityGraph(manifest)
+        : null;
+
+  const declared = hasDeclaredSlos(manifest);
+  const slos = computeSloBurns({ manifest, runs, now });
+  const costBudgets = computeCostBudgets({ manifest, ai, runs, now });
+  const findings = rankedFindings({
+    gatesAudit: gates?.audit ?? {
+      unguardedFlows: [],
+      orphanPermissions: [],
+      emptyRoles: [],
+      unattachedGates: [],
+    },
+    signals,
+    crons: clock?.crons ?? [],
+    vaultSecrets: vault?.secrets ?? [],
+    channelOutcomes: channels?.outcomes ?? [],
+    architectureGraph: graph,
+    diffChanges: diff?.changes ?? [],
+    aiVersions: ai?.versions ?? [],
+    accessHygiene: access?.hygiene ?? {
+      unusedKeys: [],
+      neverSignedInOperators: [],
+      expiredInvitations: [],
+    },
+    now,
+  });
+  const whatChanged = diff
+    ? (() => {
+        const s = whatChangedSummary(diff);
+        return {
+          hasBaseline: s.hasBaseline,
+          severity: s.severity,
+          changeCount: s.changeCount,
+          line: s.line,
+          href: s.href,
+        };
+      })()
+    : {
+        hasBaseline: false,
+        severity: null,
+        changeCount: 0,
+        line: "Manifest Diff unavailable",
+        href: "/diff",
+      };
+  const golden = computeGoldenSignals(runs, now);
+  const invite = declared ? null : firstSloInvite(runs);
+  const verdict = composeVerdict({
+    hasDeclaredSlos: declared,
+    slos,
+    costBudgets,
+    findings,
+  });
+
+  return {
+    verdict,
+    slos,
+    costBudgets,
+    whatChanged,
+    findings,
+    golden,
+    firstSloInvite: invite,
+    hasDeclaredSlos: declared,
+  };
+}

package/src/console/ui/overview/cost.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Cost budgets — same model as error budgets (console §9.16).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { computeCostBudgets } from "./cost.ts";
+import {
+  OVERVIEW_BURN_RUNS,
+  OVERVIEW_INPUTS_FIXTURE,
+  OVERVIEW_MANIFEST,
+  OVERVIEW_NOW,
+} from "./fixture.ts";
+
+describe("computeCostBudgets", () => {
+  test("reads declared flow budget and real Runs spend", () => {
+    const budgets = computeCostBudgets({
+      manifest: OVERVIEW_MANIFEST,
+      ai: OVERVIEW_INPUTS_FIXTURE.ai,
+      runs: OVERVIEW_BURN_RUNS,
+      now: OVERVIEW_NOW,
+    });
+    const flow = budgets.find((b) => b.id === "flow:bookings.create");
+    expect(flow).toBeDefined();
+    expect(flow!.declaredBudget).toBe(10);
+    // 100 runs × $0.05 = $5
+    expect(flow!.spent).toBeCloseTo(5, 5);
+    expect(flow!.burnRate).toBeCloseTo(0.5, 5);
+  });
+
+  test("includes AI prompt budgets from panel metrics", () => {
+    const budgets = computeCostBudgets({
+      manifest: OVERVIEW_MANIFEST,
+      ai: OVERVIEW_INPUTS_FIXTURE.ai,
+      runs: OVERVIEW_BURN_RUNS,
+      now: OVERVIEW_NOW,
+    });
+    expect(budgets.some((b) => b.kind === "ai-prompt")).toBe(true);
+  });
+});

package/src/console/ui/overview/cost.ts

@@ -0,0 +1,138 @@
+/**
+ * Cost budgets in the same mental model as error budgets (console §9.16).
+ *
+ * Declared budget, burn rate, projected exhaustion — from Manifest flow
+ * budgets and AI panel metrics + real Runs spend.
+ */
+
+import type { Manifest } from "../../../manifest/types.ts";
+import type { AiListResponse } from "../ai/types.ts";
+import type { RunRecord } from "../runs/types.ts";
+import type { CostBudget } from "./types.ts";
+
+/** Rolling window for cost burn (7 days). */
+export const COST_WINDOW_MS = 7 * 86_400_000;
+
+/**
+ * Project cost budgets from Manifest declarations + AI/Runs spend.
+ *
+ * @param options - Manifest, AI list, runs, clock
+ */
+export function computeCostBudgets(options: {
+  readonly manifest: Manifest | null;
+  readonly ai: AiListResponse | null;
+  readonly runs: readonly RunRecord[];
+  readonly now: number;
+}): readonly CostBudget[] {
+  const { manifest, ai, runs, now } = options;
+  const from = now - COST_WINDOW_MS;
+  const out: CostBudget[] = [];
+
+  for (const [name, flow] of Object.entries(manifest?.flows ?? {})) {
+    const budget = flow.cost?.budget;
+    if (budget == null || budget <= 0) continue;
+    const spent = sumCost(
+      runs.filter(
+        (r) => r.flow === name && r.startedAt >= from && r.startedAt <= now,
+      ),
+    );
+    out.push(budgetRow({
+      id: `flow:${name}`,
+      name,
+      kind: "flow",
+      declaredBudget: budget,
+      spent,
+      windowMs: COST_WINDOW_MS,
+    }));
+  }
+
+  if (ai) {
+    for (const prompt of ai.prompts) {
+      const cap = prompt.budgetMaxCostPerCall;
+      if (cap == null || cap <= 0) continue;
+      const version =
+        ai.versions.find(
+          (v) => v.prompt === prompt.name && v.version === prompt.version,
+        ) ??
+        ai.versions
+          .filter((v) => v.prompt === prompt.name)
+          .sort((a, b) => b.version - a.version)[0];
+      if (!version || version.sampleCount === 0) continue;
+      // Per-call budget × samples in window ≈ declared period budget.
+      const declaredBudget = cap * version.sampleCount;
+      const spent = version.cost.mean * version.sampleCount;
+      out.push(budgetRow({
+        id: `ai-prompt:${prompt.name}@${version.version}`,
+        name: `${prompt.name}@${version.version}`,
+        kind: "ai-prompt",
+        declaredBudget,
+        spent,
+        windowMs: COST_WINDOW_MS,
+      }));
+    }
+
+    for (const agent of ai.agents) {
+      const cap = agent.budgetMaxCostPerRun;
+      if (cap == null || cap <= 0) continue;
+      const agentRuns = ai.agentRuns.filter((r) => r.agent === agent.name);
+      if (agentRuns.length === 0) continue;
+      const declaredBudget = cap * agentRuns.length;
+      const spent = agentRuns.reduce((a, r) => a + r.cost, 0);
+      out.push(budgetRow({
+        id: `ai-agent:${agent.name}`,
+        name: agent.name,
+        kind: "ai-agent",
+        declaredBudget,
+        spent,
+        windowMs: COST_WINDOW_MS,
+      }));
+    }
+  }
+
+  return out.sort(
+    (a, b) =>
+      b.burnRate - a.burnRate || a.name.localeCompare(b.name),
+  );
+}
+
+function budgetRow(input: {
+  readonly id: string;
+  readonly name: string;
+  readonly kind: CostBudget["kind"];
+  readonly declaredBudget: number;
+  readonly spent: number;
+  readonly windowMs: number;
+}): CostBudget {
+  const { declaredBudget, spent, windowMs } = input;
+  const burnRate = declaredBudget <= 0 ? 0 : spent / declaredBudget;
+  const remainingFraction = Math.max(
+    0,
+    1 - (declaredBudget <= 0 ? 0 : spent / declaredBudget),
+  );
+  let timeToExhaustionMs: number | null = null;
+  if (spent > 0 && burnRate > 0 && remainingFraction > 0) {
+    // At current spend pace, remaining budget lasts:
+    const spendPerMs = spent / windowMs;
+    if (spendPerMs > 0) {
+      timeToExhaustionMs = (declaredBudget - spent) / spendPerMs;
+    }
+  } else if (burnRate >= 1 && remainingFraction <= 0) {
+    timeToExhaustionMs = 0;
+  }
+
+  return {
+    id: input.id,
+    name: input.name,
+    kind: input.kind,
+    declaredBudget,
+    spent,
+    burnRate,
+    remainingFraction,
+    timeToExhaustionMs,
+    windowMs,
+  };
+}
+
+function sumCost(runs: readonly RunRecord[]): number {
+  return runs.reduce((a, r) => a + (r.cost ?? 0), 0);
+}

package/src/console/ui/overview/fixture.ts

@@ -0,0 +1,161 @@
+/**
+ * Overview fixtures for unit tests and the axe gate (console §9.16).
+ */
+
+import type { Manifest } from "../../../manifest/types.ts";
+import { ACCESS_LIST_FIXTURE } from "../access/fixture.ts";
+import { AI_LIST_FIXTURE } from "../ai/fixture.ts";
+import { ARCHITECTURE_TEST_MANIFEST } from "../architecture/fixture.ts";
+import { CHANNELS_LIST_FIXTURE } from "../channels/fixture.ts";
+import { CLOCK_LIST_FIXTURE } from "../clock/fixture.ts";
+import { DIFF_LIST_FIXTURE } from "../diff/fixture.ts";
+import { GATES_LIST_FIXTURE } from "../gates/fixture.ts";
+import { rowToRun } from "../runs/project.ts";
+import type { RunRecord } from "../runs/types.ts";
+import { SIGNALS_FIXTURE } from "../signals/fixture.ts";
+import { VAULT_LIST_FIXTURE } from "../vault/fixture.ts";
+import type { OverviewInputs } from "./compose.ts";
+
+/** Fixed clock for deterministic burn / ceremonial math. */
+export const OVERVIEW_NOW = 1_700_000_000_000;
+
+/** Manifest with flow + journey SLOs and a cost budget. */
+export const OVERVIEW_MANIFEST: Manifest = {
+  ...ARCHITECTURE_TEST_MANIFEST,
+  app: "skyport-overview-test",
+  flows: {
+    ...ARCHITECTURE_TEST_MANIFEST.flows,
+    "bookings.create": {
+      ...(ARCHITECTURE_TEST_MANIFEST.flows?.["bookings.create"] ?? {
+        plane: "user",
+        gates: ["member"],
+      }),
+      slo: { availability: "99.9%", latency: { p99: "200ms" } },
+      cost: { budget: 10, estimatePerCall: 0.01 },
+    },
+  },
+  journeys: {
+    "book-a-flight": {
+      slo: { availability: "99.5%" },
+      flows: ["bookings.create"],
+    },
+  },
+  plugins: {
+    audit: {
+      version: "1.0.0",
+      declares: ["console.panel"],
+      intercepts: ["afterHandle"],
+    },
+  },
+};
+
+/** Diff fixture with a plugin capability widening. */
+export const OVERVIEW_DIFF_FIXTURE = {
+  ...DIFF_LIST_FIXTURE,
+  changes: [
+    ...DIFF_LIST_FIXTURE.changes,
+    {
+      path: "/plugins/audit/intercepts",
+      category: "permission-widening" as const,
+      kind: "added" as const,
+      summary: "plugin capabilities widened: intercepts afterHandle",
+      flowName: null,
+      runCountLastWeek: 0,
+      blastLine: null,
+      weeklyDeltaUsd: null,
+      weeklyBillLine: null,
+      ciGate: null,
+    },
+  ],
+};
+
+/** Vault list with one dormant secret (never read). */
+export const OVERVIEW_VAULT_FIXTURE = {
+  ...VAULT_LIST_FIXTURE,
+  secrets: [
+    ...VAULT_LIST_FIXTURE.secrets,
+    {
+      name: "LEGACY_WEBHOOK_SECRET",
+      kind: "secret" as const,
+      sensitive: true,
+      fingerprints: { dev: "sha256:cccccccccccccccc" },
+      fingerprint: "sha256:cccccccccccccccc",
+      cleartext: null,
+      winner: ".env.local" as const,
+      resolution: [
+        { source: "process.env" as const, present: false, won: false },
+        { source: ".env.local" as const, present: true, won: true },
+        { source: ".env.stack" as const, present: false, won: false },
+        { source: "driver" as const, present: false, won: false },
+        { source: "dev-fallback" as const, present: false, won: false },
+      ],
+      readers: [],
+      blastRadius: {
+        count: 0,
+        longestWakeAt: null,
+        longestOutstandingMs: null,
+        runIds: [],
+      },
+      lastReadAt: null,
+      sharedFingerprintEnvs: [],
+    },
+  ],
+};
+
+/**
+ * Runs that burn bookings.create in the short window
+ * (error rate ≫ 0.1% tolerable for 99.9%).
+ */
+export const OVERVIEW_BURN_RUNS: readonly RunRecord[] = Array.from(
+  { length: 100 },
+  (_, i) =>
+    rowToRun({
+      id: `burn-${i}`,
+      flow: "bookings.create",
+      unit: "bookings",
+      trigger: "http",
+      plane: "user",
+      cache: "none",
+      cost: 0.05,
+      startedAt: OVERVIEW_NOW - 30 * 60_000 + i * 1_000,
+      endedAt: OVERVIEW_NOW - 30 * 60_000 + i * 1_000 + 40,
+      durationMs: 40,
+      error: i < 20 ? "Timeout" : null,
+      effects: [],
+      logs: [],
+      dimensions: {
+        flow: "bookings.create",
+        error_code: i < 20 ? "Timeout" : null,
+      },
+    }),
+);
+
+/** Full Overview inputs — burning SLO + multi-panel findings. */
+export const OVERVIEW_INPUTS_FIXTURE: OverviewInputs = {
+  manifest: OVERVIEW_MANIFEST,
+  runs: OVERVIEW_BURN_RUNS,
+  gates: GATES_LIST_FIXTURE,
+  signals: SIGNALS_FIXTURE,
+  clock: CLOCK_LIST_FIXTURE,
+  vault: OVERVIEW_VAULT_FIXTURE,
+  channels: CHANNELS_LIST_FIXTURE,
+  ai: AI_LIST_FIXTURE,
+  diff: OVERVIEW_DIFF_FIXTURE,
+  access: ACCESS_LIST_FIXTURE,
+  now: OVERVIEW_NOW,
+};
+
+/** Day-one inputs — no SLOs declared. */
+export const OVERVIEW_DAY_ONE_INPUTS: OverviewInputs = {
+  ...OVERVIEW_INPUTS_FIXTURE,
+  manifest: {
+    ...OVERVIEW_MANIFEST,
+    flows: Object.fromEntries(
+      Object.entries(OVERVIEW_MANIFEST.flows ?? {}).map(([k, f]) => [
+        k,
+        { ...f, slo: undefined },
+      ]),
+    ),
+    journeys: undefined,
+  },
+};

package/src/console/ui/overview/golden.ts

@@ -0,0 +1,57 @@
+/**
+ * Golden signals from the Runs store (console §9.16 day-one empty state).
+ *
+ * Latency · traffic · errors · saturation — four numbers, one store.
+ */
+
+import type { RunRecord } from "../runs/types.ts";
+import type { GoldenSignals } from "./types.ts";
+
+/** Window for golden-signal rates (1 hour). */
+export const GOLDEN_WINDOW_MS = 60 * 60 * 1000;
+
+/** Replica lag (ms) treated as saturating. */
+export const SATURATION_LAG_MS = 200;
+
+/**
+ * Compute golden signals from real Runs.
+ *
+ * @param runs - Wide-event population
+ * @param now - Clock
+ */
+export function computeGoldenSignals(
+  runs: readonly RunRecord[],
+  now: number,
+): GoldenSignals {
+  const from = now - GOLDEN_WINDOW_MS;
+  const window = runs.filter(
+    (r) => r.startedAt >= from && r.startedAt <= now,
+  );
+  const n = window.length;
+  const errors = window.filter((r) => !!r.error).length;
+  const durations = window.map((r) => r.durationMs).sort((a, b) => a - b);
+  const saturated = window.filter(
+    (r) =>
+      (r.replicaLagMs != null && r.replicaLagMs > SATURATION_LAG_MS) ||
+      r.cache === "miss",
+  ).length;
+
+  return {
+    latencyP99Ms: percentile(durations, 0.99),
+    trafficPerMin: n === 0 ? 0 : n / (GOLDEN_WINDOW_MS / 60_000),
+    errorRate: n === 0 ? 0 : errors / n,
+    saturation: n === 0 ? 0 : saturated / n,
+    sampleCount: n,
+    windowMs: GOLDEN_WINDOW_MS,
+  };
+}
+
+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]!;
+}

package/src/console/ui/overview/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Overview panel pure modules (console §9.16).
+ */
+
+export type {
+  CostBudget,
+  FindingSource,
+  FirstSloInvite,
+  GoldenSignals,
+  OverviewFinding,
+  OverviewVerdict,
+  OverviewView,
+  SloBurn,
+  WhatChanged,
+} from "./types.ts";
+
+export {
+  composeOverview,
+  type OverviewInputs,
+} from "./compose.ts";
+
+export {
+  declaredSlos,
+  computeSloBurns,
+  hasDeclaredSlos,
+  parseAvailability,
+  BURN_SHORT_WINDOW_MS,
+  BURN_LONG_WINDOW_MS,
+  CEREMONIAL_LOOKBACK_MS,
+} from "./slo.ts";
+
+export { computeCostBudgets, COST_WINDOW_MS } from "./cost.ts";
+
+export { computeGoldenSignals, GOLDEN_WINDOW_MS } from "./golden.ts";
+
+export { firstSloInvite } from "./busiest.ts";
+
+export {
+  rankedFindings,
+  compareFindings,
+  type FindingInputs,
+} from "./rank.ts";
+
+export {
+  composeVerdict,
+  formatExhaustion,
+  formatBurnRate,
+  formatBudgetDuration,
+} from "./verdict.ts";
+
+export {
+  OVERVIEW_NOW,
+  OVERVIEW_MANIFEST,
+  OVERVIEW_INPUTS_FIXTURE,
+  OVERVIEW_DAY_ONE_INPUTS,
+  OVERVIEW_BURN_RUNS,
+  OVERVIEW_DIFF_FIXTURE,
+  OVERVIEW_VAULT_FIXTURE,
+} from "./fixture.ts";