sandwich-hime/RELEASE.md

Release process

Sandwich Hime uses separate root and runtime version lines. Compiler tags are vX.Y.Z; runtime tags are sando/vX.Y.Z. Generated headers record both the compiler version and runtime ABI. The runtime is always published before the compiler that references it.

Every tag is immutable. A failed publication is corrected with a new version, never by moving or replacing a tag.

What the version stages mean

Beta

A beta is an installable public evaluation release. The current v1.0.0-beta.1 scope is learning, classroom projects, prototypes, and compatibility feedback. It receives best-effort security assessment and fixes while it is the current prerelease, but it is not recommended or supported as a production-stable dependency. Syntax, generated output, runtime APIs, CLI behavior, and diagnostics may change in a later prerelease.

Beta 1 and Beta 2 retain their historical platform evidence. The v1 RC line raises the maintained release gate to native Linux/amd64 and Apple Silicon macOS/arm64. WSL, native Windows, Intel macOS, and other targets remain useful portability input but are not v1 release blockers or maintained promises.

Beta tags are signed, annotated, and immutable. Beta 1 is a source/module release installed through the Go toolchain; it does not promise downloadable prebuilt binaries. Signed binary artifacts, checksums, SBOMs, reproducible archives, and key-recovery rehearsal are mandatory for release candidates and final v1.

Release candidate

An RC means the intended v1 source, runtime, CLI, diagnostics, schemas, and generated contract are frozen except for release-blocking fixes. An RC requires maintainer-run Linux/amd64 and native macOS/arm64 evidence, complete release artifacts and provenance, signed tags, clean direct/proxy installs, and every RC gate in this repository. Findings produce a new RC rather than a moved tag.

Final v1

Final v1 is the compatibility and support commitment. It requires the complete repository-owned evidence campaign, resolution or explicit acceptance of every published assurance gap, and the documented RC observation period. A deployment, example, classroom project, or case study in another repository is neither imported nor required as release evidence.

Beta 1 publication gates (historical)

The first beta used a broader one-time platform campaign. The completed items below are retained as publication history; they do not define future platform support.

Before sando/v1.0.0-beta.1 and v1.0.0-beta.1 are created:

1. Use a clean reviewed canonical public commit with no private identifiers, paths, credentials, or history.
2. Run license, root/runtime test, vet, build, race, deterministic-generation, and candidate-version freshness checks on supported Go 1.25 and Go 1.26 lanes on Windows and Linux.
3. Confirm generated bytes match across those exact-candidate lanes and record all skips or platform limitations.
4. Run the bounded fuzz and known-vulnerability checks from a clean release host.
5. Review the changelog, security policy, compatibility policy, support scope, provisional macOS wording, and vanity-import metadata.
6. Build the candidate compiler at its candidate version and prove its committed generated fixtures are current under that exact binary.
7. Create signed annotated tags and publish the runtime tag first, then the compiler tag, from the same reviewed commit.
8. Verify both documented runtime-first installs from fresh GOPROXY=direct and public-proxy caches. Record propagation delays as delays, not test passes.

Beta 1 was published from public commit b7a84054d755e42285e50298e41e47f06a8325a5 (tree be9e118e38dfebed19f60403ededdadabe07d2aa) after its exact-candidate matrix passed. Future prereleases require their own candidate evidence; this result cannot be relabeled for another commit.

Beta 2 compiler publication gates

v1.0.0-beta.2 is compiler-only. Do not create or move a runtime tag when the sando subtree is byte-identical to sando/v1.0.0-beta.1.

Run its technical preflight with the retained runtime made explicit:

./scripts/release-check.sh \
  --version v1.0.0-beta.2 \
  --runtime-tag sando/v1.0.0-beta.1

In addition to every Beta 1 compiler/security/determinism gate:

1. verify protocol framing, malformed messages, shutdown, request cancellation, UTF-16 positions, CRLF/NUL handling, bounded fuzz smoke, overlays, source appearance/deletion, duplicates, cycles, symlink and nested-module boundaries, completion scope, and component definitions;
2. prove the language-server package does not write, execute project code, invoke Go, fetch, access the network, or start the development supervisor;
3. run the exact candidate on supported Go lines under executed Linux/amd64;
4. build an exact version-stamped candidate and assert the additive features: ["lsp-stdio"] JSON identity;
5. publish a signed annotated compiler tag only after the reviewed sanitized public commit is current; and
6. verify direct, public-proxy, and checksum-database installation without altering v1.0.0-beta.1 or sando/v1.0.0-beta.1.

RC and final gates

No release candidate or v1.0.0 release occurs until every applicable gate in this repository is evidenced, including deterministic generation on supported Linux and Go lanes, temporary-module compilation, fuzz/adversarial suites, race/vet/vulnerability/license checks on the latest two supported Go lines, development-supervisor failure tests, and reproducible repository-owned benchmark and security results.

Release candidates require a clean canonical checkout, reviewed changelog, compatible vanity-import metadata, reproducible Linux/amd64 and Darwin/arm64 binaries, signed annotated tags, checksums, SBOMs, vulnerability results, and verification on both maintained native targets. Darwin artifacts additionally require manual Developer ID signing, notarization, stapling, and Gatekeeper validation outside runner authority.

Human-reviewed RC evidence stays outside the source tree. After completing the fixed document set reported by himesan-release verify-evidence, the release operator seals its exact bytes and source identity once:

go run ./cmd/himesan-release evidence-manifest \
  --directory "$HIMESAN_RELEASE_EVIDENCE_DIR" \
  --repository gamertan/sandwich-hime \
  --version v1.0.0-rc.1 \
  --commit "$(git rev-parse HEAD)" \
  --tree "$(git rev-parse 'HEAD^{tree}')" \
  --reviewed-by "REVIEWER" \
  --reviewed-at "YYYY-MM-DDTHH:MM:SSZ"

The manifest is created without overwrite. Changing any document or candidate identity requires a fresh review directory and manifest; deleting a manifest is not an approval shortcut. release-check.sh --public verifies the sealed digests and identities but never substitutes for the human review itself.

Native receipts use an equally strict, extraction-scratch-free layout. Download runner ZIPs outside this directory, then copy only each checksummed receipt pair into the exact four lanes:

$HIMESAN_NATIVE_EVIDENCE_DIR/
├── darwin-arm64-go1.26.7/TEND-CI-VERIFICATION.json{,.sha256}
├── darwin-arm64-go1.27.0/TEND-CI-VERIFICATION.json{,.sha256}
├── linux-amd64-go1.26.7/TEND-CI-VERIFICATION.json{,.sha256}
└── linux-amd64-go1.27.0/TEND-CI-VERIFICATION.json{,.sha256}

ZIPs, additional files, renamed lanes, development-repository identities, and receipts for a public commit other than current canonical main are rejected. The strict layout prevents extraction debris or a nearby historical run from being mistaken for the reviewed native receipt set.

Public source and artifacts

Gitea is the only canonical public forge. Public source is exported into a separate, sanitized Gitea repository with fresh reviewed history. A sanitized GitHub discovery snapshot may copy reviewed public source, but it is not an issue, contribution, release, or module origin and must never receive private development refs or an indiscriminate Git mirror. Release binaries and provenance are built from the reviewed canonical Gitea commit.

The hosting configuration must answer exact package discovery requests, not only module-root pages. In particular, /sandwich-hime/cmd/himesan?go-get=1 returns compiler metadata and the /sandwich-hime/sando subtree returns runtime metadata. After tags and public metadata exist, run:

scripts/verify-public-install.sh --version vX.Y.Z

That check adds the nested runtime before installing the parent compiler, then exercises both commands from fresh direct-fetch and public-proxy caches. The order avoids the Go module-cache ambiguity documented for Beta 1. It is separate from the pre-tag, read-only scripts/release-check.sh.

Release notes report hardware, commit, datasets, commands, ns/op, allocations, response latency, and methodology for any performance claim. “Fastest” or equivalent language is prohibited without durable, reproducible evidence.

Production applications compile and deploy their committed .sando.go files with the Apache-2.0 sando runtime. They do not need the AGPL compiler or the local development supervisor. Release checks verify that boundary without executing or inspecting an unrelated application repository.