@twelvehart/orcats 0.0.0-seed.0 → 0.2.3

package/src/loop/graph/analyze.ts

@@ -0,0 +1,128 @@
+// Hand-built 3-color (white/grey/black) DFS over the loop graph (design D6). No graph
+// dependency: a loop is tens of nodes, so a single recursive pass yields the accidental
+// back-edge set, a topological order, and the traversal at once — while keeping the
+// declared loop back-edges as first-class domain data the builder hands us.
+//
+// The builder TELLS us which edges are loop back-edges; we trust that set rather than
+// rediscovering it. DFS runs only over the FORWARD subgraph (all edges minus the declared
+// back-edges), which is meant to be a DAG. Any back-edge the DFS finds there is therefore
+// an ACCIDENTAL cycle the author did not declare, reported as `declared: false`.
+
+import type { BackEdge, CycleReport, Edge, GraphInput, NodeId } from "./types.ts";
+
+type Color = "white" | "grey" | "black";
+
+/** Build adjacency in edge-insertion order so traversal/topo order are deterministic. */
+function adjacency(nodes: readonly NodeId[], edges: readonly Edge[]): Map<NodeId, NodeId[]> {
+  const adj = new Map<NodeId, NodeId[]>();
+  for (const n of nodes) adj.set(n, []);
+  for (const { from, to } of edges) {
+    if (!adj.has(to)) adj.set(to, []);
+    const out = adj.get(from) ?? [];
+    out.push(to);
+    adj.set(from, out);
+  }
+  return adj;
+}
+
+const edgeKey = (from: NodeId, to: NodeId): string => `${from}\u0000${to}`;
+
+/** Shortest forward path `from → … → to` over the DAG adjacency, or `null` if unreachable. */
+function forwardPath(adj: Map<NodeId, NodeId[]>, from: NodeId, to: NodeId): readonly NodeId[] | null {
+  if (from === to) return [from];
+  const prev = new Map<NodeId, NodeId>();
+  const queue: NodeId[] = [from];
+  const seen = new Set<NodeId>([from]);
+  while (queue.length > 0) {
+    const u = queue.shift();
+    if (u === undefined) break;
+    for (const v of adj.get(u) ?? []) {
+      if (seen.has(v)) continue;
+      seen.add(v);
+      prev.set(v, u);
+      if (v === to) {
+        const path: NodeId[] = [to];
+        let cur: NodeId = to;
+        while (cur !== from) {
+          const p = prev.get(cur);
+          if (p === undefined) break;
+          cur = p;
+          path.push(cur);
+        }
+        return path.reverse();
+      }
+      queue.push(v);
+    }
+  }
+  return null;
+}
+
+/**
+ * One-pass 3-color DFS. Declared back-edges are recorded first-class with the cycle they
+ * close (`to → … → from` over the forward DAG); accidental cycles are discovered by the DFS
+ * and named from the grey stack.
+ */
+export function analyzeGraph(input: GraphInput): CycleReport {
+  const { nodes, edges, declaredBackEdges } = input;
+
+  // Node universe: declared nodes ∪ every edge endpoint, in stable first-seen order.
+  const order: NodeId[] = [];
+  const known = new Set<NodeId>();
+  const see = (n: NodeId): void => {
+    if (!known.has(n)) {
+      known.add(n);
+      order.push(n);
+    }
+  };
+  for (const n of nodes) see(n);
+  for (const { from, to } of edges) {
+    see(from);
+    see(to);
+  }
+
+  const declaredKeys = new Set(declaredBackEdges.map((e) => edgeKey(e.from, e.to)));
+  const forwardEdges = edges.filter((e) => !declaredKeys.has(edgeKey(e.from, e.to)));
+  const adj = adjacency(order, forwardEdges);
+
+  const color = new Map<NodeId, Color>(order.map((n) => [n, "white"]));
+  const traversal: NodeId[] = [];
+  const postorder: NodeId[] = [];
+  const accidental: BackEdge[] = [];
+  const stack: NodeId[] = [];
+
+  const visit = (u: NodeId): void => {
+    color.set(u, "grey");
+    stack.push(u);
+    traversal.push(u);
+    for (const v of adj.get(u) ?? []) {
+      const c = color.get(v);
+      if (c === "white") {
+        visit(v);
+      } else if (c === "grey") {
+        // v is an ancestor on the current path → u→v closes an accidental cycle.
+        const cycle = [...stack.slice(stack.indexOf(v)), v];
+        accidental.push({ from: u, to: v, declared: false, cycle });
+      }
+      // black ⇒ forward/cross edge within the DAG; not a cycle.
+    }
+    stack.pop();
+    color.set(u, "black");
+    postorder.push(u);
+  };
+
+  for (const n of order) {
+    if (color.get(n) === "white") visit(n);
+  }
+
+  // Declared back-edges: trusted, recorded with the forward cycle they close.
+  const declared: BackEdge[] = declaredBackEdges.map(({ from, to }) => {
+    const path = forwardPath(adj, to, from);
+    return { from, to, declared: true, cycle: path ? [...path] : [to, from] };
+  });
+
+  return {
+    traversal,
+    topoOrder: [...postorder].reverse(),
+    backEdges: [...declared, ...accidental]
+  };
+}

package/src/loop/graph/index.ts

@@ -0,0 +1,2 @@
+export * from "./types.ts";
+export * from "./analyze.ts";

package/src/loop/graph/types.ts

@@ -0,0 +1,45 @@
+// Hand-built cycle-aware graph (design D6): a 3-color (white/grey/black) DFS giving
+// cycle detection WITH the offending back-edge set, topological order, and traversal
+// in one pass. No graph dependency. Implemented in L03 (tasks 4.3-4.5).
+//
+// Internal machinery: the loop() builder hides this, so it is intentionally NOT part
+// of the public surface re-exported by ../index.ts.
+
+export type NodeId = string;
+
+export interface Edge {
+  readonly from: NodeId;
+  readonly to: NodeId;
+}
+
+/**
+ * A back-edge closes a cycle. `declared` distinguishes intentional loop back-edges —
+ * first-class domain data the builder hands us (design D6) — from accidental cycles the
+ * DFS discovers in the forward subgraph. `cycle` is the node path naming the loop, used
+ * to name the offending cycle in build/lint errors. For a declared back-edge it runs
+ * `to → … → from` (the forward path the back-edge closes); for an accidental one it is
+ * the grey DFS-stack slice `to → … → from`.
+ */
+export interface BackEdge extends Edge {
+  readonly declared: boolean;
+  readonly cycle: readonly NodeId[];
+}
+
+/** Input to {@link analyzeGraph}: the node set, all edges, and which edges are declared loop back-edges. */
+export interface GraphInput {
+  readonly nodes: readonly NodeId[];
+  readonly edges: readonly Edge[];
+  /** Edges the builder declares as intentional loop back-edges; trusted, not rediscovered. */
+  readonly declaredBackEdges: readonly Edge[];
+}
+
+/**
+ * One-pass 3-color DFS output. `traversal` is the preorder visit sequence; `topoOrder` is a
+ * valid topological order of the forward DAG (reverse postorder, back-edges removed);
+ * `backEdges` holds both declared loop back-edges and discovered accidental cycles.
+ */
+export interface CycleReport {
+  readonly traversal: readonly NodeId[];
+  readonly topoOrder: readonly NodeId[];
+  readonly backEdges: readonly BackEdge[];
+}

package/src/loop/index.ts

@@ -0,0 +1,11 @@
+// Public loop surface — Effect-FREE by mandate (design D2). The Effect-powered engine
+// under ./engine is intentionally NOT re-exported here; the facade gate enforces that no
+// Effect type reaches this surface or the root runtime export. ./graph stays internal too.
+export * from "./builder/index.ts";
+export type { LoopContextPressure, LoopExecutionContextOptions } from "./execution.ts";
+export * from "./state/index.ts";
+export * from "./io/index.ts";
+export * from "./context/index.ts";
+// L11 distribution: defineLoop + the serve supervisor. Effect-free; the CLI (run/serve/loops)
+// and authored loop modules both consume this surface.
+export * from "./serve.ts";

package/src/loop/io/index.ts

@@ -0,0 +1,3 @@
+export * from "./linear.ts";
+export * from "./source.ts";
+export * from "./sink.ts";