Release and delivery contract

Product releases are immutable annotated Git tags and deterministic source artifacts. A mutable branch, local checkout, package version, deployment, or generated buyer repository is not a product release.

Versioning

v1.0.0 is the first stable commercial baseline. The current v0.x tags are released betas: each is an immutable tag with a verified bundle and a release note, and a v0.x minor may move a supported contract. From v1.0.0:

patch releases preserve the supported product contract and contain compatible fixes;
minor releases add backward-compatible capability or supported-path improvements;
major releases require explicit buyer action to preserve an existing supported contract.

Release candidates use vMAJOR.MINOR.PATCH-rc.N. Internal v0.0.0-rehearsal.N tags may exist only in isolated rehearsal repositories; they are never customer releases, entitlement events, or public compatibility claims.

Required release inputs

Every commercial tag requires:

a clean commit that has passed main CI;
an annotated tag pointing at that exact commit;
a matching CHANGELOG.md heading;
docs/releases/<version>.md completed from the release-note template;
pinned Node, Bun, pnpm, Vite+, TypeScript, Postgres, and provider assumptions;
migration forward/backward/irreversible notes;
environment additions/removals/rotations;
known issues and support transition window;
root, real-Postgres, custom-buyer, package-native toolchain, audit, packaging, and previous-release upgrade proof.

The first commercial tag has no previous supported release. It still requires a full fresh-buyer proof. Every later tag requires release:rehearse-upgrade from the previous supported tag.

Verification commands

Run only from the clean commit carrying the annotated target tag and against a disposable database:

RELEASE_DISPOSABLE_DATABASE=1 \
DATABASE_URL='postgresql://app:app@localhost:5432/release_verify?sslmode=disable' \
pnpm release:verify -- v1.0.0-rc.1 v1.0.0-rc.0

Omit the second tag only for the first commercial baseline. The verifier refuses a dirty checkout, a lightweight/mismatched tag, missing notes, or a database not explicitly declared disposable.

The verifier:

freezes dependencies and proves migration up → down → up;
runs DB-enabled tests, checks, supported builds, package-native escape commands, and audit;
creates and fully verifies a custom-scope/custom-brand buyer;
packages the tagged source through Git attributes;
rehearses an upgrade from the previous tag when supplied.

Artifact contract

release:package produces:

foundation-source-<tag>.tar.gz;
foundation-source-<tag>.tar.gz.sha256;
foundation-source-<tag>.manifest.json.

The tarball is git archive output compressed with timestamp-free gzip. Re-running the packager for the same tag produces the same bytes. The manifest records tag, commit, commit timestamp, artifact checksum, and toolchain pins. A checksum detects accidental change; it is not a cryptographic signature or proof of publisher identity.

The archive excludes:

the seller landing site and private planning;
historical Phase 2 instructions and internal dated author evidence;
Git history, dependencies, build output, runtime environment, evaluation runs, and release output.

It includes the buyer template, root/scoped agent rules, CI, buyer/commercial contracts, golden paths, create-app, and release/upgrade documentation.

Upgrade rehearsal

The deterministic rehearsal:

extracts both exact tags;
generates old/current buyers with the same name, scope, and brand;
refuses any modified or removed previous migration;
constructs a shared Git baseline, adds a buyer-owned product file, and merges the target foundation branch;
proves the buyer-owned file survives;
runs migration reversal, DB-enabled tests, frozen install, checks, all tests/builds, and audit.

This proves an unmodified reference plus a non-overlapping buyer change. It does not promise that arbitrary application customizations merge without conflict. Buyers must review conflicts using Upgrading.

Entitlement and access

CI artifacts are maintainer evidence, not customer fulfillment. After approval, the fulfillment system must copy the exact immutable artifact, checksum, manifest, notes, and license into the access-controlled release channel.

For each release grant, record:

order/license and authorized developer;
tag, commit, artifact checksum, and release publication timestamp;
entitlement type and updates_end_at;
grant/revocation/recovery events.

A buyer receives a release only when its publication timestamp falls within the recorded update entitlement, except an approved founding lifetime entitlement. Expiry never disables or revokes source already lawfully downloaded. Revoking managed access cannot erase a clone.

Never grant customer access to a mutable seller branch as a substitute for versioned delivery.

npm bootstrapper

The public superslate npm package is a source-delivery bootstrapper, not a copy of the paid foundation. It is no longer bound to a single source tag: the buyer's licence key is exchanged for the newest release they are entitled to, so the CLI is republished only when the CLI itself changes.

Publish a release to the licensed delivery channel before announcing it:

pnpm release:package -- v1.2.3
pnpm release:upload -- v1.2.3

release:upload refuses a dirty checkout, a tag that is not HEAD, an artifact that disagrees with its checksum file or manifest, and any attempt to republish a tag with different bytes. It writes the three artifacts first and the release index last, so a half-finished upload is never resolvable. The CLI downloads all three artifacts over the licensed channel and refuses malformed, mismatched, or modified ones. It must never download main, HEAD, another mutable branch, or an unverified archive.

Selecting the commercial version, creating the tag and release assets, and publishing are one reviewed release operation—not routine development edits.

The bootstrapper is MIT licensed, declares no runtime dependencies, and is published from a public mirror so that npm provenance can attest it. npm refuses to generate provenance from a private repository, so the private distribution repository must never publish to npm. After pnpm release:distribute places the buyer source in the private repository, publish the CLI with:

pnpm release:publish-cli -- v1.2.3

That mirrors packages/create-app out of the tagged source into superslate-dev/superslate-cli, verifies the mirrored tree still typechecks and builds a CLI reporting its own version, and pushes a cli-vX.Y.Z tag naming that version. The release tag names the immutable source to mirror from and does not have to equal the bootstrapper version: bump packages/create-app when the CLI changes, and the mirror refuses a version it has already tagged. Its workflow triggers on cli-v tags, builds from that public commit, and publishes with provenance. npm trusted publishing for the superslate package must point at that repository and workflow.

Security and support

Security fixes use the same immutable release path, plus coordinated disclosure when needed. The current tag is supported. When an update requires buyer action, the prior tag receives the commercially defined transition window unless continued use is unsafe.

Do not publish exploit details, buyer data, secrets, private repository URLs, or provider credentials in release notes, manifests, CI logs, or artifacts.

Releases