Repository navigation
facts: read-only engine README plan; Node 20 in facts-validate - #190
Conversation
scripts/facts_engine_plan.py plans an update of the engine README's fact markers without writing anything remote. It reads the hub's main commit, facts/facts.json, facts/facts.schema.json and VERSION through GitHub's public REST API (GET only, no redirects, no proxies), selects the release named by VERSION (scripts/facts_engine_release.py), resolves the engine's release tag to its commit, renders the engine README through the pure fact-marker renderer (scripts/facts_markdown.mjs, run by the Node 20 bridge scripts/facts_engine_render.mjs), and checks any open proposal pull request by its plan identity. The output is a local review directory: plan.json and, when the README changes, the proposed README. The plan is marked superseded when the hub's main commit, the engine's default branch or its commit moved during the run. tests/test_facts_engine_plan.py runs the planner against loopback HTTP servers and the real Node 20 bridge: 33 tests covering the create, noop, already-planned, update-needed and superseded outcomes and the refusals.
The facts-validate job's CLI acceptance step runs every tests/test_facts_*.py module, including the engine README plan tests, which call the Node 20 bridge scripts/facts_engine_render.mjs. That bridge refuses any other Node major, so the job now installs Node 20 with the same pinned actions/setup-node release that python-test.yml uses, under the job's existing docs-only condition.
There was a problem hiding this comment.
Graphify reviewed this change.
Worth a look — the grounded gate found no coupling regressions or blocking issues, but 3 advisory finding(s) below merit a look before merge.
Not checked: tests were not run; no formal proof of the changed code.
Graphify review — findings
Adds a read-only planner that builds a proposal for the engine README from public GitHub state, binding the facts, renderer source and proposed UTF-8 bytes to a plan identity. Every GitHub read goes through a GET-only transport that refuses redirects, ignores proxies, and sends the token only to the pinned origin. It checks exact repository identity, branch and annotated-tag resolution, Contents blob digests and capped pull-request pagination, and refuses on any mismatch rather than selecting silently, so the Content-Length-optional read path and the write_plan rollback on failure are where the guarantees can slip. Renders the README through a Node bridge with its own Markdown renderer, and installs Node 20 in the validation workflow for non-docs-only runs, so the bridge cannot run without it.
Worth a look
- CLI failures can exit with status 0 —
scripts/facts_engine_plan.py· Escalate · medium- unverified hypothesis — survived the adversarial refute pass; needs human review
- Rollback can delete a concurrent replacement file —
scripts/facts_engine_plan.py· Escalate · medium- unverified hypothesis — survived the adversarial refute pass; needs human review
- Responses without Content-Length can bypass the size limit —
scripts/facts_engine_plan.py:123· Escalate · medium- unverified hypothesis — survived the adversarial refute pass; needs human review
Review partial — this diff was larger than one review pass covers, so later files were not reviewed; some findings may be missing.
Analysis details — impact, health, verification
Impact & health
Graphify review
Impact — 110 functions depend on the 110 functions this change touches.
Health — this change adds coupling hotspots:
- new:
build_engine_plan()— 2 callers, 6 callees
Verification — 110 functions in the blast radius were not formally verified this run (proofs are advisory here).
Gate & verification
graphify gate
PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.
Advisory (not blocking):
- verification_scope: 110 function(s) in the blast radius were not formally verified this run
Test selection
Test selection
35 of 35 test file(s) selected (100%) via static blast radius.
Escalated to a full run for safety (
noncode-change,uncovered-code) — the selection is not trustworthy on its own (see below). CI should run the whole suite.
tests/test_facts_cards.py— full-run-safetytests/test_facts_descriptions.py— full-run-safetytests/test_facts_engine_plan.py— impact, changed-test, full-run-safetytests/test_facts_fanout.py— full-run-safetytests/test_facts_validate.py— full-run-safetytests/test_fingerprint_canonical.py— full-run-safetytests/test_parity_bundle.py— full-run-safetytests/test_parity_source_proof.py— full-run-safetytests/test_release_action_pins.py— full-run-safetytests/test_release_asset_fetch.py— full-run-safetytests/test_release_binding.py— full-run-safetytests/test_release_binding_workflows.py— full-run-safetytests/test_release_coordinator_receipts.py— full-run-safetytests/test_release_docs_runtime.py— full-run-safetytests/test_release_fanout_check.py— full-run-safetytests/test_release_guard_policy.py— full-run-safetytests/test_release_hosted_postmerge_receipts.py— full-run-safetytests/test_release_hpo_image.py— full-run-safetytests/test_release_main_push_inventory.py— full-run-safetytests/test_release_pair.py— full-run-safetytests/test_release_parity.py— full-run-safetytests/test_release_parity_image.py— full-run-safetytests/test_release_parity_runtime.py— full-run-safetytests/test_release_parity_wire.py— full-run-safetytests/test_release_receipt_collect_sweep.py— full-run-safetytests/test_release_receipt_legacy_previous.py— full-run-safetytests/test_release_receipt_shards.py— full-run-safetytests/test_release_receipts.py— full-run-safetytests/test_release_redeliver.py— full-run-safetytests/test_release_runtime_smoke.py— full-run-safetytests/test_release_sink_image.py— full-run-safetytests/test_release_sources.py— full-run-safetytests/test_release_workflows.py— full-run-safetytests/test_repo_descriptions.py— full-run-safetytools/release-dry-run/test_wfrun.py— full-run-safety
non-code file(s) changed (
.github/workflows/facts-validate.yml) → running the full suite for safety (a code graph can't see config/fixture/data deps)
changed code file(s) with no mapped test (
.github/workflows/facts-validate.yml,scripts/facts_engine_render.mjs,scripts/facts_markdown.mjs) — a coverage gap or a missing link — running the full suite rather than only the selected tests
Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.
Docs that may be stale (advisory)
AGENTS.md§ a. What CI runs, per trigger (lines 35-62): references changed symbolscanonical,plan,sha256AGENTS.md§ b. Local-only checks (not run by CI) (lines 63-71): references changed symbolsmetadataAGENTS.md§ Conventions and safety rules (from this repo's own files) (lines 89-98): references changed symbolsref,sha256CLAUDE.md§ a. What CI runs, per trigger (lines 35-62): references changed symbolscanonical,plan,sha256CLAUDE.md§ b. Local-only checks (not run by CI) (lines 63-71): references changed symbolsmetadataCLAUDE.md§ Conventions and safety rules (from this repo's own files) (lines 89-98): references changed symbolsref,sha256README.md§ pineforge-release (lines 1-43): references changed symbolspullREADME.md§ Knobs, modes and exit codes (lines 44-75): references changed symbolscountREADME.md§ Automated release flow (lines 157-214): references changed symbolscanonical,refREADME.md§ Debian source packages (lines 284-340): references changed symbolssha256
…and 10 more.
· 1 grounded finding(s) anchored inline below.
| return current | ||
|
|
||
|
|
||
| def build_engine_plan(api, renderer): |
There was a problem hiding this comment.
build_engine_plan()
fans out to 6 callees (efferent coupling).
Grounded coupling-delta finding (deterministic), not an LLM guess.
Adds a read-only plan step for the engine README facts, and installs Node 20 in the facts-validate job so the facts renderer runs on the version it needs.
scripts/facts_engine_plan.py,scripts/facts_engine_release.py,scripts/facts_engine_render.mjs,scripts/facts_markdown.mjs: the plan reads the engine README facts without writing..github/workflows/facts-validate.yml: installs Node 20 before the facts steps.🤖 Generated with Claude Code