test(engine): classify every Engine method in the contract-case registry

[Kiran01bm]

Restructures the engine contract suite around a case registry with a completeness test, so every engine.Engine method is either pinned by a contract case or carries a documented exclusion.

Why

The enginetest suite hand-enumerated its subtests, so nothing connected the suite to the engine.Engine interface: a new engine method could land with no conformance decision, and a new Harness fixture could sit unconsumed without any test noticing. The storage conformance suite already solved this with a registry plus a reflection-driven completeness test; this applies the same treatment to the engine layer.

What

• contractCases registry in pkg/engine/enginetest: each case names its Harness fixture field, the engine.Engine methods whose cross-engine contract it pins, and its run function. Run iterates the registry.
• engineMethodExclusions: documented reasons for the methods the suite deliberately does not pin (engine-specific behavior each engine's own tests cover).
• TestContractCaseCoverage (DB-free): registry rows are unique; every claimed fixture field exists, is a function, and is claimed exactly once; each case runs the function named for it; every engine.Engine method is pinned or excluded (both at once fails); exclusions have non-empty reasons and match real methods; no Harness fixture goes unconsumed.

Verified non-vacuous by mutation: excluding a pinned method, adding a stale exclusion, dropping an exclusion, deleting a registry row, and wiring the wrong run function each fail the test.

Before / after

Before:
  Run(t, h) ── hand-enumerated t.Run blocks
  engine.Engine method added ──▶ suite silently ignores it
  Harness fixture added       ──▶ nothing checks it is consumed

After:
  Run(t, h) ── iterates contractCases registry
                    │
                    ▼
  TestContractCaseCoverage (no DB)
    ├─ every Engine method: pinned by a case OR documented exclusion
    ├─ every Harness fixture: claimed by exactly one case
    └─ every case: runs the function named for it
  engine.Engine method added ──▶ test fails until classified

[Copilot]

🟢 Approval recommended

The refactor is localized to test infrastructure and the only noted issue is a minor robustness improvement (avoiding a potential nil-function panic in a completeness test).

Pull request overview

Refactors the pkg/engine/enginetest contract suite to use a registry-driven structure with DB-free completeness tests, ensuring every engine.Engine method and every Harness fixture is explicitly classified (pinned by a case or documented as excluded).

Changes:

• Introduces a contractCases registry tying each contract Case to exactly one Harness fixture field, its pinned engine.Engine methods, and a dedicated runner function.
• Adds engineMethodExclusions plus coverage tests that enforce: no unclaimed Harness fixtures, no unclassified Engine methods, and no stale exclusions.
• Updates engine documentation to point readers to pkg/engine/enginetest as the conformance decision source.

File summaries

File	Description
pkg/engine/README.md	Documents that pkg/engine/enginetest classifies/pins the conformance decision for each engine.Engine method.
pkg/engine/enginetest/enginetest.go	Replaces hand-enumerated subtests with a contractCases registry and adds method-exclusion documentation.
pkg/engine/enginetest/enginetest_test.go	Adds DB-free completeness tests for registry uniqueness, Harness fixture consumption, Engine method classification, and run-function execution fidelity.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Kiran01bm]

Duplicate of #1211, which already merged this branch as 95f53b1.