From 98bd7c0f75590b0b50cf0ae21bb1c8aa963f143b Mon Sep 17 00:00:00 2001 From: Teakowa Date: Sun, 6 Sep 2026 13:59:04 +0800 Subject: [PATCH] docs(opy): remove stale support-contract residue Fixes #201 --- AGENTS.md | 2 +- README.md | 22 +--- docs/README.md | 8 +- docs/compatibility/upstream-references.md | 7 +- docs/opy/architecture.md | 12 +- docs/opy/compatibility-baseline.md | 144 ---------------------- docs/opy/conformance-baseline.md | 11 +- docs/opy/implementation-role.md | 11 +- docs/opy/support-matrix.md | 5 - docs/opy/tooling-api.md | 5 +- tools/overpy/README.md | 19 +-- tools/overpy/compiler-expectations.json | 4 +- 12 files changed, 44 insertions(+), 206 deletions(-) delete mode 100644 docs/opy/compatibility-baseline.md delete mode 100644 docs/opy/support-matrix.md diff --git a/AGENTS.md b/AGENTS.md index fd4f879..a54ab3b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,7 +81,7 @@ source provenance, or compatibility correctness. 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 49f04e8..8de3ff2 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 7969579..5cdc490 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,7 +12,7 @@ architecture, compatibility evidence, APIs, and internal contracts live here. - [Architecture](opy/architecture.md): source parsing, semantic HIR, compiler/reconstruction boundaries, and dependency direction. - [Tooling API](opy/tooling-api.md): Rust library and CLI contracts for checking, - inspection, overlays, diagnostics, and support queries. + inspection, overlays, and diagnostics. - [LPP provider](opy/provider.md): first-party provider capabilities, entry-based project loading, artifact boundary, and release archive contract. - [Source-edit policy](opy/trivia-retention-policy.md): provenance and trivia @@ -22,10 +22,8 @@ architecture, compatibility evidence, APIs, and internal contracts live here. - [OverPy support contract](language-support.md): audited, human-readable OverPy feature coverage. -- [Compatibility baseline](opy/compatibility-baseline.md): planning/reference - inventory for remaining OverPy surface and compatibility priorities. -- [Offline conformance baseline](opy/conformance-baseline.md): independent - oracle, failure-frontier, and canonical-WIR comparison contract. +- [Offline conformance evidence](opy/conformance-baseline.md): oracle, + failure-frontier, and canonical-WIR comparison contract. - [Upstream references](compatibility/upstream-references.md): pinned reference identity, provenance, licensing notes, and oracle boundaries. - [OverPy evidence harness](../tools/overpy/README.md): oracle tooling, 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 926f063..9a14d8e 100644 --- a/docs/opy/architecture.md +++ b/docs/opy/architecture.md @@ -78,7 +78,7 @@ request through the compiler backend. - Opy HIR and OverPy-specific semantic identities; - OverPy-specific compiler/lowering behavior; - supported backend-affecting directives and post-compile-hook behavior; -- standalone `check`, `inspect`, support, compiler, and future reconstruction +- standalone `check`, `inspect`, compiler, and future reconstruction APIs/CLI surfaces; - OPY compatibility evidence and Workshopβ†’OPY reconstruction. @@ -158,16 +158,16 @@ reconstruction. - **Observable semantic compatibility, not output identity.** Formatting, temporary variables, optimizer internals, and text shape are evidence only unless they affect a declared observable contract. -- **Corpus-defined support.** Current support is derived from fixtures, - real-project evidence, pinned reference observations, and the canonical - language-support inventories. +- **Canonical support contract.** Current support is defined by the canonical + language-support contract and its linked inventories; fixtures, real-project + evidence, and pinned reference observations provide the evidence. - **No WrightKit-only OPY dialect.** `opy-rs` follows the OverPy language rather than inventing source syntax for Wright convenience. - **Source-aware edits by default.** Tooling uses semantic identities, provenance, and authored source spans; whole-file regeneration is not the default mutation model. - **Explicit unsupported behavior.** Incomplete lowering or evidence gaps remain - diagnostics/support states rather than guessed semantics. + diagnostics or explicit evidence states rather than guessed semantics. ## Provider integration @@ -181,7 +181,7 @@ of `opy-rs`, and standalone library/CLI users do not need Wright. The Workshop-independent semantic/tooling foundation and bounded OPYβ†’Workshop compiler surface are implemented and corpus-backed. The reconstruction module is owned here, while broader Workshopβ†’OPY coverage remains explicit in the -compatibility corpus report. +compatibility evidence reports. Do not infer a stronger claim from this document; use the canonical language-support contract and current executable evidence. 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..c3f49dd 100644 --- a/docs/opy/conformance-baseline.md +++ b/docs/opy/conformance-baseline.md @@ -5,14 +5,15 @@ 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 support-status source. 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 support status in `opy-rs`. ## Comparison contract diff --git a/docs/opy/implementation-role.md b/docs/opy/implementation-role.md index 4baa2f7..d60e166 100644 --- a/docs/opy/implementation-role.md +++ b/docs/opy/implementation-role.md @@ -67,10 +67,11 @@ The dependency direction is `opy-rs β†’ workshop-rs`; there is no dependency fro ## Current reality -The repository exposes standalone check/inspect/support tooling and a bounded -versioned OPY β†’ Workshop compile surface. Broader corpus gaps remain explicit, -and Workshop β†’ OPY reconstruction is not yet implemented. These are +The repository exposes standalone check/inspect tooling and a bounded versioned +OPY β†’ Workshop compile surface. Broader corpus gaps remain explicit, and +Workshop β†’ OPY reconstruction is not yet implemented. These are implementation-completeness gaps, not reasons to narrow `opy-rs` to one compiler stage. -Support claims must continue to follow the compatibility matrix and executable -evidence rather than this architectural intent alone. +Support claims belong to the canonical language-support contract and its linked +inventories. The evidence harness and executable tests substantiate those +claims; this document describes ownership rather than current feature status. 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..8f5b17d 100644 --- a/docs/opy/tooling-api.md +++ b/docs/opy/tooling-api.md @@ -161,8 +161,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 +178,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..69c2089 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 @@ -241,12 +241,13 @@ Use `--allow-inconclusive` only for local contract checks. ## Offline conformance baseline (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 support status. Reference failures carry an audited stage and first-construct frontier tied to text in their pinned oracle snapshot. diff --git a/tools/overpy/compiler-expectations.json b/tools/overpy/compiler-expectations.json index 3a71666..734d33c 100644 --- a/tools/overpy/compiler-expectations.json +++ b/tools/overpy/compiler-expectations.json @@ -1,7 +1,7 @@ { "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.", "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.", @@ -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."