knodin 0.7.6 → 0.8.3

package/dist/src/worktree-lifecycle.js

@@ -0,0 +1,234 @@
+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,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+}
+function canonicalPath(target) {
+    try {
+        return fs.realpathSync(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+function commonDirectory(repo) {
+    const value = git(repo, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).trim();
+    return path.resolve(repo, value);
+}
+function registryPath(repo) {
+    return path.join(commonDirectory(repo), "knodin", "worktrees.json");
+}
+function emptyRegistry() {
+    return { schemaVersion: 1, graphState: "per-worktree", entries: [] };
+}
+function readRegistry(repo) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(registryPath(repo), "utf-8"));
+        return parsed.schemaVersion === 1 && Array.isArray(parsed.entries) ? parsed : emptyRegistry();
+    }
+    catch {
+        return emptyRegistry();
+    }
+}
+function writeRegistry(repo, registry) {
+    const target = registryPath(repo);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const temporary = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(registry, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, target);
+}
+function identityFor(repo, worktreePath, classification) {
+    let administrativePath = classification;
+    try {
+        administrativePath = path.resolve(worktreePath, git(worktreePath, ["rev-parse", "--path-format=absolute", "--git-dir"]).trim());
+    }
+    catch {
+        // A removed worktree retains its registry identity.
+    }
+    return crypto
+        .createHash("sha256")
+        .update(`${commonDirectory(repo)}\0${administrativePath}`)
+        .digest("hex")
+        .slice(0, 24);
+}
+function listGitWorktrees(repo) {
+    const fields = git(repo, ["worktree", "list", "--porcelain", "-z"]).split("\0");
+    const records = [];
+    for (const field of fields) {
+        if (field.startsWith("worktree ")) {
+            records.push({
+                path: path.resolve(field.slice("worktree ".length)),
+                classification: records.length === 0 ? "main" : "linked",
+                head: null,
+                branch: null,
+                locked: false,
+                prunable: null,
+            });
+            continue;
+        }
+        const current = records.at(-1);
+        if (!current)
+            continue;
+        if (field.startsWith("HEAD "))
+            current.head = field.slice(5);
+        else if (field.startsWith("branch "))
+            current.branch = field.slice(7).replace(/^refs\/heads\//, "");
+        else if (field === "detached")
+            current.branch = null;
+        else if (field.startsWith("locked"))
+            current.locked = true;
+        else if (field.startsWith("prunable "))
+            current.prunable = field.slice(9);
+    }
+    return records;
+}
+/** Register one initialized checkout in Git-common metadata without sharing its graph database. */
+export function registerInitializedWorktree(repoPath) {
+    const repo = path.resolve(repoPath);
+    const current = listGitWorktrees(repo).find((worktree) => canonicalPath(worktree.path) === canonicalPath(repo));
+    if (!current)
+        throw new Error(`knodin worktrees: ${repo} is not a registered Git worktree`);
+    const registry = readRegistry(repo);
+    const now = new Date().toISOString();
+    const identity = identityFor(repo, current.path, current.classification);
+    const existing = registry.entries.find((entry) => entry.identity === identity);
+    if (existing) {
+        existing.path = current.path;
+        existing.lastSeenAt = now;
+        delete existing.removedAt;
+    }
+    else {
+        registry.entries.push({
+            identity,
+            path: current.path,
+            classification: current.classification,
+            registeredAt: now,
+            lastSeenAt: now,
+        });
+    }
+    // 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) {
+    const repo = path.resolve(repoPath);
+    const current = listGitWorktrees(repo);
+    const registry = readRegistry(repo);
+    const livePaths = new Set(current.map((worktree) => worktree.path));
+    const worktrees = [];
+    for (const worktree of current) {
+        const identity = identityFor(repo, worktree.path, worktree.classification);
+        const registered = registry.entries.some((entry) => entry.identity === identity);
+        const graphInitialized = fs.existsSync(path.join(worktree.path, ".knodin", "db.sqlite"));
+        let indexedHead = null;
+        if (graphInitialized) {
+            try {
+                indexedHead = (await status(worktree.path)).lastIndexedHead || null;
+            }
+            catch {
+                indexedHead = null;
+            }
+        }
+        worktrees.push({
+            ...worktree,
+            identity,
+            registered,
+            graphInitialized,
+            indexedHead,
+            freshness: indexedHead === null || worktree.head === null
+                ? "unknown"
+                : indexedHead === worktree.head
+                    ? "fresh"
+                    : "stale",
+            removedAt: null,
+        });
+    }
+    for (const entry of registry.entries) {
+        if (livePaths.has(entry.path))
+            continue;
+        worktrees.push({
+            identity: entry.identity,
+            path: entry.path,
+            classification: entry.classification,
+            head: null,
+            branch: null,
+            locked: false,
+            prunable: "registered worktree is absent from Git's worktree inventory",
+            registered: true,
+            graphInitialized: fs.existsSync(path.join(entry.path, ".knodin", "db.sqlite")),
+            indexedHead: null,
+            freshness: "removed",
+            removedAt: entry.removedAt ?? null,
+        });
+    }
+    worktrees.sort((left, right) => left.path.localeCompare(right.path));
+    return { schemaVersion: 1, graphState: "per-worktree", worktrees };
+}
+/** Reconcile the durable registry with Git metadata; no checkout or graph is deleted. */
+export function reconcileWorktrees(repoPath) {
+    const repo = path.resolve(repoPath);
+    const current = listGitWorktrees(repo);
+    const registry = readRegistry(repo);
+    const now = new Date().toISOString();
+    const seen = new Set();
+    const added = [];
+    const restored = [];
+    for (const worktree of current) {
+        const identity = identityFor(repo, worktree.path, worktree.classification);
+        seen.add(identity);
+        const existing = registry.entries.find((entry) => entry.identity === identity);
+        if (!existing) {
+            registry.entries.push({
+                identity,
+                path: worktree.path,
+                classification: worktree.classification,
+                registeredAt: now,
+                lastSeenAt: now,
+            });
+            added.push(worktree.path);
+        }
+        else {
+            if (existing.removedAt)
+                restored.push(worktree.path);
+            existing.path = worktree.path;
+            existing.lastSeenAt = now;
+            delete existing.removedAt;
+        }
+    }
+    const removed = [];
+    for (const entry of registry.entries) {
+        if (!seen.has(entry.identity) && !entry.removedAt) {
+            entry.removedAt = now;
+            removed.push(entry.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 };
+}
+/** Remove exactly one linked worktree through Git, then retain removal evidence in the registry. */
+export function removeManagedWorktree(repoPath, targetPath, dryRun) {
+    const repo = path.resolve(repoPath);
+    const target = path.resolve(targetPath);
+    const record = listGitWorktrees(repo).find((worktree) => canonicalPath(worktree.path) === canonicalPath(target));
+    if (!record)
+        throw new Error(`knodin worktrees remove: ${target} is not a registered Git worktree`);
+    if (record.classification === "main")
+        throw new Error("knodin worktrees remove: refusing to remove the main worktree");
+    if (dryRun)
+        return { schemaVersion: 1, target, dryRun: true, removed: false };
+    childProcess.execFileSync("git", ["worktree", "remove", target], {
+        cwd: repo,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    reconcileWorktrees(repo);
+    return { schemaVersion: 1, target, dryRun: false, removed: true };
+}

package/docs/BEHAVIORAL-CONTRACT.md

@@ -0,0 +1,114 @@
+# 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:** the intended mechanism is fewer corrective agent round trips without
+  hosted-service, account, authentication, or source-egress overhead. C93's
+  accepted two-task replay measured no round-trip benefit; both arms needed one
+  correction. It therefore authorizes no productivity claim and leaves billed
+  cost and unobserved token counts unavailable.
+- **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.
+
+`ExplainResult.callers[].kind` and `ExplainResult.omissions[]` are governed by
+the existing explain mapping: relationship kinds require source provenance and
+stable resolved endpoints, while omissions require an exact source location and
+must never be promoted into a graph edge. C99 exercises these added fields
+without adding a gateway operation or discriminator, so the C95 applicability
+matrix is unchanged.
+
+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.
+
+## C101 composition closure
+
+C101 composes four independently bounded decisions without adding an MCP tool
+or operation:
+
+- C97 retained lazy semantic residency in one local process. It does **not**
+  authorize an idle-RSS-reclamation claim.
+- C98 reports literal TS/JS source-to-sink paths as static heuristics with
+  coverage, omissions, freshness, budgets, and continuation. Truncation cannot
+  become a complete-result claim.
+- C99 persists only uniquely source-resolved Inversify/tsyringe relationships;
+  ambiguous, dynamic, factory, alias, conditional, and reflective wiring stays
+  omission evidence rather than an edge.
+- C100 proves one Salesforce Flow action to one uniquely resolved Apex
+  `@InvocableMethod`. It does not prove Terraform, dbt, arbitrary Salesforce
+  metadata, or general cross-substrate traversal.
+
+`npm run verify:c101` source-binds those decisions, checks the CLI and one-tool
+MCP query declarations, and rejects eight adversarial mutations of actual
+production responses. Stale resource/path evidence and heuristic-to-exact
+promotion fail; a truncated result cannot be presented as complete; and a DI
+ambiguity, missing source witness, or path omission cannot become a supported
+edge.
+
+## Repository stewardship
+
+An authoritative pull request starts the full test matrix and Sonar analysis,
+so it is a long, resource-intensive operation. Assistants must not automatically
+open one PR per item. Dependency-compatible, coherently scoped commits should
+normally be stacked into one reasonably sized shared PR; unrelated work must
+not be bundled merely to make the PR larger. The user or approved batch decides
+when that review unit is ready.
+
+## 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 outside C99's declared Inversify/tsyringe patterns, 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,17 @@ 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`
+`knodin query resource_reachability --limit 100` runs cached, on-demand static
+TS/JS source-to-sink analysis. It covers literal `process.env` and
+`fs.readFileSync` reads reaching `console.log`, `fetch`, or `db.query` through
+bounded assignment, argument, and return handoff. Results include ordered source
+evidence, stable path identities, registry coverage, omissions, freshness, and
+hard truncation/continuation metadata. Depth is fixed at 6 and paths at 100;
+dynamic names, reflection, computed aliases, and unsupported languages are
+reported rather than guessed. This is a static heuristic, not runtime reachability
+or an exploitability verdict.
+
+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 +64,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