<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/plans/events-domain-move/companion-wheel-research/">
  <id>https://docs.spec-kitty.ai/plans/events-domain-move/companion-wheel-research/</id>
  <title>Companion services wheel — research note</title>
  <updated>2026-10-31T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/plans/events-domain-move/companion-wheel-research/"/>
  <summary>Read-only research for the optional spec-kitty-services companion platform wheel that fills the spec_kitty.service_binaries slot (#6904).</summary>
  <content type="html">&lt;h2 id=&quot;companion-services-wheel-research-note&quot;&gt;Companion services wheel: research note&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; ruled and built. The operator accepted all twelve recommendations below on 2026-10-31, plus the uv workspace member for the exact extra; they are recorded in ADR 2026-10-29-1, Amendment 2026-10-31, and delivered by Mission &lt;code dir=&quot;auto&quot;&gt;companion-services-wheel-01M694B1&lt;/code&gt; (#6904).
&lt;strong&gt;Tracks:&lt;/strong&gt; #6904 (child of #6117). This delivers operator ruling 2 of 2026-10-31 (#6117 comment 6544221340).
&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer who has to rule on the open points, or who builds the companion wheel.&lt;/p&gt;
&lt;p&gt;Every claim cites either a file in this repository at &lt;code dir=&quot;auto&quot;&gt;origin/main&lt;/code&gt; (2026-10-31) or a named external source. Statements marked &lt;em&gt;estimate&lt;/em&gt; are reasoning, not measurements.&lt;/p&gt;
&lt;h2 id=&quot;1-what-exists-today&quot;&gt;1. What exists today&lt;/h2&gt;
&lt;h3 id=&quot;the-install-slot-is-built-and-digest-checked&quot;&gt;The install slot is built and digest-checked&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/services/resolution.py:91&lt;/code&gt; defines &lt;code dir=&quot;auto&quot;&gt;BINARY_PROVIDER_GROUP = &quot;spec_kitty.service_binaries&quot;&lt;/code&gt;.
&lt;ul&gt;
&lt;li&gt;An entry point is named after the service (for example &lt;code dir=&quot;auto&quot;&gt;write-service&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Its value loads to a zero-argument callable that returns a path or &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_provided_path&lt;/code&gt;, :316).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Resolution order (&lt;code dir=&quot;auto&quot;&gt;resolve_binary&lt;/code&gt;, :444) is: explicit path, then the install slot, then the cache or fetch, then the jar.&lt;/li&gt;
&lt;li&gt;A path from the install slot goes through &lt;code dir=&quot;auto&quot;&gt;_match_supplied&lt;/code&gt; (:249):
&lt;ul&gt;
&lt;li&gt;its bytes must equal the pinned host build, or the pinned jar;&lt;/li&gt;
&lt;li&gt;it is then adopted into the cache (&lt;code dir=&quot;auto&quot;&gt;kernel.service_artifacts.adopt_asset&lt;/code&gt;), so the cached copy runs, never the file inside site-packages.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;A path that does not match the pin refuses with &lt;code dir=&quot;auto&quot;&gt;SERVICE_BINARY_DIGEST_MISMATCH&lt;/code&gt;. It does &lt;strong&gt;not&lt;/strong&gt; fall through to the cache.&lt;/li&gt;
&lt;li&gt;A provider that raises refuses with &lt;code dir=&quot;auto&quot;&gt;SERVICE_BINARY_MISSING&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;tests-four-gaps&quot;&gt;Tests: four gaps&lt;/h3&gt;
&lt;p&gt;Tests in &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/services/test_resolution.py&lt;/code&gt; (:348–:399, :712) cover:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the install slot winning over an empty cache;&lt;/li&gt;
&lt;li&gt;the real &lt;code dir=&quot;auto&quot;&gt;entry_points&lt;/code&gt; selection;&lt;/li&gt;
&lt;li&gt;a provider that returns &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;a binary that is not the pinned build, and a provider that raises.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;They do not cover:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the install slot winning over a cache that is already warm;&lt;/li&gt;
&lt;li&gt;a wrong-digest binary refusing while the cache is warm;&lt;/li&gt;
&lt;li&gt;the install slot supplying a jar;&lt;/li&gt;
&lt;li&gt;an explicit path beating the install slot.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;pins&quot;&gt;Pins&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt; holds only &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; has no &lt;code dir=&quot;auto&quot;&gt;service-v*&lt;/code&gt; tag yet (checked with &lt;code dir=&quot;auto&quot;&gt;git ls-remote&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The services are &lt;code dir=&quot;auto&quot;&gt;write-service&lt;/code&gt; (launchable), &lt;code dir=&quot;auto&quot;&gt;charter-service&lt;/code&gt; (pinned, not yet launchable) and &lt;code dir=&quot;auto&quot;&gt;read-service&lt;/code&gt; (CI only, never launched; &lt;code dir=&quot;auto&quot;&gt;services/policies.py:56-60&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The targets come from &lt;code dir=&quot;auto&quot;&gt;kernel.service_pin.ServiceTarget&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;linux-x64&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;linux-arm64&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;macos-arm64&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;windows-x64&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;jvm&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;the-fetch-owner&quot;&gt;The fetch owner&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kernel.service_artifacts.fetch_asset(pin, asset, *, offline, cache_root, asset_dir)&lt;/code&gt; verifies every byte against the pinned sha256 before it returns a path.&lt;/li&gt;
&lt;li&gt;Downloads go through &lt;code dir=&quot;auto&quot;&gt;kernel.release_assets&lt;/code&gt; (gate &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_release_asset_download_owner.py&lt;/code&gt;). That gate scans only &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;, so a build script elsewhere is not gated, but it should still call &lt;code dir=&quot;auto&quot;&gt;fetch_asset&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;the-release-workflow&quot;&gt;The release workflow&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.github/workflows/release.yml&lt;/code&gt; builds with &lt;code dir=&quot;auto&quot;&gt;python -m build&lt;/code&gt; (:189).&lt;/li&gt;
&lt;li&gt;The packs drift check is at :186–187.&lt;/li&gt;
&lt;li&gt;“Verify wheel contents” assumes exactly one wheel in &lt;code dir=&quot;auto&quot;&gt;dist/&lt;/code&gt; (:209).&lt;/li&gt;
&lt;li&gt;Publishing uses PyPI Trusted Publishing, scoped to the &lt;code dir=&quot;auto&quot;&gt;pypi&lt;/code&gt; environment and the &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; project (:326–386).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;packaging-guards&quot;&gt;Packaging guards&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/cross_cutting/packaging/test_packaging_safety.py:282-333&lt;/code&gt; already fails any wheel or sdist member that ends in a target suffix or &lt;code dir=&quot;auto&quot;&gt;.jar&lt;/code&gt;, or that sits under a cache path.&lt;/li&gt;
&lt;li&gt;The CLI sdist includes the bare &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; with gitignore semantics (&lt;code dir=&quot;auto&quot;&gt;pyproject.toml:266-269&lt;/code&gt;). A nested &lt;code dir=&quot;auto&quot;&gt;packages/**/README.md&lt;/code&gt; would leak into the sdist unless &lt;code dir=&quot;auto&quot;&gt;packages/**&lt;/code&gt; is excluded.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_pyproject_shape.py:140-151&lt;/code&gt; treats every &lt;code dir=&quot;auto&quot;&gt;src/*&lt;/code&gt; directory that holds Python files as first-party, so the companion module must not live under &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;2-external-facts&quot;&gt;2. External facts&lt;/h2&gt;
&lt;h3 id=&quot;pypi-limits&quot;&gt;PyPI limits&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;PyPI allows 100 MB per file and 10 GB per project by default.&lt;/li&gt;
&lt;li&gt;Raising either limit takes a request to &lt;code dir=&quot;auto&quot;&gt;pypi/support&lt;/code&gt;. A file-size increase also requires at least one existing release under 100 MB.&lt;/li&gt;
&lt;li&gt;Source: docs.pypi.org/project-management/storage-limits, quoted through search because this session’s network blocks that host; pypi/support #243, #3757 and #7112.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;wheel-tags-and-glibc&quot;&gt;Wheel tags and glibc&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The tags are &lt;code dir=&quot;auto&quot;&gt;manylinux_2_X_{x86_64,aarch64}&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;macosx_11_0_arm64&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;win_amd64&lt;/code&gt; (packaging.python.org platform-compatibility-tags).&lt;/li&gt;
&lt;li&gt;GraalVM native images link glibc dynamically by default, against the glibc of the build host.
&lt;ul&gt;
&lt;li&gt;The events native job builds on &lt;code dir=&quot;auto&quot;&gt;ubuntu-24.04&lt;/code&gt;, which has glibc 2.39 (&lt;code dir=&quot;auto&quot;&gt;.github/workflows/mission-status-api.yml:149-171&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;A &lt;code dir=&quot;auto&quot;&gt;manylinux2014&lt;/code&gt; (glibc 2.17) tag would therefore be untrue.&lt;/li&gt;
&lt;li&gt;Source: graalvm.org native-image static-executables guide; z3prover/z3#7232 shows the same failure in the wild.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;size&quot;&gt;Size&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;No binary size has ever been measured.&lt;/strong&gt; No release has been cut (&lt;code dir=&quot;auto&quot;&gt;plan.md:38&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Published minimal Spring Boot native images are 48–129 MB uncompressed (Baeldung 82.8 MB; alexcheng1982/spring-boot-native-samples).&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Estimate:&lt;/em&gt;
&lt;ul&gt;
&lt;li&gt;30–40 MB compressed per native binary;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;60–85 MB per platform wheel holding the write and charter binaries&lt;/strong&gt;: under the 100 MB cap, with little headroom;&lt;/li&gt;
&lt;li&gt;adding a jar (25–40 MB) to each platform wheel would likely push it over the cap.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;install-behaviour&quot;&gt;Install behaviour&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;With &lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-cli[services]&lt;/code&gt;, pip picks the platform wheel that matches the host.&lt;/li&gt;
&lt;li&gt;When no wheel matches and the companion has no sdist, the whole install fails, &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; included.&lt;/li&gt;
&lt;li&gt;PEP 508 markers can skip the requirement per OS and architecture, but they cannot tell glibc from musl or read the glibc version.&lt;/li&gt;
&lt;li&gt;A &lt;code dir=&quot;auto&quot;&gt;py3-none-any&lt;/code&gt; wheel of the same version is the fallback pip picks when no platform wheel matches.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;3-decisions-for-the-operator-recommendations&quot;&gt;3. Decisions for the operator (recommendations)&lt;/h2&gt;






































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;#&lt;/th&gt;&lt;th&gt;Open point&lt;/th&gt;&lt;th&gt;Recommendation&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;Name&lt;/td&gt;&lt;td&gt;Distribution &lt;code dir=&quot;auto&quot;&gt;spec-kitty-services&lt;/code&gt;, import package &lt;code dir=&quot;auto&quot;&gt;spec_kitty_services&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;Extra or separate install&lt;/td&gt;&lt;td&gt;Both work. Add an extra &lt;code dir=&quot;auto&quot;&gt;services&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;spec-kitty-services==&amp;#x3C;cli version&gt;&lt;/code&gt;), so &lt;code dir=&quot;auto&quot;&gt;pip install &quot;spec-kitty-cli[services]&quot;&lt;/code&gt; is the one offline-ready command; &lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-services==&amp;#x3C;cli version&gt;&lt;/code&gt; also works. Plan §3.4 named the extra &lt;code dir=&quot;auto&quot;&gt;[native]&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;services&lt;/code&gt; matches the distribution name.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;3&lt;/td&gt;&lt;td&gt;Version lock&lt;/td&gt;&lt;td&gt;The companion’s version equals the CLI’s version exactly. It is built from the &lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt; of the same release commit and embeds a manifest of &lt;code dir=&quot;auto&quot;&gt;{service, tag, target, sha256}&lt;/code&gt;. Its provider returns &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt; (fall through to the cache or fetch) when the installed &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; version differs from the version it was built for, so a version skew degrades to option A instead of refusing with &lt;code dir=&quot;auto&quot;&gt;DIGEST_MISMATCH&lt;/code&gt;. Resolution still digest-checks whatever the provider returns.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;Contents&lt;/td&gt;&lt;td&gt;The native write service and charter service for the host target. Not the read service (ruling 3, D-6). Not the jar: the jar fallback stays on the fetch path, which keeps each wheel under the cap.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;Unsupported hosts&lt;/td&gt;&lt;td&gt;Also publish a &lt;strong&gt;binary-free &lt;code dir=&quot;auto&quot;&gt;py3-none-any&lt;/code&gt; fallback wheel&lt;/strong&gt; whose providers return &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;. Every host then resolves the extra (Intel macOS, musl, old glibc, win-arm64) and falls through to the option A fetch. No PEP 508 markers are needed, and no sdist.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;6&lt;/td&gt;&lt;td&gt;Linux tag&lt;/td&gt;&lt;td&gt;Tag honestly with the glibc floor of the build: &lt;code dir=&quot;auto&quot;&gt;manylinux_2_39&lt;/code&gt; for the &lt;code dir=&quot;auto&quot;&gt;ubuntu-24.04&lt;/code&gt; builds. This floor is a build input recorded per release, not a guess. Hosts with an older glibc get the fallback wheel. Lowering the floor (&lt;code dir=&quot;auto&quot;&gt;--static-nolibc&lt;/code&gt;, or an older builder) is an events-side follow-up.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;7&lt;/td&gt;&lt;td&gt;Size&lt;/td&gt;&lt;td&gt;The build fails when any companion wheel exceeds &lt;strong&gt;95 MB&lt;/strong&gt; and warns above 60 MB (plan §3.4). Splitting into one wheel per service is the documented escape, and needs its own amendment. Budget: roughly 4 × 60–85 MB per release against 10 GB, so old RC releases need pruning after about 30 releases.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;8&lt;/td&gt;&lt;td&gt;Build&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;scripts/build_services_wheel.py&lt;/code&gt; reads the release commit’s &lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt;, fetches every native target of every user-facing service through &lt;code dir=&quot;auto&quot;&gt;kernel.service_artifacts.fetch_asset&lt;/code&gt; (digest-verified; nothing is rebuilt), and writes the wheels deterministically with the standard library (&lt;code dir=&quot;auto&quot;&gt;WHEEL&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;METADATA&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;RECORD&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;entry_points.txt&lt;/code&gt;). It adds no build dependency. The Python source lives in &lt;code dir=&quot;auto&quot;&gt;packages/spec-kitty-services/&lt;/code&gt;, which is excluded from the CLI sdist.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;9&lt;/td&gt;&lt;td&gt;Release job&lt;/td&gt;&lt;td&gt;A new &lt;code dir=&quot;auto&quot;&gt;build-companion-wheels&lt;/code&gt; job (&lt;code dir=&quot;auto&quot;&gt;needs: build-release&lt;/code&gt;) writes to &lt;code dir=&quot;auto&quot;&gt;dist-services/&lt;/code&gt;, not &lt;code dir=&quot;auto&quot;&gt;dist/&lt;/code&gt;, and runs &lt;code dir=&quot;auto&quot;&gt;twine check&lt;/code&gt;, the size cap and the digest guard. A separate &lt;code dir=&quot;auto&quot;&gt;publish-companion-pypi&lt;/code&gt; job uses its own environment (&lt;code dir=&quot;auto&quot;&gt;pypi-services&lt;/code&gt;) and a Trusted Publisher for the new project, and runs &lt;strong&gt;before&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;publish-pypi&lt;/code&gt;, so the CLI’s &lt;code dir=&quot;auto&quot;&gt;==&lt;/code&gt; extra can always resolve. &lt;strong&gt;Operator action:&lt;/strong&gt; register &lt;code dir=&quot;auto&quot;&gt;spec-kitty-services&lt;/code&gt; on PyPI (a pending publisher) and create the environment.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;10&lt;/td&gt;&lt;td&gt;Empty pins&lt;/td&gt;&lt;td&gt;With no pin, only the fallback wheel is built. The extra still resolves, and nothing ships a binary.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;11&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;sync_services.py&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;release.yml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Cheap. Add &lt;code dir=&quot;auto&quot;&gt;sync_services.py --service all&lt;/code&gt; after the packs check: it fetches and digest-verifies the host’s assets, so a later &lt;code dir=&quot;auto&quot;&gt;--check&lt;/code&gt; would not fail on a cold cache. The companion job’s all-target verification is the stronger guard. Also add the service steps to &lt;code dir=&quot;auto&quot;&gt;RELEASE_CHECKLIST.md&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;12&lt;/td&gt;&lt;td&gt;Slicing&lt;/td&gt;&lt;td&gt;One PR. The ADR amendment is its first commit. Nothing here is large enough to need stacked PRs.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;</content>
</entry>
