knodin 0.7.5 → 0.8.2

package/dist/src/visualization.js

@@ -2,9 +2,180 @@ import { execFileSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { compareBytes } from "./compare.js";
+import { layoutGraph } from "./graph-layout.js";
 const DEFAULT_BYTE_BUDGET = 32_768;
+/** Repo scope draws coordinates for many nodes, so it needs a larger default. */
+const DEFAULT_REPO_BYTE_BUDGET = 524_288;
 const MIN_BYTE_BUDGET = 4_096;
+const MAX_BYTE_BUDGET = 2_097_152;
 const MAX_CALL_FLOW_EDGES = 20;
+/** Repo-scope caps. Exceeding either truncates and is reported honestly. */
+const MAX_REPO_NODES = 400;
+const MAX_REPO_EDGES = 900;
+/** Communities requested from `map()` for repo scope; 12 is the call-flow bound. */
+const REPO_COMMUNITY_TOP_N = 60;
+/** Palette for community fills. Fixed order keeps colour assignment stable. */
+const COMMUNITY_COLORS = [
+    "#4c78d8",
+    "#f58518",
+    "#e45756",
+    "#72b7b2",
+    "#54a24b",
+    "#eeca3b",
+    "#b279a2",
+    "#ff9da6",
+    "#9d755d",
+    "#bab0ac",
+];
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}
+function shortLabel(id, granularity) {
+    if (granularity === "symbol")
+        return id;
+    const segments = id.split("/");
+    return segments.length <= 2 ? id : segments.slice(-2).join("/");
+}
+/**
+ * Builds the repo-scope graph from `map()` output.
+ *
+ * Returns pre-cap totals alongside the capped node and edge lists so the
+ * caller can report what was withheld rather than presenting a sample as if it
+ * were the whole graph.
+ */
+function buildRepoGraph(map, graph, granularity) {
+    // Rank so that truncation keeps exact evidence before heuristics.
+    const ranked = [...mergeEdges(graph).values()].sort(compareArtifactEdges);
+    const edges = ranked.slice(0, MAX_REPO_EDGES);
+    const nodes = buildRepoNodes(endpointsOf(edges), granularity, {
+        degreeOf: indexDegrees(map, graph, granularity),
+        communityOf: indexCommunities(map),
+    });
+    // Keep the highest-degree nodes, then drop edges that lost an endpoint.
+    const kept = nodes.slice(0, MAX_REPO_NODES);
+    const keptIds = new Set(kept.map((node) => node.id));
+    return {
+        nodes: kept,
+        edges: edges.filter((edge) => keptIds.has(edge.from) && keptIds.has(edge.to)),
+        nodeTotal: endpointsOf(ranked).size,
+        // Distinct relationships before the node/edge caps. Duplicate records
+        // that merged into one drawn edge are not "withheld", so they must not
+        // inflate the denominator and make an untruncated graph look truncated.
+        edgeTotal: ranked.length,
+    };
+}
+/** Symbol/file -> community name, from whichever membership map() populated. */
+function indexCommunities(map) {
+    const communityOf = new Map();
+    for (const community of map.communities) {
+        for (const file of community.files ?? [])
+            communityOf.set(file, community.name);
+        for (const symbol of community.symbols ?? [])
+            communityOf.set(symbol, community.name);
+    }
+    return communityOf;
+}
+/**
+ * Node id -> reference degree. Symbol granularity keeps map()'s symbol-scoped
+ * hubs; file granularity uses the per-file degree the dependency graph already
+ * computed.
+ */
+function indexDegrees(map, graph, granularity) {
+    const degreeOf = new Map();
+    if (granularity === "symbol")
+        for (const hub of map.hubs)
+            degreeOf.set(hub.symbol, hub.degree);
+    else
+        for (const [file, degree] of Object.entries(graph.degrees))
+            degreeOf.set(file, degree);
+    return degreeOf;
+}
+/**
+ * Collapses the dependency graph's records into the edges the artifact draws:
+ * one per distinct (from, to, kind), keyed so that duplicates merge instead of
+ * being drawn on top of each other.
+ */
+function mergeEdges(graph) {
+    const merged = new Map();
+    for (const edge of graph.edges) {
+        // Endpoints are used exactly as stored under both granularities. A file is
+        // a valid node in the symbol view too, and inventing a symbol for one would
+        // be a fabrication — so there is nothing to resolve. This was a function
+        // whose two branches both returned their argument, which read as though a
+        // mapping happened here.
+        const from = edge.fromFile;
+        const to = edge.toFile;
+        if (!from || !to || from === to)
+            continue;
+        // JSON encoding rather than a delimiter. Both endpoints are file paths,
+        // which may contain any byte except NUL and `/`, so no printable separator
+        // is collision-proof — and reaching for NUL is how this file acquired two
+        // raw 0x00 bytes, which blinds grep across the whole file while still
+        // reporting success. Encoding the tuple sidesteps the choice entirely.
+        const key = JSON.stringify([from, to, edge.kind]);
+        const existing = merged.get(key);
+        // Exact only when a narrow source declaration backs the edge at full
+        // confidence; anything weaker must read as heuristic.
+        const label = edge.sourceEvidence && edge.confidence >= 1 ? "exact" : "heuristic";
+        if (existing) {
+            // A merged pair is only "exact" when every contributing edge was.
+            if (label === "heuristic")
+                existing.label = "heuristic";
+            continue;
+        }
+        merged.set(key, {
+            from,
+            to,
+            kind: edge.kind,
+            evidence: edge.sourceEvidence ?? "no narrow source declaration recorded",
+            label,
+        });
+    }
+    return merged;
+}
+/** Distinct node ids touched by `edges`, in first-appearance order. */
+function endpointsOf(edges) {
+    const ids = new Set();
+    for (const edge of edges) {
+        ids.add(edge.from);
+        ids.add(edge.to);
+    }
+    return ids;
+}
+/**
+ * Materializes drawable nodes for `ids`, ordered by the degree that decides
+ * which of them survive the node cap.
+ */
+function buildRepoNodes(ids, granularity, index) {
+    return [...ids]
+        .map((id) => ({
+        id,
+        label: shortLabel(id, granularity),
+        weight: index.degreeOf.get(id) ?? 1,
+        community: index.communityOf.get(id),
+    }))
+        .sort(compareRepoNodes);
+}
+/**
+ * Byte order, not localeCompare: these sorts decide which edges and nodes
+ * survive the caps, so collation differing by host locale or ICU build would
+ * change the artifact's contents, not merely its ordering — and this file
+ * promises byte-identical output from identical evidence.
+ */
+function compareArtifactEdges(left, right) {
+    if (left.label !== right.label)
+        return left.label === "exact" ? -1 : 1;
+    if (left.from !== right.from)
+        return compareBytes(left.from, right.from);
+    return compareBytes(left.to, right.to);
+}
+/** Highest degree first; byte order breaks ties, for the reason above. */
+function compareRepoNodes(left, right) {
+    return left.weight === right.weight
+        ? compareBytes(left.id, right.id)
+        : right.weight - left.weight;
+}
 function html(value) {
     return value
         .replaceAll("&", "&amp;")
@@ -46,6 +217,67 @@ function safeOutput(repo, output) {
         throw new Error("knodin visualize: output path may not traverse a symlink outside the repository");
     return { absolute, relative: path.relative(repo, absolute).replaceAll(path.sep, "/") };
 }
+/**
+ * Renders the repo-scope artifact: an inline SVG with coordinates computed at
+ * generation time, plus a community legend and honest totals. No script tags
+ * and no external references, so the file works offline and unchanged evidence
+ * reproduces identical bytes.
+ */
+function renderRepo(input) {
+    const { positions, viewport } = layoutGraph(input.nodes.map((node) => ({ id: node.id, weight: node.weight })), input.edges.map((edge) => ({ from: edge.from, to: edge.to })), input.commit);
+    const at = new Map(positions.map((position) => [position.id, position]));
+    // Colour by community, in first-appearance order for stable assignment.
+    const colorOf = new Map();
+    for (const node of input.nodes) {
+        if (!node.community || colorOf.has(node.community))
+            continue;
+        colorOf.set(node.community, COMMUNITY_COLORS[colorOf.size % COMMUNITY_COLORS.length]);
+    }
+    const unassigned = "#9aa5b1";
+    const maxWeight = Math.max(1, ...input.nodes.map((node) => node.weight));
+    const edgeSvg = input.edges
+        .map((edge) => {
+        const from = at.get(edge.from);
+        const to = at.get(edge.to);
+        if (!from || !to)
+            return "";
+        // Dashed strokes mark heuristic or inferred evidence; solid means the
+        // edge is backed by a narrow source declaration.
+        const dash = edge.label === "heuristic" ? ' stroke-dasharray="4 3"' : "";
+        const title = html(`${edge.from} → ${edge.to} (${edge.kind}, ${edge.label})`);
+        return `<line x1="${from.x}" y1="${from.y}" x2="${to.x}" y2="${to.y}" stroke="#c3ccd8" stroke-width="1"${dash}><title>${title}</title></line>`;
+    })
+        .join("");
+    const nodeSvg = input.nodes
+        .map((node) => {
+        const position = at.get(node.id);
+        if (!position)
+            return "";
+        const radius = 3 + 9 * Math.sqrt(node.weight / maxWeight);
+        const fill = node.community ? (colorOf.get(node.community) ?? unassigned) : unassigned;
+        const community = node.community ? ` — ${node.community}` : " — unassigned";
+        const title = `${node.label}${community} (degree ${node.weight})`;
+        return `<circle cx="${position.x}" cy="${position.y}" r="${round2(radius)}" fill="${fill}" fill-opacity="0.85" stroke="#ffffff" stroke-width="1"><title>${html(title)}</title></circle>`;
+    })
+        .join("");
+    const legendRows = input.communities
+        .map((community) => {
+        const swatch = colorOf.get(community.name) ?? unassigned;
+        return `<li><span class="sw" style="background:${swatch}"></span>${html(community.name)} <span class="meta">${community.size} symbols, cohesion ${community.cohesion.toFixed(3)}</span></li>`;
+    })
+        .join("");
+    const shown = (count, total, noun) => count === total
+        ? `all ${total} ${noun}`
+        : `${count} of ${total} ${noun} (${total - count} withheld by the artifact budget)`;
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>knodin repository graph</title><style>body{font:16px system-ui,sans-serif;margin:2rem auto;max-width:78rem;color:#172033;background:#f6f8fb;line-height:1.45}section{background:#fff;border:1px solid #d9dee7;border-radius:.55rem;padding:1rem 1.25rem;margin:1rem 0}svg{width:100%;height:auto;background:#fdfefe;border-radius:.4rem}ul{list-style:none;padding:0;columns:2;column-gap:2rem}li{margin:.35rem 0;break-inside:avoid}.sw{display:inline-block;width:.75rem;height:.75rem;border-radius:.2rem;margin-right:.5rem;vertical-align:baseline}.meta{color:#526170;font-size:.85em}code{background:#edf1f6;padding:.1rem .3rem;border-radius:.2rem}.key{color:#526170;font-size:.9em}</style></head>
+<body><h1>knodin repository graph</h1><p>Generated locally from the persisted knodin graph; no hosted service was contacted. Source commit <code>${html(input.commit)}</code>; index freshness <code>${html(input.freshness)}</code>; granularity <code>${html(input.granularity)}</code>.</p>
+<section><h2>Architecture</h2><svg viewBox="0 0 ${viewport} ${viewport}" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Repository dependency graph">${edgeSvg}${nodeSvg}</svg>
+<p class="key">Solid edges carry a narrow source declaration. Dashed edges are heuristic or inferred and are not proof of a relationship. Node size follows reference degree.</p></section>
+<section><h2>Coverage</h2><p>Showing ${shown(input.nodes.length, input.nodeTotal, input.granularity === "file" ? "files" : "symbols")}, ${shown(input.edges.length, input.edgeTotal, "relationships")}, and ${shown(input.communities.length, input.communityTotal, "communities")}.</p></section>
+<section><h2>Communities</h2><ul>${legendRows || "<li>No communities were returned.</li>"}</ul></section>
+</body></html>\n`;
+}
 function render(input) {
     const communityRows = input.communities
         .map((community) => {
@@ -72,25 +304,93 @@ function render(input) {
 <section><h2>Call-flow navigation</h2><p>Static downstream traversal from <code>${html(input.entry)}</code>, depth ${input.depth}; this is not a runtime trace.</p><ul>${edgeRows(input.callFlowEdges)}</ul></section>
 </body></html>\n`;
 }
-export async function writeVisualization(engine, repoPath, request) {
-    const repo = fs.realpathSync(repoPath);
-    const output = safeOutput(repo, request.outputPath);
-    const entry = request.entry.trim();
-    if (!entry)
-        throw new Error("knodin visualize: an entry selector is required");
-    const depth = request.depth ?? 3;
-    if (!Number.isInteger(depth) || depth < 1 || depth > 6)
-        throw new Error("knodin visualize: --depth must be an integer from 1 through 6");
-    const byteBudget = request.byteBudget ?? DEFAULT_BYTE_BUDGET;
-    if (!Number.isInteger(byteBudget) || byteBudget < MIN_BYTE_BUDGET || byteBudget > 65_536)
-        throw new Error("knodin visualize: --max-bytes must be an integer from 4096 through 65536");
-    const [map, traversal] = await Promise.all([
-        engine.map(repo, "standard", { topN: 12, sort: "name" }),
-        engine.query("traverse", entry, repo, undefined, MAX_CALL_FLOW_EDGES, depth, "standard", request.selector, undefined, { direction: "downstream", relationKinds: ["call"], includeDataFlow: true }),
+/**
+ * Repo-scope artifact. Renders the whole architecture graph rather than a
+ * traversal from one entry, so it consults `map()` alone.
+ *
+ * Budget pressure sheds edges first, then nodes, then communities — losing
+ * relationships degrades the drawing least, and the coverage section keeps
+ * reporting the pre-truncation totals throughout.
+ */
+async function writeRepoVisualization(engine, repo, output, options) {
+    // map() supplies community membership and naming; dependencyGraph() supplies
+    // the complete edge set. Using map()'s ranked edges here would draw a sample
+    // while the coverage line implied it was the whole graph.
+    const [map, dependencies] = await Promise.all([
+        engine.map(repo, "standard", { topN: REPO_COMMUNITY_TOP_N, sort: "size" }),
+        engine.dependencyGraph(repo),
     ]);
-    if (traversal.ambiguity || traversal.count === 0)
-        throw new Error("knodin visualize: entry selector did not resolve to a traversable symbol");
-    const architectureEdges = map.edges
+    const graph = buildRepoGraph(map, dependencies, options.granularity);
+    const communityTotal = map.communityCount ?? map.communities.length;
+    const commit = sourceCommit(repo);
+    const freshness = map.staleness ?? "unknown";
+    let nodes = graph.nodes;
+    let edges = graph.edges;
+    let communities = map.communities.map((community) => ({
+        name: community.name,
+        size: community.size,
+        cohesion: community.cohesion,
+    }));
+    let truncated = graph.nodes.length < graph.nodeTotal ||
+        graph.edges.length < graph.edgeTotal ||
+        communities.length < communityTotal;
+    let artifact = "";
+    for (;;) {
+        artifact = renderRepo({
+            commit,
+            freshness,
+            granularity: options.granularity,
+            nodes,
+            edges,
+            communities,
+            nodeTotal: graph.nodeTotal,
+            edgeTotal: graph.edgeTotal,
+            communityTotal,
+            truncated,
+        });
+        if (Buffer.byteLength(artifact) <= options.byteBudget)
+            break;
+        truncated = true;
+        if (edges.length)
+            edges = edges.slice(0, -1);
+        else if (nodes.length)
+            nodes = nodes.slice(0, -1);
+        else if (communities.length)
+            communities = communities.slice(0, -1);
+        else
+            throw new Error("knodin visualize: budget is too small for visualization metadata");
+    }
+    fs.mkdirSync(path.dirname(output.absolute), { recursive: true });
+    fs.writeFileSync(output.absolute, artifact);
+    return {
+        outputPath: output.relative,
+        bytes: Buffer.byteLength(artifact),
+        sha256: crypto.createHash("sha256").update(artifact).digest("hex"),
+        byteBudget: options.byteBudget,
+        truncated,
+        indexFreshness: freshness,
+        scope: "repo",
+        callFlow: { entry: "", depth: 0, edgeCount: 0, truncated: false },
+        repo: {
+            granularity: options.granularity,
+            nodeCount: nodes.length,
+            nodeTotal: graph.nodeTotal,
+            edgeCount: edges.length,
+            edgeTotal: graph.edgeTotal,
+            communityCount: communities.length,
+            communityTotal,
+        },
+    };
+}
+/**
+ * Bounded architecture relationships from `map()`.
+ *
+ * Only edges carrying source evidence are drawn, and an edge is "exact" only
+ * when it was extracted at full confidence — anything the engine labelled
+ * heuristic, or merely inferred, must read as heuristic here too.
+ */
+function toArchitectureEdges(edges) {
+    return edges
         .filter((edge) => Boolean(edge.sourceEvidence))
         .slice(0, MAX_CALL_FLOW_EDGES)
         .map((edge) => ({
@@ -102,7 +402,16 @@ export async function writeVisualization(engine, repoPath, request) {
             ? "heuristic"
             : "exact",
     }));
-    const callFlowEdges = (traversal.edges ?? []).slice(0, MAX_CALL_FLOW_EDGES).map((edge) => ({
+}
+/**
+ * Bounded call-flow relationships from the downstream traversal.
+ *
+ * Traversal edges carry their evidence on the data-flow record when there is
+ * one; otherwise the file and line stand in, naming what is missing rather than
+ * rendering a blank.
+ */
+function toCallFlowEdges(edges) {
+    return edges.slice(0, MAX_CALL_FLOW_EDGES).map((edge) => ({
         from: edge.from,
         to: edge.to,
         kind: edge.kind ?? "call",
@@ -112,6 +421,49 @@ export async function writeVisualization(engine, repoPath, request) {
             ? "heuristic"
             : "exact",
     }));
+}
+/**
+ * Applies defaults and rejects an unusable request before any work is done.
+ *
+ * Every ceiling and enum names the flag that sets it, because these surface on
+ * the CLI and an error the operator cannot act on is just a failure.
+ */
+function validateRequest(request) {
+    const scope = request.scope ?? "call-flow";
+    if (scope !== "call-flow" && scope !== "repo")
+        throw new Error("knodin visualize: --scope must be call-flow or repo");
+    const granularity = request.granularity ?? "file";
+    if (granularity !== "file" && granularity !== "symbol")
+        throw new Error("knodin visualize: --granularity must be file or symbol");
+    const entry = (request.entry ?? "").trim();
+    // Repo scope draws the whole graph, so it has no entry to resolve.
+    if (scope === "call-flow" && !entry)
+        throw new Error("knodin visualize: an entry selector is required");
+    const depth = request.depth ?? 3;
+    if (!Number.isInteger(depth) || depth < 1 || depth > 6)
+        throw new Error("knodin visualize: --depth must be an integer from 1 through 6");
+    const byteBudget = request.byteBudget ?? (scope === "repo" ? DEFAULT_REPO_BYTE_BUDGET : DEFAULT_BYTE_BUDGET);
+    if (!Number.isInteger(byteBudget) || byteBudget < MIN_BYTE_BUDGET || byteBudget > MAX_BYTE_BUDGET)
+        throw new Error(`knodin visualize: --max-bytes must be an integer from ${MIN_BYTE_BUDGET} through ${MAX_BYTE_BUDGET}`);
+    return { scope, granularity, entry, depth, byteBudget };
+}
+export async function writeVisualization(engine, repoPath, request) {
+    const repo = fs.realpathSync(repoPath);
+    const output = safeOutput(repo, request.outputPath);
+    const { scope, granularity, entry, depth, byteBudget } = validateRequest(request);
+    if (scope === "repo")
+        return writeRepoVisualization(engine, repo, output, {
+            granularity,
+            byteBudget,
+        });
+    const [map, traversal] = await Promise.all([
+        engine.map(repo, "standard", { topN: 12, sort: "name" }),
+        engine.query("traverse", entry, repo, undefined, MAX_CALL_FLOW_EDGES, depth, "standard", request.selector, undefined, { direction: "downstream", relationKinds: ["call"], includeDataFlow: true }),
+    ]);
+    if (traversal.ambiguity || traversal.count === 0)
+        throw new Error("knodin visualize: entry selector did not resolve to a traversable symbol");
+    const architectureEdges = toArchitectureEdges(map.edges);
+    const callFlowEdges = toCallFlowEdges(traversal.edges ?? []);
     let communities = map.communities.slice(0, 12);
     let hubs = map.hubs.slice(0, 10);
     let bridges = map.bridges.slice(0, 10);
@@ -157,6 +509,7 @@ export async function writeVisualization(engine, repoPath, request) {
         byteBudget,
         truncated,
         indexFreshness: map.staleness ?? "unknown",
+        scope: "call-flow",
         callFlow: { entry, depth, edgeCount: callFlow.length, truncated: Boolean(traversal.truncated) },
     };
 }

package/dist/src/worktree-lifecycle.js

@@ -2,6 +2,7 @@ import childProcess from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { compareBytes } from "./compare.js";
 function git(repo, args) {
     return childProcess.execFileSync("git", args, {
         cwd: repo,
@@ -112,7 +113,8 @@ export function registerInitializedWorktree(repoPath) {
             lastSeenAt: now,
         });
     }
-    registry.entries.sort((left, right) => left.path.localeCompare(right.path));
+    // Byte order: the registry is written to disk in this order.
+    registry.entries.sort((left, right) => compareBytes(left.path, right.path));
     writeRegistry(repo, registry);
 }
 export async function inspectWorktrees(repoPath, status) {
@@ -207,7 +209,8 @@ export function reconcileWorktrees(repoPath) {
             removed.push(entry.path);
         }
     }
-    registry.entries.sort((left, right) => left.path.localeCompare(right.path));
+    // Byte order: the registry is written to disk in this order.
+    registry.entries.sort((left, right) => compareBytes(left.path, right.path));
     writeRegistry(repo, registry);
     return { schemaVersion: 1, added, restored, removed };
 }

package/docs/BEHAVIORAL-CONTRACT.md

@@ -0,0 +1,72 @@
+# Behavioral contract
+
+Knodin's intended product contract is the composition of seven behaviors behind the
+single local gateway: truthful budgets, explicit freshness and availability,
+source evidence and provenance, ambiguity-safe stable identity, recoverable
+handles, bounded diagnosis confidence, and privacy/locality. The authoritative
+operation-to-clause declaration matrix is
+[`contracts/behavior-contract-v1.json`](../contracts/behavior-contract-v1.json),
+and `npm run verify:c95` replays adversarial evidence before release. The gate
+dispatches all 22 operations and every schema-declared query/action
+discriminator against an offline linked-worktree fixture. Positive,
+action-specific response semantics fail closed when a required signal is absent.
+
+## Product answers, with checked evidence
+
+- **Value:** less manual context assembly and fewer missed dependencies. The
+  paired task method and its bounded results are checked in under
+  [`benchmarks/evaluations/c93-engineering-outcomes/`](../benchmarks/evaluations/c93-engineering-outcomes/).
+- **ROI:** fewer corrective agent round trips without hosted-service, account,
+  authentication, or source-egress overhead. C93 reports measured local task
+  outcomes and explicitly leaves billed cost and token counts unavailable when
+  the harness cannot observe them.
+- **Tomorrow:** run `knodin init`, inspect `knodin status`, then use the existing
+  checkout through the CLI or the single `knodin.knodin` MCP gateway. The
+  installation and client readiness evidence remains bounded by C91 below.
+- **Secret sauce:** stable identity, source provenance, graph freshness, and
+  truthful response budgets remain composed across applicable operations. The
+  C95 matrix and representative replay fail closed if an operation declaration,
+  mandatory clause, or representative fixture is omitted.
+
+## Composition invariants
+
+A continuation or retained artifact may expand a bounded response only while
+preserving its stable identity and evidence provenance. Stale, unavailable, or
+ambiguous graph evidence must remain explicit and cannot be promoted to a
+confident failure diagnosis, impact claim, or runtime-causality proof.
+
+The C95 fixtures run in a linked non-default worktree. A child harness installs
+guards before importing the production dispatcher and observes global `fetch`,
+HTTP/HTTPS request and get, TCP/TLS connection, callback and promise DNS
+resolution, JavaScript-visible native-addon loading, and production-owned child
+process argv, inherited or explicit environment, synchronous input, and streamed
+stdin boundaries. The release gate derives
+privacy and source-egress results from those observations: network attempts,
+credential forwarding, source bytes at network/subprocess boundaries, and
+native-addon loads must remain zero. Local subprocess execution is counted and
+permitted only when those observed payload checks remain clean.
+
+## Known bounds
+
+This replay proves the checked operation/action fixtures, not all repositories,
+languages, frameworks, dynamic runtime behavior, clients, or deployment
+environments. Static relationships and failure correlations are candidates,
+not runtime-causality proof. Budgets can truncate results; indexes can be stale
+or unavailable; names can be ambiguous; generated code, dynamic dispatch,
+framework wiring, and language coverage can leave relationships unresolved.
+
+C91 remains parked pending native client, runtime-manager, Homebrew, and
+Artifactory certification evidence. C94 remains blocked on C91 and therefore
+does not establish a certified five-minute client demonstration. No fixture,
+benchmark, or contract replay supports a universal superiority claim. The
+authoritative roadmap remains the complete source for limitations and status.
+
+A new production operation or schema-declared action must add an applicability
+row, positive action semantics, and isolated adversarial mutation before
+release; omission causes `verify:c95` and release preflight to fail. Every mapped
+fixture/clause row is independently redispatched through the real production
+handler, mutated at the guarded pre-serialization boundary, and rejected by the
+same oracle. Network construction is denied before body streaming. JavaScript
+cannot observe opaque operating-system activity performed entirely inside an
+already-loaded native library; these remain explicit bounds rather than claims
+of universal egress detection.

package/docs/CLI.md

@@ -32,7 +32,7 @@ example repository existence, mutually exclusive configuration modes, and
 graph-query target rules), but syntax cannot reach a handler unless the shared
 declarative model accepts it first.
 
-For support evidence, `knodin diagnostics enable|status|collect|inspect|clear|disable`
+For support evidence, `knodin diagnostics enable|status|preview|archive|inspect|clear|disable`
 manages an explicit local failure journal and redacted gzip JSON bundles.
 Collection does not upload data. See `docs/DIAGNOSTICS.md` for retention,
 redaction, inspection, and known bounds.
@@ -54,6 +54,25 @@ centrality, churn, co-change, and coupling evidence. Git history has explicit
 commit/file/time bounds and truthful unavailable or truncation states; see
 `docs/GIT-HISTORY-REVIEW.md`.
 
+`knodin visualize` writes a self-contained local HTML artifact and takes two
+scopes. The default, `--scope call-flow <entry>`, draws a bounded static
+downstream traversal from one entry symbol; `--depth` accepts 1 through 6.
+`--scope repo` needs no entry and draws the repository's dependency graph as
+inline SVG, with `--granularity file` (default) or `symbol`.
+
+Repo scope reads every recorded dependency rather than the ranked summary
+`knodin map` returns, so its coverage section measures against the whole graph.
+Node and edge caps and the `--max-bytes` budget (4096 through 2097152; repo
+scope defaults to 524288) can still withhold detail, and the artifact always
+states how much: "showing 200 of 1,847 relationships". Solid edges carry a
+narrow source declaration at full confidence; dashed edges are heuristic or
+inferred and are not proof of a relationship.
+
+Coordinates are computed when the artifact is written, from a PRNG seeded by
+the source commit, so the file contains no script and no network reference and
+identical evidence reproduces byte-identical output. That makes the artifact
+safe to open offline and its SHA-256 meaningful.
+
 `knodin pack grep` evaluates user patterns with exact-pinned RE2 WebAssembly,
 not Node's backtracking regular-expression engine. Backreferences and lookaround
 are rejected because they cannot retain RE2's linear-time guarantee. Route