Release Artifacts Are Product Promises
Release artifacts are product promises
A release artifact is not just a file. It is a promise about support.
Users do not parse your internal maturity model when they see a ZIP, DMG, installer, package, or binary attached to a release. They read it as "this is for me to install." That promise needs to match reality.
The rule
Only publish an artifact when the project can defend these claims:
- It contains the current code for the thing it claims to ship.
- It launches on a clean machine in the supported environment.
- It passes at least one smoke test through the real artifact, not just the inner binary.
- It meets the platform's normal trust expectations: signing, notarization, checksums, provenance, or a loud documented exception.
- It has install and update docs that match the artifact's real status.
If those are not true, keep the artifact internal or mark it as a preview in the artifact name, release notes, and docs.
What mxr taught us
The older Mxr Desktop App work taught the first version of this lesson. A wrapper around the same daemon is still a separate promise once it is published as an app. It needs its own first-run flow, packaging, signing story, and smoke test. The current repo removed that lane instead of shipping a half-ready wrapper.
The current shipped artifacts are narrower and easier to defend: Linux x86_64 and macOS Apple Silicon CLI archives, checksums, Homebrew, and cargo install --git. The embedded web app rides inside that same binary. That is one product promise, not two.
The macOS side still matters. Unsigned CLI archives can be a valid current promise if the release says so and the workflow warns loudly. It would become a broken promise only if the docs claimed signed/notarized macOS distribution while CI shipped unsigned bytes.
What spotuify clarified
Spotuify now has two macOS release surfaces, not one.
The CLI tarballs are built by CI, shipped with checksums/provenance, and are
documented as unsigned/not notarized. That is an honest product promise.
The SwiftUI Spotuify macOS App DMG is different. It is built locally with
clients/macos/scripts/build-dmg.sh, bundles a universal spotuify binary, and
is attached to the release manually because CI does not have the macOS 26 SDK.
The script can sign and notarize, but only when local Developer ID and notary
credentials are configured.
That means the install page must not collapse the two surfaces into "the macOS
release". It should say which artifact it means, which process built it, and
whether signing/notarization is a guarantee or a conditional release property.
What docs-only mxr releases clarified
The promise cuts both ways. If a tag only changes docs, version metadata, or generated OpenAPI, the honest release may have no binary artifacts at all.
mxr now scopes release work through scripts/release_change_scope.sh. CLI-affecting tags build Linux x86_64 and macOS Apple Silicon archives and update Homebrew. Docs-only or version-only tags create the GitHub Release and changelog, but skip tarballs and Homebrew. That is a better promise than publishing fresh-looking binaries for a change that did not affect the binary.
The 2026-05-31 release pass added another edge: live Gmail smoke tests and Apple signing are useful confidence signals, but they are not the same kind of promise as deterministic build/test failures. Missing MXR_GMAIL_TEST_* credentials should skip live provider smoke. Missing Apple signing credentials should ship the current unsigned CLI artifact with a warning. Bundled Gmail build credentials are different, but only in the shape of the promise. If BYOC is the documented v1 Gmail path, a release can honestly ship without bundled credentials. A half-configured bundled client cannot.
The important bit is documentation. Install pages, roadmap notes, and release runbooks must say which targets actually exist and when artifacts are intentionally skipped. A missing artifact is fine when it is intentional and documented. It is a broken promise when the docs still tell a user to download it.
What cognitive-memory clarified
The 2026-05-31 Agentic Cognitive Memory docs pass found the package-export version of the same problem.
The SDK source says TypeScript is at v0.5.1 and contains a RemoteAdapter. PyPI is published at v0.5.1. npm still reports cognitive-memory@0.4.0, and the TypeScript package.json export map only exposes the root package plus adapters/postgres and adapters/jsonl. So the sentence "import RemoteAdapter from cognitive-memory/adapters/remote" is true in source and false for a normal npm install.
That is not a small wording bug. It changes what a user can actually do. Docs need to name the surface they are talking about: source build, PyPI package, npm package, daemon repo, or future planned export. "It exists in the repo" is not the same as "it ships to users."
What spotuify clarified
The 2026-06-09 Spotuify hardening pass hit the platform version of this.
Windows moved from "planned" to a published x64 zip:
spotuify-v{version}-windows-x86_64.zip. That artifact is real, backed by
Windows CI check/test/build plus fake-provider smoke. But it is still beta until
a real Windows machine verifies login, daemon startup, playback, and Task
Scheduler install. That is a valid promise only if the docs say both halves:
"you can download this" and "this platform is not fully live-smoked yet."
The Spotuify macOS App exposed the sibling problem. A DMG is not the same
surface as the CI-built CLI tarballs. The script can sign and notarize when
local Developer ID/notary credentials exist, but the tag-driven CI release does
not build the DMG today. So the install page cannot promise "latest signed
build" unless the release workflow can actually produce it.
This is where artifact names, CI matrices, install docs, and release notes all
need to agree. If they don't, the user will believe the most install-shaped
thing they can see.
The reusable checklist
- Does the artifact build whenever its transitive runtime changes?
- Does this release need an artifact at all, or is it docs-only?
- Which release gates are hard blockers, and which are optional confidence signals?
- Does CI fail if generated metadata is dirty?
- Does the packaged artifact launch, not just the inner executable?
- Does the platform trust model pass? For macOS, that usually means Developer ID signing, hardened runtime, notarization, and a clean Gatekeeper launch.
- Does the package export map expose the API the docs import?
- Does the docs site say "preview" everywhere the artifact is preview?
- Do install docs list only the targets that the workflow actually builds?
- If an artifact is built manually, do the docs say who builds it and which
trust guarantees are conditional?