Plan the long-term retirement of the compatibility harness

[Teakowa]

Goal

Define how opy-rs should retire compatibility/ as a permanent repository subsystem once semantic convergence no longer depends on it, while preserving the long-term contracts and evidence that remain valuable.

Context

compatibility/ was created during the bootstrap/convergence phase to make an independent OverPy implementation measurable against a pinned upstream reference. It currently combines several distinct responsibilities: upstream/oracle investigation, support-state bookkeeping, synthetic and real-project corpus evidence, differential comparison, and regression protection.

That aggregation is useful while opy-rs is still discovering broad parser/semantic/lowering gaps, but it should not automatically become the target architecture. Compatibility remains a permanent correctness requirement; a dedicated compatibility subsystem does not.

Current corpus-convergence work such as #88 may continue using the existing harness while it provides discovery value. This issue is not a request to remove that evidence prematurely.

Scope

• Classify the current contents of compatibility/ by durable responsibility:
  • language/support contract;
  • focused regression protection;
  • conformance coverage;
  • real-project corpus/integration coverage;
  • upstream/oracle investigation;
  • temporary support/progress bookkeeping.
• Define the target owner/location for responsibilities that should survive the convergence phase, for example:
  • durable OverPy contracts -> support/spec documentation;
  • established source/semantic/compiler regressions -> focused native tests;
  • executable language conformance -> a bounded conformance suite derived from the audited language inventory;
  • real-project usability -> provenance-preserving project corpus/integration tests;
  • upstream behavior investigation/version rebaseline -> maintainer oracle tooling;
  • support/progress matrices and issue-state bookkeeping -> remove rather than relocate unless a concrete stable consumer contract exists.
• Define a graduation path for compatibility discoveries: independent upstream/oracle evidence establishes a semantic contract, implementation lands, then the stable invariant is protected by the smallest appropriate owner-side regression/conformance test rather than requiring permanent differential execution for the same case.
• Define exit/readiness criteria for decomposing or deleting compatibility/ as a top-level subsystem.
• Identify any current public API/CLI/CI contract that unintentionally depends on compatibility bookkeeping and decide whether it is genuinely durable before migration.

Non-goals

• Do not remove or weaken Complete OverPy source-language compatibility within 10 implementation PRs #88 corpus/oracle evidence while it is still exposing unresolved root capabilities.
• Do not delete independently valuable real-project provenance or minimized regressions merely to simplify the tree.
• Do not replace external correctness evidence with self-referential implementation snapshots.
• Do not change OverPy semantics, compatibility targets, or canonical Workshop ownership.
• Do not require a single large migration PR; implementation work should be split only after the target responsibilities and exit criteria are agreed.

Acceptance criteria

• A reviewed target model states which compatibility responsibilities are permanent and which are convergence-only.
• The target model does not require compatibility/ to remain a permanent architecture concept solely because current CI or tooling uses it.
• Each durable responsibility has one clear owner/location and does not create a second support/status source of truth.
• Established regressions can graduate from oracle/differential discovery into focused native regression or conformance tests with retained provenance where materially useful.
• Upstream/oracle execution can remain available for unknown behavior, upstream-version review, or explicit rebaseline work without being required as the normal proof for every already-established contract.
• Real-project corpus coverage remains available as workflow/integration evidence and is not treated as a compatibility percentage or language-surface definition.
• Explicit exit criteria are documented for when the top-level compatibility/ subsystem can be decomposed or removed.

Relationships

• Build an independent OverPy-compatible engine with canonical Workshop integration #1 — independent OverPy-compatible engine goal and compatibility policy.
• Audit the complete OverPy surface and establish the authoritative support matrix #57 — audited OverPy support contract and separation of public status from engineering evidence.
• Complete OverPy source-language compatibility within 10 implementation PRs #88 — current residual corpus convergence; expected to continue using the existing harness until its discovery value materially declines.