okengine 0.1.4

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

@@ -0,0 +1,165 @@
+/**
+ * Declared architecture edges derived from the Flows causality graph (§9.1 / §9.13).
+ *
+ * Reuses {@link buildCausalityGraph} output — does not recompute causality.
+ */
+
+import type { CausalityGraph, FlowNode } from "../flows/graph.ts";
+import {
+  isBoundaryExternal,
+  layerOfCause,
+  layerOfEffectRef,
+} from "./layers.ts";
+import type { ElementLayer } from "./types.ts";
+
+/** One fine-grained declared relationship before aggregation / focus. */
+export interface DeclaredEdge {
+  /** Source node id (flow: / unit: / cause:). */
+  readonly from: string;
+  /** Target node id. */
+  readonly to: string;
+  /** Owning flow that declares the relationship (for traffic lookup). */
+  readonly flowId: string;
+  /** Effect ref when the target is a resource. */
+  readonly ref?: string;
+  /** Typed layer, or structural call. */
+  readonly layer: ElementLayer | "call";
+  /** Source unit. */
+  readonly fromUnit: string;
+  /** Target unit (`external` for boundary-crossing resources). */
+  readonly toUnit: string;
+}
+
+/**
+ * Extract every declared typed edge from the causality graph.
+ *
+ * @param graph - Flows causality graph
+ */
+export function declaredEdgesOf(graph: CausalityGraph): DeclaredEdge[] {
+  const edges: DeclaredEdge[] = [];
+  const consumersOf = signalConsumers(graph);
+
+  for (const flow of graph.flows) {
+    // Cause → flow (time / messaging triggers)
+    for (const causeId of flow.causeIds) {
+      const cause = graph.causeById.get(causeId);
+      if (!cause) continue;
+      const layer = layerOfCause(cause);
+      if (!layer) continue;
+      edges.push({
+        from: `cause:${cause.id}`,
+        to: `flow:${flow.id}`,
+        flowId: flow.id,
+        layer,
+        fromUnit: flow.unit,
+        toUnit: flow.unit,
+      });
+    }
+
+    // Flow → resources / callees
+    for (const ref of flow.effectRefs) {
+      if (ref.startsWith("flow:")) {
+        const callee = ref.slice("flow:".length);
+        const calleeUnit = unitOfFlowId(callee);
+        edges.push({
+          from: `flow:${flow.id}`,
+          to: `flow:${callee}`,
+          flowId: flow.id,
+          ref,
+          layer: "call",
+          fromUnit: flow.unit,
+          toUnit: calleeUnit,
+        });
+        continue;
+      }
+
+      const layer = layerOfEffectRef(ref);
+      if (!layer) continue;
+
+      const toUnit = isBoundaryExternal(ref) ? "external" : ownerUnitOf(ref, graph);
+      edges.push({
+        from: `flow:${flow.id}`,
+        to: ref,
+        flowId: flow.id,
+        ref,
+        layer,
+        fromUnit: flow.unit,
+        toUnit,
+      });
+
+      // Messaging fan-out: emitter unit → consumer units
+      if (layer === "messaging" && ref.startsWith("signal:")) {
+        const sig = ref.slice("signal:".length);
+        for (const consumerId of consumersOf.get(sig) ?? []) {
+          const consumer = graph.flowById.get(consumerId);
+          if (!consumer || consumer.id === flow.id) continue;
+          edges.push({
+            from: `flow:${flow.id}`,
+            to: `flow:${consumer.id}`,
+            flowId: flow.id,
+            ref,
+            layer: "messaging",
+            fromUnit: flow.unit,
+            toUnit: consumer.unit,
+          });
+        }
+      }
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Unit that "owns" a resource for clustering (first writing/emitting flow's unit,
+ * else first touching unit, else `shared`).
+ *
+ * @param ref - Effect ref
+ * @param graph - Causality graph
+ */
+export function ownerUnitOf(ref: string, graph: CausalityGraph): string {
+  const effect = graph.effectByRef.get(ref);
+  if (!effect || effect.flowIds.length === 0) return "shared";
+
+  const writers = effect.flowIds.filter((id) => {
+    const flow = graph.flowById.get(id);
+    if (!flow) return false;
+    return flowWritesOrEmits(flow, ref);
+  });
+  const pick = writers[0] ?? effect.flowIds[0];
+  if (!pick) return "shared";
+  return unitOfFlowId(pick);
+}
+
+function flowWritesOrEmits(flow: FlowNode, ref: string): boolean {
+  const effects = flow.raw.effects;
+  if (!effects) return false;
+  if (ref.startsWith("signal:")) {
+    const name = ref.slice("signal:".length);
+    return (effects.emits ?? []).includes(name);
+  }
+  if ((effects.writes ?? []).includes(ref)) return true;
+  return false;
+}
+
+function signalConsumers(graph: CausalityGraph): Map<string, string[]> {
+  const map = new Map<string, string[]>();
+  for (const flow of graph.flows) {
+    const sig = flow.raw.trigger?.signal;
+    if (!sig) continue;
+    const list = map.get(sig) ?? [];
+    list.push(flow.id);
+    map.set(sig, list);
+  }
+  return map;
+}
+
+/**
+ * Unit prefix of a flow id.
+ *
+ * @param flowId - Flow id
+ */
+export function unitOfFlowId(flowId: string): string {
+  const i = flowId.indexOf(".");
+  return i === -1 ? flowId : flowId.slice(0, i);
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Manifest + Runs fixtures for Architecture panel tests (console §9.13).
+ */
+
+import type { Manifest } from "../../../manifest/types.ts";
+import { FLOWS_TEST_MANIFEST } from "../flows/fixture.ts";
+import { RUNS_CHAIN_FIXTURE } from "../runs/fixture.ts";
+import type { RunRecord } from "../runs/types.ts";
+
+/**
+ * Architecture fixture — extends the Flows causality slice with a cycle,
+ * an orphan signal, a cron (time layer), and a cross-unit call.
+ */
+export const ARCHITECTURE_TEST_MANIFEST: Manifest = {
+  ...FLOWS_TEST_MANIFEST,
+  app: "skyport-architecture-test",
+  flows: {
+    ...FLOWS_TEST_MANIFEST.flows,
+    "ops.nightlyReconcile": {
+      trigger: { cron: "0 3 * * *" },
+      effects: {
+        reads: ["sql:bookings"],
+        writes: ["sql:bookings"],
+      },
+      source: "src/flows/ops/index.ts:8",
+    },
+    "ops.pingPayments": {
+      effects: {
+        calls: ["payments.reportToOps"],
+      },
+      source: "src/flows/ops/index.ts:20",
+    },
+    "payments.reportToOps": {
+      effects: {
+        calls: ["ops.pingPayments"],
+        emits: ["payment-reported"],
+      },
+      source: "src/flows/payments/index.ts:40",
+    },
+    "reports.onPayment": {
+      trigger: { signal: "payment-reported" },
+      effects: {
+        writes: ["sql:reports"],
+      },
+      source: "src/flows/reports/index.ts:4",
+    },
+    "reports.list": {
+      trigger: { http: { method: "GET", path: "/reports" } },
+      effects: {
+        reads: ["sql:reports"],
+      },
+      source: "src/flows/reports/index.ts:18",
+    },
+  },
+  signals: {
+    ...FLOWS_TEST_MANIFEST.signals,
+    "payment-reported": { delivery: "once", retries: 3, deadLetter: true },
+    /** Declared, never emitted, never consumed. */
+    "legacy-unused": { delivery: "once", retries: 1, deadLetter: false },
+  },
+  stores: {
+    db: {
+      facet: "sql",
+      tables: {
+        bookings: {},
+        shipments: {},
+        reports: {},
+      },
+    },
+  },
+};
+
+/** Runs fixture reused for traffic thickness / dashed edges. */
+export const ARCHITECTURE_RUNS_FIXTURE: readonly RunRecord[] = RUNS_CHAIN_FIXTURE;

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

@@ -0,0 +1,84 @@
+/**
+ * Architecture panel pure modules (console §9.13).
+ */
+
+export type {
+  ArchitectureEdge,
+  ArchitectureFinding,
+  ArchitectureNode,
+  ArchitectureNodeKind,
+  ArchitectureView,
+  ElementLayer,
+  FocusDepth,
+  LayerFlags,
+  PathologyKind,
+} from "./types.ts";
+
+export {
+  DEFAULT_LAYERS,
+  ELEMENT_LAYERS,
+  LAYER_LABEL,
+} from "./types.ts";
+
+export {
+  isBoundaryExternal,
+  labelOfRef,
+  layerOfCause,
+  layerOfEffectRef,
+} from "./layers.ts";
+
+export {
+  boundaryCrossingCount,
+  boundaryCrossingRefs,
+} from "./boundary.ts";
+
+export {
+  normalizeTrafficRef,
+  observeTraffic,
+  thicknessOf,
+  trafficEdgeKey,
+  traversalsOf,
+} from "./traffic.ts";
+
+export {
+  declaredEdgesOf,
+  ownerUnitOf,
+  unitOfFlowId,
+} from "./declared.ts";
+
+export {
+  computePathologies,
+  findCycles,
+  findGodNodes,
+  findOrphanSignals,
+  findSinglePointsOfFailure,
+} from "./pathologies.ts";
+
+export {
+  buildArchitectureView,
+  setLayer,
+  type ArchitectureViewOptions,
+} from "./view.ts";
+
+export {
+  clearFocus,
+  focusNode,
+  layersOf,
+  parseArchitectureSearch,
+  serializeArchitectureSearch,
+  setDepth,
+  setLayerSearch,
+  type ArchitectureSearch,
+} from "./search.ts";
+
+export {
+  ARCHITECTURE_RUNS_FIXTURE,
+  ARCHITECTURE_TEST_MANIFEST,
+} from "./fixture.ts";
+
+export {
+  layoutNodes,
+  SYSTEM_BOUNDARY,
+  type BoundaryRect,
+  type NodePosition,
+} from "./layout.ts";

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

@@ -0,0 +1,64 @@
+/**
+ * Typed element-layer classification for architecture edges (console §9.13).
+ *
+ * Layers toggle real edge kinds — Store / Signal / Clock / Channel+AI —
+ * not visual grouping of an undifferentiated graph.
+ */
+
+import type { CauseNode } from "../flows/graph.ts";
+import type { ElementLayer } from "./types.ts";
+
+/**
+ * Classify a causality effect ref into a toggleable element layer.
+ *
+ * Returns `null` for secrets and flow portals (not among the four layers).
+ *
+ * @param ref - Effect ref (`sql:bookings`, `signal:order-placed`, …)
+ */
+export function layerOfEffectRef(ref: string): ElementLayer | null {
+  if (
+    ref.startsWith("sql:") ||
+    ref.startsWith("kv:") ||
+    ref.startsWith("files:") ||
+    ref.startsWith("index:")
+  ) {
+    return "data";
+  }
+  if (ref.startsWith("signal:")) return "messaging";
+  if (ref.startsWith("channel:") || ref.startsWith("ai:")) return "external";
+  return null;
+}
+
+/**
+ * Classify a cause into a toggleable element layer.
+ *
+ * HTTP / CDC / caller causes are structural (always shown when relevant);
+ * signal → messaging; cron / every → time.
+ *
+ * @param cause - Cause node from the causality graph
+ */
+export function layerOfCause(cause: CauseNode): ElementLayer | null {
+  if (cause.kind === "signal") return "messaging";
+  if (cause.kind === "cron" || cause.kind === "every") return "time";
+  return null;
+}
+
+/**
+ * Whether a resource ref sits outside the system boundary
+ * (Channel / AI — irreversible tier).
+ *
+ * @param ref - Effect ref
+ */
+export function isBoundaryExternal(ref: string): boolean {
+  return ref.startsWith("channel:") || ref.startsWith("ai:");
+}
+
+/**
+ * Strip a kind prefix for display (`channel:booking-confirmed` → `booking-confirmed`).
+ *
+ * @param ref - Effect ref
+ */
+export function labelOfRef(ref: string): string {
+  const i = ref.indexOf(":");
+  return i === -1 ? ref : ref.slice(i + 1);
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Deterministic layout for the architecture SVG (console §9.13).
+ *
+ * Units sit inside the system boundary; external nodes sit outside.
+ */
+
+import type { ArchitectureNode } from "./types.ts";
+
+/** Pixel position for a diagram node. */
+export interface NodePosition {
+  readonly id: string;
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Boundary rectangle in SVG user units. */
+export interface BoundaryRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** Fixed boundary geometry. */
+export const SYSTEM_BOUNDARY: BoundaryRect = {
+  x: 32,
+  y: 40,
+  width: 440,
+  height: 300,
+};
+
+/**
+ * Place nodes: units / flows / resources inside the boundary; externals outside.
+ *
+ * @param nodes - Visible nodes
+ */
+export function layoutNodes(
+  nodes: readonly ArchitectureNode[],
+): ReadonlyMap<string, NodePosition> {
+  const inside = nodes.filter((n) => n.insideBoundary);
+  const outside = nodes.filter((n) => !n.insideBoundary);
+  const map = new Map<string, NodePosition>();
+
+  const cols = Math.max(1, Math.ceil(Math.sqrt(inside.length)));
+  const cellW = SYSTEM_BOUNDARY.width / (cols + 1);
+  const rows = Math.max(1, Math.ceil(inside.length / cols));
+  const cellH = SYSTEM_BOUNDARY.height / (rows + 1);
+
+  inside.forEach((n, i) => {
+    const col = i % cols;
+    const row = Math.floor(i / cols);
+    map.set(n.id, {
+      id: n.id,
+      x: SYSTEM_BOUNDARY.x + cellW * (col + 1),
+      y: SYSTEM_BOUNDARY.y + cellH * (row + 1),
+    });
+  });
+
+  outside.forEach((n, i) => {
+    map.set(n.id, {
+      id: n.id,
+      x: SYSTEM_BOUNDARY.x + SYSTEM_BOUNDARY.width + 96,
+      y: SYSTEM_BOUNDARY.y + 48 + i * 56,
+    });
+  });
+
+  return map;
+}

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

@@ -0,0 +1,260 @@
+/**
+ * Architecture pathologies computed from the causality graph as data (§9.13).
+ *
+ * Cycles, god nodes, orphan signals, single points of failure —
+ * surfaced as a findings list, not decoration on the diagram.
+ */
+
+import type { CausalityGraph } from "../flows/graph.ts";
+import { declaredEdgesOf } from "./declared.ts";
+import type { ArchitectureFinding } from "./types.ts";
+
+/**
+ * Compute all architecture findings for a causality graph.
+ *
+ * @param graph - Flows causality graph
+ */
+export function computePathologies(
+  graph: CausalityGraph,
+): ArchitectureFinding[] {
+  const findings: ArchitectureFinding[] = [];
+  findings.push(...findCycles(graph));
+  findings.push(...findGodNodes(graph));
+  findings.push(...findOrphanSignals(graph));
+  findings.push(...findSinglePointsOfFailure(graph));
+  return findings;
+}
+
+/**
+ * Directed cycles among flows (calls + signal producer→consumer).
+ *
+ * @param graph - Causality graph
+ */
+export function findCycles(graph: CausalityGraph): ArchitectureFinding[] {
+  const adj = new Map<string, Set<string>>();
+  const ensure = (id: string): Set<string> => {
+    let set = adj.get(id);
+    if (!set) {
+      set = new Set();
+      adj.set(id, set);
+    }
+    return set;
+  };
+
+  for (const edge of declaredEdgesOf(graph)) {
+    if (!edge.from.startsWith("flow:") || !edge.to.startsWith("flow:")) {
+      continue;
+    }
+    const from = edge.from.slice("flow:".length);
+    const to = edge.to.slice("flow:".length);
+    ensure(from).add(to);
+  }
+
+  const cycles: string[][] = [];
+  const visited = new Set<string>();
+  const stack: string[] = [];
+  const onStack = new Set<string>();
+
+  const dfs = (node: string): void => {
+    visited.add(node);
+    stack.push(node);
+    onStack.add(node);
+    for (const next of adj.get(node) ?? []) {
+      if (!visited.has(next)) {
+        dfs(next);
+      } else if (onStack.has(next)) {
+        const idx = stack.indexOf(next);
+        if (idx !== -1) {
+          cycles.push([...stack.slice(idx), next]);
+        }
+      }
+    }
+    stack.pop();
+    onStack.delete(node);
+  };
+
+  for (const id of graph.flows.map((f) => f.id)) {
+    if (!visited.has(id)) dfs(id);
+  }
+
+  // Deduplicate by normalised cycle signature
+  const seen = new Set<string>();
+  const findings: ArchitectureFinding[] = [];
+  for (const cycle of cycles) {
+    const body = cycle.slice(0, -1);
+    const rotated = rotateMin(body);
+    const sig = rotated.join("→");
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    findings.push({
+      kind: "cycle",
+      severity: "critical",
+      title: "Cycle",
+      detail: `Causal cycle: ${rotated.join(" → ")}`,
+      nodeIds: rotated.map((id) => `flow:${id}`),
+    });
+  }
+  return findings;
+}
+
+/**
+ * Resources touched by the most flows ("god nodes").
+ *
+ * @param graph - Causality graph
+ */
+export function findGodNodes(graph: CausalityGraph): ArchitectureFinding[] {
+  if (graph.effects.length === 0) return [];
+  const ranked = [...graph.effects]
+    .filter((e) => e.touchCount > 0)
+    .sort(
+      (a, b) => b.touchCount - a.touchCount || a.ref.localeCompare(b.ref),
+    );
+  const top = ranked[0];
+  if (!top || top.touchCount < 2) return [];
+
+  // Only flag when clearly dominant (strictly more than the runner-up, or sole)
+  const second = ranked[1]?.touchCount ?? 0;
+  if (top.touchCount === second && ranked.filter((e) => e.touchCount === top.touchCount).length > 1) {
+    // Tie for first — report all tied gods
+    return ranked
+      .filter((e) => e.touchCount === top.touchCount)
+      .map((e) => ({
+        kind: "god-node" as const,
+        severity: "warning" as const,
+        title: "God node",
+        detail: `${e.ref} is touched by ${e.touchCount} flows — the most in the system`,
+        nodeIds: [e.ref],
+      }));
+  }
+
+  return [
+    {
+      kind: "god-node",
+      severity: "warning",
+      title: "God node",
+      detail: `${top.ref} is touched by ${top.touchCount} flows — the most in the system`,
+      nodeIds: [top.ref],
+    },
+  ];
+}
+
+/**
+ * Orphan signals: declared but never emitted, never consumed, or both sides missing.
+ *
+ * @param graph - Causality graph
+ */
+export function findOrphanSignals(
+  graph: CausalityGraph,
+): ArchitectureFinding[] {
+  const findings: ArchitectureFinding[] = [];
+  const signalNames = new Set<string>();
+
+  for (const effect of graph.effects) {
+    if (effect.ref.startsWith("signal:")) {
+      signalNames.add(effect.ref.slice("signal:".length));
+    }
+  }
+  for (const flow of graph.flows) {
+    for (const sig of flow.raw.effects?.emits ?? []) signalNames.add(sig);
+    const trigger = flow.raw.trigger?.signal;
+    if (trigger) signalNames.add(trigger);
+  }
+
+  for (const name of [...signalNames].sort()) {
+    const ref = `signal:${name}`;
+    const emitters = graph.flows.filter((f) =>
+      (f.raw.effects?.emits ?? []).includes(name),
+    );
+    const consumers = graph.flows.filter(
+      (f) => f.raw.trigger?.signal === name,
+    );
+
+    if (emitters.length === 0 && consumers.length === 0) {
+      findings.push({
+        kind: "orphan-signal",
+        severity: "warning",
+        title: "Orphan signal",
+        detail: `${name} is declared but has no producers and no consumers`,
+        nodeIds: [ref],
+      });
+      continue;
+    }
+    if (emitters.length === 0) {
+      findings.push({
+        kind: "orphan-signal",
+        severity: "warning",
+        title: "Orphan signal",
+        detail: `${name} has consumers but no producer`,
+        nodeIds: [ref, ...consumers.map((c) => `flow:${c.id}`)],
+      });
+      continue;
+    }
+    if (consumers.length === 0) {
+      findings.push({
+        kind: "orphan-signal",
+        severity: "warning",
+        title: "Orphan signal",
+        detail: `${name} is emitted but has no consumers`,
+        nodeIds: [ref, ...emitters.map((e) => `flow:${e.id}`)],
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Single points of failure: widely-touched resources with exactly one writer/emitter.
+ *
+ * @param graph - Causality graph
+ */
+export function findSinglePointsOfFailure(
+  graph: CausalityGraph,
+): ArchitectureFinding[] {
+  const findings: ArchitectureFinding[] = [];
+
+  for (const effect of graph.effects) {
+    if (effect.touchCount < 2) continue;
+    if (effect.ref.startsWith("secret:")) continue;
+    if (effect.ref.startsWith("channel:") || effect.ref.startsWith("ai:")) {
+      continue;
+    }
+
+    const writers = effect.flowIds.filter((id) => {
+      const flow = graph.flowById.get(id);
+      if (!flow?.raw.effects) return false;
+      if (effect.ref.startsWith("signal:")) {
+        const name = effect.ref.slice("signal:".length);
+        return (flow.raw.effects.emits ?? []).includes(name);
+      }
+      return (flow.raw.effects.writes ?? []).includes(effect.ref);
+    });
+
+    if (writers.length !== 1) continue;
+    const writer = writers[0]!;
+    findings.push({
+      kind: "spof",
+      severity: "critical",
+      title: "Single point of failure",
+      detail: `${effect.ref} is touched by ${effect.touchCount} flows but written/emitted by only ${writer}`,
+      nodeIds: [effect.ref, `flow:${writer}`],
+    });
+  }
+
+  return findings;
+}
+
+function rotateMin(cycle: readonly string[]): string[] {
+  if (cycle.length === 0) return [];
+  let best = [...cycle];
+  let bestKey = best.join("\0");
+  for (let i = 1; i < cycle.length; i++) {
+    const rotated = [...cycle.slice(i), ...cycle.slice(0, i)];
+    const key = rotated.join("\0");
+    if (key < bestKey) {
+      best = rotated;
+      bestKey = key;
+    }
+  }
+  return best;
+}