the-open-engine · tomdps · Jul 18, 2026 · Jul 14, 2026 · Jul 14, 2026 · Jul 14, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -54,6 +54,11 @@ jobs:
           node-version: 22
           cache: npm
 
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -65,9 +70,25 @@ jobs:
       - name: Install
         run: npm ci
 
+      - name: Install authoritative mypy
+        run: python -m pip install --disable-pip-version-check mypy==2.3.0
+
+      - name: Install authoritative Pyright
+        run: npm install --prefix "${RUNNER_TEMP}/opcore-pyright" --no-package-lock --ignore-scripts pyright@1.1.411
+
       - name: Check
         run: npm run ci
 
+      - name: Prove authoritative mypy after-state execution
+        run: npm run python:mypy-authority-proof
+        env:
+          OPCORE_REAL_MYPY: ${{ env.pythonLocation }}/bin/mypy
+
+      - name: Prove authoritative Pyright after-state execution
+        run: npm run python:pyright-authority-proof
+        env:
+          OPCORE_REAL_PYRIGHT: ${{ runner.temp }}/opcore-pyright/node_modules/.bin/pyright
+
   native-artifact:
     name: native-artifact (${{ matrix.target }})
     needs: check

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -26,7 +26,7 @@ jobs:
       (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
     runs-on: ubuntu-latest
     env:
-      RELEASE_VERSION: "0.2.0"
+      RELEASE_VERSION: "0.2.1"
       NPM_TAG: latest
     steps:
       - name: Checkout
@@ -97,7 +97,7 @@ jobs:
         if: github.event_name == 'workflow_run'
         run: npm run release:publish -- --version "$RELEASE_VERSION" --tag "$NPM_TAG"
         env:
-          OPCORE_CONFIRM_PUBLISH: "0.2.0"
+          OPCORE_CONFIRM_PUBLISH: "0.2.1"
           OPCORE_REQUIRE_ALL_NATIVE_PACKAGES: "1"
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

diff --git a/AGENTS.md b/AGENTS.md
diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -3,7 +3,7 @@ members = ["crates/graph-core"]
 resolver = "2"
 
 [workspace.package]
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/the-open-engine/opcore"

diff --git a/docs/architecture/runtime-cli-ard.md b/docs/architecture/runtime-cli-ard.md
@@ -58,6 +58,8 @@ Canonical `opcore graph`, `opcore edit`, `opcore check`, and `opcore validate` c
 
 #58 adds `opcore validate pre-write --request-file <validation-request.json> --timeout-ms 30000 --json` for hook integration. The route is validation-owned, file-based, fail-closed, overlay-only, and emits a typed `PreWriteValidationReceipt` with timing, repo, scope, checks, graph, overlay, status, and failure summary data.
 
+#197 makes hypothetical graph-backed validation state-exact. `packages/validation` creates the before/after `ValidationFileView`, acquires one disposable exact graph session for each state, shares that immutable session across every selected check and streaming/fail-fast path, and disposes it on every exit. `reportMode:"introduced"` uses distinct before and after snapshots. `packages/graph` owns bounded temporary source materialization, one graph-core build, bound queries, and recursive cleanup; product, advanced, and ASP composition inject that implementation through validation-owned types. Exact materialization, build, listing, or query failures are non-pass even under optional persistent-graph policy. ASP continues to obtain all source content through host callbacks and preserves `workspace/listTree.truncated`. The target source tree, persistent `.opcore/graph`, configuration, lockfiles, environments, and caches remain untouched.
+
 #30 adds `ReleaseCutoverReceipt` and `npm run cutover:check` as the installed-artifact cutover proof. The gate packs the public release packages, installs them into a clean temporary project, clears current-tool environment resolution, excludes local wrapper/sibling paths, verifies installed canonical bins (`opcore` and `opcore-asp-provider`), binds every command receipt id to its expected canonical command/status/exit, and fails on old-tool/private-path markers or advertised `not_implemented` release commands.
 
 #120 adds `AspDogfoodReceipt` and `npm run asp-dogfood:check` as advisory/shadow evidence that the independent ASP manager can install/enroll Opcore as a Core check provider and record host-owned decisions separately from provider assessments. The receipt uses temporary `ASP_HOME` state, records `opcore-asp-provider --stdio` manifest/bin evidence, co-records retained current-tool guardrails, and keeps `oldToolReplacementClaimed: false`; it is not a cutover, host authority claim, public standard-readiness claim, or `opcore asp` route.
@@ -72,9 +74,9 @@ There is no public `opcore asp` router group in this release. ASP Core check int
 |---|---|
 | `packages/contracts` | Public wire contracts, schemas, command payloads, adapter request/result envelopes, validation shapes, graph query contracts, and generated TypeScript types. |
 | `crates/graph-core` | Planned Rust graph core for source extraction, parser integration, SQLite/WAL persistence, freshness metadata, watch daemon state, hot query execution, and clone index analysis through the existing native binary. |
-| `packages/graph` | npm facade/package track for graph commands, public graph command adapter, native graph-core loading, and graph JSON output. It must not duplicate graph-core internals or depend on the aggregate CLI. |
+| `packages/graph` | npm facade/package track for graph commands, public graph command adapter, native graph-core loading, graph JSON output, and bounded disposable exact-state source snapshots. It must not duplicate graph-core internals or depend on the aggregate CLI. |
 | `packages/edit` | Edit planner, public edit command adapter, patch/tree edits, symbol-aware orchestration, graph-backed discovery integration, and whole-plan validation. It consumes contracts and graph queries, not graph internals or the aggregate CLI. |
-| `packages/validation` | Mechanical checks, public check/validate command adapters, validation manifests, failure policy, hypothetical validation, graph-aware rule orchestration, and `check`/`validate` reporting. It consumes contracts and adapters, not edit internals or the aggregate CLI. |
+| `packages/validation` | Mechanical checks, public check/validate command adapters, validation manifests, failure policy, hypothetical validation, file-view-state graph-session lifecycle, graph-aware rule orchestration, and `check`/`validate` reporting. It consumes contracts and injected graph adapters, not graph internals, edit internals, or the aggregate CLI. |
 | `packages/validation-rust` | Rust validation adapter rules, temporary workspace materialization from validation file views, and Cargo/native-tool-backed checks exposed to validation through contracts. It does not own host decisions or current external guardrail replacement policy. |
 | `packages/validation-typescript` | TypeScript adapter rules, compiler-backed checks, and TypeScript graph-aware validations exposed to validation through contracts. |
 | `packages/validation-clone` | Duplicate-code validation adapter rules over `ValidationCheckContext.fileView`, with an injected native clone invoker supplied by CLI composition. It does not own graph-provider status, daemon lifecycle, host decisions, SAST/security policy, or scoring. |
@@ -118,10 +120,16 @@ Before replacing current external tool behavior, add golden/reference fixtures a
 
 #20 adds `@the-open-engine/opcore-validation-rust` as a validation adapter package composed by the CLI beside TypeScript checks. Stable check ids are `rust.source-hygiene`, `rust.fmt`, `rust.cargo-check`, `rust.clippy`, `rust.rustdoc`, `rust.import-graph`, `rust.dead-code`, `rust.graph-signals`, `rust.unused-deps`, and `rust.function-metrics`. These are provider assessment checks; ASP hosts decide allow, deny, or degraded coverage later. `rust.graph-signals` is graph-provider-backed evidence over public contracts only; it does not replace the retained mechanical cargo/rustdoc/clippy/Rox guardrails.
 
-Rust checks read candidate files through `ValidationCheckContext.fileView`. Checks that need Cargo or native tools materialize a temporary workspace from after-state content, apply write/delete overlays there, and clean up without mutating the real worktree. `.rs`, `.inc`, and `Cargo.toml` are adapter-owned inputs. Cargo.lock-only changes remain retained compatibility until a later decision expands Rust adapter ownership.
+Rust checks read candidate files through `ValidationCheckContext.fileView`. Checks that need Cargo or native tools materialize one temporary workspace per validation file-view state from after-state content, apply write/delete overlays there, share that immutable workspace across selected checks with the same materialization environment, and dispose it when the state exits. Distinct environments remain distinct resources because Git index/tree environment can change staged or tree snapshots. The real worktree is never mutated. `.rs`, `.inc`, and `Cargo.toml` are adapter-owned inputs. Cargo.lock-only changes remain retained compatibility until a later decision expands Rust adapter ownership.
 
 `opcore status --json` and `opcore doctor --json` expose Rust adapter status, toolchain availability, degraded checks, retained compatibility notes, `currentUsage` metadata for Opcore/Orchestra/CoVibes/gateway consumers, and temporary workspace requirements so #21 can decide daemon/cache/check UX without rediscovering Rust coverage. Missing `cargo`, `rustfmt`, or `clippy` makes the Rust foundation unavailable; missing `rustdoc` is reported as degraded retained compatibility instead of disabling the core `rust.fmt`, `rust.cargo-check`, and `rust.clippy` foundation.
 
+## Python Syntax Validation
+
+#244 makes `python.syntax` compiler-truthful. The adapter resolves one concrete project interpreter once, retains its executable, working directory, version, resolution source, and declared-target compatibility, then invokes that exact executable with isolated no-bytecode flags. A versioned JSON stdin/stdout protocol compiles sorted `.py` and `.pyi` after-state content with `compile(..., "exec", dont_inherit=True)` without importing, executing, or materializing source files.
+
+Python syntax diagnostics carry normalized workspace-relative paths, stable compiler-error codes, 1-based ranges when supplied by the interpreter, and interpreter provenance. Validation run summaries preserve fine-grained `passed`, `findings`, `tool_unavailable`, `invalid_config`, `timeout`, `unsupported_target`, and `tool_failure` outcomes while retaining aggregate validation statuses. Protocol/schema mismatch, unknown nonzero exit, timeout, signal, spawn failure, and mismatched file/provenance output fail closed. Hand-written delimiter, quote, comment, or compound-header grammar checks must not override compiler success; any future supplemental Python policy requires a separate check ID and category.
+
 ## Clone Validation Adapter
 
 #151 adds `@the-open-engine/opcore-validation-clone` as the duplicate-code validation adapter package. The stable check id is `clone.duplication`; it requiresGraph:false, reads candidate after-state through `ValidationCheckContext.fileView.readAfter`, and emits line-free duplicate-code diagnostics with stable clone-class identity. The adapter receives its native invocation function from Opcore validation composition, so it does not import graph-core loaders, raw SQLite, graph internals, or the aggregate CLI.

diff --git a/docs/concepts.md b/docs/concepts.md
@@ -4,7 +4,7 @@
 
 Opcore starts by counting the repository. TypeScript, JavaScript, Rust sources, `Cargo.toml`, retained Rust metadata, and Python `.py`/`.pyi` files are recognized for alpha checks. Unsupported extensions are still counted with examples so reports do not imply broader coverage than exists.
 
-Python coverage is experimental and degraded-honest. Graph-backed structure, untested modules, dead exports, syntax, source-hygiene, import graph, and relevant-test signals may be reported for `.py`/`.pyi` files. `python.types` depends on mypy or pyright; missing tools produce degraded optional-tool evidence instead of fake pass/fail findings.
+Python coverage is experimental and degraded-honest. Graph-backed structure, untested modules, dead exports, syntax, source-hygiene, import graph, and relevant-test signals may be reported for `.py`/`.pyi` files. `python.types` executes exactly one configured mypy or Pyright authority per project over the same hypothetical after-state. Missing, conflicting, or unavailable authority evidence is degraded instead of becoming a fake pass/fail finding.
 
 ## Findings
 

diff --git a/docs/examples.md b/docs/examples.md
@@ -92,7 +92,7 @@ For Python-only validation in the same scan, check, measure loop:
 opcore check --changed --checks python.syntax,python.source-hygiene --json
 ```
 
-`python.types` is optional-tool evidence; missing mypy or pyright is reported as degraded instead of inventing a finding.
+`python.types` is configured-authority evidence. Exactly one configured mypy or Pyright runs per project; absent, conflicting, or unavailable authority is degraded instead of inventing a finding.
 
 ## Read Deltas
 
@@ -108,5 +108,5 @@ Coverage:
 Signals:
   typescript.type_errors: 2 baseline=-1 previous=+0
   python-measure-delta: python.dead-code previous=-1 baseline=+0
-  python.types: degraded requiredTool=mypy|pyright
+  python.types: degraded requiredTool=configured-authority
 ```
diff --git a/docs/planning/opcore-alpha-roadmap.md b/docs/planning/opcore-alpha-roadmap.md
@@ -68,7 +68,7 @@ Ship only signals the engine can defend:
 - Rust oversized files.
 - Rust module cycles, orphans, and unresolved module evidence.
 - Rust cargo, fmt, clippy, rustdoc, and optional-tool evidence when available, with honest degraded status when tools are missing.
-- Python `.py`/`.pyi` graph-backed structure, untested modules, dead exports, syntax, source-hygiene, import graph, relevant-test signals, and optional `python.types` via mypy or pyright with degraded status when tools are missing.
+- Python `.py`/`.pyi` graph-backed structure, untested modules, dead exports, syntax, source-hygiene, import graph, relevant-test signals, and configured-authority `python.types`; exactly one mypy or Pyright authority runs per project, while absent/conflicting/unavailable authority remains degraded. Python readiness and parity remain gated on later release evidence.
 - Unsupported language census with no fake findings.
 
 Do not ship headline claims for generic complexity, TS complexity, Python code analysis, Go/Java analysis, security, cross-repo percentiles, automatic fixes, or old-tool replacement.

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -79,7 +79,7 @@ Approved repo install writes additive `.opcore/config`, one delimited guidance b
 
 ## Coverage
 
-Opcore is deep for TypeScript/JavaScript graph-backed signals and useful for Rust validation signals. Python is experimental and degraded-honest: `.py`/`.pyi` graph-backed structure, untested modules, dead exports, syntax, and source-hygiene are reported when available; `python.types` depends on mypy or pyright and reports missing tools as degraded. Other non-TS/JS/Rust/Python languages are counted and reported as unsupported; they do not get fake findings or fake ratings.
+Opcore is deep for TypeScript/JavaScript graph-backed signals and useful for Rust validation signals. Python is experimental and degraded-honest: `.py`/`.pyi` graph-backed structure, untested modules, dead exports, syntax, and source-hygiene are reported when available; `python.types` runs exactly one configured mypy or Pyright authority per project and degrades when authority is absent, conflicting, or unavailable. Other non-TS/JS/Rust/Python languages are counted and reported as unsupported; they do not get fake findings or fake ratings.
 
 ## Demo Loop
 

diff --git a/docs/release/artifact-attestation.md b/docs/release/artifact-attestation.md
@@ -12,16 +12,16 @@ Graph input evidence: docs/release/graph-release-receipt.json
 
 | Platform | Binary | Binary SHA-256 | Checksum File |
 |----------|--------|----------------|---------------|
-| darwin-arm64 | node_modules/@the-open-engine/opcore-graph-core-darwin-arm64/opcore-graph-core | c222610c492e628fa48ff50be22310e5bf8ebcd62bffbde1903d1fa91c45f6cb | node_modules/@the-open-engine/opcore-graph-core-darwin-arm64/opcore-graph-core.sha256 |
+| darwin-arm64 | node_modules/@the-open-engine/opcore-graph-core-darwin-arm64/opcore-graph-core | 72acf10de0ece619c3896943addfb0cc1b09dab22000b48a653b033224217bc8 | node_modules/@the-open-engine/opcore-graph-core-darwin-arm64/opcore-graph-core.sha256 |
 | darwin-x64 | node_modules/@the-open-engine/opcore-graph-core-darwin-x64/opcore-graph-core | 1b72afa74d48b087c967cb01b39630ed3fa58b5a2895037a778eb5612ef73059 | node_modules/@the-open-engine/opcore-graph-core-darwin-x64/opcore-graph-core.sha256 |
-| linux-x64 | node_modules/@the-open-engine/opcore-graph-core-linux-x64/opcore-graph-core | 70cb6d213d74594f337a67522c879b77767872dc4601063686f1abe70886127b | node_modules/@the-open-engine/opcore-graph-core-linux-x64/opcore-graph-core.sha256 |
+| linux-x64 | node_modules/@the-open-engine/opcore-graph-core-linux-x64/opcore-graph-core | c3a771435a7a8172a9e5f0bb20b0d111453efc70901e95308094664f77e7bdf1 | node_modules/@the-open-engine/opcore-graph-core-linux-x64/opcore-graph-core.sha256 |
 
 No package publishing happens in this gate.
 
 ## Cutover Gate
 
 Issue #30 receipt: docs/release/cutover-receipt.json
-Cutover receipt SHA-256: c8d33f671a1f6801a6b46362c4f2bd1f152dfbd13e161ef83c007b194723adf8
+Cutover receipt SHA-256: c72be0d79199505770c631b08201be09f8602e239e80c1ffa974e7f24d1cf32b
 Installed command receipts: 28
 Rust command receipts: 7
 Python command receipts: 8