okengine 0.1.4

package/src/console/ui/architecture/search.ts

@@ -0,0 +1,145 @@
+/**
+ * URL search state for the Architecture panel (console §7 · §9.13).
+ *
+ * Focus, depth, and layer toggles live in the URL so a pasted link
+ * reproduces the exact view.
+ */
+
+import { z } from "zod";
+import {
+  DEFAULT_LAYERS,
+  ELEMENT_LAYERS,
+  type ElementLayer,
+  type FocusDepth,
+  type LayerFlags,
+} from "./types.ts";
+
+const searchBool = z
+  .union([z.boolean(), z.literal("true"), z.literal("false")])
+  .transform((v) => v === true || v === "true");
+
+/** Zod schema for Architecture URL search params. */
+export const ArchitectureSearchSchema = z.object({
+  /** Focus node id (`unit:bookings`, `flow:bookings.create`, `sql:bookings`). */
+  focus: z.string().optional(),
+  /** Neighbourhood depth when focused. */
+  depth: z.union([z.literal(1), z.literal(2), z.literal("1"), z.literal("2")])
+    .transform((v) => (Number(v) === 2 ? 2 : 1) as FocusDepth)
+    .default(1),
+  /** Data (Store) layer. */
+  data: searchBool.optional(),
+  /** Messaging (Signal) layer. */
+  messaging: searchBool.optional(),
+  /** Time (Clock) layer. */
+  time: searchBool.optional(),
+  /** External (Channel/AI) layer. */
+  external: searchBool.optional(),
+});
+
+/** Parsed Architecture URL search. */
+export type ArchitectureSearch = {
+  readonly focus?: string;
+  readonly depth: FocusDepth;
+  readonly data?: boolean;
+  readonly messaging?: boolean;
+  readonly time?: boolean;
+  readonly external?: boolean;
+};
+
+/**
+ * Parse Architecture panel search params.
+ *
+ * @param search - Raw router search
+ */
+export function parseArchitectureSearch(
+  search: Record<string, unknown>,
+): ArchitectureSearch {
+  const parsed = ArchitectureSearchSchema.safeParse(search);
+  if (!parsed.success) {
+    return { depth: 1 };
+  }
+  return parsed.data;
+}
+
+/**
+ * Serialize Architecture search for navigation (omit defaults).
+ *
+ * @param search - Search state
+ */
+export function serializeArchitectureSearch(
+  search: ArchitectureSearch,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (search.focus) out.focus = search.focus;
+  if (search.depth === 2) out.depth = "2";
+  for (const layer of ELEMENT_LAYERS) {
+    const value = search[layer];
+    if (value === false) out[layer] = "false";
+  }
+  return out;
+}
+
+/**
+ * Resolve layer flags from URL search (absent → on).
+ *
+ * @param search - Parsed search
+ */
+export function layersOf(search: ArchitectureSearch): LayerFlags {
+  return {
+    data: search.data ?? DEFAULT_LAYERS.data,
+    messaging: search.messaging ?? DEFAULT_LAYERS.messaging,
+    time: search.time ?? DEFAULT_LAYERS.time,
+    external: search.external ?? DEFAULT_LAYERS.external,
+  };
+}
+
+/**
+ * Focus a node (unit / flow / resource).
+ *
+ * @param search - Current search
+ * @param focus - Node id
+ */
+export function focusNode(
+  search: ArchitectureSearch,
+  focus: string,
+): ArchitectureSearch {
+  return { ...search, focus };
+}
+
+/**
+ * Clear focus — return to unit-cluster overview.
+ *
+ * @param search - Current search
+ */
+export function clearFocus(search: ArchitectureSearch): ArchitectureSearch {
+  const { focus: _f, ...rest } = search;
+  return { ...rest, depth: search.depth };
+}
+
+/**
+ * Set neighbourhood depth.
+ *
+ * @param search - Current search
+ * @param depth - 1 or 2
+ */
+export function setDepth(
+  search: ArchitectureSearch,
+  depth: FocusDepth,
+): ArchitectureSearch {
+  return { ...search, depth };
+}
+
+/**
+ * Toggle one element layer in URL state.
+ *
+ * @param search - Current search
+ * @param layer - Layer
+ * @param on - Desired visibility
+ */
+export function setLayerSearch(
+  search: ArchitectureSearch,
+  layer: ElementLayer,
+  on: boolean,
+): ArchitectureSearch {
+  return { ...search, [layer]: on };
+}

package/src/console/ui/architecture/traffic.ts

@@ -0,0 +1,102 @@
+/**
+ * Observed edge traffic from Runs (console §9.13).
+ *
+ * Edge thickness is real traffic, not declaration. A dashed edge is
+ * declared in code and never traversed.
+ */
+
+import type { EffectKind } from "../../../kernel/effects.ts";
+import type { RunRecord } from "../runs/types.ts";
+
+/**
+ * Normalise a recorded effect resource to the causality effect-ref form.
+ *
+ * @param kind - Effect kind from the run ledger
+ * @param resource - Raw resource string on the run
+ */
+export function normalizeTrafficRef(
+  kind: EffectKind,
+  resource: string,
+): string {
+  switch (kind) {
+    case "emit":
+      return resource.startsWith("signal:") ? resource : `signal:${resource}`;
+    case "send":
+      return resource.startsWith("channel:")
+        ? resource
+        : `channel:${resource}`;
+    case "ask":
+      return resource.startsWith("ai:") ? resource : `ai:${resource}`;
+    case "secret":
+      return resource.startsWith("secret:") ? resource : `secret:${resource}`;
+    case "call":
+      return resource.startsWith("flow:") ? resource : `flow:${resource}`;
+    default:
+      return resource;
+  }
+}
+
+/**
+ * Stable key for a flow → resource relationship.
+ *
+ * @param flowId - Flow id
+ * @param ref - Normalised effect ref
+ */
+export function trafficEdgeKey(flowId: string, ref: string): string {
+  return `${flowId}\0${ref}`;
+}
+
+/**
+ * Count observed traversals of each declared flow→resource edge from Runs.
+ *
+ * @param runs - Wide-event population
+ */
+export function observeTraffic(
+  runs: readonly RunRecord[],
+): ReadonlyMap<string, number> {
+  const counts = new Map<string, number>();
+  for (const run of runs) {
+    for (const effect of run.effects) {
+      const ref = normalizeTrafficRef(effect.kind, effect.resource);
+      const key = trafficEdgeKey(run.flow, ref);
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    // Flow invocation itself counts as traversal of call edges into this flow
+    // when a parent exists — parent.flow → flow:run.flow
+    if (run.parentId) {
+      // Parent resolution is optional; call traffic is also recorded as effects.
+    }
+  }
+  return counts;
+}
+
+/**
+ * Look up traversals for a flow→resource edge.
+ *
+ * @param traffic - Observed map
+ * @param flowId - Flow id
+ * @param ref - Effect ref
+ */
+export function traversalsOf(
+  traffic: ReadonlyMap<string, number>,
+  flowId: string,
+  ref: string,
+): number {
+  return traffic.get(trafficEdgeKey(flowId, ref)) ?? 0;
+}
+
+/**
+ * Map absolute traversal counts to stroke thickness 1–8.
+ *
+ * @param traversals - Observed count
+ * @param maxTraversals - Max among visible edges (for relative scale)
+ */
+export function thicknessOf(
+  traversals: number,
+  maxTraversals: number,
+): number {
+  if (traversals <= 0) return 1;
+  if (maxTraversals <= 1) return 2;
+  const ratio = traversals / maxTraversals;
+  return Math.max(1, Math.min(8, Math.ceil(ratio * 8)));
+}

package/src/console/ui/architecture/types.ts

@@ -0,0 +1,144 @@
+/**
+ * Architecture panel domain types (console §9.13).
+ *
+ * Second rendering of the Flows causality graph — shape, not which-one.
+ */
+
+/** Toggleable element layers — edges are typed, not merely grouped. */
+export type ElementLayer = "data" | "messaging" | "time" | "external";
+
+/** All toggleable layers in display order. */
+export const ELEMENT_LAYERS: readonly ElementLayer[] = [
+  "data",
+  "messaging",
+  "time",
+  "external",
+] as const;
+
+/** Human labels for element layers. */
+export const LAYER_LABEL: Readonly<Record<ElementLayer, string>> = {
+  data: "Data",
+  messaging: "Messaging",
+  time: "Time",
+  external: "External",
+};
+
+/** Node kinds on the architecture diagram. */
+export type ArchitectureNodeKind =
+  | "unit"
+  | "flow"
+  | "resource"
+  | "external";
+
+/**
+ * One node on the architecture diagram.
+ *
+ * Default view uses unit clusters; focus expands flows / resources at depth.
+ */
+export interface ArchitectureNode {
+  /** Stable id (`unit:bookings`, `flow:bookings.create`, `sql:bookings`). */
+  readonly id: string;
+  /** Visual / semantic kind. */
+  readonly kind: ArchitectureNodeKind;
+  /** Human label. */
+  readonly label: string;
+  /** Owning unit when applicable. */
+  readonly unit?: string;
+  /** Element layer for resources (typed edges). */
+  readonly layer?: ElementLayer;
+  /** True when inside the drawn system boundary. */
+  readonly insideBoundary: boolean;
+  /** Flow count for unit clusters. */
+  readonly flowCount?: number;
+  /** True when this node is the current focus. */
+  readonly focused?: boolean;
+  /** Hop distance from focus (0 = focus). */
+  readonly depth?: number;
+}
+
+/**
+ * One declared (and optionally observed) edge.
+ *
+ * Thickness comes from Runs traffic; dashed means declared but never traversed.
+ */
+export interface ArchitectureEdge {
+  /** Stable id. */
+  readonly id: string;
+  /** Source node id. */
+  readonly from: string;
+  /** Target node id. */
+  readonly to: string;
+  /**
+   * Element layer, or `call` for structural flow→flow portals
+   * (always shown; not behind a layer toggle).
+   */
+  readonly layer: ElementLayer | "call";
+  /** Declared in the Manifest / causality graph. */
+  readonly declared: boolean;
+  /** Observed traversals from Runs. */
+  readonly traversals: number;
+  /** `declared && traversals === 0` — dead relationship. */
+  readonly dashed: boolean;
+  /** Stroke weight 1–8 from relative traffic. */
+  readonly thickness: number;
+  /** Aggregated across flows when clustered by unit. */
+  readonly aggregated: boolean;
+}
+
+/** Computed pathology kinds (findings list, not decoration). */
+export type PathologyKind =
+  | "cycle"
+  | "god-node"
+  | "orphan-signal"
+  | "spof";
+
+/** One diagnostic finding from the graph-as-data. */
+export interface ArchitectureFinding {
+  /** Pathology class. */
+  readonly kind: PathologyKind;
+  /** Ranking hint for Overview union. */
+  readonly severity: "warning" | "critical";
+  /** Short title. */
+  readonly title: string;
+  /** Plain-language detail. */
+  readonly detail: string;
+  /** Related node ids. */
+  readonly nodeIds: readonly string[];
+}
+
+/** Focus depth — neighbourhood hops from the selected node. */
+export type FocusDepth = 1 | 2;
+
+/** Layer visibility map. */
+export type LayerFlags = Readonly<Record<ElementLayer, boolean>>;
+
+/** Default: every typed layer on. */
+export const DEFAULT_LAYERS: LayerFlags = {
+  data: true,
+  messaging: true,
+  time: true,
+  external: true,
+};
+
+/**
+ * Fully projected architecture view for one Manifest + Runs population.
+ */
+export interface ArchitectureView {
+  /** Visible nodes (clustered or focused neighbourhood). */
+  readonly nodes: readonly ArchitectureNode[];
+  /** Visible edges after layer + focus filters. */
+  readonly edges: readonly ArchitectureEdge[];
+  /**
+   * Distinct Manifest external effects (channel/ai) that flows touch —
+   * the boundary-crossing metric (§9.13).
+   */
+  readonly boundaryCrossingCount: number;
+  /** Computed pathologies. */
+  readonly findings: readonly ArchitectureFinding[];
+  /** Current focus node id, or null for unit-cluster overview. */
+  readonly focus: string | null;
+  /** Neighbourhood depth when focused. */
+  readonly depth: FocusDepth;
+  /** Active element layers. */
+  readonly layers: LayerFlags;
+}

package/src/console/ui/architecture/view.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Architecture view — cluster default, focus depth, layers, traffic (§9.13).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { buildCausalityGraph } from "../flows/graph.ts";
+import { boundaryCrossingCount } from "./boundary.ts";
+import {
+  ARCHITECTURE_RUNS_FIXTURE,
+  ARCHITECTURE_TEST_MANIFEST,
+} from "./fixture.ts";
+import { computePathologies } from "./pathologies.ts";
+import {
+  layersOf,
+  parseArchitectureSearch,
+  serializeArchitectureSearch,
+} from "./search.ts";
+import { observeTraffic, thicknessOf } from "./traffic.ts";
+import { buildArchitectureView } from "./view.ts";
+
+describe("architecture view", () => {
+  const graph = buildCausalityGraph(ARCHITECTURE_TEST_MANIFEST);
+
+  test("reuses Flows causality graph — same flow ids", () => {
+    expect(graph.flowById.has("bookings.create")).toBe(true);
+    expect(graph.effectByRef.has("sql:bookings")).toBe(true);
+  });
+
+  test("default is clustered by unit — never every flow", () => {
+    const view = buildArchitectureView(graph, {
+      runs: ARCHITECTURE_RUNS_FIXTURE,
+    });
+    const kinds = new Set(view.nodes.map((n) => n.kind));
+    expect(kinds.has("unit")).toBe(true);
+    expect(view.nodes.some((n) => n.kind === "flow")).toBe(false);
+    expect(view.nodes.some((n) => n.id === "unit:bookings")).toBe(true);
+    expect(view.edges.every((e) => e.aggregated)).toBe(true);
+  });
+
+  test("focus expands neighbourhood at depth 1–2", () => {
+    const d1 = buildArchitectureView(graph, {
+      focus: "unit:bookings",
+      depth: 1,
+      runs: ARCHITECTURE_RUNS_FIXTURE,
+    });
+    expect(d1.focus).toBe("unit:bookings");
+    expect(d1.nodes.some((n) => n.id === "flow:bookings.create")).toBe(true);
+
+    const d2 = buildArchitectureView(graph, {
+      focus: "unit:bookings",
+      depth: 2,
+      runs: ARCHITECTURE_RUNS_FIXTURE,
+    });
+    expect(d2.nodes.length).toBeGreaterThanOrEqual(d1.nodes.length);
+  });
+
+  test("element layers toggle typed edges", () => {
+    const all = buildArchitectureView(graph, {
+      layers: {
+        data: true,
+        messaging: true,
+        time: true,
+        external: true,
+      },
+    });
+    const noExternal = buildArchitectureView(graph, {
+      layers: {
+        data: true,
+        messaging: true,
+        time: true,
+        external: false,
+      },
+    });
+    expect(all.edges.some((e) => e.layer === "external")).toBe(true);
+    expect(noExternal.edges.some((e) => e.layer === "external")).toBe(false);
+
+    const withTime = buildArchitectureView(graph, {
+      focus: "flow:ops.nightlyReconcile",
+      depth: 1,
+      layers: {
+        data: false,
+        messaging: false,
+        time: true,
+        external: false,
+      },
+    });
+    expect(withTime.edges.some((e) => e.layer === "time")).toBe(true);
+  });
+
+  test("boundary crossing count comes from Manifest external effects", () => {
+    const count = boundaryCrossingCount(graph);
+    expect(count).toBe(1); // channel:booking-confirmed
+    const view = buildArchitectureView(graph);
+    expect(view.boundaryCrossingCount).toBe(count);
+    expect(
+      view.nodes.some((n) => n.id === "channel:booking-confirmed"),
+    ).toBe(true);
+    expect(
+      view.nodes.find((n) => n.id === "channel:booking-confirmed")
+        ?.insideBoundary,
+    ).toBe(false);
+  });
+
+  test("edge thickness follows Runs traffic; zero traversals are dashed", () => {
+    const view = buildArchitectureView(graph, {
+      runs: ARCHITECTURE_RUNS_FIXTURE,
+    });
+    const withTraffic = view.edges.filter((e) => e.traversals > 0);
+    const dashed = view.edges.filter((e) => e.dashed);
+    expect(dashed.length).toBeGreaterThan(0);
+    expect(dashed.every((e) => e.traversals === 0)).toBe(true);
+    if (withTraffic.length > 0) {
+      expect(withTraffic.every((e) => !e.dashed)).toBe(true);
+      expect(withTraffic.every((e) => e.thickness >= 1)).toBe(true);
+    }
+  });
+
+  test("pathologies surface as findings", () => {
+    const findings = computePathologies(graph);
+    const kinds = new Set(findings.map((f) => f.kind));
+    expect(kinds.has("cycle")).toBe(true);
+    expect(kinds.has("god-node")).toBe(true);
+    expect(kinds.has("orphan-signal")).toBe(true);
+    expect(kinds.has("spof")).toBe(true);
+    expect(
+      findings.some((f) => f.detail.includes("legacy-unused")),
+    ).toBe(true);
+  });
+});
+
+describe("architecture traffic helpers", () => {
+  test("observeTraffic counts flow→resource traversals", () => {
+    const traffic = observeTraffic(ARCHITECTURE_RUNS_FIXTURE);
+    expect(traffic.size).toBeGreaterThan(0);
+  });
+
+  test("thickness scales 1–8", () => {
+    expect(thicknessOf(0, 100)).toBe(1);
+    expect(thicknessOf(100, 100)).toBe(8);
+    expect(thicknessOf(50, 100)).toBe(4);
+  });
+});
+
+describe("architecture URL search", () => {
+  test("round-trips focus, depth, and layer offs", () => {
+    const parsed = parseArchitectureSearch({
+      focus: "unit:bookings",
+      depth: "2",
+      external: "false",
+    });
+    expect(parsed.focus).toBe("unit:bookings");
+    expect(parsed.depth).toBe(2);
+    expect(layersOf(parsed).external).toBe(false);
+    expect(layersOf(parsed).data).toBe(true);
+    const serialized = serializeArchitectureSearch(parsed);
+    expect(serialized.focus).toBe("unit:bookings");
+    expect(serialized.depth).toBe("2");
+    expect(serialized.external).toBe("false");
+  });
+
+  test("invalid search falls back", () => {
+    const parsed = parseArchitectureSearch({ depth: "9", focus: 1 });
+    expect(parsed.depth).toBe(1);
+  });
+});