Versioned Shared Interfaces

1. Owned problem

Having v1 and v2 does not by itself protect consumers from interface breakage. The real question is what exact public surface each version names, what changed, which consumers are affected, and whether migration and rollback are proven. ARC-002 owns that shared-interface contract; Venture Separation in ARC-001 and Resource Broker Metadata in ARC-003 remain separate outcomes.

2. Deliverable

Build Shared Interface Version & Compatibility Contract v1. For each interface/consumer, record Version, Public Surface Hash, Change Set, Producer Owner, Compatibility, Breaking Flag, Deprecation State, Support Window, Migration Target/Evidence, Contract Test, Rollback, Adoption, Exception, Timestamp, and Provenance.

3. Mental model: surface → change → compatibility → consumers

Use this order: public surface → change set → compatibility classification → required version class → consumer inventory → tests/migration → deprecation/rollback → bounded decision. The version number is not the first decision; it follows classification. If the public surface is unknown, a version label cannot repair the missing evidence.

4. What SemVer says—and what it does not

Semantic Versioning requires a declared public API; incompatible changes map to a major version, backward-compatible functionality to a minor version, and backward-compatible bug fixes to a patch version. A released version must not be silently changed. SemVer does not prove that your consumer was tested, migrated, or can roll back; those are separate evidence obligations.

5. Bind version to an exact surface

A contract_version without a public_surface_hash is ambiguous. If a required field, type, default behavior, or error contract changes, the change set must identify that surface. Treat the released version as immutable; publish a new version for a new surface rather than rewriting the old version in place.

6. Classify compatibility before choosing the version

First ask whether the change is backward compatible or breaking. Adding an optional field can be compatible; renaming a required field or changing semantic defaults can break an old consumer. If the change is breaking and the major version did not change, the state is REJECT. Release notes cannot override this gate.

7. Consumer inventory is part of the contract

A shared interface has real consumers. Track each consumer's owner, payload/client version, migration target, contract-test result, and adoption state separately. Producer deployment does not equal consumer migration. A consumer still sending the old payload remains part of the decision even when most consumers have moved.

8. Worked baseline: v2 with one consumer still on v1

The producer moves from 1.4.2 to 2.0.0 because a required-field rename is breaking. Venture A and B pass v2 contract tests and have migration evidence. Venture C remains on v1 in an embedded workflow; v1 has a named support end date and owner, and rollback to 1.4.2 exists. The result is MIGRATION_REQUIRED, not failure and not “everything is compatible.”

9. Forbidden shortcut: breaking change under the same version

If customer_id becomes profile_id while the producer still claims 1.4.2, the public surface changed without the required version change. This mutation is REJECT. Do not mutate a released version in place; issue a new version.

10. MIGRATED without a contract test is unproven

Adoption is not a manual label. A consumer is MIGRATED only when migration evidence and a current contract test for the target version exist and pass. If the team flips the flag but never replays the contract tests, the decision becomes HOLD until evidence is repaired.

11. Deprecation windows need ownership

Keeping an old version can be correct, but an unlimited or ownerless support window creates hidden debt. support_window_end, deprecation_owner, and review evidence must be explicit. Extending the date without owner/authority produces HOLD; silent extension is not a compatibility strategy.

12. Venture-specific forks need convergence

If one venture receives a private interface fork with no explicit convergence plan, the system has effectively broken the shared contract. This lesson returns REJECT. A temporary exception is defensible only with owner, expiry, and a convergence path.

13. Transfer: a migrated consumer sends an old payload again

In the transfer case, a delayed worker for a consumer previously marked MIGRATED sends a v1 payload again. Recompute adoption. The state can return to MIGRATION_REQUIRED, forcing a bounded choice among continued old-version support, a compatibility adapter, or producer rollback. The baseline verdict is not reusable because the evidence changed.

14. Lab execution

Open lab/ARC-002-LAB1/learner/ and run python run_checks.py offline. Eight fixtures cover baseline, a breaking change without a major bump, migration without contract tests, ownerless deprecation, a venture fork, stale evidence, a missing surface hash, and a delayed-old-payload transfer. Do not memorize verdicts; explain the first controlling gate.

15. Assessment, freshness, and claim boundary

Assessment covers boundary retrieval, baseline contract construction, diagnosis of the breaking-change shortcut, and transfer. SemVer bounds FACT semantics for public APIs, version increments, and released-version immutability. Consumer inventory, migration evidence, deprecation governance, rollback, and typed states remain MAKNOW DESIGN. Any canonical change to an accepted package requires a new package version.