fix(python): share import resolution between validation and graph

[EivMeyer]

Parent

Parent EPIC: #243

Current dev baseline

Planned immediately before implementation against dev at 91955e3193ceecc72c0e1f46ce21af79d834e5ed (PR #254 / #246 merged).

• P0 — Make Python syntax validation compiler-truthful #244 is complete and merged through PRs feat: P0 — Make Python syntax validation compiler-truthful #252 and feat: add canonical Python project-context resolver #254: Python syntax now uses the canonical project/interpreter resolver.
• P0 — Resolve Python projects, interpreters, environments, and tools canonically #246 is complete: @the-open-engine/opcore-validation-python owns canonical PythonProjectContext discovery and after-state workspace access.
• Hypothetical (validate pre-write) evaluation must be comprehensive — graph-backed checks are silently skipped #197 remains open and owns comprehensive overlay graph evaluation. This issue must not duplicate it; Hypothetical (validate pre-write) evaluation must be comprehensive — graph-backed checks are silently skipped #197 will later prove overlay/on-disk parity using the canonical import expectations delivered here.
• No duplicate or superseding issue/PR was found. The earlier dependency wording around P0 — Unify Python imports and all checks on one overlay graph snapshot #247 is stale; P0 — Unify Python imports and all checks on one overlay graph snapshot #247 is not a prerequisite and must not be recreated.

Problem

Python import validation still implements a second parser and module resolver in packages/validation-python/src/source-files.ts. It splits physical lines with regexes, strips comments heuristically, and resolves a hand-built candidate set. Graph extraction already parses Python with tree-sitter and emits IMPORTS_FROM edges through the Rust graph-core resolver. The two semantic sources disagree on multiline and parenthesized imports, conditional imports, from pkg import submodule, package initializers, stubs, namespace/src layouts, and overlays. That causes false PY_IMPORT_GRAPH_MISSING_EDGE diagnostics and can omit source closure files from type checking.

Decision: one owner

The Rust graph-core extraction pipeline is the sole parser/resolver for Python repo-import expectations.

Validation must not parse Python imports. @the-open-engine/opcore-graph will expose a package-owned, injected Python import analysis adapter that materializes a supplied after-state Python file set in an isolated temporary repo, invokes the existing installed graph-core build/query path, returns its IMPORTS_FROM file edges, and cleans up. It may write only inside that temporary repo. It must not mutate the target worktree or introduce a second native binary/protocol/package.

@the-open-engine/opcore-validation-python owns only a structural analyzer interface and consumption of the returned edges. Opcore and ASP validation compositions inject the graph implementation through validation-policy options, following the existing clone-invoker dependency-injection pattern. Missing/failed native analysis is a typed infrastructure failure for python.import-graph, never an empty success.

Implementation scope

1. Remove production import parsing/resolution from packages/validation-python/src/source-files.ts (parsePythonImports, comment stripping, regex grammar, module candidate resolution, and related duplicate types/helpers).
2. Make Python source materialization enumerate after-state .py/.pyi files from ValidationFileView.listVisibleFiles() and readAfter(), then select the target/transitive closure from canonical graph-core import edges. Do not read the real worktree behind the file view.
3. Add the narrow graph-package adapter over the existing graph-core sidecar. Reuse current artifact resolution, build, and query contracts; no new public CLI route, daemon, graph schema, native package, or release claim.
4. Thread the injected analyzer through createPythonValidationChecks, @the-open-engine/opcore-validation-policy, the Opcore product/advanced compositions, and the ASP provider composition. Preserve package ownership boundaries: validation-python must not import graph internals.
5. Compare canonical expected edges with the validation graph session in python.import-graph. Report PY_IMPORT_GRAPH_MISSING_EDGE only for a real expected edge absent from the supplied graph. Preserve directed file-edge normalization.
6. Add fixture-backed edge cases shared by graph and validation tests: multiline/parenthesized imports, aliases, conditional imports, from pkg import submodule, star imports, relative imports, package __init__, .pyi, namespace package, and src layout. Include an intentionally omitted graph edge proving real missing-edge diagnostics still fire.
7. Update only directly affected package README/fixture metadata and AGENTS.md if a durable ownership pattern is added.

Acceptance criteria

• Production validation contains no line-regex Python import parser/resolver.
• For every shared fixture, graph extraction and validation consume exactly the same directed repo-local IMPORTS_FROM file edges.
• Valid multiline, parenthesized, aliased, conditional, package, stub, namespace, src-layout, and after-state overlay imports do not create false missing-edge diagnostics when the canonical graph edge is present.
• An intentionally absent canonical edge still emits PY_IMPORT_GRAPH_MISSING_EDGE with the correct from/to paths.
• Type-check source materialization includes canonical transitive repo imports without parsing source text in TypeScript.
• Missing or malformed native/graph analysis fails visibly as infrastructure/degraded coverage; it never passes with an empty edge set.
• The analysis path uses an isolated temporary repository and leaves source/config/lock/environment files in the target repo unchanged.
• Focused Rust graph extraction, Python validation, ASP provider, policy/package, contract/fixture, and installed-bin tests pass.
• npm run build, npm run lint, and opcore check --changed --json pass.
• zeroshot cmdproof check opcore-ci passes, the scoped diff has no generated native package binary/checksum/metadata churn or release receipt churn, and the PR targets dev with green CI.

Non-goals / forbidden scope

• Hypothetical (validate pre-write) evaluation must be comprehensive — graph-backed checks are silently skipped #197 overlay GraphProvider construction or overlay/on-disk full-pack parity.
• Python type-checker policy, syntax compiler behavior, language-service inspect/edit, dead-code/relevant-tests semantics, metrics, launch docs, or readiness claims.
• New graph schema versions, public command groups, ASP authority, daemons, sockets, native packages, or persistent target-repo analysis state.
• Generated packages/opcore-graph-core-* artifacts, release/cutover/provenance receipts, and package version changes unless a focused package-surface test proves a narrowly required fixture/packlist update.

Required verification evidence

The PR/issue completion comment must record the exact dev base and final commit, fixture edge matrix, canonical graph-versus-validation comparison, real missing-edge reproduction, after-state overlay reproduction, missing-analyzer failure, target-worktree immutability check, focused commands/results, opcore check --changed --json, zeroshot cmdproof check opcore-ci, green GitHub checks, and a scoped diff audit.

[tomdps]

Completed via PR #255, merged into dev as 47d2b3f39c936d05ca546282e627a24f9ffe2893 from final implementation commit b1d02384163258cf756195203f97f2ab9c485ed5 (base 91955e3193ceecc72c0e1f46ce21af79d834e5ed).

Evidence:

• Shared graph/validation fixture matrix covers multiline/parenthesized, alias, conditional, submodule, star, relative, initializer, stub, namespace, and src-layout imports.
• Canonical graph extraction and validation edge comparison passed.
• Intentionally omitted edge reproduced PY_IMPORT_GRAPH_MISSING_EDGE with correct endpoints.
• Overlay identity/deletion, canonical transitive type source closure, missing/malformed analyzer failures, temporary analyzer cleanup, and target-worktree immutability passed.
• npm run build, npm run lint, package packlists, and focused graph/validation/policy/ASP/installed-bin/boundary suites passed (143 focused tests after final repairs).
• Source-built opcore check --changed --json passed with isolated Pyright 1.1.411.
• Configured opcore-ci command proof passed: exit 0, 376955 ms, no workspace drift, proof sha256:5f65cb778ea68cbc9d661b22f247985907e141ec0383746e430c299320511e1c.
• PR fix(python): share import resolution with graph #255 CI passed: main check, provenance, and CodeQL.
• Scoped diff has no native binary/checksum/metadata churn and no release receipt churn.

The graph-core analyzer is now the sole production owner of Python repo-import expectations; validation consumes injected directed edges and contains no line-regex import parser/resolver.