<?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-25-1-shared-package-boundary/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-25-1-shared-package-boundary/</id>
  <title>ADR: Shared Package Boundary Cutover</title>
  <updated>2026-10-29T00: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-25-1-shared-package-boundary/"/>
  <summary>Retires the standalone runtime package by internalizing the surface the CLI needs, with an import-graph test forbidding production imports of the retired package.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The Spec Kitty product surface includes three Python packages:
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt;, &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;, plus the
retiring &lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt;. Pre-cutover, the CLI consumed a hybrid
mix:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;vendored events code under &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/spec_kitty_events/&lt;/code&gt; in the
CLI’s production paths (~23 kLoC);&lt;/li&gt;
&lt;li&gt;production imports of &lt;code dir=&quot;auto&quot;&gt;spec_kitty_runtime&lt;/code&gt; from CLI code, even though
&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; did not list &lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; as a dependency;&lt;/li&gt;
&lt;li&gt;an editable &lt;code dir=&quot;auto&quot;&gt;[tool.uv.sources]&lt;/code&gt; entry pointing at a sibling
&lt;code dir=&quot;auto&quot;&gt;../spec-kitty-events&lt;/code&gt; checkout, which masked the missing dependency in
local development;&lt;/li&gt;
&lt;li&gt;a &lt;code dir=&quot;auto&quot;&gt;constraints.txt&lt;/code&gt; file that papered over the transitive
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&amp;#x3C;4.0&lt;/code&gt; pin in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; 0.4.x.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This state failed in two predictable ways. (1) Clean-install CI did not
exist, so a fresh &lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-cli&lt;/code&gt; would &lt;code dir=&quot;auto&quot;&gt;ImportError&lt;/code&gt; on
the first &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; invocation. (2) Cross-package releases had to
land in lockstep, because any contract change in events or tracker
required a coordinated CLI release.&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/779&quot;&gt;PR #779&lt;/a&gt; attempted a
partial cutover that moved runtime-shaped code into the CLI tree but kept
&lt;code dir=&quot;auto&quot;&gt;spec_kitty_runtime&lt;/code&gt; production imports alive. That PR was rejected
because the resulting hybrid state was structurally identical to the
pre-cutover state from a clean-install perspective and re-imposed
cross-package release lockstep.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;The mission &lt;code dir=&quot;auto&quot;&gt;shared-package-boundary-cutover-01KQ22DS&lt;/code&gt; lands the cutover
in 10 work packages. Concretely:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;The CLI internalizes the runtime surface it needs from
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; into
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/next/_internal_runtime/&lt;/code&gt;. Production code paths
import only from the internalized module. The standalone
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; PyPI package is retired and is not a CLI
dependency. (WP01, WP02)&lt;/li&gt;
&lt;li&gt;The architectural test
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_shared_package_boundary.py&lt;/code&gt; enforces R1 / C-001:
no production module under &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; may import &lt;code dir=&quot;auto&quot;&gt;spec_kitty_runtime&lt;/code&gt;
(top-level, sub-module, or lazy). The rule is enforced by &lt;code dir=&quot;auto&quot;&gt;pytestarch&lt;/code&gt;
(import-graph) and an AST-walk fallback. (WP03)&lt;/li&gt;
&lt;li&gt;CLI consumes events through the public PyPI package
(&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt;); the vendored copy at
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/spec_kitty_events/&lt;/code&gt; is deleted in its entirety.
(WP04, WP05)&lt;/li&gt;
&lt;li&gt;The wheel-shape and filesystem assertions in
&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_packaging_no_vendored_events.py&lt;/code&gt; lock the
deletion: PRs that re-introduce the directory or ship vendored paths
in the wheel fail CI. (WP06)&lt;/li&gt;
&lt;li&gt;CLI consumes tracker through the public PyPI package
(&lt;code dir=&quot;auto&quot;&gt;spec_kitty_tracker&lt;/code&gt;); CLI-internal &lt;code dir=&quot;auto&quot;&gt;specify_cli.tracker.*&lt;/code&gt;
adapters do not re-export tracker public surface. Consumer-test
contracts under
&lt;code dir=&quot;auto&quot;&gt;tests/contract/spec_kitty_events_consumer/&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;tests/contract/spec_kitty_tracker_consumer/&lt;/code&gt; pin the subset of the
public surfaces CLI uses; upstream contract changes break these tests
explicitly. (WP07)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; lists events / tracker via compatibility ranges
(&lt;code dir=&quot;auto&quot;&gt;&gt;=4.0.0,&amp;#x3C;5.0.0&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;&gt;=0.4,&amp;#x3C;0.5&lt;/code&gt; respectively); exact pins live
only in &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;. (WP08)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;[tool.uv.sources]&lt;/code&gt; does not contain editable / path entries for any
shared package on the committed configuration path. Developer
overrides live in dev-only configuration documented in
&lt;a href=&quot;/development/how-to/local-overrides/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/development/local-overrides.md&lt;/code&gt;&lt;/a&gt;.
(WP08)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;constraints.txt&lt;/code&gt; is removed; its only purpose (papering over the
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; transitive &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&amp;#x3C;4.0&lt;/code&gt; pin
conflict) is gone. (WP08)&lt;/li&gt;
&lt;li&gt;CI runs a &lt;code dir=&quot;auto&quot;&gt;clean-install-verification&lt;/code&gt; job that proves
&lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; works in a fresh venv after only
&lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-cli&lt;/code&gt;. The job builds the wheel, creates a
clean Python venv, installs the wheel, asserts
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; is not installed, asserts &lt;code dir=&quot;auto&quot;&gt;import specify_cli&lt;/code&gt;
does not pull &lt;code dir=&quot;auto&quot;&gt;spec_kitty_runtime&lt;/code&gt; into &lt;code dir=&quot;auto&quot;&gt;sys.modules&lt;/code&gt;, and runs
&lt;code dir=&quot;auto&quot;&gt;spec-kitty next --json&lt;/code&gt; against a fixture mission. (WP09)&lt;/li&gt;
&lt;li&gt;Operator-facing documentation (&lt;code dir=&quot;auto&quot;&gt;CHANGELOG.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;CLAUDE.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/development/*&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/migration/*&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;docs/host-surface-parity.md&lt;/code&gt;) is updated to describe the new
boundary, and the closing PR formally supersedes PR #779. (WP10)&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Cross-package release lockstep is dissolved: events / tracker can ship
within their compatibility windows without forcing a CLI release; the
consumer-test contracts in WP07 catch breaking changes explicitly.&lt;/li&gt;
&lt;li&gt;Operators install only &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; from PyPI. The retired
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; package is unused; existing installs can leave it
installed (it is harmless) or remove it via &lt;code dir=&quot;auto&quot;&gt;pip uninstall&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The CLI codebase grows by ~3 kLoC (the internalized runtime).&lt;/li&gt;
&lt;li&gt;The CLI codebase shrinks by ~23 kLoC (the deleted vendored events
tree).&lt;/li&gt;
&lt;li&gt;Cross-package contract changes (events / tracker public surface) break
the CLI’s consumer-test suite explicitly, forcing CLI to react in a
controlled PR rather than fail at runtime in a customer environment.&lt;/li&gt;
&lt;li&gt;The hybrid state (runtime-shaped code in the CLI tree alongside live
&lt;code dir=&quot;auto&quot;&gt;spec_kitty_runtime&lt;/code&gt; production imports) is mechanically forbidden by
the architectural and packaging tests.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Re-publish &lt;code dir=&quot;auto&quot;&gt;spec-kitty-runtime&lt;/code&gt; as a stable library&lt;/strong&gt;: rejected. The
runtime API is CLI-specific; it has no other consumers. Maintaining a
standalone PyPI package added cross-package release coordination cost
without delivering external value.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Keep events vendored&lt;/strong&gt;: rejected. Vendoring forks the contract;
consumers see two events surfaces that may diverge. Worse, the
vendored copy was already drifting from PyPI’s
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events==4.0.0&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Land the cutover in two PRs (runtime first, events second)&lt;/strong&gt;:
rejected. Constraint C-007 of the mission spec explicitly forbids
partial cutovers; PR #779 was the cautionary example.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/shared-package-boundary-cutover-01KQ22DS/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Migration runbook: &lt;a href=&quot;/migrations/shared-package-boundary-cutover/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/migration/shared-package-boundary-cutover.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Local-overrides dev doc: &lt;a href=&quot;/development/how-to/local-overrides/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/development/local-overrides.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Architectural enforcement:
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;../../../tests/architectural/test_shared_package_boundary.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_shared_package_boundary.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;../../../tests/architectural/test_pyproject_shape.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_pyproject_shape.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;../../../tests/architectural/test_events_tracker_public_imports.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_events_tracker_public_imports.py&lt;/code&gt;&lt;/a&gt; (public symbols only; see Amendment 2026-10-22)&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Consumer contracts:
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;../../../tests/contract/spec_kitty_events_consumer/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/contract/spec_kitty_events_consumer/&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;../../../tests/contract/spec_kitty_tracker_consumer/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/contract/spec_kitty_tracker_consumer/&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Packaging assertions:
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;../../../tests/contract/test_packaging_no_vendored_events.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/contract/test_packaging_no_vendored_events.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Clean-install verification:
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.github/workflows/ci-quality.yml&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;clean-install-verification&lt;/code&gt; job (deleted per PROGRAM.md §2 / planning#57 — this repo runs no GitHub Actions)&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;../../../tests/integration/test_clean_install_next.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_clean_install_next.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;PR #779 (rejected, superseded): &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/779&quot;&gt;https://github.com/Priivacy-ai/spec-kitty/pull/779&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-22-the-boundary-covers-public-symbols-not-only-the-public-package-6607&quot;&gt;Amendment 2026-10-22: the boundary covers public symbols, not only the public package (#6607)&lt;/h2&gt;
&lt;p&gt;The boundary now means public &lt;strong&gt;symbols&lt;/strong&gt;. A production import of a &lt;code dir=&quot;auto&quot;&gt;_&lt;/code&gt;-prefixed module segment or a &lt;code dir=&quot;auto&quot;&gt;_&lt;/code&gt;-prefixed imported name from &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;spec_kitty_tracker&lt;/code&gt; is a violation, even when the package itself is the permitted public one. Core’s last such import, &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.conformance.validators._EVENT_TYPE_TO_MODEL&lt;/code&gt;, was deleted together with the dead hosted lifecycle builder that used it.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_events_tracker_public_imports.py&lt;/code&gt; enforces this over all six production roots (&lt;code dir=&quot;auto&quot;&gt;src/kernel&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/charter&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/glossary&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/runtime&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/mission_runtime&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli&lt;/code&gt;). It checks the imported name (&lt;code dir=&quot;auto&quot;&gt;alias.name&lt;/code&gt;) as well as the module path, and has no allowlist. It joins the enforcement references of this ADR beside &lt;code dir=&quot;auto&quot;&gt;test_shared_package_boundary.py&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;amendment-2026-10-29-accepted-the-events-services-live-in-spec-kitty-events&quot;&gt;Amendment 2026-10-29 (Accepted): the events services live in spec-kitty-events&lt;/h2&gt;
&lt;p&gt;&lt;a href=&quot;/adr/4.x/2026-10-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events/&quot;&gt;ADR 2026-10-29-1&lt;/a&gt; records the operator and CEO ruling of 2026-10-29 that the events domain’s Java services and contracts move to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;, and that core consumes a released, pinned build.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;What &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; is to core.&lt;/strong&gt; Core now consumes two artifact kinds from &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;: the PyPI package (a SemVer range plus &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;, unchanged) and pinned service builds (&lt;code dir=&quot;auto&quot;&gt;pins/&amp;#x3C;service&gt;.source.yaml&lt;/code&gt;, holding a &lt;code dir=&quot;auto&quot;&gt;service-v*&lt;/code&gt; tag, the commit and a sha256 per asset). A pin is the release record for a binary, just as &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt; is for the package. No editable, path or moving-branch reference is allowed for either.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Nothing else in this record changes.&lt;/p&gt;</content>
</entry>
