<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/how-to/contract-pinning/">
  <id>https://docs.spec-kitty.ai/development/how-to/contract-pinning/</id>
  <title>Contract pinning workflow (`spec-kitty-events`)</title>
  <updated>2026-09-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/how-to/contract-pinning/"/>
  <summary>The contract-pinning workflow for spec-kitty-events: how tests/contract pin a resolved package version, why it exists, and the ADR and mission authority behind it.</summary>
  <content type="html">&lt;h2 id=&quot;contract-pinning-workflow-spec-kitty-events&quot;&gt;Contract pinning workflow (&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;)&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Status&lt;/strong&gt;: stable (2026-04-26)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Authority&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-04-26-1-contract-pinning-resolved-version/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-04-26-1-contract-pinning-resolved-version.md&lt;/code&gt;&lt;/a&gt;
(DIRECTIVE_003)&lt;/li&gt;
&lt;li&gt;Mission &lt;code dir=&quot;auto&quot;&gt;stability-and-hygiene-hardening-2026-04-01KQ4ARB&lt;/code&gt;,
FR-022 / FR-023.&lt;/li&gt;
&lt;li&gt;Contract surface:
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/contracts/events-envelope.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/contracts/events-envelope.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;why-this-exists&quot;&gt;Why this exists&lt;/h2&gt;
&lt;p&gt;Contract tests under &lt;code dir=&quot;auto&quot;&gt;tests/contract/&lt;/code&gt; are the hard mission-review
gate (FR-023). They pin the upstream &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; envelope at
the &lt;em&gt;resolved&lt;/em&gt; version (&lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;), not at a literal hard-coded one.
Bumping &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; without regenerating the snapshot is, by
design, a hard contract failure with a clear diagnostic.&lt;/p&gt;
&lt;h2 id=&quot;the-two-step-bump-workflow&quot;&gt;The two-step bump workflow&lt;/h2&gt;
&lt;p&gt;When you need to bump &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Update the dependency.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Either edit the compatibility range in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;toml&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;[project]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;dependencies&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; = [&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# ...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;spec-kitty-events&gt;=X.Y.0,&amp;#x3C;X+1&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# choose the supported range; uv.lock records the exact version&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# ...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;…or just let &lt;code dir=&quot;auto&quot;&gt;uv&lt;/code&gt; pick a newer compatible version:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;lock&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--upgrade-package&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;spec-kitty-events&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;sync&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Regenerate the envelope snapshot.&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts/snapshot_events_envelope.py&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--force&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The script:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Resolves the version from &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; (falling back to
&lt;code dir=&quot;auto&quot;&gt;importlib.metadata&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Captures &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.Event.model_json_schema()&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Writes
&lt;code dir=&quot;auto&quot;&gt;tests/contract/snapshots/spec-kitty-events-&amp;#x3C;resolved-version&gt;.json&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Prints the resolved version it pinned, so you can sanity-check
against &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Verify the contract gate is green.&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;pytest&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tests/contract/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-q&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;This is the same one-liner the mission-review skill runs.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Commit both files together.&lt;/strong&gt;&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;safe-commit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--message&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;chore: bump spec-kitty-events to &amp;#x3C;version&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;pyproject.toml&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;uv.lock&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tests/contract/snapshots/spec-kitty-events-&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;*&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;If you skip step 2, the contract test
&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_events_envelope_matches_resolved_version.py&lt;/code&gt; will
fail with a structured message pointing at this doc and the snapshot
script. That is intentional.&lt;/p&gt;
&lt;h2 id=&quot;what-the-snapshot-script-does-and-does-not-do&quot;&gt;What the snapshot script does and does not do&lt;/h2&gt;
&lt;p&gt;The script (&lt;code dir=&quot;auto&quot;&gt;scripts/snapshot_events_envelope.py&lt;/code&gt;) is intentionally
small. It:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Does&lt;/strong&gt; resolve the version from &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; first, then
&lt;code dir=&quot;auto&quot;&gt;importlib.metadata&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Does&lt;/strong&gt; capture the full &lt;code dir=&quot;auto&quot;&gt;Event&lt;/code&gt; JSON schema, plus a sorted list of
field names and required-field names for ergonomic diffs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Does&lt;/strong&gt; print the resolved version it used.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Does not&lt;/strong&gt; overwrite an existing snapshot unless &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; is
passed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Does not&lt;/strong&gt; install &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;. Run &lt;code dir=&quot;auto&quot;&gt;uv sync&lt;/code&gt; first.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Useful flags:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Flag&lt;/th&gt;&lt;th&gt;Purpose&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--output-dir DIR&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Write the snapshot to a different directory (used by tests).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--repo-root DIR&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Override repo root (used to point at a different &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Overwrite an existing snapshot for the current version.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--print-version&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Print only the resolved version and exit (useful in CI scripts).&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;what-happens-when-you-forget-step-2&quot;&gt;What happens when you forget step 2&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;pytest tests/contract/&lt;/code&gt; will fail with one of:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Missing envelope snapshot for spec-kitty-events &amp;#x3C;version&gt;&lt;/code&gt; — you
resolved a new version but did not regenerate the snapshot. Run the
script with &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; and re-run the contract suite.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Envelope field drift detected&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;required-field drift&lt;/code&gt; — the live
envelope schema does not match the snapshot. Either the upstream
package made a real shape change (in which case investigate), or the
snapshot file is from a different version (regenerate).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.__version__ = &apos;...&apos; but uv.lock pins &apos;...&apos;&lt;/code&gt; —
installed version disagrees with &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;. Run &lt;code dir=&quot;auto&quot;&gt;uv sync&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Each diagnostic includes a pointer back to this doc.&lt;/p&gt;
&lt;h2 id=&quot;snapshot-lifetime&quot;&gt;Snapshot lifetime&lt;/h2&gt;
&lt;p&gt;Snapshot files are version-controlled and intentionally accumulate
one-per-bump. They are small (a few KB) and serve as historical
anchors for upstream-shape regression reviews. Do not delete old
snapshots when bumping; just add the new one.&lt;/p&gt;
&lt;h2 id=&quot;related&quot;&gt;Related&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/spec.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/stability-and-hygiene-hardening-2026-04-01KQ4ARB/spec.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Mission review gate (FR-023): &lt;code dir=&quot;auto&quot;&gt;tests/integration/test_mission_review_contract_gate.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Public-import freeze (FR-024): &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_events_tracker_public_imports.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Companion ADR (boundary cutover): &lt;a href=&quot;/adr/3.x/2026-04-25-1-shared-package-boundary/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-04-25-1-shared-package-boundary.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
