@pablotech/neuro 0.1.22

package/cli.ts

@@ -0,0 +1,201 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Dag } from "./dag";
+import { isStamped } from "./dag";
+import type { Slices } from "./canonical";
+import { canonicalFor, driftedKeys } from "./canonical";
+import type { Finding } from "./validate";
+import { validate } from "./validate";
+import { renderMermaid, writeDagBlock } from "./mermaid";
+import { dagFromFiles, parseVaultNode } from "./markdown";
+import { sha256hex12 } from "./hash-node";
+
+// The vault-mode front-end over the same Dag type the TypeScript manifest front-end uses
+// (index.ts) — see README.md. Walks a directory tree of plain markdown/YAML vault files rather than
+// a compiled manifest, for a non-code consumer that has no toolchain.
+
+export type Command = "lint" | "mermaid" | "stale";
+const COMMANDS: readonly Command[] = ["lint", "mermaid", "stale"];
+
+export interface ParsedArgs {
+  command: Command;
+  dir: string;
+  write?: string;
+  update?: boolean;
+  json?: boolean;
+}
+
+// Hand-rolled arg parsing — no new dependency for three flags.
+export function parseArgs(argv: string[]): ParsedArgs {
+  const [command, dir, ...rest] = argv;
+  if (!command || !(COMMANDS as readonly string[]).includes(command)) {
+    throw new Error(`unknown subcommand "${command ?? ""}". Expected one of: ${COMMANDS.join(", ")}`);
+  }
+  if (!dir) throw new Error(`${command} requires a <dir> argument`);
+  const out: ParsedArgs = { command: command as Command, dir };
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--write") out.write = rest[++i];
+    else if (a === "--update") out.update = true;
+    else if (a === "--json") out.json = true;
+    else throw new Error(`unknown flag "${a}"`);
+  }
+  return out;
+}
+
+// Recursive readdir, collecting *.md (frontmatter nodes) and *.neuro-pil.yml (bare folder
+// manifests) into path -> raw text. Skips .git, node_modules, .neuro-pil (the stale stamp dir),
+// and any other dotfile/dotdir.
+export function walkVault(dir: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const walk = (d: string) => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const p = join(d, entry.name);
+      if (entry.isDirectory()) { walk(p); continue; }
+      if (entry.name.endsWith(".md") || entry.name.endsWith(".neuro-pil.yml")) out[p] = readFileSync(p, "utf8");
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+export interface LintResult {
+  findings: Finding[];
+  nodeCount: number;
+}
+
+// No sliceParity here — that check needs a host's slice map, and vault mode has no analogue for one
+// (see canonical.ts); it's a TS-manifest-only lint, run separately by whichever host wires slices up.
+export function runLint(dir: string): LintResult {
+  const dag = dagFromFiles(walkVault(dir));
+  return { findings: validate(dag), nodeCount: dag.nodes.length };
+}
+
+export function runMermaid(dir: string): string {
+  return renderMermaid(dagFromFiles(walkVault(dir)));
+}
+
+// One slice per source node key -> that node's own raw file text, keyed by node key rather than
+// path (a node's key comes from its frontmatter, not its filename).
+function subjectOf(files: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const text of Object.values(files)) {
+    const meta = parseVaultNode(text);
+    if (meta) out[meta.node] = text;
+  }
+  return out;
+}
+
+function slicesOf(dag: Dag): Slices<Record<string, string>> {
+  const slices: Slices<Record<string, string>> = {};
+  for (const n of dag.nodes) if (n.kind === "source") slices[n.key] = (subject) => subject[n.key];
+  return slices;
+}
+
+function stampPathOf(dir: string): string {
+  return join(dir, ".neuro-pil", "stamp.json");
+}
+
+export interface StaleResult {
+  baseline: boolean;
+  drifted: string[];
+  nodeCount: number;
+}
+
+// The same nodeHashesOf/staleNodesOf pattern the TypeScript manifest front-end uses, applied to a
+// vault directory instead of a compiled Dag. Read-only by default — the stamp is written only when
+// opts.update is true, matching this package's "read-only first" doctrine for anything touching a
+// real vault.
+export function runStale(dir: string, opts: { update?: boolean } = {}): StaleResult {
+  const files = walkVault(dir);
+  const dag = dagFromFiles(files);
+  const subject = subjectOf(files);
+  const slices = slicesOf(dag);
+  const now: Record<string, string> = {};
+  for (const n of dag.nodes) if (isStamped(n)) now[n.key] = sha256hex12(canonicalFor(dag, subject, slices, n.key));
+
+  const stampPath = stampPathOf(dir);
+  const stamped: Record<string, string> | null = existsSync(stampPath)
+    ? JSON.parse(readFileSync(stampPath, "utf8"))
+    : null;
+  const baseline = stamped === null;
+  const drifted = baseline ? [] : driftedKeys(now, stamped);
+
+  if (opts.update) {
+    mkdirSync(join(dir, ".neuro-pil"), { recursive: true });
+    writeFileSync(stampPath, JSON.stringify(now, null, 2) + "\n");
+  }
+
+  return { baseline, drifted, nodeCount: dag.nodes.length };
+}
+
+// Drift is reported before the "wrote stamp" line, including under --update: the drift is measured
+// against the *old* stamp (runStale computes it before overwriting), and without this a --update run
+// that exits 1 would print nothing about why.
+export function staleLines(
+  result: StaleResult,
+  opts: { dir: string; update?: boolean; json?: boolean },
+): string[] {
+  if (opts.json) return [JSON.stringify({ ...result, updated: opts.update === true })];
+
+  const lines: string[] = [];
+  if (result.baseline) lines.push("no prior stamp — nothing to compare.");
+  else if (result.drifted.length === 0) lines.push(`neuro-pil: no drift across ${result.nodeCount} stamped nodes.`);
+  else for (const k of result.drifted) lines.push(`[stale] ${k}`);
+
+  if (opts.update) lines.push(`Wrote stamp for ${result.nodeCount} nodes into ${stampPathOf(opts.dir)}`);
+  return lines;
+}
+
+function requireDir(dir: string): void {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+    throw new Error(`no such directory: ${dir}`);
+  }
+}
+
+function main() {
+  let parsed: ParsedArgs;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+    requireDir(parsed.dir);
+  } catch (err) {
+    process.stderr.write(`${(err as Error).message}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  if (parsed.command === "lint") {
+    const result = runLint(parsed.dir);
+    if (parsed.json) {
+      process.stdout.write(JSON.stringify(result) + "\n");
+    } else if (result.findings.length === 0) {
+      process.stdout.write(`neuro-pil: no findings across ${result.nodeCount} nodes.\n`);
+    } else {
+      for (const f of result.findings) process.stdout.write(`[${f.rule}] ${f.node}: ${f.message}\n`);
+    }
+    if (result.findings.length > 0) process.exitCode = 1;
+    return;
+  }
+
+  if (parsed.command === "mermaid") {
+    if (parsed.write) {
+      const doc = readFileSync(parsed.write, "utf8");
+      const dag = dagFromFiles(walkVault(parsed.dir));
+      writeFileSync(parsed.write, writeDagBlock(doc, dag));
+      process.stdout.write(`Wrote ${dag.nodes.length}-node mermaid into ${parsed.write}\n`);
+    } else {
+      process.stdout.write(runMermaid(parsed.dir) + "\n");
+    }
+    return;
+  }
+
+  // stale
+  const result = runStale(parsed.dir, { update: parsed.update });
+  for (const line of staleLines(result, { dir: parsed.dir, update: parsed.update, json: parsed.json })) {
+    process.stdout.write(line + "\n");
+  }
+  if (result.drifted.length > 0) process.exitCode = 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/compare.ts

@@ -0,0 +1,41 @@
+// A brain-comparison harness: given a case set, a set of candidate versions, a way to run one version
+// against one case, and a way to score the result, report each version's scores. See
+// ./ARCHITECTURE.md and ../akesi-pil/ARCHITECTURE.md for why this exists and what it deliberately
+// doesn't do.
+//
+// `run` and `score` are the entire extension surface, on purpose: this does not call any model
+// provider, does not assume Anthropic or any other vendor, and does not compete with an eval platform
+// (PromptLayer, Langfuse, Portkey, Helicone, MLflow) an adopter may already run. Wire `run` to whichever
+// SDK, self-hosted model, or nothing at all a given brain currently uses — the harness never sees it.
+//
+// `Case`, `Version`, and `Result` are deliberately opaque type parameters, not a shared `BrainEntry`
+// shape: an adopter's own registry entry is passed through untouched as `Version`, whatever shape it
+// happens to be.
+
+export interface VersionScore<Version> {
+  version: Version;
+  scores: number[];
+  mean: number;
+}
+
+export interface Comparison<Version> {
+  perVersion: VersionScore<Version>[];
+}
+
+export async function compareBrains<Case, Version, Result>(
+  cases: Case[],
+  versions: Version[],
+  run: (c: Case, v: Version) => Promise<Result>,
+  score: (result: Result, c: Case) => number | Promise<number>,
+): Promise<Comparison<Version>> {
+  const perVersion: VersionScore<Version>[] = [];
+  for (const version of versions) {
+    const scores: number[] = [];
+    for (const c of cases) {
+      scores.push(await score(await run(c, version), c));
+    }
+    const mean = scores.length === 0 ? 0 : scores.reduce((a, b) => a + b, 0) / scores.length;
+    perVersion.push({ version, scores, mean });
+  }
+  return { perVersion };
+}

package/dag.ts

@@ -0,0 +1,81 @@
+// The generalized shape of a source -> derived -> leaf/projection dependency graph.
+//
+// upstreamOf/downstreamOf/sourceClosureOf are the dependency-closure walk any build-graph engine in
+// this lineage needs (see README.md "Lineage") — the set of nodes to recompute is exactly the
+// downstream closure of what changed, never a human-maintained list.
+
+export type NodeKind = "source" | "derived" | "leaf" | "projection";
+
+export interface DagNode {
+  key: string;
+  label: string;
+  kind: NodeKind;
+  inputs: string[]; // keys of upstream nodes
+  basis: string; // the human sentence describing what this node is derived from
+  // Commentary, not evidence — never allowed to feed a node other than a `noteSink` (validate.ts's
+  // note-feeds-non-sink rule). Kept as a flag rather than a fifth NodeKind so it never changes a
+  // node's `source`-set membership, which is what canonical hashing keys off — see canonical.ts.
+  note?: true;
+  // The only kind of node allowed to consume a `note` node in its `inputs`.
+  noteSink?: true;
+}
+
+export interface Dag {
+  nodes: DagNode[];
+  dagNode(key: string): DagNode | undefined;
+  // Transitive upstream (everything this node depends on, directly or indirectly).
+  upstreamOf(key: string): Set<string>;
+  // Transitive downstream (everything that would be invalidated if this node changed).
+  downstreamOf(key: string): Set<string>;
+  // The `source` nodes a node ultimately depends on (its transitive upstream, filtered to sources,
+  // plus itself if it is itself a source). Every derived node is a deterministic function of the
+  // source nodes above it, so hashing over exactly this closure invalidates precisely the nodes whose
+  // sources actually changed. Sorted for a stable canonical order.
+  sourceClosureOf(key: string): string[];
+}
+
+// Pins, stars, and other UI-only attention flags are deliberately NOT modeled here — never a node,
+// never an edge. They must not affect any canonical string (see canonical.ts's pinNeutrality helper).
+
+export function isStamped(node: DagNode): boolean {
+  return node.kind !== "projection";
+}
+
+export function defineDag(nodes: DagNode[]): Dag {
+  const byKey = new Map(nodes.map((n) => [n.key, n]));
+  const dagNode = (key: string) => byKey.get(key);
+
+  const upstreamOf = (key: string): Set<string> => {
+    const out = new Set<string>();
+    const walk = (k: string) => {
+      for (const dep of byKey.get(k)?.inputs ?? []) {
+        if (!out.has(dep)) { out.add(dep); walk(dep); }
+      }
+    };
+    walk(key);
+    return out;
+  };
+
+  const downstreamOf = (key: string): Set<string> => {
+    const children = (k: string) => nodes.filter((n) => n.inputs.includes(k)).map((n) => n.key);
+    const out = new Set<string>();
+    const walk = (k: string) => {
+      for (const c of children(k)) {
+        if (!out.has(c)) { out.add(c); walk(c); }
+      }
+    };
+    walk(key);
+    return out;
+  };
+
+  const sourceKeys = new Set(nodes.filter((n) => n.kind === "source").map((n) => n.key));
+
+  const sourceClosureOf = (key: string): string[] => {
+    const closure = new Set<string>();
+    if (sourceKeys.has(key)) closure.add(key);
+    for (const u of upstreamOf(key)) if (sourceKeys.has(u)) closure.add(u);
+    return [...closure].sort();
+  };
+
+  return { nodes, dagNode, upstreamOf, downstreamOf, sourceClosureOf };
+}

package/hash-node.ts

@@ -0,0 +1,8 @@
+import { createHash } from "node:crypto";
+
+// node:crypto variant of the truncated-SHA-256 hash. Kept separate from the isomorphic core (dag.ts,
+// canonical.ts) so nothing that runs in a browser or a Cloudflare Pages Function ever pulls in
+// node:crypto — see hash-web.ts for that path.
+export function sha256hex12(str: string): string {
+  return createHash("sha256").update(str).digest("hex").slice(0, 12);
+}

package/hash-web.ts

@@ -0,0 +1,8 @@
+const enc = new TextEncoder();
+
+// SubtleCrypto variant of the truncated-SHA-256 hash, for the browser and Cloudflare Pages Functions
+// (workerd exposes the same Web Crypto API). See hash-node.ts for the node:crypto twin.
+export async function sha256hex12(str: string): Promise<string> {
+  const buf = await globalThis.crypto.subtle.digest("SHA-256", enc.encode(str) as BufferSource);
+  return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, 12);
+}

package/index.ts

@@ -0,0 +1,11 @@
+// The isomorphic core: safe to import from a browser bundle, a Cloudflare Pages Function, or a
+// node:crypto-based CLI alike. Runtime-specific hashing lives in ./hash-node and ./hash-web instead —
+// import those directly rather than adding a `node:`/DOM-specific dependency here.
+export type { NodeKind, DagNode, Dag } from "./dag";
+export { defineDag, isStamped } from "./dag";
+export type { Slices } from "./canonical";
+export { stableStringify, canonicalFor, canonicalMap, driftedKeys } from "./canonical";
+export type { MermaidBlockMarkers } from "./mermaid";
+export { renderMermaid, extractDagBlock, writeDagBlock, DEFAULT_MERMAID_MARKERS } from "./mermaid";
+export type { Finding, ValidateOptions } from "./validate";
+export { validate, sliceParity } from "./validate";

package/markdown.ts

@@ -0,0 +1,120 @@
+import type { Dag, DagNode, NodeKind } from "./dag";
+import { defineDag } from "./dag";
+
+// The second front-end for the same Dag type — a plain-markdown vault convention, alongside the
+// TypeScript manifest front-end (defineDag). Built to prove the shape works for a no-toolchain
+// consumer before any concrete vault needs it.
+//
+// Deliberately NOT a general YAML parser — only the flat scalar/flow-list/block-list/boolean subset
+// this schema needs (no nesting beyond one list, no anchors, no block scalars). If a future vault's
+// frontmatter needs more than this, that's the point at which a real YAML dependency earns its keep;
+// not before there's a second real consumer to justify adding one.
+
+export interface VaultNodeMeta {
+  node: string;
+  kind: NodeKind;
+  label?: string;
+  inputs?: string[];
+  basis?: string;
+  note?: boolean;
+  noteSink?: boolean;
+}
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+// The frontmatter block's raw text (between the `---` delimiters), or null if the file has none —
+// e.g. a `.neuro-pil.yml` folder manifest has no delimiters at all, just the block directly.
+export function extractFrontmatter(text: string): string | null {
+  const m = FRONTMATTER.exec(text);
+  return m ? m[1] : null;
+}
+
+function unquote(s: string): string {
+  const v = s.trim();
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) return v.slice(1, -1);
+  return v;
+}
+
+function parseScalar(raw: string): string | boolean {
+  const v = raw.trim();
+  if (v === "true") return true;
+  if (v === "false") return false;
+  return unquote(v);
+}
+
+function parseFlowList(raw: string): string[] {
+  const inner = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
+  if (!inner.trim()) return [];
+  return inner.split(",").map((s) => unquote(s));
+}
+
+// One key per line: `key: value`, `key: [a, b, c]` (flow list), or `key:` followed by `  - item`
+// lines (block list). Not a general YAML parser — see the module comment above.
+export function parseFrontmatterBlock(block: string): Record<string, unknown> {
+  const lines = block.split(/\r?\n/);
+  const out: Record<string, unknown> = {};
+  let currentListKey: string | null = null;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const listItem = /^\s+-\s*(.+)$/.exec(line);
+    if (listItem && currentListKey) {
+      (out[currentListKey] as string[]).push(unquote(listItem[1]));
+      continue;
+    }
+    currentListKey = null;
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    const [, key, rest] = kv;
+    if (rest.trim() === "") {
+      out[key] = [];
+      currentListKey = key;
+    } else if (rest.trim().startsWith("[")) {
+      out[key] = parseFlowList(rest);
+    } else {
+      out[key] = parseScalar(rest);
+    }
+  }
+  return out;
+}
+
+// Parses one file's frontmatter (or, for a `.neuro-pil.yml` folder manifest, the whole file) into
+// a node descriptor. Returns null for a file with no frontmatter, or missing the two required keys
+// (`node`, `kind`) — silently skipped by dagFromFiles rather than thrown, since a vault will always
+// have plenty of files (a README, a legal PDF's sibling notes) that were never meant to be graph
+// nodes at all.
+export function parseVaultNode(text: string): VaultNodeMeta | null {
+  const block = extractFrontmatter(text) ?? (/^[A-Za-z_][\w-]*:/.test(text) ? text : null);
+  if (!block) return null;
+  const parsed = parseFrontmatterBlock(block);
+  if (typeof parsed.node !== "string" || typeof parsed.kind !== "string") return null;
+  return {
+    node: parsed.node,
+    kind: parsed.kind as NodeKind,
+    label: typeof parsed.label === "string" ? parsed.label : undefined,
+    inputs: Array.isArray(parsed.inputs) ? (parsed.inputs as string[]) : [],
+    basis: typeof parsed.basis === "string" ? parsed.basis : "",
+    note: parsed.note === true,
+    noteSink: parsed.noteSink === true,
+  };
+}
+
+// Builds a Dag from a set of already-read file contents (path -> text). The host walks the
+// filesystem and reads files; this module only knows how to turn text into a Dag, not how to find
+// it — keeps this library free of any node:fs dependency.
+export function dagFromFiles(files: Record<string, string>): Dag {
+  const nodes: DagNode[] = [];
+  for (const text of Object.values(files)) {
+    const meta = parseVaultNode(text);
+    if (!meta) continue;
+    nodes.push({
+      key: meta.node,
+      label: meta.label ?? meta.node,
+      kind: meta.kind,
+      inputs: meta.inputs ?? [],
+      basis: meta.basis ?? "",
+      ...(meta.note ? { note: true as const } : {}),
+      ...(meta.noteSink ? { noteSink: true as const } : {}),
+    });
+  }
+  return defineDag(nodes);
+}

package/mermaid.ts

@@ -0,0 +1,37 @@
+import type { Dag } from "./dag";
+
+// A DAG diagram generated from the manifest itself, not hand-maintained, so the picture can never
+// drift from the code. Keys off node key + label + inputs only, never `kind`, so it is unaffected by
+// a source/derived rename.
+
+export function renderMermaid(dag: Dag): string {
+  const lines = ["graph LR"];
+  for (const n of dag.nodes) lines.push(`  ${n.key}["${n.label}"]`);
+  for (const n of dag.nodes) for (const dep of n.inputs) lines.push(`  ${dep} --> ${n.key}`);
+  return lines.join("\n");
+}
+
+export interface MermaidBlockMarkers { start: string; end: string }
+
+export const DEFAULT_MERMAID_MARKERS: MermaidBlockMarkers = { start: "<!-- DAG:START -->", end: "<!-- DAG:END -->" };
+
+// The mermaid body currently checked into a doc (between the markers), or null if the markers/block
+// are missing. Shared by the writer and a drift test so both parse the block identically.
+export function extractDagBlock(docText: string, markers: MermaidBlockMarkers = DEFAULT_MERMAID_MARKERS): string | null {
+  const s = docText.indexOf(markers.start);
+  const e = docText.indexOf(markers.end);
+  if (s < 0 || e < 0 || e < s) return null;
+  const between = docText.slice(s + markers.start.length, e);
+  const m = /```mermaid\n([\s\S]*?)\n```/.exec(between);
+  return m ? m[1] : null;
+}
+
+// Rewrites the fenced block between the markers to the current renderMermaid(dag) output. Throws if
+// the markers aren't present, rather than silently no-op'ing on a doc that was never wired up.
+export function writeDagBlock(docText: string, dag: Dag, markers: MermaidBlockMarkers = DEFAULT_MERMAID_MARKERS): string {
+  const s = docText.indexOf(markers.start);
+  const e = docText.indexOf(markers.end);
+  if (s < 0 || e < 0 || e < s) throw new Error(`markers ${markers.start} / ${markers.end} not found`);
+  const block = `${markers.start}\n\n\`\`\`mermaid\n${renderMermaid(dag)}\n\`\`\`\n\n${markers.end}`;
+  return docText.slice(0, s) + block + docText.slice(e + markers.end.length);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pablotech/neuro",
+  "version": "0.1.22",
+  "description": "Dependency-graph, staleness and canonical-hashing engine: record what a value was derived from, and know later whether that evidence has moved. Domain-free.",
+  "type": "module",
+  "main": "index.ts",
+  "types": "index.ts",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "*.ts",
+    "benchmarks/**/*.ts",
+    "!tests"
+  ],
+  "exports": {
+    ".": "./index.ts",
+    "./hash-node": "./hash-node.ts",
+    "./hash-web": "./hash-web.ts",
+    "./markdown": "./markdown.ts",
+    "./compare": "./compare.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "cli": "tsx cli.ts",
+    "bench": "tsx benchmarks/staleness-corpus.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.22.3",
+    "vitest": "^4.1.8"
+  }
+}

package/validate.ts

@@ -0,0 +1,98 @@
+import type { Dag } from "./dag";
+import type { Slices } from "./canonical";
+
+export interface Finding {
+  rule: string;
+  node: string;
+  message: string;
+}
+
+export interface ValidateOptions {
+  // source-kind nodes with zero downstream consumers are flagged as `orphan` (dead wiring — data
+  // collected that nothing ever reads) unless their key is listed here. derived/leaf/projection nodes
+  // are exempt: a "generated together" or "input-local" artifact is routinely also a terminal report
+  // section shown directly to the user, not just an intermediate computation step — verified against
+  // the live Finding DAG, where several `derived` nodes (e.g. healthProgression) are legitimately
+  // terminal and would otherwise false-positive on every run.
+  terminalAllowlist?: string[];
+}
+
+// Structural checks over the graph shape alone — no host data (a subject, a stamp, a slices map)
+// required. See sliceParity() below for the one check that needs a host's slice map too.
+export function validate(dag: Dag, opts: ValidateOptions = {}): Finding[] {
+  const findings: Finding[] = [];
+  const keys = new Set(dag.nodes.map((n) => n.key));
+  const allowlist = new Set(opts.terminalAllowlist ?? []);
+
+  const seenKeys = new Set<string>();
+  for (const n of dag.nodes) {
+    if (seenKeys.has(n.key)) findings.push({ rule: "duplicate-key", node: n.key, message: `duplicate node key "${n.key}"` });
+    seenKeys.add(n.key);
+
+    for (const dep of n.inputs) {
+      if (!keys.has(dep)) findings.push({ rule: "unknown-input", node: n.key, message: `"${n.key}" lists unknown input "${dep}"` });
+    }
+
+    if (n.kind === "source" && n.inputs.length > 0) {
+      findings.push({ rule: "source-has-inputs", node: n.key, message: `source node "${n.key}" declares inputs — sources are raw, never derived` });
+    }
+  }
+
+  for (const n of dag.nodes) {
+    const path = cyclePath(dag, n.key);
+    if (path) findings.push({ rule: "cycle", node: n.key, message: `cycle: ${path.join(" -> ")}` });
+  }
+
+  const downstreamCount = new Map<string, number>(dag.nodes.map((n) => [n.key, 0]));
+  for (const n of dag.nodes) for (const dep of n.inputs) downstreamCount.set(dep, (downstreamCount.get(dep) ?? 0) + 1);
+  for (const n of dag.nodes) {
+    if (n.kind === "source" && downstreamCount.get(n.key) === 0 && !allowlist.has(n.key)) {
+      findings.push({ rule: "orphan", node: n.key, message: `"${n.key}" (source) is consumed by nothing — collected but never read by anything downstream` });
+    }
+  }
+
+  for (const n of dag.nodes) {
+    for (const dep of n.inputs) {
+      if (dag.dagNode(dep)?.note && !n.noteSink) {
+        findings.push({ rule: "note-feeds-non-sink", node: n.key, message: `"${n.key}" consumes note "${dep}" but isn't a noteSink — notes must never become evidence` });
+      }
+    }
+  }
+
+  return findings;
+}
+
+// The one node/edge relationship not captured by `Dag` alone: which source keys a host's slice map
+// (the functions that turn a subject into hashable data — see canonicalFor in canonical.ts) actually
+// covers. A source with no matching slice silently contributes nothing to any node's canonical string
+// (canonicalFor's `slices[k]?.(subject)` -> undefined); a slice with no matching source is dead code.
+export function sliceParity<T>(dag: Dag, slices: Slices<T>): Finding[] {
+  const findings: Finding[] = [];
+  const sourceKeys = new Set(dag.nodes.filter((n) => n.kind === "source").map((n) => n.key));
+  for (const k of sourceKeys) {
+    if (!(k in slices)) findings.push({ rule: "missing-slice", node: k, message: `source "${k}" has no matching slice function` });
+  }
+  for (const k of Object.keys(slices)) {
+    if (!sourceKeys.has(k)) findings.push({ rule: "missing-slice", node: k, message: `slice "${k}" doesn't match any source node` });
+  }
+  return findings;
+}
+
+// DFS returning the actual cycle path (not just a boolean) the first time `start` is revisited on its
+// own walk. Re-run per node rather than memoized across the whole graph — the graphs this validates
+// are tens of nodes, not thousands, so the O(n^2) worst case is not worth the complexity to avoid.
+function cyclePath(dag: Dag, start: string): string[] | null {
+  const path: string[] = [];
+  const visit = (k: string): string[] | null => {
+    const idx = path.indexOf(k);
+    if (idx !== -1) return [...path.slice(idx), k];
+    path.push(k);
+    for (const dep of dag.dagNode(k)?.inputs ?? []) {
+      const found = visit(dep);
+      if (found) return found;
+    }
+    path.pop();
+    return null;
+  };
+  return visit(start);
+}