P0 — Make Python syntax validation compiler-truthful

[tomdps]

Parent

Parent EPIC: #243

Problem

python.syntax currently parses with ast.parse but then runs regex/string post-checks that reject valid Python. The audited revision emitted 109 false-positive syntax errors on a repository where python -m compileall -q src scripts tests passed. Repeated false errors included valid multiline def/if/with headers and multiline literals reported as "compound statements must end with a colon."

The syntax check can also probe one interpreter and execute another because resolution and invocation are separate. Parser success followed by heuristic failure is not compiler truth.

Required behavior

1. Resolve one concrete interpreter through the canonical Python project resolver and execute that exact command. Do not probe a path and later invoke raw python3.
2. Validate every selected after-state file using compiler-equivalent behavior for the target Python version. Use py_compile/compile() semantics with stable doraise behavior; do not run source code.
3. Remove grammar-breaking regex/string post-validation. Parser success must not be overridden by checks that reinterpret Python grammar. If any supplemental static policy remains, it must have a separate check ID/category and must not emit python.syntax diagnostics.
4. Translate syntax/indentation/null-byte/compiler failures into stable diagnostics with file, 1-based line, column/end location when available, normalized code, severity, message, interpreter path/version, and provenance.
5. Distinguish passed, findings, tool_unavailable, invalid_config, timeout, and infrastructure/tool failure. Unknown nonzero output or malformed machine output must never become a pass.
6. Validate the exact overlay/after-state content selected by the request, including new and changed Python files, without mutating the source project.
7. Handle .py and .pyi. Version-specific syntax must be judged by the selected interpreter and declared target policy; unsupported target/interpreter combinations are explicit degraded/unsupported results.
8. Keep diagnostics deterministic: normalized workspace-relative paths and stable sort order.

Acceptance fixtures

Must pass:

• multiline def, class, if, elif, for, while, with, match, and case headers;
• decorators, async forms, type comments, nested f-strings, comprehensions, semicolon-separated simple statements, continuations, triple-quoted strings containing Python-looking text, and .pyi constructs;
• valid syntax supported only by the selected newer interpreter;
• the audited repository's src, scripts, and tests corpus when its native compile baseline passes.

Must fail with precise locations:

• missing colon/indentation;
• unterminated strings/brackets;
• invalid target-version syntax under the selected interpreter;
• null bytes and compiler recursion/overflow errors;
• malformed tool output/infrastructure failure as non-pass states.

Must prove overlay semantics:

• baseline file passes while invalid after-state fails;
• invalid baseline file passes when corrected in after-state;
• newly introduced invalid .py and .pyi files fail.

Scope

Primary implementation surfaces:

• packages/validation-python/src/syntax-check.ts
• the canonical resolver/toolchain and process runner used by this check
• Python validation contracts/diagnostics only where required
• fixture-backed tests in the existing Python validation and conformance suites

Non-goals

• type checking, linting, formatting, import resolution, security scanning, notebook execution, or automatic source rewrites;
• installing Python or packages;
• widening launch-facing Python claims.

Verification

At minimum:

npm run build
node --test tests/validation-python.test.mjs tests/graph-extraction-conformance.test.mjs
npm run lint
bash ./scripts/ci/run-local-ci-equivalent.sh

Also run the native compile baseline and python.syntax against a real Python repository, and attach a before/after diagnostic comparison demonstrating that the known false positives are gone while seeded invalid overlay files fail.

Completion evidence

PR must link exact interpreter/version used, machine-readable diagnostic examples, passing fixture matrix, real-repository comparison, and confirmation that no source project files/config/lockfiles/environments were modified.

[tomdps]

#244 implementation evidence is merged into dev via PR #252, merge commit c7f6a26a32f1b141b1dc8eac036a374a8f9cc9ea.

Verified after the ship run:

• compiler-truth fixtures cover multiline-valid, invalid control-flow/future imports, .py/.pyi, indentation, null-byte, recursion/overflow, and stable ranges;
• overlay corrected/new/deleted after-state cases pass;
• the exact probed interpreter is executed;
• malformed/nonzero/timeout/signal/incomplete protocol states fail closed;
• audited /Users/tom/code/benchmarks passes python -m compileall -q src scripts tests, passes opcore check all --checks python.syntax, and an invalid overlay produces PY_SYNTAX_ERROR without modifying the target repo;
• zeroshot cmdproof check opcore-ci passes for head e7528561fc0876c241f25f0d969bbbaab35c414e, proof sha256:9aff8ccb0c36bb4a276bed5903707978983b0520baed793605a3df5b0743ff5c;
• GitHub CI and provenance checks are green.

The implementation introduced package-local packages/validation-python/src/toolchain-resolver.ts. Per the approved epic execution gate, #244 remains open while #246 establishes the canonical project resolver. After #246 merges, #244 gets one integration correction to consume that resolver; only then should #244 and its #243 checkbox close.

[tomdps]

Deferred resolver integration is complete in PR #254, merged into dev as 91955e3193ceecc72c0e1f46ce21af79d834e5ed.

The integration deletes the package-local toolchain-resolver.ts; no resolvePythonInterpreter/toolchain-resolver source path remains. createPythonValidationChecks now constructs one canonical PythonProjectContextResolver and injects it into python.syntax, python.types, and import checks. python.syntax groups targets by canonical projectKey and executes compileSources with each context's exact interpreter provenance/cwd.

#244 compiler-truth and overlay cases passed within the final 177/177 resolver acceptance matrix; packed installed execution passed 3/3; GitHub CI/CodeQL/provenance and the configured opcore-ci proof are green at final head 25084bd632eb657fec4101cf15a447f10f6aa15f (proof sha256:b8e6b9e171e929cf518c4f8768c1474ba46187462f7d9ea087a0812d5eac585d). The temporary deferral is resolved; #244 is complete.