diff --git a/AGENTS.md b/AGENTS.md index 36577e5..5ce5472 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,7 +119,7 @@ feature cohesive is in scope; unrelated cleanup remains out of scope. cargo fmt --all -- --check cargo clippy --workspace --all-targets --all-features -- -D warnings cargo test --workspace --all-targets --all-features -python3 -m unittest discover -s compatibility/tests +python3 -m unittest discover -s tools/overpy/tests ``` Oracle-required compatibility probes run separately against the pinned diff --git a/README.md b/README.md index 6f45cd6..13fbae9 100644 --- a/README.md +++ b/README.md @@ -87,28 +87,16 @@ The Rust library surface, including the bounded Workshop compiler, lives in Compatibility targets observable OverPy semantics for the declared support surface, not byte-identical output, optimizer choices, formatting, temporary variables, or upstream internal architecture. Support claims are backed by the -compatibility corpus and pinned OverPy reference evidence. +canonical [language-support contract](docs/language-support.md), its linked +inventories, and pinned OverPy reference evidence. > [!IMPORTANT] > `opy-rs` follows the OverPy language. It does not introduce a WrightKit-only > OPY dialect. -| Capability | Status | Notes | -| --- | --- | --- | -| Core syntax & control flow | βœ… Supported | Workshop-independent parsing and semantic representation | -| Declarations | βœ… Supported | `globalvar`/`playervar`, `subroutine`, `def`, `enum`, `macro` | -| Preprocessing & macros | βœ… Supported | `#!include`, `#!define`, `#!undef`, bounded JavaScript macros | -| Rules & directives | βœ… Supported | Rules, events, conditions, team/slot context in the declared surface | -| Builtin actions & values | 🟑 Partial | Declared semantic subset works; full catalog-backed breadth is still being closed | -| Receiver/member functions | 🟑 Partial | Declared members work; full member breadth is not yet complete | -| Enums & constants | 🟑 Partial | Declared domains resolve; full domain breadth is not yet complete | -| Advanced directives, translations & optimizer controls | 🟑 Partial | Source state exists; Workshop-dependent effects remain incomplete | -| OPY β†’ Workshop compilation | 🟑 Partial | The versioned library/CLI compile contract and bounded lowering surface are supported; remaining corpus gaps stay explicit | -| Workshop β†’ OPY reconstruction | ⏳ Not yet | Will consume canonical `workshop-rs` semantics and remain owned by `opy-rs` | - -The exhaustive per-feature evidence and pinned denominator are maintained in -the [canonical human-readable support contract](docs/language-support.md) and -its linked inventories. +The exhaustive per-feature evidence, pinned denominator, and current status are +maintained in the [canonical human-readable support contract](docs/language-support.md) +and its linked inventories. ## Relationship with Wright diff --git a/docs/README.md b/docs/README.md index 7135fa8..069097e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -41,9 +41,7 @@ compatibility pointers rather than separate architecture authorities. - [OverPy support contract](language-support.md): current evidenced feature coverage. -- [Compatibility baseline](opy/compatibility-baseline.md): planning/reference - inventory for remaining evidence work. -- [Offline conformance baseline](opy/conformance-baseline.md): oracle and +- [Offline conformance evidence](opy/conformance-baseline.md): oracle and comparison methodology. - [Upstream references](compatibility/upstream-references.md): pinned upstream identity, provenance, licensing, and reference boundaries. diff --git a/docs/compatibility/upstream-references.md b/docs/compatibility/upstream-references.md index 34f8384..b711f9b 100644 --- a/docs/compatibility/upstream-references.md +++ b/docs/compatibility/upstream-references.md @@ -66,9 +66,9 @@ it serves as: * the reference for S (syntax), D (diagnostic), and N (normalized-output) evidence in the compatibility corpus (`crates/opy-rs/tests/fixtures/corpus/**`, `tools/overpy/oracle/`); -* the source of systematic probe validation for the proactive compatibility - baseline (see [`docs/opy/compatibility-baseline.md`](../opy/compatibility-baseline.md) - and [`docs/opy/compat-manifest-spec.md`](../opy/compat-manifest-spec.md)); +* the source of systematic probe validation for the pinned language-support + inventories (see [`docs/language-support.md`](../language-support.md) and + [`docs/opy/compat-manifest-spec.md`](../opy/compat-manifest-spec.md)); * the reference for differential parity at the Opy HIR v2 boundary ([`docs/hir/opy-hir-v2.md`](../hir/opy-hir-v2.md)): the native differential suite (`crates/opy-rs/tests/differential.rs`, merged in PR #13) runs @@ -262,7 +262,6 @@ when the oracle is absent. ## Related documents * [`docs/language-support.md`](../language-support.md): audited public support contract and current states -* [`docs/opy/compatibility-baseline.md`](../opy/compatibility-baseline.md): tiered planning baseline * [`docs/opy/compat-manifest-spec.md`](../opy/compat-manifest-spec.md): machine-readable semantic manifest specification * [`docs/opy/tooling-notes.md`](../opy/tooling-notes.md): harness usage * [`tools/overpy/README.md`](../../tools/overpy/README.md): oracle and fixture layout diff --git a/docs/opy/architecture.md b/docs/opy/architecture.md index 19d9859..985b53a 100644 --- a/docs/opy/architecture.md +++ b/docs/opy/architecture.md @@ -7,5 +7,3 @@ The current architecture contracts are maintained under - [`workshop-boundary.md`](../architecture/workshop-boundary.md) β€” canonical Workshop dependency/lowering/reconstruction boundary. This path is retained for existing links. The previous "accepted living architecture" combined current contracts, implementation mechanisms, capability status, and references to the semantic manifest. That content remains available in Git history but is no longer the current architecture authority. - -Current support must be established from [`../language-support.md`](../language-support.md) and executable evidence. Current implementation reality comes from source, tests, Cargo metadata, corpus/differential evidence, and real-project workflows. ADRs or older design prose do not prove either. diff --git a/docs/opy/compatibility-baseline.md b/docs/opy/compatibility-baseline.md deleted file mode 100644 index 92bcf0c..0000000 --- a/docs/opy/compatibility-baseline.md +++ /dev/null @@ -1,144 +0,0 @@ -# Proactive OPY Compatibility Baseline - -Status: accepted baseline (planning). A proactive OPY compatibility baseline -for opy-rs (issue #2), ported and adapted from the WrightKit evidence base. -Scope: forward-looking, tiered inventory of the OPY language surface against -the pinned OverPy 9.7.10 reference, classifying every category by -implementation tier and by support dimension - -This document is the planning counterpart to the -[canonical language-support contract](../language-support.md): that contract -records the corpus-evidenced surface the opy-rs source implementation targets, while this baseline -records how the remaining surface is **tiered and sequenced**. A construct is -not called supported merely because it parses; each row states parse, -semantic, compilation, tooling/analysis, and reference coverage separately. - -The reference identity is the pinned OverPy 9.7.10 content -(`889d9749d1def17f146548cbddb94ea1ab015847`); see -[`docs/compatibility/upstream-references.md`](../compatibility/upstream-references.md) -for provenance. Evidence claims in this document were verified against the -pinned oracle (the declared corpus now contains 42 provenance-linked -snapshots). The opy-rs source implementation foundation and #7 readiness work are -implemented on `main` (issues #3–#7, #28–#30, and #33); the category table is the -**tier assignment contract** for the remaining surface. The status and -coverage fields in the linked feature inventory track actual implementation -progress against it, and rows marked `baseline-supported` in this document are -implemented unless the table says otherwise. - -## Tier taxonomy - -| Tier | Meaning | -| --- | --- | -| `baseline-supported` | Implemented and corpus/reference-evidenced; part of the declared supported surface | -| `baseline-planned` | Stable, high-fan-out, systematically implementable; contract is discoverable and reference-testable; not yet implemented | -| `evidence-prioritized` | Complex or broad feature with clear tooling value; corpus/consumer evidence determines ordering | -| `legacy-quirk/demand-driven` | Rare historical quirks, upstream bugs, obsolete aliases, scripting hooks; implemented only when the declared compatibility target requires them | -| `reference-limited/inconclusive` | Cannot be resolved from the pinned reference; needs a demonstrated need, a pin change, or further investigation | - -## Support dimensions - -For each category the following dimensions are distinguished: - -* **Parse**: accepted by the opy-rs source implementation grammar; -* **Semantic resolution**: resolved to a meaningful HIR/semantic value - (names, members, enums, call semantics); -* **Compilation**: standalone compile/emission through the `workshop-rs` -backend succeeds with reference-equivalent semantics. The bounded #35 -vertical slice is now evidenced through workshop-rs v0.1.19; the remaining -surface is **lowering-dependent** and stays inventory-only until later #8 -work; -* **Tooling/analysis**: `check`/`analyze`/`lint`/`inspect` and language - services can operate on the construct; -* **Reference coverage**: oracle probes/fixtures validate the behavior. - -In the table, `βœ…` marks a dimension that is part of the declared contract for -the tier (evidenced by the merged source implementation via the corpus and the native -differential suite), `❌` a deliberately -rejected/documented-absent dimension, `β€”` an inapplicable dimension, and -`partial` a bounded subset. - -## Category inventory - -| # | Category | Tier | Parse | Sem | Comp | Tooling | Ref | -| --- | --- | --- | --- | --- | --- | --- | --- | -| 1 | **Expression/postfix/member/call grammar**: operators and precedence, `[]` indexing, `.` member, calls, `del`, `in`/`not in`, hex `0x`, statement-level `++`/`--` | `baseline-supported` for the corpus subset (operators, indexing, calls, member/call, and bounded postfix assignments); prefix `++` and embedded postfix `++`/`--` remain rejected, while prefix `--x` remains valid consecutive unary-minus syntax | βœ… corpus | βœ… | βœ… (integration) | βœ… | βœ… differential (issue #7) | -| 1a | `switch`/`case`/`default`, `break`, `do…while`, `in`/`not in`, `0x` hex literals | `baseline-supported` for the pinned source implementation surface; Workshop control-flow lowering remains integration-owned | βœ… | βœ… | partial (integration) | βœ… | βœ… oracle probes | -| 1b | String modifiers (`f`/`w`/`l`/`b`/`c`/`t`), dict literals, list comprehensions, signature-gated `lambda` | `baseline-supported` for the pinned source implementation surface; canonical lowering covers f/w/b/c literals and literal-key dictionary lookup, while l/t translation content and broader dict writes remain lowering-dependent | βœ… | βœ… | partial (integration) | βœ… | βœ… oracle probes | -| 2 | **Declarations**: `globalvar`/`playervar` (index + initializer forms), `subroutine`, `enum`, `macro` constants (incl. member constants) | `baseline-supported` | βœ… | βœ… | βœ… (integration) | βœ… | βœ… | -| 3 | **Assignments & control flow**: `=`, evidenced augmented (`+= -= *= /= %= **= ++ --`), `if`/`elif`/`else`, `for … in range(...)`, `while`, `pass` | `baseline-supported`; `min=`/`max=` remain workshop-rs#95 follow-up | βœ… | βœ… | βœ… (integration) | βœ… | βœ… | -| 4 | **Rule directives & annotations**: `@Event`, `@Condition`, bare `@Team`/`@Slot`, rule name, event defaults (`global`, `all` team/player) | `baseline-supported` (bare forms) | βœ… | βœ… | βœ… (integration) | βœ… | βœ… | -| 4a | `@Team`/`@Slot` with arguments, `@Name`, `@Hero`, `@Disabled`, `@Delimiter`, `@NewPage`, `@SuppressWarnings` | `baseline-supported` for source implementation state; Workshop domain/UI effects remain lowering-dependent | βœ… | βœ… | partial | βœ… | βœ… oracle probes | -| 5 | **Preprocessing/include/macro**: `#!include`, `#!define` (object- and function-like), `#!undef`, include cycle detection | `baseline-supported` | βœ… | βœ… | βœ… (integration) | βœ… | βœ… | -| 5a | `#!mainFile`, `#!allowMacroRedeclaration`, `#!optimize*`/`#!replace0By*` family, `#!translations`, `#!rulePrefix*`, `__script__` JS hooks | `baseline-supported` for source implementation state; rule-prefix metadata, catalog locale emission, and post-compile hooks have bounded compiler evidence, while optimizer/replacement effects remain explicit gaps | βœ… | βœ… | partial | βœ… | βœ… oracle probes | -| 6 | **OPY builtin actions & values (generic)**: manifest identities, signatures, aliases, and call semantics | `baseline-supported` for the probe-validated manifest overlay; canonical Workshop existence/content/emission is `lowering-dependent` | βœ… | βœ… | partial (integration) | βœ… | βœ… probes | -| 6a | **Canonical Workshop builtin action/value catalog**: full catalog existence, content, and emission | `lowering-dependent` (`workshop-rs`, #8) | β€” | β€” | ❌ (integration) | β€” | βœ… inventory/oracle evidence | -| 7 | **OPY receiver/member semantics**: receiver categories, explicit-argument signatures, variable receivers | `baseline-supported` for the manifest-declared OPY overlay; canonical member existence/content/emission is `lowering-dependent` | βœ… | βœ… | partial (integration) | βœ… | βœ… probes | -| 7a | **Canonical Workshop receiver/member catalog**: member existence, content, and emission | `lowering-dependent` (`workshop-rs`, #8) | β€” | β€” | ❌ (integration) | β€” | βœ… inventory/oracle evidence | -| 7b | Bare playervar receiver member access (`A = B.C`) | `baseline-supported` for the OPY member-expression representation; canonical member existence remains lowering-dependent | βœ… | βœ… | partial (integration) | βœ… | βœ… oracle evidence | -| 8 | **OPY enum/domain semantics**: declared domain identities and contextual dispatch | `baseline-supported` for manifest identity links; canonical member lists/membership/emission are `lowering-dependent` | βœ… (identities) | βœ… | partial (integration) | partial | βœ… probes | -| 8a | **Canonical Workshop enum/domain catalog**: member lists, membership, and emission | `lowering-dependent` (`workshop-rs`, #8) | β€” | β€” | ❌ (integration) | β€” | βœ… inventory/oracle evidence | -| 9 | **Aliases**: old function names (`stopChasingVariable`β†’`stopChasing`, `getCurrentHero`β†’`getHero`, `hasStatusEffect`β†’`hasStatus`, …), hero renames (`MCCREE`β†’`CASSIDY`), `ChaseReeval` contextual alias | `baseline-supported` for the manifest-declared non-contextual aliases and the `ChaseReeval` call-context resolution; the remaining alias surface stays `legacy-quirk/demand-driven` | βœ… (declared) | βœ… | βœ… (chase forms catalog-covered at integration) | βœ… | βœ… | -| 10 | **Modules**: `random.{randint,uniform,choice,shuffle}` | `baseline-supported` (corpus: `random.uniform`, `random.choice`) | βœ… | βœ… | βœ… (integration) | βœ… | βœ… | -| 11 | **Named/keyword arguments**: `chase(A, B, rate=30, …)`, generic `name = expr` binding against manifest signatures | `baseline-supported` for the evidence surface (generic keyword binding plus the `chase`/`ChaseReeval` call-context forms); `raycast` `include=`/`exclude=` forms and macro keyword arguments stay `evidence-prioritized` (no corpus/reference evidence in the declared surface) | βœ… | βœ… | βœ… (integration) | βœ… | βœ… probes | -| 12 | **Settings/content metadata**: `settings { … }` blocks | `baseline-supported` (JSONC subset + typed HIR payload); the Workshop `settings` emission table is **lowering-dependent** | βœ… | βœ… | ❌ (integration) | βœ… | βœ… | -| 12a | `settings "file"`, richer settings expressions, hero/map/ability content beyond the pin | `legacy-quirk/demand-driven` / `reference-limited` | ❌/partial | ❌ | ❌ | ❌ | partial (data newer than pin unavailable per the pinning policy) | -| 13 | **Source identity & diagnostics**: structured, source-located source implementation errors, `wright-result/v1` | `baseline-supported` | βœ… | βœ… | β€” | βœ… | βœ… S/D | - -## Current planning notes - -The pinned OPY source implementation surface from -#28/#29/#30/#33 is represented as source implementation- or semantic-supported; Workshop -catalog, emission, and runtime effects remain explicitly -`lowering-dependent`. Their tiers above -distinguish **evidence-prioritized** work (broad or high-fan-out surface with -clear tooling value, ordered by corpus/consumer evidence) from -**legacy-quirk/demand-driven** compatibility (rare historical quirks and -upstream behaviors implemented only when the declared compatibility target -requires them), not every upstream quirk is a planned implementation. - -## Residual evidence items (classified) - -Verified against the pinned oracle. Each item is classified with the tier it -belongs to; none is a per-symbol implementation request. Items marked -*manifest-covered* resolve through the OPY semantic compatibility manifest -(`crates/opy-rs/src/manifest/`), which is merged on `main`; rows below -record their current opy-rs status against the current support-matrix baseline, -and remaining gaps stay classified rather than being filed per-symbol. - -| Evidence | Oracle 9.7.10 | opy-rs status | Classification | -| --- | --- | --- | --- | -| **Bare playervar receiver**: `A = B.C` (declared playervar member on a player-valued receiver) | accept (`__playerVar__`) | implemented as a provenance-preserving OPY member expression; canonical member existence remains lowering-dependent | `baseline-supported` (receiver/member semantics; category 7) | -| **Value member as statement**: `B.isAlive()` on its own line | **reject** ("Expected an action, but got … a value") | implemented: rejects with `value-in-action-position` | `baseline-supported` (reviewed difference; recorded in the probe set) | -| **Generic action gap**: `chaseOverTime(A, 0, 30, ChaseTimeReeval.NONE)` | accept (warning recorded) | implemented: manifest-declared; differential fixture: `synthetic/chase-condition-agentlab`, probe `chase-over-time` | `baseline-supported` (manifest-covered); emission via catalog spelling is lowering-dependent | -| **Generic value gap**: `@Condition isGameInProgress() == true` | accept | implemented: manifest entry; probe `is-game-in-progress` | `baseline-supported` (manifest-covered) | -| **Member value/signature gap**: `getPlayersInRadius(...).setStatusEffect(eventPlayer, 30)` | **reject** (arity: `.setStatusEffect` needs `player, assister, status, duration`) | implemented: rejects with a structured arity diagnostic (`missing-argument`); probe `invalid-arity-member` | `baseline-supported` (manifest-covered) | -| **Enum-gated members**: `eventPlayer.setInvisibility(Invis.ALL)`, `eventPlayer.getThrottle()`, `worldVector(...)` (args typed `Invis`/`Transform`) | accept | implemented: manifest domain identities resolve as opaque members; member-existence validation is **lowering-dependent** (#8); probe `enum-gated-members` | `baseline-supported` (manifest-covered); catalog spellings lowering-dependent | -| **Named arguments / `ChaseReeval` alias**: `chase(A, 10, rate=2, ChaseReeval.NONE)` | accept (contextual alias resolution) | implemented: generic `name = expr` binding plus the `chase` special form; probes `chase-keywords`, `chase-reeval-context`, `chase-keyword-binding`, the `chase-*` diagnostic probes, and the `synthetic/chase-keywords` corpus fixture | `baseline-supported` (manifest-covered) | -| **Ambiguous Workshop enum spelling**: `ChaseTimeReeval.NONE`, `ChaseRateReeval.NONE`, and `Invis.NONE` all emit as bare `None` | β€” | emission-context resolution is **lowering-dependent** (needs the Workshop emission context); source implementation-side signature-pinned resolution stays source implementation-owned | `lowering-dependent` for context-free `None`; signature-pinned contexts are `baseline-supported` | -| **Constant-0 canonicalization**: `globalvar A = 0` drops the initializer; `= 5`/`= 0.0` preserved via the Initialize rule; `globalvar A 0` is an explicit index | canonical | implemented: `globalvar A = 0` drops the initializer and `= 5`/`= 0.0` are preserved, matching the reference; Initialize-rule synthesis is lowering-dependent | `baseline-supported` (source implementation part); lowering-dependent (Initialize synthesis) | -| **Diagnostic provenance**: unresolved action/value errors surface as structured semantic diagnostics, not emitter catalog misses | β€” | implemented: structured semantic diagnostics (`unknown-action`, `unknown-value`, `unknown-member`, `invalid-arity`, `invalid-receiver`, `action-in-value-position`, `value-in-action-position`, `invalid-call-context`, `invalid-iterable`, argument-binding codes); Workshop enum member/domain mismatch codes were removed with the catalog validation (PR #9) and stay `lowering-dependent` | `baseline-supported` (manifest-covered) | - -## Boundaries - -* **No per-symbol issues.** These evidence items are grouped into semantic - categories; none justifies a one-symbol implementation issue. -* **No temporary Workshop IR.** Workshop-dependent features are classified - `lowering-dependent` in the language-support inventory and inventory-only until the - `workshop-rs` integration stage (#8). Nothing here starts `workshop-rs` - work or duplicates catalog/WIR/emitter data. -* **Runtime content registry stays deferred.** This baseline is - compile-time language-compatibility metadata, versioned with the pinned - reference identity. A runtime content registry (heroes/maps/abilities - content data, extension boundaries, independent version identities) is not - triggered by this inventory (see [`compat-manifest-spec.md`](compat-manifest-spec.md) - for the boundary). -* **Sequencing.** The bounded child-issue categories and their ordering are - recorded in the issue #1 execution list (#3–#7); this baseline does not - create implementation issues. - -## Related documents - -* [`docs/compatibility/upstream-references.md`](../compatibility/upstream-references.md): pinned reference identity and provenance -* [`compat-manifest-spec.md`](compat-manifest-spec.md): machine-readable semantic manifest specification (data in `crates/opy-rs/src/manifest/`) -* [`../language-support.md`](../language-support.md): canonical feature status and coverage -* [`tools/overpy/README.md`](../../tools/overpy/README.md): corpus and harness layout diff --git a/docs/opy/conformance-baseline.md b/docs/opy/conformance-baseline.md index e7cd2f9..6c37471 100644 --- a/docs/opy/conformance-baseline.md +++ b/docs/opy/conformance-baseline.md @@ -1,18 +1,19 @@ -# Offline OverPy conformance baseline +# Offline OverPy conformance evidence -Issue #158 establishes the conformance boundary used before further OPY -compatibility implementation. The durable machine-readable inventory is +Issue #158 establishes the conformance evidence contract for OPY compatibility +implementation. The durable machine-readable inventory is [`docs/language-support/conformance-manifest.json`](../../docs/language-support/conformance-manifest.json); the executable runner is [`tools/overpy/conformance.py`](../../tools/overpy/conformance.py). -## Independent inventory +## Canonical inventory relationship The inventory categories are derived from the pinned OverPy 9.7.10 source registries and public project/test evidence recorded in [`upstream-references.md`](../compatibility/upstream-references.md) and [`language-support/registries.md`](../language-support/registries.md). The -manifest declares structural contracts for each category. Every contract has -a reviewable claim, one or more probe kinds (`positive`, `negative`, +manifest is a linked executable-evidence inventory within the canonical +language-support contract, not a second feature-support authority. Every contract +has a reviewable claim, one or more probe kinds (`positive`, `negative`, `contextual`, or `composition`), and one or more executable fixture probes; the validator rejects missing, unknown, or empty mappings. It does not derive its declared surface, reference outcome, or expected behavior from the current @@ -33,8 +34,8 @@ The categories are: | `ownership.workshop-feature-census` | opaque consumer evidence for the workshop-rs-owned census | The existing `docs/language-support/registries.md` remains the leaf inventory -of upstream names. This baseline adds the executable structural probes and -does not duplicate upstream catalog data in `opy-rs`. +of upstream names. This evidence manifest adds executable structural probes and +does not duplicate upstream catalog data or feature-support authority in `opy-rs`. ## Comparison contract diff --git a/docs/opy/support-matrix.md b/docs/opy/support-matrix.md deleted file mode 100644 index d0b14ff..0000000 --- a/docs/opy/support-matrix.md +++ /dev/null @@ -1,5 +0,0 @@ -# Support contract redirect - -The canonical public OverPy compatibility contract is -[`../language-support.md`](../language-support.md). Its linked inventories are -the complete audited support documentation for pinned OverPy `9.7.10`. diff --git a/docs/opy/tooling-api.md b/docs/opy/tooling-api.md index 973e9e3..952a2eb 100644 --- a/docs/opy/tooling-api.md +++ b/docs/opy/tooling-api.md @@ -44,9 +44,10 @@ it directly with the native lowered WIR through input digests; the public compile report and `opy-cli compile` have no oracle input or compatibility-evidence field. -The compatibility runner uses the separate +The compatibility runner uses the separate reviewed compiler expectation +contract in [`tools/overpy/compiler-expectations.json`](../../tools/overpy/compiler-expectations.json) -baseline for compiler outcomes. The source/frontend expectation contract is +for compiler outcomes. The source/frontend expectation contract is kept in `differential-expectations.json`; it is not reused as compiler parity evidence. Compiler gaps must carry durable evidence and an owner, while expectation mismatches remain blocking. @@ -161,8 +162,7 @@ opy-cli version # crate + source implementatio Exit codes: `0` clean/success, `1` diagnostics found, `2` usage or I/O errors. `check`/`inspect` resolve includes against the main file's parent directory. The CLI runs anywhere the binary runs: no Node, no Workshop -backend, no runtime data files (the matrix and the semantic manifest are -embedded). +backend, and no runtime data files; the semantic manifest is embedded. ### Presentation candidate for Issue #43 @@ -179,7 +179,7 @@ unchanged: GitHub Actions never receives ANSI even when `always` is requested. * `--format json` is currently available on `check`. It writes only `{ok, diagnostics}` JSON to stdout and returns the same 0/1 result code. `inspect` - and `support` remain JSON by default and bypass presentation entirely. + remains JSON by default and bypasses presentation entirely. Compile format json writes the versioned compile report described above; compiler failures return 1. If the required input path is missing, or the path cannot be read, the CLI cannot produce a machine result: it returns exit `2`, writes the human I/O diff --git a/tools/overpy/README.md b/tools/overpy/README.md index 12136f4..1652a5b 100644 --- a/tools/overpy/README.md +++ b/tools/overpy/README.md @@ -188,9 +188,9 @@ Artifacts under `target/`: * `target/opy-differential/.native.json`: normalized native HIR wire payload (span endpoints removed) per fixture; * `target/opy-differential-report.json`: machine-readable per-fixture status - (`resolve` / `expected-diagnostic` / `divergence`), native diagnostic code, - reference status, rule-name comparison, and the support-matrix feature ids - the fixture evidences. + (`resolve` / `expected-diagnostic` / `divergence`), classification, native + diagnostic details, reference status, `referenceGap`, rule-name comparison, + and expectation evidence. Fixtures without an `oracle.json` are marked `skip` (reference comparison degraded gracefully); the structural self-check and the expected-outcome @@ -239,18 +239,19 @@ presentation difference. A normalized-output or semantic-WIR regression exits a producer. Use `--allow-inconclusive` only for local contract checks. -## Offline conformance baseline (issue #158) +## Offline conformance evidence (issue #158) -`../../docs/language-support/conformance-manifest.json` is the independent inventory for the pinned -OverPy source-language baseline. Its categories cite the pinned upstream -registries or an accepted canonical-WIR contract. Each category declares -structural contracts with a claim, probe kinds (`positive`, `negative`, -`contextual`, or `composition`), and executable fixture probes; validation -rejects empty or unknown mappings. It contains no native expected outcomes. +`../../docs/language-support/conformance-manifest.json` is the linked +executable-evidence inventory for the canonical pinned OverPy source-language +contract. Its categories cite the pinned upstream registries or an accepted +canonical-WIR contract. Each category declares structural contracts with a +claim, probe kinds (`positive`, `negative`, `contextual`, or `composition`), +and executable fixture probes; validation rejects empty or unknown mappings. +It contains no native expected outcomes or alternate feature-support authority. Reference failures carry an audited stage and first-construct frontier tied to text in their pinned oracle snapshot. -Run the baseline after building both CLI targets: +Run the evidence check after building both CLI targets: ```sh python3 tools/overpy/conformance.py \ @@ -268,7 +269,7 @@ parsed by `workshop-rs::roundtrip::equivalent`. For reference failures, the runner compares stage and first construct, retaining both sides' diagnostic provenance without requiring diagnostic wording identity. -This baseline is evidence-producing rather than a production implementation +This command is evidence-producing rather than a production implementation gate: current divergence is expected to remain visible while follow-up Issues resolve root capabilities. Malformed manifests, stale oracle evidence, and missing producer data remain hard failures. diff --git a/tools/overpy/compiler-expectations.json b/tools/overpy/compiler-expectations.json index 3a71666..aabb50c 100644 --- a/tools/overpy/compiler-expectations.json +++ b/tools/overpy/compiler-expectations.json @@ -1,9 +1,9 @@ { "schemaVersion": 1, "contract": "compiler", - "description": "Independent compiler outcome expectations for the #38 OPY-to-Workshop compatibility baseline. Source/frontend expectations remain in differential-expectations.json.", + "description": "Reviewed compiler outcome expectations for the #38 OPY-to-Workshop evidence contract. Source/frontend expectations remain in differential-expectations.json.", "evidencePolicy": { - "native": "The compiler result is compared with this separately reviewed baseline; it never creates its own expectation.", + "native": "The compiler result is compared with this separately reviewed expectation contract; it never creates its own expectation.", "classification": "match requires normalized output, direct canonical-WIR equivalence, or a stable diagnostic contract. known-gap and unsupported require pinned oracle and fixture provenance evidence plus a concrete follow-up owner.", "semanticWIR": "The runner compares native WIR directly with the pinned oracle WIR through workshop-rs::roundtrip::equivalent and verifies both complete project input digests. It never reparses native Workshop text as a substitute for native WIR." }, @@ -412,7 +412,7 @@ "evidence": [ "oracle:census/workshop-feature-census/oracle.json", "provenance:census/workshop-feature-census/fixture.json", - "support-matrix:compilation/end-to-end" + "contract:lowering.canonical-wir/vertical-slice" ], "owner": "opy-rs#38", "note": "The bounded feature census matches the pinned oracle through the normalized compiler output contract." @@ -519,7 +519,7 @@ "provenance:real-world/overpy-meipocalypse/fixture.json" ], "owner": "opy-rs#157", - "note": "The full real-world project now resolves included settings; it remains outside the compiler baseline at the fixture's missing generateWalls.js script resource.", + "note": "The full real-world project now resolves included settings; it remains outside the compiler contract at the fixture's missing generateWalls.js script resource.", "failureClass": "frontend", "diagnosticCode": "script-not-found" }, @@ -546,7 +546,7 @@ "provenance:real-world/overpy-pixelart/fixture.json" ], "owner": "opy-rs#157", - "note": "The source compiles, but full real-world Workshop parity is outside the declared #38 baseline.", + "note": "The source compiles, but full real-world Workshop parity is outside the declared #38 compiler contract.", "semanticEquivalent": false }, { @@ -572,7 +572,7 @@ "provenance:real-world/overpy-zencopter/fixture.json" ], "owner": "opy-rs#157", - "note": "The full real-world project remains outside the #38 compiler baseline and currently stops at a frontend lexical gap.", + "note": "The full real-world project remains outside the #38 compiler contract and currently stops at a frontend lexical gap.", "failureClass": "frontend", "diagnosticCode": "lex-error" }, @@ -709,7 +709,7 @@ "provenance:synthetic/directives/fixture.json" ], "owner": "opy-rs#157", - "note": "Optimizer/backend directive execution remains outside the declared compiler baseline.", + "note": "Optimizer/backend directive execution remains outside the declared compiler contract.", "failureClass": "integration", "diagnosticCode": "backend-directive-unsupported" }, @@ -753,7 +753,7 @@ "provenance:synthetic/include-scope/fixture.json" ], "owner": "opy-rs#157", - "note": "Optimizer scope is represented in source state, but optimizer execution is outside the compiler baseline.", + "note": "Optimizer scope is represented in source state, but optimizer execution is outside the compiler contract.", "semanticEquivalent": false }, { diff --git a/tools/overpy/conformance.py b/tools/overpy/conformance.py index 7b5da13..cd01f9f 100644 --- a/tools/overpy/conformance.py +++ b/tools/overpy/conformance.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Run the independent, stage-aware offline OverPy conformance baseline.""" +"""Run the independent, stage-aware offline OverPy conformance evidence.""" from __future__ import annotations @@ -49,7 +49,7 @@ class ConformanceError(RuntimeError): - """A malformed baseline, fixture, or producer response.""" + """A malformed evidence inventory, fixture, or producer response.""" def load_json(path: Path) -> dict[str, Any]: diff --git a/tools/overpy/diff.py b/tools/overpy/diff.py index 3260c70..020e21b 100644 --- a/tools/overpy/diff.py +++ b/tools/overpy/diff.py @@ -627,7 +627,7 @@ def compare_compiler_fixture( stage( "compiler-contract", "accepted-gap", - reason="compiler parity is outside the declared baseline", + reason="compiler parity is outside the declared compiler contract", evidence=expectation["evidence"], ) )