<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/migrations/shared-package-boundary-cutover/">
  <id>https://docs.spec-kitty.ai/migrations/shared-package-boundary-cutover/</id>
  <title>Migration: Shared Package Boundary Cutover</title>
  <updated>2026-06-03T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/migrations/shared-package-boundary-cutover/"/>
  <summary>Migration for the shared-package-boundary cutover (mission 01KQ22DS, released in 3.2.0): how vendored copies were removed in favor of the external PyPI packages.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Migration note: This page documents a migration path or historical transition. It is not the current 3.2 happy path.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;span id=&quot;migration-shared-package-boundary-cutover&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Mission&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;shared-package-boundary-cutover-01KQ22DS&lt;/code&gt;
&lt;strong&gt;Released&lt;/strong&gt;: spec-kitty-cli 3.2.0
&lt;strong&gt;Audience&lt;/strong&gt;: operators upgrading &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; from a pre-cutover version.&lt;/p&gt;
&lt;h2 id=&quot;what-changed&quot;&gt;What changed&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; no longer depends on the &lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; PyPI package.
The runtime now lives inside &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; under
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/next/_internal_runtime/&lt;/code&gt;. Events and tracker remain
external PyPI dependencies, but the vendored events copy at
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/spec_kitty_events/&lt;/code&gt; was removed.&lt;/p&gt;
&lt;p&gt;Concretely, after this release:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; is the only package you need to install. Prefer
&lt;code dir=&quot;auto&quot;&gt;pipx install spec-kitty-cli&lt;/code&gt; for the CLI; &lt;code dir=&quot;auto&quot;&gt;python -m pip install spec-kitty-cli&lt;/code&gt; remains supported inside a virtual environment or another
intentionally managed Python environment.&lt;/li&gt;
&lt;li&gt;&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 pulled in transitively
with current 3.2 compatibility ranges (&lt;code dir=&quot;auto&quot;&gt;&gt;=5.2.0,&amp;#x3C;6.0.0&lt;/code&gt; for events and the tracker range declared by the release,
respectively); exact versions live in &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; is not installed and is not referenced.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;action-required&quot;&gt;Action required&lt;/h2&gt;
&lt;p&gt;For most operators: nothing. Re-run
&lt;code dir=&quot;auto&quot;&gt;pipx upgrade spec-kitty-cli&lt;/code&gt; (or the equivalent upgrade command for your
installer, such as &lt;code dir=&quot;auto&quot;&gt;uv tool upgrade spec-kitty-cli&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;python -m pip install --upgrade spec-kitty-cli&lt;/code&gt; inside a virtual environment) and the new release
works without &lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt;. The retired package may remain installed in
your environment from a previous release; it is harmless and unused.&lt;/p&gt;
&lt;h2 id=&quot;optional-cleanup&quot;&gt;Optional cleanup&lt;/h2&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;pip&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;uninstall&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-runtime&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, if you used &lt;code dir=&quot;auto&quot;&gt;uv&lt;/code&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;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;pip&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;uninstall&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-runtime&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;If your environment was set up with a pre-cutover &lt;code dir=&quot;auto&quot;&gt;constraints.txt&lt;/code&gt;
override (&lt;code dir=&quot;auto&quot;&gt;pip install -e &quot;.[dev]&quot; -c constraints.txt&lt;/code&gt;), drop the
&lt;code dir=&quot;auto&quot;&gt;-c constraints.txt&lt;/code&gt; flag — the file no longer exists in the repo.&lt;/p&gt;
&lt;h2 id=&quot;verification&quot;&gt;Verification&lt;/h2&gt;
&lt;p&gt;After upgrading, confirm the cutover landed cleanly:&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:#919F9F;--1:#5F636F&quot;&gt;# 1. Confirm spec-kitty-runtime is not a dep:&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;pip&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;show&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-runtime&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:#919F9F;--1:#5F636F&quot;&gt;# Expected: &quot;WARNING: Package(s) not found: spec-kitty-runtime&quot;&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;/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:#919F9F;--1:#5F636F&quot;&gt;# 2. Confirm the CLI loads without spec-kitty-runtime in sys.modules:&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;python&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;-c&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;/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:#ECC48D;--1:#984E4D&quot;&gt;import sys, specify_cli&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:#ECC48D;--1:#984E4D&quot;&gt;leaked = [k for k in sys.modules if &apos;spec_kitty_runtime&apos; in k]&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:#ECC48D;--1:#984E4D&quot;&gt;assert not leaked, f&apos;spec_kitty_runtime imported: {leaked}&apos;&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:#ECC48D;--1:#984E4D&quot;&gt;print(&apos;OK: spec_kitty_runtime not imported&apos;)&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:#D9F5DD;--1:#111111&quot;&gt;&quot;&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;/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:#919F9F;--1:#5F636F&quot;&gt;# 3. Confirm spec-kitty next runs against your 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:#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;next&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;--agent&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;&amp;#x3C;agent&gt;&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;--mission&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;&amp;#x3C;mission&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;The repo’s CI runs an automated equivalent of this check on every PR
(&lt;code dir=&quot;auto&quot;&gt;clean-install-verification&lt;/code&gt; job in &lt;code dir=&quot;auto&quot;&gt;.github/workflows/ci-quality.yml&lt;/code&gt;).&lt;/p&gt;
&lt;h2 id=&quot;developer-workflows&quot;&gt;Developer workflows&lt;/h2&gt;
&lt;p&gt;If you work across &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; simultaneously (e.g. testing an unreleased events
contract change), see
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/development/local-overrides.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/development/local-overrides.md&lt;/code&gt;&lt;/a&gt;
for editable-install patterns that don’t pollute committed config.&lt;/p&gt;
&lt;h2 id=&quot;why-this-happened&quot;&gt;Why this happened&lt;/h2&gt;
&lt;p&gt;See &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/adr/3.x/2026-04-25-1-shared-package-boundary.md&quot;&gt;ADR 2026-04-25-1: Shared Package Boundary&lt;/a&gt;
for the full decision rationale and the alternatives considered.&lt;/p&gt;
&lt;h2 id=&quot;supersedes&quot;&gt;Supersedes&lt;/h2&gt;
&lt;p&gt;This mission supersedes &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/779&quot;&gt;PR #779&lt;/a&gt;,
which was rejected for preserving the hybrid model (runtime-shaped code in
the CLI tree alongside live &lt;code dir=&quot;auto&quot;&gt;spec_kitty_runtime&lt;/code&gt; production imports). The
work in this mission completes the cutover that PR #779 attempted.&lt;/p&gt;</content>
</entry>
