<?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/service-pins/">
  <id>https://docs.spec-kitty.ai/development/how-to/service-pins/</id>
  <title>How to fetch, verify and bump the pinned service binaries</title>
  <updated>2026-11-01T00: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/service-pins/"/>
  <summary>Fetch and verify the pinned service builds in a checkout or in CI, work offline, run an unpinned local build, and bump a pin with spec-kitty service vendor.</summary>
  <content type="html">&lt;span id=&quot;how-to-fetch-verify-and-bump-the-pinned-service-binaries&quot;&gt;&lt;/span&gt;
&lt;p&gt;Core runs services it does not build: the write service, the Mission Status read service and the
charter service. Each service releases on its own &lt;code dir=&quot;auto&quot;&gt;service-vX.Y.Z&lt;/code&gt; line in its own repository: the
events services (write and read) in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&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;),
the charter service in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-charter&lt;/code&gt; (its ADR-0046). A release carries per-OS native
binaries, a portable jar, and - for the events services - the contract bundles and conformance
fixtures, each with a SHA-256 digest.&lt;/p&gt;
&lt;p&gt;A &lt;strong&gt;service pin&lt;/strong&gt; is the lockfile &lt;code dir=&quot;auto&quot;&gt;pins/&amp;#x3C;service&gt;.source.yaml&lt;/code&gt;. It records which released build core
runs: the tag, the commit it resolves to, the protocol versions, the core version range it needs,
and the file name and digest of every asset. The wheel ships the pins (as &lt;code dir=&quot;auto&quot;&gt;specify_cli/_pins/&lt;/code&gt;) but
never a binary: every asset is fetched and checked against its pinned digest before it is used.&lt;/p&gt;
&lt;p&gt;The CLI reads &lt;strong&gt;its own&lt;/strong&gt; pin, never one in the user’s project. It looks in the &lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt; directory of
the spec-kitty source checkout the running &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; package belongs to (an editable install;
the checkout’s &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; must name &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt;), and otherwise in the &lt;code dir=&quot;auto&quot;&gt;specify_cli/_pins/&lt;/code&gt;
resource of the installed wheel. A &lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt; directory in the project you run spec-kitty in is ignored:
the pin names the build this CLI runs, so a project cannot choose it.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;No pin exists yet.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt; holds only its &lt;code dir=&quot;auto&quot;&gt;README.md&lt;/code&gt; until a service repository cuts its first
&lt;code dir=&quot;auto&quot;&gt;service-v*&lt;/code&gt; release. Until then &lt;code dir=&quot;auto&quot;&gt;make sync-services&lt;/code&gt; prints &lt;code dir=&quot;auto&quot;&gt;no service pinned&lt;/code&gt; and exits 0, and
every command that needs a service refuses with &lt;code dir=&quot;auto&quot;&gt;SERVICE_PIN_INVALID&lt;/code&gt;. The pull request that adds
the first pin also wires the &lt;code dir=&quot;auto&quot;&gt;sync-services&lt;/code&gt; action into CI and &lt;code dir=&quot;auto&quot;&gt;sync-services&lt;/code&gt; into &lt;code dir=&quot;auto&quot;&gt;make dev-setup&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;fetch-and-verify-in-a-checkout&quot;&gt;Fetch and verify in a checkout&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;make&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-services&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;# fetch and verify every pinned asset for this host&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;make&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-services&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;ARGS=--check&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;# verify the cached copies only; fetch, write and delete nothing&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;make&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-services&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;ARGS=--offline&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;# use the cache and SPEC_KITTY_SERVICE_ASSET_DIR only&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;For each pin, the target takes the host’s native build (the jar when the pin has no build for this
host) plus every extras asset, and fetches and verifies each into
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;cache dir&gt;/services/&amp;#x3C;service&gt;/&amp;#x3C;tag&gt;/&amp;#x3C;name&gt;&lt;/code&gt;, where &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;cache dir&gt;&lt;/code&gt; is the per-user cache
directory: &lt;code dir=&quot;auto&quot;&gt;${XDG_CACHE_HOME:-~/.cache}/spec-kitty&lt;/code&gt; on Linux, &lt;code dir=&quot;auto&quot;&gt;~/Library/Caches/spec-kitty&lt;/code&gt; on
macOS, &lt;code dir=&quot;auto&quot;&gt;%LOCALAPPDATA%\spec-kitty\Cache&lt;/code&gt; on Windows (one authority since #6488:
&lt;code dir=&quot;auto&quot;&gt;kernel.user_dirs.user_cache_dir()&lt;/code&gt;). It exits 1 with a stable &lt;code dir=&quot;auto&quot;&gt;SERVICE_*&lt;/code&gt; code on any failure. The script behind it is &lt;code dir=&quot;auto&quot;&gt;scripts/sync_services.py&lt;/code&gt;; pass
&lt;code dir=&quot;auto&quot;&gt;--service &amp;#x3C;name&gt;&lt;/code&gt; to handle one service.&lt;/p&gt;
&lt;h2 id=&quot;fetch-and-verify-in-ci&quot;&gt;Fetch and verify in CI&lt;/h2&gt;
&lt;p&gt;The composite action &lt;code dir=&quot;auto&quot;&gt;.github/actions/sync-services&lt;/code&gt; restores the cache, keyed on
&lt;code dir=&quot;auto&quot;&gt;hashFiles(&apos;pins/*.source.yaml&apos;)&lt;/code&gt;, and then runs &lt;code dir=&quot;auto&quot;&gt;scripts/sync_services.py --service all&lt;/code&gt;. It takes
the same &lt;code dir=&quot;auto&quot;&gt;python&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;python-exe&lt;/code&gt; inputs as &lt;code dir=&quot;auto&quot;&gt;.github/actions/sync-packs&lt;/code&gt;. No job uses it yet;
&lt;code dir=&quot;auto&quot;&gt;tests/ci/test_sync_services.py&lt;/code&gt; fails, saying “wire it now”, once a pin exists and no workflow uses
it.&lt;/p&gt;
&lt;h2 id=&quot;what-a-user-does&quot;&gt;What a user does&lt;/h2&gt;
&lt;p&gt;Nothing, normally: the first command that needs a service fetches, verifies and starts it.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty service fetch [--service &amp;#x3C;name&gt; | --all] [--offline]&lt;/code&gt; fetches and verifies ahead of time.
&lt;code dir=&quot;auto&quot;&gt;--all&lt;/code&gt; covers the services the CLI launches; the read service is pinned for CI conformance only
(&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; D-6),
so it is fetched only when named with &lt;code dir=&quot;auto&quot;&gt;--service read-service&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty service status [--service &amp;#x3C;name&gt;] [--json]&lt;/code&gt; shows the pin, the cache state and the
running instance. It only reads, like &lt;code dir=&quot;auto&quot;&gt;make sync-services ARGS=--check&lt;/code&gt;: it starts nothing, writes
nothing and evicts nothing. A cached copy that does not verify is reported &lt;code dir=&quot;auto&quot;&gt;corrupt&lt;/code&gt; and left in
place; the next fetch or start replaces it.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty service stop [--service &amp;#x3C;name&gt;]&lt;/code&gt; stops this clone’s running instance.&lt;/li&gt;
&lt;li&gt;On a machine with no network, run &lt;code dir=&quot;auto&quot;&gt;spec-kitty service fetch&lt;/code&gt; on a connected machine and copy the
cache, or set &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SERVICE_ASSET_DIR&lt;/code&gt; to a directory that holds the pinned asset files
(flat, or under &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;tag&gt;/&lt;/code&gt;). Its files are digest-checked and copied into the cache, never run in place.
The same holds for a binary named by &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_WRITE_SERVICE_BINARY&lt;/code&gt; or provided by an installed
package: it is copied into the cache and the copy runs, so those sources also need a writable cache.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;bump-a-pin&quot;&gt;Bump a pin&lt;/h2&gt;
&lt;p&gt;Bump a pin only with the vendor command, never by hand:&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;service&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;vendor&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;--service&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;write-service&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;--tag&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;service-v0.2.0&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;service&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;vendor&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;--service&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;write-service&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;--check&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;git&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;add&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;pins/write-service.source.yaml&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&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;commit&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;vendor&lt;/code&gt; reads the release’s &lt;code dir=&quot;auto&quot;&gt;SHA256SUMS&lt;/code&gt;, downloads and hashes every asset it pins, and writes the
lockfile. It prints the native targets the release has no build for. &lt;code dir=&quot;auto&quot;&gt;--check&lt;/code&gt; verifies the lockfile
offline against the shape rules and, online, against the release. Tags follow
&lt;code dir=&quot;auto&quot;&gt;service-v&amp;#x3C;major&gt;.&amp;#x3C;minor&gt;.&amp;#x3C;patch&gt;[-&amp;#x3C;pre-release&gt;]&lt;/code&gt;; build metadata (&lt;code dir=&quot;auto&quot;&gt;+...&lt;/code&gt;) is refused. The
repository must be an &lt;code dir=&quot;auto&quot;&gt;https://&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;file://&lt;/code&gt; URL without credentials.&lt;/p&gt;
&lt;p&gt;The release repository defaults per service: &lt;code dir=&quot;auto&quot;&gt;charter-service&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;https://github.com/spec-kitty/spec-kitty-charter&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;write-service&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;read-service&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;https://github.com/spec-kitty/spec-kitty-events&lt;/code&gt;. An explicit &lt;code dir=&quot;auto&quot;&gt;--repository&lt;/code&gt; wins, and so does the
repository already recorded in the pin you are bumping.&lt;/p&gt;
&lt;p&gt;On a GitHub &lt;code dir=&quot;auto&quot;&gt;https://&lt;/code&gt; release, every downloaded asset is also checked against the release’s build
attestation before the lockfile is written:&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;gh&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;attestation&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;verify&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;asset&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;--repo&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;owner/repo&gt;&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:#82AAFF;--1:#3B61B0&quot;&gt;--signer-workflow&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;owner/repo&gt;/.github/workflows/service-release.yml&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:#82AAFF;--1:#3B61B0&quot;&gt;--source-ref&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;refs/tags/&amp;#x3C;tag&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;A release whose attestation is missing, signed by another workflow, or from another ref is refused
and the lockfile is left byte-identical. &lt;code dir=&quot;auto&quot;&gt;--no-attestation&lt;/code&gt; skips the check for an offline mirror or
a rehearsal only - never for a real bump. A &lt;code dir=&quot;auto&quot;&gt;file://&lt;/code&gt; repository is skipped: it has no attestation,
and the pinned digest is the whole check there.&lt;/p&gt;
&lt;p&gt;A bump writes only the &lt;code dir=&quot;auto&quot;&gt;pins/&lt;/code&gt; of the spec-kitty source checkout the CLI runs from, and only when you
run it inside that checkout (an editable install, for example &lt;code dir=&quot;auto&quot;&gt;uv run spec-kitty service vendor ...&lt;/code&gt;
in your clone). Anywhere else it is a usage error (exit 2, &lt;code dir=&quot;auto&quot;&gt;SERVICE_VENDOR_USAGE&lt;/code&gt;) and nothing is
written.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Maintainer note: the provenance check is automatic now.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;vendor&lt;/code&gt; runs the check above for a
GitHub release, so a committed pin has already been checked against the release’s build
attestation. The manual command is still useful as an independent second source: compare the
vendored digests with the asset digests GitHub shows on the release page, or run&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;sha256sum&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;--check&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;--ignore-missing&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;SHA256SUMS&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;gh&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;attestation&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;verify&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;downloaded&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;asset&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;--repo&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/spec-kitty-charter&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:#82AAFF;--1:#3B61B0&quot;&gt;--signer-workflow&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/spec-kitty-charter/.github/workflows/service-release.yml&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:#82AAFF;--1:#3B61B0&quot;&gt;--source-ref&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;refs/tags/&amp;#x3C;tag&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;run-a-local-build-of-a-service&quot;&gt;Run a local build of a service&lt;/h2&gt;
&lt;p&gt;When you work on &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;, point core at your own build:&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:#C792EA;--1:#8844AE&quot;&gt;export&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;SPEC_KITTY_WRITE_SERVICE_BINARY&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;path&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;your&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;build&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;/&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;spec-kitty-write-service&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:#C792EA;--1:#8844AE&quot;&gt;export&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;SPEC_KITTY_SERVICE_UNPINNED&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1&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;# prints a warning on every start&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Without &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SERVICE_UNPINNED=1&lt;/code&gt; an explicit path must still match the pinned digest. The
opt-in is honoured only together with an explicit path (&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_&amp;#x3C;SERVICE&gt;_BINARY&lt;/code&gt;). The start
timeout is &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SERVICE_START_TIMEOUT&lt;/code&gt; (seconds, default 15).&lt;/p&gt;
&lt;h2 id=&quot;refusal-codes&quot;&gt;Refusal codes&lt;/h2&gt;




























































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Code&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;th&gt;What to do&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;SERVICE_PIN_INVALID&lt;/code&gt;&lt;/td&gt;&lt;td&gt;No pin for the service in this core version, or the lockfile is malformed or a placeholder.&lt;/td&gt;&lt;td&gt;Wait for the first release, or re-run &lt;code dir=&quot;auto&quot;&gt;spec-kitty service vendor&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_BINARY_MISSING&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The asset is not in the cache and cannot be fetched (offline, unreachable, or the cache is full or not writable), or the verified binary cannot be executed (no exec permission, a &lt;code dir=&quot;auto&quot;&gt;noexec&lt;/code&gt; mount).&lt;/td&gt;&lt;td&gt;Fetch while online, set &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SERVICE_ASSET_DIR&lt;/code&gt;, free space in or fix the cache, or move the cache to an exec-capable file system (set &lt;code dir=&quot;auto&quot;&gt;XDG_CACHE_HOME&lt;/code&gt; on Linux and macOS; on Windows the cache follows &lt;code dir=&quot;auto&quot;&gt;%LOCALAPPDATA%&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_BINARY_DIGEST_MISMATCH&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The bytes are not the pinned bytes.&lt;/td&gt;&lt;td&gt;Delete the copy and fetch again; if it persists, the release or mirror does not match the pin.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_UNSUPPORTED_PLATFORM&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The pin has no build for this host, and either no jar or no Java 25+ runtime to run the pinned jar.&lt;/td&gt;&lt;td&gt;Install a Java 25 runtime (&lt;code dir=&quot;auto&quot;&gt;JAVA_HOME&lt;/code&gt;, or an absolute &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; entry) when the pin has a jar, or use a supported host.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_UNHEALTHY&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The service started but did not become healthy, or its directory in the git common dir cannot be created or written (a read-only or full &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt;, a symlinked &lt;code dir=&quot;auto&quot;&gt;service.log&lt;/code&gt;).&lt;/td&gt;&lt;td&gt;Read the service log, run &lt;code dir=&quot;auto&quot;&gt;spec-kitty service stop&lt;/code&gt;, retry; or make the directory the message names writable.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_VERSION_MISMATCH&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The running service speaks no protocol version this CLI accepts.&lt;/td&gt;&lt;td&gt;Upgrade spec-kitty, or stop the running service.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_ATTESTATION_UNSUPPORTED&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A bump’s release repository is not a GitHub &lt;code dir=&quot;auto&quot;&gt;https://&lt;/code&gt; URL, so no signer workflow can be derived.&lt;/td&gt;&lt;td&gt;Pin a GitHub repository, or pass &lt;code dir=&quot;auto&quot;&gt;--no-attestation&lt;/code&gt; for an offline mirror (never for a real bump).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_ATTESTATION_UNAVAILABLE&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;gh&lt;/code&gt; is not on &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; or could not run.&lt;/td&gt;&lt;td&gt;Install the GitHub CLI and run &lt;code dir=&quot;auto&quot;&gt;gh auth login&lt;/code&gt;, or pass &lt;code dir=&quot;auto&quot;&gt;--no-attestation&lt;/code&gt; for a rehearsal.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_ATTESTATION_FAILED&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;gh attestation verify&lt;/code&gt; rejected an asset: no attestation, another signer workflow, or another source ref.&lt;/td&gt;&lt;td&gt;Do not pin that release; check the release’s workflow and tag before retrying.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SERVICE_VENDOR_*&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty service vendor&lt;/code&gt; refused (usage, an unresolvable tag, an unavailable or invalid release, a digest mismatch, a &lt;code dir=&quot;auto&quot;&gt;requires_core&lt;/code&gt; range this version does not satisfy).&lt;/td&gt;&lt;td&gt;Follow the remedy the command prints.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;</content>
</entry>
