kgverify

Overview ¶

Command kgverify is the knowledge graph's fidelity gate.

The project mandates that the knowledge graph be kept current at every commit, and that it be the authority a reader trusts INSTEAD of reading files. Nothing checked either claim, and by the close of sprint 352 the graph had gone further than merely stale: it asserted facts that were never true. Two Test nodes, TestSchemaWalkHoisted and TestEvalWithReentrancy, existed in the graph and nowhere in the repository; a previous "fidelity repair" had itself invented two symbols the code deleted two days later. A gap is recoverable, a fabrication is not — it is a wrong answer delivered with the authority of a verified one.

This command makes fidelity enforceable rather than aspirational. It exits non-zero when the graph's claims about the tree, about rmp, or about its own documented schema stop holding.

The fabrication route, and how this closes it ¶

A fabricated node is created when a symbol's NAME is typed from a task description or a report instead of being read out of the tree. The oracle here is go/parser: the inventory of what exists is built by PARSING every .go file, never by scanning text. That distinction is the whole mechanism, and it is measurable rather than rhetorical — edgeTypeFilterFor, deleted from the code in sprint 352, still appears in four Go comments and one Markdown document, so a text scan reports it present while the declaration inventory correctly reports it absent.

Detection is the enforceable half: symbol-absent has a baseline of zero, so any node naming a non-declaration fails the gate. Generation is the other half, and it is an affordance rather than a hard block, because this command cannot intercept `rmp graph create`: `-emit symbols` prints the inventory and `-emit missing` prints the declarations that have no node yet, so the supported way to write a symbol node is to copy a name out of the tree's own output. A hand-typed name therefore survives at most until the next run.

Baselines ¶

Four counted backlogs predate this gate and cannot be repaired by a checker. Each is recorded in baseline.json with the count measured when it was written; the gate fails when a count EXCEEDS its baseline, and reports every count on every run so the remaining figure is never a qualitative claim. The zero-baseline checks are the ones that must never regress at all: fixture-fabrication-present, symbol-absent, task-id-not-int, task-legacy-identity, task-status-invalid and task-absent-in-rmp. This is the same ratchet the openCypher TCK gate uses, for the same reason.

Usage ¶

go run ./cmd/kgverify              # verify; exit 1 on any regression
go run ./cmd/kgverify -v           # list every violation, not just a sample
go run ./cmd/kgverify -json        # machine-readable results
go run ./cmd/kgverify -emit symbols   # every declaration go/parser found
go run ./cmd/kgverify -emit missing   # declarations with no node: the sync worklist
go run ./cmd/kgverify -emit packages  # per-package declarations vs nodes
go run ./cmd/kgverify -emit absent    # nodes naming a symbol the tree does not have
go run ./cmd/kgverify -emit cypher    # one statement per line that closes the gap

Exit codes are deliberately distinct, so a broken harness can never be read as either a pass or a fidelity defect:

0  every check at or below its baseline
1  at least one check exceeds its baseline
2  usage error
3  the harness could not conclude (rmp or git unavailable, a .go file that
   will not parse, an implausibly small inventory, a stale fixture)