<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-11-6-pypi-exact-pinning-for-spec-kitty-events/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-11-6-pypi-exact-pinning-for-spec-kitty-events/</id>
  <title>PyPI Exact Pinning for `spec-kitty-events` Across Consumer Repos</title>
  <updated>2026-02-11T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-11-6-pypi-exact-pinning-for-spec-kitty-events/"/>
  <summary>Forces the CLI and the hosted backend onto the same exact published version of the events contract, banning git refs and committed path overrides that caused drift.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; is the canonical contract authority for event envelope fields and reducer semantics used by both:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; (CLI)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt; (server projections)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Before this decision, consumers used mixed sourcing strategies:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;direct git commit references in one repo&lt;/li&gt;
&lt;li&gt;local path overrides in committed config in another repo&lt;/li&gt;
&lt;li&gt;non-normalized pre-release version strings&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This created a high risk of semantic drift between development, CI, and production and made cross-repo replay/projection parity less reliable.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Determinism:&lt;/strong&gt; identical reducer and schema behavior across all environments&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Contract integrity:&lt;/strong&gt; no implicit local-path overrides in committed config&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reproducibility:&lt;/strong&gt; exact dependency versions, not floating refs&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Open-source usability:&lt;/strong&gt; consumers can install from public package index&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Diligence readiness:&lt;/strong&gt; clear release artifacts and upgrade history&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; PyPI exact pins (&lt;code dir=&quot;auto&quot;&gt;==&lt;/code&gt;) in all consumer repos (chosen)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Git SHA direct references in all consumer repos&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Local path overrides for active development&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Version ranges (&lt;code dir=&quot;auto&quot;&gt;&gt;=&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;~=&lt;/code&gt;) with lockfile mediation&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; PyPI exact pinning with strict consumer parity.&lt;/p&gt;
&lt;h3 id=&quot;policy&quot;&gt;Policy&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; publishes contract releases to PyPI.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt; pin &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; with exact &lt;code dir=&quot;auto&quot;&gt;==&lt;/code&gt; versions.&lt;/li&gt;
&lt;li&gt;Committed dependency sources must not use local path overrides for &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Upgrades happen only through coordinated contract-bump changes across consumer repos.&lt;/li&gt;
&lt;li&gt;Local developer overrides are permitted only in uncommitted/local-only configuration.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;initial-implementation&quot;&gt;Initial implementation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; dependency pin set to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events==0.4.0a0&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt; dependency pin set to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events==0.4.0a0&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;committed path source override for &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; removed from &lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&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;Eliminates committed local-path drift between repos.&lt;/li&gt;
&lt;li&gt;Aligns CLI and SaaS to the same contract artifact from PyPI.&lt;/li&gt;
&lt;li&gt;Makes upgrades auditable and reproducible.&lt;/li&gt;
&lt;li&gt;Improves external contributor and deployment consistency.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Requires explicit release cadence in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Slows ad-hoc cross-repo changes if release process is bypassed.&lt;/li&gt;
&lt;li&gt;Requires CI policy checks to enforce parity and prevent regressions.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Local co-development remains possible through local-only overrides, but these are no longer valid committed defaults.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;confirmation-and-enforcement&quot;&gt;Confirmation and Enforcement&lt;/h2&gt;
&lt;p&gt;The decision is considered effective when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;both consumer repos pin exact same &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; version&lt;/li&gt;
&lt;li&gt;no committed local-path source override for &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; exists&lt;/li&gt;
&lt;li&gt;CI includes a contract alignment check that fails on version mismatch&lt;/li&gt;
&lt;li&gt;contract upgrades follow a documented contract-bump PR flow&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;rollout-notes&quot;&gt;Rollout Notes&lt;/h2&gt;
&lt;p&gt;Recommended follow-up controls:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Add CI checks in both consumers to assert exact version parity.&lt;/li&gt;
&lt;li&gt;Add CI checks rejecting committed local/path/git source overrides for &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Add a reusable “contract bump” PR template for synchronized version updates.&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
