<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-26-1-contract-pinning-resolved-version/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-26-1-contract-pinning-resolved-version/</id>
  <title>ADR: Contract Pinning to the Resolved Package Version</title>
  <updated>2026-04-26T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-26-1-contract-pinning-resolved-version/"/>
  <summary>Contract tests must resolve external package versions from the lockfile at runtime instead of embedding literals, with envelope snapshots keyed by that version.</summary>
  <content type="html">&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_cross_repo_consumers.py&lt;/code&gt;&lt;/p&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;After the shared-package-boundary cutover
(&lt;code dir=&quot;auto&quot;&gt;shared-package-boundary-cutover-01KQ22DS&lt;/code&gt;, 2026-04-25),
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; are external PyPI
dependencies consumed via their public surfaces. Compatibility ranges
live in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;; exact pins live in &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;. Contract tests
under &lt;code dir=&quot;auto&quot;&gt;tests/contract/&lt;/code&gt; are the load-bearing assertions that protect the
CLI from upstream-shape regressions.&lt;/p&gt;
&lt;p&gt;Prior to this ADR, a key contract test
(&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_cross_repo_consumers.py&lt;/code&gt;) hard-coded the expected
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; version as &lt;code dir=&quot;auto&quot;&gt;&quot;3.2.0&quot;&lt;/code&gt;. When the cutover bumped the
package to 4.0.0, that test went red and stayed red — visible to the
WP04 reviewer of mission
&lt;code dir=&quot;auto&quot;&gt;stability-and-hygiene-hardening-2026-04-01KQ4ARB&lt;/code&gt; as the canonical
example of contract-test drift behind real package state. A hard-coded
version string in a contract test is structurally guaranteed to drift
the moment &lt;code dir=&quot;auto&quot;&gt;uv sync&lt;/code&gt; resolves a different version. Since the goal of
&lt;code dir=&quot;auto&quot;&gt;tests/contract/&lt;/code&gt; (per FR-023) is to be a hard mission-review gate,
that pattern silently inverts: instead of catching drift it produces
drift.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Every contract test that depends on a specific external-package version
MUST resolve that version dynamically, rather than embedding it as a
literal. The canonical resolution path is:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Read &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; via &lt;code dir=&quot;auto&quot;&gt;tomllib&lt;/code&gt; and look up the package in the
&lt;code dir=&quot;auto&quot;&gt;[[package]]&lt;/code&gt; array.&lt;/li&gt;
&lt;li&gt;If &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; is unavailable (e.g. clean-install CI run), fall back
to &lt;code dir=&quot;auto&quot;&gt;importlib.metadata.version(&quot;&amp;#x3C;package-name&gt;&quot;)&lt;/code&gt; and emit a
&lt;code dir=&quot;auto&quot;&gt;RuntimeWarning&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;For envelope-shape pinning we add a snapshot file at
&lt;code dir=&quot;auto&quot;&gt;tests/contract/snapshots/spec-kitty-events-&amp;#x3C;resolved-version&gt;.json&lt;/code&gt;
generated by &lt;code dir=&quot;auto&quot;&gt;scripts/snapshot_events_envelope.py&lt;/code&gt;. The contract test
loads the snapshot keyed by the resolved version. Bumping the package
without regenerating the snapshot is, by design, a hard contract
failure with a structured diagnostic that points at the snapshot
script.&lt;/p&gt;
&lt;p&gt;This pattern is owned by WP05 of mission
&lt;code dir=&quot;auto&quot;&gt;stability-and-hygiene-hardening-2026-04-01KQ4ARB&lt;/code&gt; (see
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/contracts/events-envelope.md&lt;/code&gt;
and the WP05 task file).&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Drift becomes loud, not silent.&lt;/strong&gt; A bump to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;
without a paired snapshot regeneration fails the contract gate
(FR-022 + FR-023) immediately, instead of leaving the test pinned to
a stale version forever.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Two-step bump workflow is explicit.&lt;/strong&gt; Operators run
&lt;code dir=&quot;auto&quot;&gt;uv sync&lt;/code&gt; (or edit the version range), then
&lt;code dir=&quot;auto&quot;&gt;python scripts/snapshot_events_envelope.py --force&lt;/code&gt;, then &lt;code dir=&quot;auto&quot;&gt;pytest tests/contract/&lt;/code&gt;. This is documented in
&lt;code dir=&quot;auto&quot;&gt;docs/development/contract-pinning.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The mission-review gate has teeth.&lt;/strong&gt; FR-023 declares
&lt;code dir=&quot;auto&quot;&gt;pytest tests/contract/&lt;/code&gt; a hard blocker; by removing hard-coded
versions we eliminate the failure mode where the gate is “always
red” and therefore ignored.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative--costs&quot;&gt;Negative / costs&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Contributors must run the snapshot script after a package bump;
forgetting to do so produces an obvious red test, but adds a
friction step.&lt;/li&gt;
&lt;li&gt;Snapshot files accumulate one-per-version. They are small JSON files
under &lt;code dir=&quot;auto&quot;&gt;tests/contract/snapshots/&lt;/code&gt;, intentionally version-controlled
to anchor regressions historically.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;operationally&quot;&gt;Operationally&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Bumping &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; is a 2-step PR:
&lt;ol&gt;
&lt;li&gt;Edit &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; range and run &lt;code dir=&quot;auto&quot;&gt;uv lock&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Run &lt;code dir=&quot;auto&quot;&gt;python scripts/snapshot_events_envelope.py --force&lt;/code&gt; and
commit the new snapshot.&lt;/li&gt;
&lt;/ol&gt;
&lt;/li&gt;
&lt;li&gt;The dev workflow is documented in
&lt;a href=&quot;/development/how-to/contract-pinning/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/development/contract-pinning.md&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;h3 id=&quot;alternative-a--hard-coded-version-literals-in-contract-tests&quot;&gt;Alternative A — Hard-coded version literals in contract tests&lt;/h3&gt;
&lt;p&gt;This is the pre-2026-04-26 status quo. Rejected because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It guarantees drift the moment &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; changes, with no signal at
the bump site.&lt;/li&gt;
&lt;li&gt;It conflicts directly with FR-023 (hard mission-review gate): a
permanently red contract test makes the gate informational, not
blocking.&lt;/li&gt;
&lt;li&gt;The WP04 reviewer of this mission flagged it as the load-bearing
example of why the contract surface needs resolved-version pinning.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;alternative-b--pin-contract-tests-to-pyprojecttoml-ranges-eg-405&quot;&gt;Alternative B — Pin contract tests to &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; ranges (e.g. ”&gt;=4.0,&amp;#x3C;5”)&lt;/h3&gt;
&lt;p&gt;Rejected because compatibility ranges describe what the CLI is &lt;em&gt;allowed&lt;/em&gt;
to install, not what it &lt;em&gt;did&lt;/em&gt; install. A range-only contract test
cannot distinguish 4.0.0 from 4.7.3 envelopes; the snapshot would have
to be a union of all possible shapes within the range, which is the
opposite of what a contract test should pin.&lt;/p&gt;
&lt;h3 id=&quot;alternative-c--generate-the-snapshot-at-test-time&quot;&gt;Alternative C — Generate the snapshot at test time&lt;/h3&gt;
&lt;p&gt;Rejected because the snapshot would then trivially match itself; there
would be no shipped artifact to compare against. The whole point of
the snapshot is that it is a reviewed, version-controlled representation
of the upstream contract at a known point in time.&lt;/p&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/spec.md&lt;/code&gt;
(FR-022, FR-023, FR-024, FR-025, FR-026)&lt;/li&gt;
&lt;li&gt;Research: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/research.md&lt;/code&gt; D8&lt;/li&gt;
&lt;li&gt;Contract: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/contracts/events-envelope.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Companion ADR: &lt;code dir=&quot;auto&quot;&gt;architecture/2.x/adr/2026-04-25-1-shared-package-boundary.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Dev workflow: &lt;code dir=&quot;auto&quot;&gt;docs/development/contract-pinning.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Implementation:
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;scripts/snapshot_events_envelope.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_events_envelope_matches_resolved_version.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_cross_repo_consumers.py&lt;/code&gt; (rewritten as part of WP05)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/contract/snapshots/spec-kitty-events-&amp;#x3C;version&gt;.json&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
