test: language-packs step 0 — identity net, forbidden-edge gate, plane reports

[zaebee]

Step 0 of docs/plans/2026-10-14-language-packs.md (spec docs/specs/2026-10-14-language-packs-design.md, #146). Tests and tooling only. No src/ change.

What lands

• scripts/graph_identity.py: a canonical dump of a stored graph and a diff of two dumps.

  • The dump covers every node column, including metadata, ontology_class and domains; every edge column; and ingest_state.
  • Absolute paths are normalised to <ROOT>, and the mtime-derived ingested_at is dropped.
  • snapshot ingests three roots of a temp copy of the corpus, with a .git marker, the way cgis ingest does.

• tests/fixtures/graph_identity/corpus/ (18 files). Each case was checked in the graph before committing:

  • Python: DI alias, ABC → DISPATCHES, a star-import chain, src/ and lib/ layouts, the alembic collision;
  • TS: a monorepo with package.json and pnpm workspaces, tsconfig paths, node: imports, .d.ts, a shadowed global, configs above the root.

• test_graph_identity.py: the snapshot is diffed under PYTHONHASHSEED 0 and 1, plus one run in-process for coverage. Renaming one corpus function fails it and names the moved node and edge. A snapshot taken from a fresh git archive matches with 0 diff rows.

• Forbidden-edge gate (test_architecture.py, Invariant 7): six rules, compared for equality with forbidden_edges_allowlist.json. Today:

  rule	edges
  uplift → sqlite_store	8
  mcp_server/cli → extractor classes	9
  cli/api/guardian → storage	65
  everything else	0

  Planted edges fire every rule.

• Plane quotients, observe-only: build vs orchestrator 0.238, read vs layered_dag 0.676. These are the spec's numbers.

Rulings made while executing

• Ingest records root. The test helper and the script record root and options as cgis ingest does. pipeline.run alone records no root, which would leave nothing to normalise.
• Snapshot read from --out. The pipeline's structlog output goes to stdout, so the snapshot is read from the --out file instead.
• Three roots instead of two. py/src is added because the whole-corpus ingest never strips the src layout.
• tests/fixtures excluded from pytest collection and ruff. The corpus holds a test file, and a reformat would change the snapshot's input.
• Gate mutation as a lazy import. A module-level import in core/paths.py is circular and errors before the gate runs.

Fixed after the final (Fable) review

• Critical: .gitignore's lib/ ignored three corpus files. The snapshot had been made with files a clone lacks. They are now un-ignored, a test fails if git ignores any corpus file, and the fresh-archive check is clean.
• Important:
  • the star-import chain now resolves in py_src;
  • the dump carries the fields uplift writes;
  • scripts/graph_identity.py coverage went from 57% to 92% under --cov=scripts.

Deferred minors

• test_architecture.py's module docstring still says "Six invariants".
• _PLANES names extraction/resolution. Step 6 must update it; it fails loudly if not.
• .gitattributes pins only *.py to LF. TS edge ids carry no byte offsets today.
• files_state is not dumped. It is a deterministic hash cache that steps 1–5 don't move.

Test plan

• make format && make lint && make type-check && make pytest && make doc-coverage: 3135 passed.
• Test-count floor check.
• Snapshot from a fresh git archive HEAD corpus: 0 diff rows in all three roots.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a graph identity testing framework to ensure that code migrations do not alter graph ingestion behavior. It adds a test corpus, a script to dump and diff SQLite graphs, and tests enforcing architectural invariants like forbidden edges and drift scoring. The review feedback highlights several robust improvements: correcting path normalization on Windows within recursive JSON parsing, explicitly verifying database file existence before connecting, capturing and printing subprocess stderr for better CI debugging, and specifying UTF-8 encoding when writing files to prevent platform-dependent test failures.

[zaebee]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a graph identity snapshotting tool to ensure consistent ingestion behavior across environments, along with new architecture tests for forbidden edges and drift monitoring. The review identified a resource leak in sqlite3.connect usage, a potential failure point in git-related tests when the git executable is missing, and a redundant database query in the drift tests. All three comments provide actionable improvements and have been retained.

[gemini-code-assist]

In Python, using sqlite3.connect as a context manager only manages transactions (committing on success, rolling back on exception); it does not close the connection. This can lead to unclosed database connections, file locks, and resource leaks, which is especially problematic on Windows when trying to clean up temporary directories. Use a try...finally block to ensure the connection is explicitly closed.

Suggested change

	with sqlite3.connect(db_path) as conn:
	state = {
	key: _normalise(value, prefix)
	for key, value in conn.execute("SELECT key, value FROM ingest_state ORDER BY key")
	if key not in _VOLATILE_STATE
	}
	return {
	"nodes": _rows(conn, "nodes", _NODE_COLUMNS, prefix),
	"edges": _rows(conn, "edges", _EDGE_COLUMNS, prefix),
	"ingest_state": state,
	}
	conn = sqlite3.connect(db_path)
	try:
	state = {
	key: _normalise(value, prefix)
	for key, value in conn.execute('SELECT key, value FROM ingest_state ORDER BY key')
	if key not in _VOLATILE_STATE
	}
	return {
	'nodes': _rows(conn, 'nodes', _NODE_COLUMNS, prefix),
	'edges': _rows(conn, 'edges', _EDGE_COLUMNS, prefix),
	'ingest_state': state,
	}
	finally:
	conn.close()

[zaebee]

Adopted in d4c66b2, as with closing(sqlite3.connect(db_path)) as conn — same guarantee as try/finally, one line. Pinned by test_dump_closes_its_connection (records the connection, asserts it is closed after dump()); it failed before the change with DID NOT RAISE.

[gemini-code-assist]

Running git check-ignore via subprocess.run can raise a FileNotFoundError if the git executable is not installed in the environment (e.g., in minimal CI containers, Nix builds, or zip deployments). Additionally, if the tests are run outside of a git repository, the command will fail. It is safer to check if the .git directory exists and handle FileNotFoundError gracefully by skipping the test.

    if not (REPO / '.git').exists():
        pytest.skip('Not a git repository')
    try:
        result = subprocess.run(
            ['git', 'check-ignore', *files], cwd=REPO, capture_output=True, text=True, check=False
        )
    except FileNotFoundError:
        pytest.skip('git executable not found')
    ignored = result.stdout.split()

[zaebee]

Declining, deliberately. This test exists because .gitignore's lib/ silently dropped three corpus files: the snapshot was taken with them and every fresh clone ingested without them. A skip when git is absent turns that guard into one that passes by not running — exactly the failure it was written to catch. git is already a hard dependency of this suite (seven other test files call it unconditionally), CI always has it, and a missing git should fail loudly here, not vanish into the skipped column.

[gemini-code-assist]

The root_graph_data fixture already provides nodes and edges as the second and third elements of the tuple. Unpacking only store and then querying the database again with store.get_all_nodes() and store.get_all_edges() is redundant and inefficient. We can directly unpack nodes and edges from the fixture.

Suggested change

	store, _, _ = root_graph_data
	scorer = DriftScorer(_PATTERNS)
	binding = scorer.load_project_level()[0]
	by_name = {d.name: d for d in _selected_domains(scorer, graph="python")}
	nodes, edges = store.get_all_nodes(), store.get_all_edges()
	store, nodes, edges = root_graph_data
	scorer = DriftScorer(_PATTERNS)
	binding = scorer.load_project_level()[0]
	by_name = {d.name: d for d in _selected_domains(scorer, graph='python')}

[zaebee]

Declining — the two are not the same input. Measured on this branch: the fixture tuple carries 8726 edges, the store 8715 (same node set, same distinct edge set; the store drops 11 duplicates). quotient_call_tally counts edges, so the swap would change the observed numbers. Reading back from the store also matches the gating quotient test above (line 149), so the planes and the domain quotient are measured on the same graph.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
92.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud