Document the Passage compatibility boundary

[pzfreo]

Outcome

Closes #1339 by making the already-deployed Passage declaration and the future F4b compatibility boundary independently reviewable and executable.

Current main is ahead of the stale premise that triggered #1339:

• PR Upgrade b123d-recognisers 0.2.4 → 0.2.6 (#1244) #1248 already moved the exact dependency and lockfile to b123d-recognisers==0.2.6 and added the exhaustive passages declaration.
• PR chore: pin b123d-recognisers 0.3.1 #1293 subsequently moved the exact dependency and lockfile together to the reviewed released 0.3.1 package.
• The installed 0.3.1 manifest truthfully reports passages introduced in 0.2.6, and pending_family_declarations() is already empty.

This PR therefore does not manufacture another dependency bump. It:

• documents the current schema-v1 Passage family as a truthful unsupported Draftwright disposition tracked by Decide what a recognised Passage means to draftwright (new family in b123d-recognisers 0.2.6) #1245;
• freezes the reviewed released interval >=0.2.6,<0.4.0 as the adoption boundary;
• records the future 0.4 compatibility-facade paper model without implementing it early;
• pins the installed manifest/declaration join, all unsupported semantic boundaries, deferred completeness, tracking issue, and absence from pending declarations in an executable test;
• retains the ordinary fail-closed validator with no forward declaration or stale-manifest exception.

The later 0.4 adoption remains a separate coordinated PR updating the adapter/declaration model, validator, tests, exact pin and lockfile together after b123d-recognisers#184 and Draftwright #1337 are accepted and implemented.

Validation

• uv run pytest -q tests/test_recogniser_capabilities.py tests/test_recogniser_adoption.py tests/test_external_recognition_boundary.py — 83 passed
• uv run ruff check tests/test_recogniser_capabilities.py
• git diff --check

[pzfreo]

Reviewed against the round-4 baseline (the live #184/#1339 texts vs actual main). The framing is right and honestly stated: the PR correctly acknowledges that #1248/#1293 already did the pin move and truthful declaration, doesn't manufacture another bump, and separates the deployed state from the future 0.4 migration. I ran the new test plus the adoption suite on the head — passes. The five-bullet paper model faithfully compresses the #184 facade clauses. Three findings, one substantive:

The main one: the PR body claims to freeze the >=0.2.6,<0.4.0 interval "in an executable test", but only the point version is executable — the interval, and especially its load-bearing upper bound, lives in prose (inline comment). Plus one omission in the paper model (the slot→passage disposition flip and its #1245 gate) and one unpinned boundary (documentation).

[pzfreo]

The adoption interval is not actually executable — only the point version is. The PR body says it "freezes the reviewed released interval >=0.2.6,<0.4.0 as the adoption boundary" and "pins … in an executable test", but this asserts == "0.3.1". The exact-literal ratchet is fine as a both-sides-changed-together convention (like the 25-family literal above), but the upper bound — the part the doc says "prevents accidental adoption of the planned 0.4 compatibility change" — has no executable form: when someone bumps the pin and dutifully updates this literal to "0.4.0", nothing fails and nothing routes them to the F4b gate. Add an interval assertion alongside the literal, e.g. parse INSTALLED_PACKAGE_VERSION and assert (0, 2, 6) <= v < (0, 4, 0) with a comment naming b123d-recognisers#184 / #1337 as the gate that must be ACCEPTed before the upper bound moves.

[pzfreo]

The paper model omits the one consumer-visible consequence of the 0.4 migration, and the crossing condition doesn't mention #1245. Under the revised #184, a principal split-junction void whose walls contain a Slot group flips ownership at 0.4: today the legacy finder never sees it, so the Slot is the accepted, counted, rendered claim (slots is fully supported); post-0.4 the rich passage wins (SLOT_SUPERSEDED_BY_PASSAGE) and the claim moves to a family this page declares Draftwright does not draw. As specified, crossing 0.4 would silently replace a rendered slot callout with nothing. Since this section is the consumer-side boundary statement, it should say so: add a bullet that adoption changes which family claims Slot-superseding split-junction voids, and condition the pin crossing 0.4 not only on the capability-contract representation but on #1245 resolving what a passage draws (or an explicit decision to accept the callout loss).

[pzfreo]

Minor: the unsupported lowering emits a sixth boundary this test doesn't pin — documentation: {"state": "supported", "evidence": ["docs/reference/recogniser-capabilities.md"]} — and this PR is precisely that evidence. Worth one more assertion (passage_consumer["documentation"]["state"] == "supported" plus the evidence path) so the boundary set checked here is exhaustive rather than four-of-six, and so deleting the new doc section can't leave the declaration claiming evidence that no longer exists.

[pzfreo]

Addressed all three review findings at exact 719a6c02:

• the released adoption interval is now executable alongside the exact 0.3.1 ratchet: (0, 2, 6) <= installed < (0, 4, 0), explicitly gated on b123d-recognisers#184 and Draftwright Review F4b SectionPassage public schema and 0.4.0 authority transition #1337/Decide what a recognised Passage means to draftwright (new family in b123d-recognisers 0.2.6) #1245;
• the paper model now records the consumer-visible SLOT_SUPERSEDED_BY_PASSAGE ownership/rendering transition and requires Decide what a recognised Passage means to draftwright (new family in b123d-recognisers 0.2.6) #1245 resolution or an explicit reviewed callout-loss decision before crossing 0.4;
• the test pins the supported documentation boundary and exact evidence path as well as all four unsupported semantic stages and deferred completeness.

Re-run: 83 focused tests pass; Ruff and diff-check clean. CI restarted on the new head.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.57%. Comparing base (062d152) to head (719a6c0).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1341      +/-   ##
==========================================
- Coverage   93.59%   93.57%   -0.03%     
==========================================
  Files          61       62       +1     
  Lines       20803    21262     +459     
  Branches     3972     4080     +108     
==========================================
+ Hits        19470    19895     +425     
- Misses        774      790      +16     
- Partials      559      577      +18     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.