Stacks protocol

The vendored protocol suite, the Stacks conformance adapter, and the release evidence tooling. This repository owns the governance material that used to live under .github/protocol/ and storage/framework/core/buddy/src/commands/protocol/ in stacksjs/stacks.

Every command here inspects a Stacks checkout rather than the repository it ships in, so the implementation under review and the tooling that reviews it version independently.

Setup

bun install

Pointing at a Stacks checkout

Resolution order, first match wins:

1. --stacks <path> on any command
2. the STACKS_ROOT environment variable
3. ../stacks, relative to this repository

The path must be a Git working tree, and manifest/release need full history and tags — they read immutable Git objects, which a shallow clone cannot see.

Commands

bun run check            # the vendored suite matches its lock, catalog + fixtures are sound
bun run sync             # re-vendor the suite from a local stacksjs/rfcs checkout
bun run conformance      # execute the adapter against Stacks and write a report
bun run manifest         # pin an immutable Stacks source revision
bun run release          # map a Stacks release tag to its packages
bun run drivers          # generate the driver capability evidence
bun run drivers:test     # run the supported-driver contract matrix
bun run desktop          # generate the desktop support matrix evidence
bun run pantry           # generate the Pantry toolchain evidence
bun run craft            # generate the Craft packaging evidence

Each generator has a :check counterpart that regenerates in memory and fails if the committed artifact is stale or hand-edited. Those are what CI runs.

The suite

Stacks consumes the canonical protocol suite from stacksjs/rfcs. The files below suite/1.0-draft are a generated, immutable snapshot: do not edit them by hand.

• suite.lock.json records the exact RFC commit and SHA-256 digest of every file.
• bun run check rejects missing, changed, or extra vendored files, then validates that catalog requirement ids are unique and that every fixture resolves to a real requirement.
• bun run sync -- --source ../rfcs intentionally refreshes the snapshot from a local RFC checkout and rewrites the lock.
• bun run conformance executes the Stacks adapter, validates the resulting JSON against the canonical schema, and writes JSON and Markdown evidence to the ignored reports/ directory.

The adapter does not infer conformance from an existing unit test. A result only becomes pass when the corresponding protocol fixture is executed through a public Stacks API and linked to revision-specific evidence. Until every inherited requirement passes, profileClaim remains null.

The evidence

evidence/source-manifest.json is a deterministic inventory of an immutable Stacks Git revision. Its digest is SHA-256 over the complete recursive Git tree listing (modes, blob identities, sizes, and paths). It separates source, tests, generated output, configuration, documentation, and assets; records every versioned workspace package and runtime prerequisite; and states the implementation's non-certifying classification. Refresh it explicitly with bun run manifest, then review and commit the resulting snapshot.

evidence/release-manifest.json maps an exact semantic release tag to its peeled commit, tree, digest, runtime prerequisites, and every versioned package at that revision. The tag version must match storage/framework/package.json; the private root package is an independently versioned monorepo orchestrator and is recorded rather than treated as the released package. Refresh a reviewed release with bun run release -- --tag vX.Y.Z. CI resolves the tag again and rejects moved tags, mismatched package versions, stale snapshots, and manual edits.

evidence/drivers.json is generated from the runtime capability registry used by configuration validation. Each database, queue, cache, storage, mail, realtime, and deployment driver is classified as supported, partial, experimental, or unsupported, with implementation paths, test evidence, topology, prerequisites, and explicit limitations. CI rejects stale evidence and operational entries whose implementation or cited tests do not exist.

evidence/desktop-support.json is generated from the Craft support policy. A target cannot become stable until native install/launch and update/rollback evidence is linked and signing (plus macOS notarization) is enforced. The build also refuses a stable channel for unqualified targets and emits exact source, runtime digest, per-file SHA-256 checksums, and platform metadata.

evidence/craft.json pins the exact Craft source tag, commit, packaging code, MSI contract, native lifecycle workflow, and release workflow used by the desktop matrix. The desktop-lifecycle workflow re-runs that immutable source on four native GitHub runner targets and validates the retained report before attesting it. Packaging evidence and release evidence remain separate: unsigned install/update/rollback fixtures do not satisfy signing, notarization, or stable support gates.

evidence/pantry.json pins the Pantry toolchain release, its documentation contracts, and its Redis service contracts by digest.