Skip to content

How to fetch, verify and bump the pinned service binaries

Who is this for (1)

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 service-vX.Y.Z line in its own repository: the events services (write and read) in spec-kitty-events (ADR 2026-10-29-1), the charter service in spec-kitty-charter (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.

A service pin is the lockfile pins/<service>.source.yaml. 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 specify_cli/_pins/) but never a binary: every asset is fetched and checked against its pinned digest before it is used.

The CLI reads its own pin, never one in the user’s project. It looks in the pins/ directory of the spec-kitty source checkout the running specify_cli package belongs to (an editable install; the checkout’s pyproject.toml must name spec-kitty-cli), and otherwise in the specify_cli/_pins/ resource of the installed wheel. A pins/ 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.

No pin exists yet. pins/ holds only its README.md until a service repository cuts its first service-v* release. Until then make sync-services prints no service pinned and exits 0, and every command that needs a service refuses with SERVICE_PIN_INVALID. The pull request that adds the first pin also wires the sync-services action into CI and sync-services into make dev-setup.

Fetch and verify in a checkout

Terminal window
make sync-services # fetch and verify every pinned asset for this host
make sync-services ARGS=--check # verify the cached copies only; fetch, write and delete nothing
make sync-services ARGS=--offline # use the cache and SPEC_KITTY_SERVICE_ASSET_DIR only

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 <cache dir>/services/<service>/<tag>/<name>, where <cache dir> is the per-user cache directory: ${XDG_CACHE_HOME:-~/.cache}/spec-kitty on Linux, ~/Library/Caches/spec-kitty on macOS, %LOCALAPPDATA%\spec-kitty\Cache on Windows (one authority since #6488: kernel.user_dirs.user_cache_dir()). It exits 1 with a stable SERVICE_* code on any failure. The script behind it is scripts/sync_services.py; pass --service <name> to handle one service.

Fetch and verify in CI

The composite action .github/actions/sync-services restores the cache, keyed on hashFiles('pins/*.source.yaml'), and then runs scripts/sync_services.py --service all. It takes the same python and python-exe inputs as .github/actions/sync-packs. No job uses it yet; tests/ci/test_sync_services.py fails, saying “wire it now”, once a pin exists and no workflow uses it.

What a user does

Nothing, normally: the first command that needs a service fetches, verifies and starts it.

  • spec-kitty service fetch [--service <name> | --all] [--offline] fetches and verifies ahead of time. --all covers the services the CLI launches; the read service is pinned for CI conformance only (ADR 2026-10-29-1 D-6), so it is fetched only when named with --service read-service.
  • spec-kitty service status [--service <name>] [--json] shows the pin, the cache state and the running instance. It only reads, like make sync-services ARGS=--check: it starts nothing, writes nothing and evicts nothing. A cached copy that does not verify is reported corrupt and left in place; the next fetch or start replaces it.
  • spec-kitty service stop [--service <name>] stops this clone’s running instance.
  • On a machine with no network, run spec-kitty service fetch on a connected machine and copy the cache, or set SPEC_KITTY_SERVICE_ASSET_DIR to a directory that holds the pinned asset files (flat, or under <tag>/). Its files are digest-checked and copied into the cache, never run in place. The same holds for a binary named by SPEC_KITTY_WRITE_SERVICE_BINARY or provided by an installed package: it is copied into the cache and the copy runs, so those sources also need a writable cache.

Bump a pin

Bump a pin only with the vendor command, never by hand:

Terminal window
spec-kitty service vendor --service write-service --tag service-v0.2.0
spec-kitty service vendor --service write-service --check
git add pins/write-service.source.yaml && git commit

vendor reads the release’s SHA256SUMS, downloads and hashes every asset it pins, and writes the lockfile. It prints the native targets the release has no build for. --check verifies the lockfile offline against the shape rules and, online, against the release. Tags follow service-v<major>.<minor>.<patch>[-<pre-release>]; build metadata (+...) is refused. The repository must be an https:// or file:// URL without credentials.

The release repository defaults per service: charter-service to https://github.com/spec-kitty/spec-kitty-charter, write-service and read-service to https://github.com/spec-kitty/spec-kitty-events. An explicit --repository wins, and so does the repository already recorded in the pin you are bumping.

On a GitHub https:// release, every downloaded asset is also checked against the release’s build attestation before the lockfile is written:

Terminal window
gh attestation verify <asset> --repo <owner/repo> \
--signer-workflow <owner/repo>/.github/workflows/service-release.yml \
--source-ref refs/tags/<tag>

A release whose attestation is missing, signed by another workflow, or from another ref is refused and the lockfile is left byte-identical. --no-attestation skips the check for an offline mirror or a rehearsal only - never for a real bump. A file:// repository is skipped: it has no attestation, and the pinned digest is the whole check there.

A bump writes only the pins/ of the spec-kitty source checkout the CLI runs from, and only when you run it inside that checkout (an editable install, for example uv run spec-kitty service vendor ... in your clone). Anywhere else it is a usage error (exit 2, SERVICE_VENDOR_USAGE) and nothing is written.

Maintainer note: the provenance check is automatic now. vendor 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

Terminal window
sha256sum --check --ignore-missing SHA256SUMS
gh attestation verify <downloaded asset> --repo spec-kitty/spec-kitty-charter \
--signer-workflow spec-kitty/spec-kitty-charter/.github/workflows/service-release.yml \
--source-ref refs/tags/<tag>

Run a local build of a service

When you work on spec-kitty-events, point core at your own build:

Terminal window
export SPEC_KITTY_WRITE_SERVICE_BINARY=/path/to/your/build/spec-kitty-write-service
export SPEC_KITTY_SERVICE_UNPINNED=1 # prints a warning on every start

Without SPEC_KITTY_SERVICE_UNPINNED=1 an explicit path must still match the pinned digest. The opt-in is honoured only together with an explicit path (SPEC_KITTY_<SERVICE>_BINARY). The start timeout is SPEC_KITTY_SERVICE_START_TIMEOUT (seconds, default 15).

Refusal codes

CodeMeaningWhat to do
SERVICE_PIN_INVALIDNo pin for the service in this core version, or the lockfile is malformed or a placeholder.Wait for the first release, or re-run spec-kitty service vendor.
SERVICE_BINARY_MISSINGThe 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 noexec mount).Fetch while online, set SPEC_KITTY_SERVICE_ASSET_DIR, free space in or fix the cache, or move the cache to an exec-capable file system (set XDG_CACHE_HOME on Linux and macOS; on Windows the cache follows %LOCALAPPDATA%).
SERVICE_BINARY_DIGEST_MISMATCHThe bytes are not the pinned bytes.Delete the copy and fetch again; if it persists, the release or mirror does not match the pin.
SERVICE_UNSUPPORTED_PLATFORMThe pin has no build for this host, and either no jar or no Java 25+ runtime to run the pinned jar.Install a Java 25 runtime (JAVA_HOME, or an absolute PATH entry) when the pin has a jar, or use a supported host.
SERVICE_UNHEALTHYThe 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 .git, a symlinked service.log).Read the service log, run spec-kitty service stop, retry; or make the directory the message names writable.
SERVICE_VERSION_MISMATCHThe running service speaks no protocol version this CLI accepts.Upgrade spec-kitty, or stop the running service.
SERVICE_ATTESTATION_UNSUPPORTEDA bump’s release repository is not a GitHub https:// URL, so no signer workflow can be derived.Pin a GitHub repository, or pass --no-attestation for an offline mirror (never for a real bump).
SERVICE_ATTESTATION_UNAVAILABLEgh is not on PATH or could not run.Install the GitHub CLI and run gh auth login, or pass --no-attestation for a rehearsal.
SERVICE_ATTESTATION_FAILEDgh attestation verify rejected an asset: no attestation, another signer workflow, or another source ref.Do not pin that release; check the release’s workflow and tag before retrying.
SERVICE_VENDOR_*spec-kitty service vendor refused (usage, an unresolvable tag, an unavailable or invalid release, a digest mismatch, a requires_core range this version does not satisfy).Follow the remedy the command prints.