@githolon/dsl 0.108.7 → 0.110.0

package/src/law_dependency_index.ts

@@ -0,0 +1,231 @@
+// Compile-time indexing of the existing transient typed law graph. This is neither a second
+// law representation nor an authorization evaluator: only emitted USD is runtime authority.
+import type { LawGraph } from "./law_graph.js";
+import type { CompiledSparseLawGraphUsda } from "./law_graph_usda.js";
+
+type Node = LawGraph["nodes"][number];
+type Dependency = Parameters<
+  CompiledSparseLawGraphUsda["resolveDependency"]
+>[0];
+interface Entry {
+  readonly graph: LawGraph;
+  readonly node: Node;
+  readonly path: string | undefined;
+}
+
+export interface LawDependencySlice {
+  readonly nodes: ReadonlySet<Node>;
+  readonly paths: ReadonlySet<string>;
+  readonly visitedNodes: number;
+  readonly traversedEdges: number;
+}
+
+/** Build once per package. A selection subsequently visits only reachable adjacency lists.
+ * Domain ownership is context, not a request to follow the domain's complete member inventory.
+ * USD population masks retain the selected prims' ancestors and their authored metadata.
+ */
+export class LawDependencyIndex {
+  private readonly entries = new Map<Node, Entry>();
+  private readonly edges = new Map<Node, Set<Node>>();
+  private readonly guards = new Map<Node, Set<Node>>();
+  private readonly local = new Map<LawGraph, Map<string, Node>>();
+  private readonly byPath = new Map<string, Node>();
+
+  constructor(
+    graphs: readonly LawGraph[],
+    paths: ReadonlyMap<Node, string>,
+    private readonly resolveExport: (
+      graph: LawGraph,
+      dependency: Dependency
+    ) => string
+  ) {
+    for (const graph of graphs) {
+      this.local.set(
+        graph,
+        new Map(graph.nodes.map((node) => [node.entity.id, node]))
+      );
+      for (const node of graph.nodes) {
+        const path = paths.get(node);
+        this.entries.set(node, { graph, node, path });
+        if (path !== undefined) this.byPath.set(path, node);
+      }
+    }
+    for (const entry of this.entries.values()) {
+      // Lowering can retain source-only anonymous occurrences which have no emitted prim.
+      // They are not index roots. A semantic edge reaching one still fails in select(), below.
+      if (entry.path === undefined) continue;
+      const edges = new Set<Node>();
+      // `owner` locates a structural node in the source graph. Except a flow's explicit `on`
+      // relationship it is provenance/namespace placement, not a runtime dependency back to an
+      // unrelated source command which happened to introduce a shared value type first.
+      const { owner: _owner, ...value } = entry.node as Node & {
+        owner?: unknown;
+      };
+      const semantic =
+        entry.node.kind === "structural" && entry.node.structuralKind === "flow"
+          ? entry.node
+          : value;
+      try {
+        this.visitReferences(entry.graph, semantic, (target) => {
+          if (target.kind !== "domain") edges.add(target);
+        });
+      } catch (error) {
+        throw new Error(
+          `${entry.graph.domain.entity.label}/${entry.node.entity.label}: ${
+            error instanceof Error ? error.message : error
+          }`
+        );
+      }
+      this.edges.set(entry.node, edges);
+      const node = entry.node;
+      // These declarations point TO the governed member. Outgoing reachability alone would
+      // silently omit them. Keep these reverse applicability edges distinct from ordinary refs.
+      const appliesTo =
+        node.kind === "invariant"
+          ? node.invariantKind === "workspace"
+            ? [node.on]
+            : [node.onAggregate]
+          : node.kind === "structural" && node.structuralKind === "flow"
+          ? [node.owner]
+          : node.kind === "capability"
+          ? [
+              node.task,
+              node.obligation,
+              node.complete,
+              node.fail,
+              node.block,
+              node.deadLetter,
+            ]
+          : [];
+      for (const ref of appliesTo) {
+        const target = this.local.get(entry.graph)?.get(ref.id);
+        if (target === undefined)
+          throw new Error(
+            `law guard '${node.entity.id}' has missing owner '${ref.id}'`
+          );
+        const guards = this.guards.get(target) ?? new Set();
+        guards.add(node);
+        this.guards.set(target, guards);
+      }
+    }
+  }
+
+  private visitReferences(
+    graph: LawGraph,
+    value: unknown,
+    visit: (node: Node) => void
+  ): void {
+    if (Array.isArray(value)) {
+      for (const item of value) this.visitReferences(graph, item, visit);
+      return;
+    }
+    if (value === null || typeof value !== "object") return;
+    const record = value as Readonly<Record<string, unknown>>;
+    if (record.kind === "dependency-export") {
+      if (
+        typeof record.entityKind !== "string" ||
+        typeof record.label !== "string"
+      ) {
+        throw new Error("typed law graph has a malformed dependency export");
+      }
+      // Resolution is supplied by the USD emitter itself. There is no second implementation
+      // of domain qualification, shared-contract fallback, or framework relation identity here.
+      const path = this.resolveExport(graph, record as unknown as Dependency);
+      if (path.startsWith("/Nomos/Framework/")) return;
+      const target = this.byPath.get(path);
+      if (target === undefined)
+        throw new Error(`emitted law dependency '${path}' has no indexed node`);
+      visit(target);
+      return;
+    }
+    // References are nominal {id} records. An entity's own identity/source is not an edge.
+    if (typeof record.id === "string" && Object.keys(record).length === 1) {
+      const target = this.local.get(graph)?.get(record.id);
+      if (target === undefined)
+        throw new Error(
+          `law dependency has missing local identity '${record.id}'`
+        );
+      visit(target);
+      return;
+    }
+    for (const [key, nested] of Object.entries(record)) {
+      if (key !== "entity" && key !== "source")
+        this.visitReferences(graph, nested, visit);
+    }
+  }
+
+  select(
+    seeds: Iterable<Node>,
+    includeApplicableGuards = false
+  ): LawDependencySlice {
+    const nodes = new Set<Node>();
+    const paths = new Set<string>();
+    const queue: Node[] = [];
+    let traversedEdges = 0;
+    const enqueue = (node: Node): void => {
+      if (!this.entries.has(node))
+        throw new Error("law dependency selection uses a foreign graph node");
+      if (node.kind === "domain" || nodes.has(node)) return;
+      nodes.add(node);
+      queue.push(node);
+    };
+    for (const seed of seeds) enqueue(seed);
+    // An index cursor, not Array.shift(): large closures remain linear in visited nodes/edges.
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+      const node = queue[cursor]!;
+      const entry = this.entries.get(node)!;
+      if (entry.path === undefined)
+        throw new Error(
+          `selected law dependency '${node.entity.id}' (${entry.graph.domain.entity.label}/${node.entity.label}) has no emitted USD path`
+        );
+      paths.add(entry.path);
+      for (const edge of this.edges.get(node) ?? []) {
+        traversedEdges++;
+        enqueue(edge);
+      }
+      if (includeApplicableGuards) {
+        for (const guard of this.guards.get(node) ?? []) {
+          traversedEdges++;
+          enqueue(guard);
+        }
+      }
+    }
+    return { nodes, paths, visitedNodes: nodes.size, traversedEdges };
+  }
+
+  command(command: Node): LawDependencySlice {
+    if (command.kind !== "intent")
+      throw new Error("command law selection requires an intent node");
+    return this.select([command], true);
+  }
+}
+
+/** Diagnostic output only. Not a serialized law contract or runtime authority. */
+export function commandWorkingSetReport(
+  graphs: readonly LawGraph[],
+  index: LawDependencyIndex
+) {
+  const commands = graphs.flatMap((graph) =>
+    graph.nodes.flatMap((node) => {
+      if (node.kind !== "intent") return [];
+      const slice = index.command(node);
+      return [
+        {
+          domain: graph.domain.entity.label,
+          directive: node.publicRoute,
+          id: node.entity.id,
+          visitedNodes: slice.visitedNodes,
+          traversedEdges: slice.traversedEdges,
+          paths: [...slice.paths].sort(),
+        },
+      ];
+    })
+  );
+  return {
+    kind: "nomos-command-working-sets-v1",
+    scope:
+      "compile-time static dependency selection; not runtime contract or performance proof",
+    graphNodes: graphs.reduce((sum, graph) => sum + graph.nodes.length, 0),
+    commands,
+  };
+}