sandwich-hime/docs/V1_RELEASE_PLAN.md

<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# v1.0.0 launch initiative

Sandwich Hime v1 is a compatibility and evidence milestone, not a reason to
accumulate features. The intended product is already visible: an HTML-first,
ahead-of-time template engine for Go, typed generated components, a small
HTTP-independent runtime, and an optional opinionated local development loop.

Development records may remain private, but their repository names, branch
names, paths, commit mappings, and history are not release provenance. Public
releases originate only from the reviewed canonical public tree.

## Repository and publication topology

| Surface | Purpose | History and tags |
| --- | --- | --- |
| Private development storage | Working branches, private review records, and historical context | identities and history are not exported; no public release tags |
| Public Gitea `sandwich-hime` | Canonical sanitized source, contribution venue, module origin, and releases | fresh reviewed history; authoritative immutable `sando/vX.Y.Z` and `vX.Y.Z` tags |
| GitHub `gamertan/sandwich-hime` | Discoverability and a convenient sanitized source snapshot | no private refs, force-mirrors, workflows, contribution authority, release artifacts, or semver tags |

Each public update is exported through the exact committed allowlist, inspected,
committed as a fresh public snapshot, and compared byte-for-byte with the
reviewed export. GitHub receives that public tree only. It never receives
private history or an indiscriminate Git mirror.

## Current readiness

Beta 1 is deliberately earlier than a release candidate. It creates a real,
repeatable install for learners and evaluators without claiming that the final
v1 compatibility, native release, artifact, signing, or soak gates are complete.

### Demonstrated for Beta 1

Public commit `b7a84054d755e42285e50298e41e47f06a8325a5` (tree
`be9e118e38dfebed19f60403ededdadabe07d2aa`) passed maintainer-run Go
1.25.12 and Go 1.26.5 matrices on native Windows/amd64 and Linux/amd64 under
WSL2, with the earlier pre-beta server-container run retained only as
supplementary Linux evidence. The same generated golden SHA-256 was observed
across the exact Beta Windows and Linux lanes. This is historical evidence,
not the current support definition; Linux/amd64 and Darwin/arm64 are the
maintained v1 release targets.

Other demonstrated controls include:

- zero third-party Go module requirements in the compiler and nested `sando`
  runtime;
- a version-specific compile-time runtime ABI marker;
- owned-output, orphan, stale, symlink, nested-module, permission, last-good,
  writer-error, and enumerated contextual-output tests;
- loopback-only, browser-origin-hardened development proxy behavior; and
- a public threat model, security policy, and dated evidence ledger.

### Demonstrated for the first RC candidate

- native Linux/amd64 and Darwin/arm64 release-candidate lanes on pinned Go
  1.26.7 and Go 1.27.0 toolchains;
- exact-public-candidate execution of the committed real-browser generated
  document and development-supervisor gates;
- a long semantic fuzz campaign beyond bounded no-panic smoke;
- exact-candidate comparative benchmark results;
- deterministic prebuilt archives, checksums, SPDX SBOMs, and provenance;
- Developer ID signing, notarization, stapling, and Gatekeeper validation for
  the Darwin/arm64 distribution; and
- byte-identical generated output and independently reproduced release
  archives across the maintained native evidence lanes.

The final immutable tags, clean direct/proxy installation, credential-recovery
drills, and public observation period remain publication or post-publication
gates rather than properties that source code can prove by itself.

## Beta 1 publication lane

Beta 1 is supported for learning, classroom projects, evaluation, prototypes,
and compatibility feedback. It is not recommended as a production-stable
dependency, and its interfaces may change.

- [x] Define beta support, security, and compatibility language.
- [x] Establish the historical public pre-beta Linux/Windows evidence baseline.
- [x] Rerun the supported Go matrix and deterministic generation on the exact
  Beta 1 candidate.
- [x] Run the candidate-version freshness, bounded fuzz, vulnerability, and
  license gates.
- [x] Publish immutable `sando/v1.0.0-beta.1`, then
  `v1.0.0-beta.1`, from the same reviewed public commit.
- [x] Verify clean runtime-first direct and public-proxy installs and record the
  result.

## Milestone 1: contract freeze

Required before security/native release-candidate work is declared complete:

- [x] Specify generic component function signatures as ordinary Go-backed v1
  APIs and compile them in a temporary consumer module.
- [x] Inventory and freeze every exported `sando` symbol, trusted type,
  sentinel error, concrete error field, helper, and ABI marker.
- [x] Freeze CLI commands, exit-code meanings, diagnostic codes, JSON schemas,
  `himesan.json` schema, and generated provenance fields.
- [x] Specify nil/stringification behavior, supported HTML-context matrix,
  component trust boundary, URL semantics, and explicit unsupported cases.
- [x] Add machine-checked public API, CLI, diagnostic, schema, and generated
  output compatibility snapshots.
- [x] Define the v1 deprecation and security-support policy.

## Milestone 2: security and native release evidence

- [x] Run the pinned patched Go 1.26 and Go 1.27 lines on Linux/amd64 and
  native Darwin/arm64 runners, plus a Linux deployment-class host.
- [x] Prove identical generated bytes across both native platforms and exercise
  path, replacement, permission, race, process-tree, and watcher behavior.
- [x] Build a systematic differential corpus against Go's documented
  `html/template` safety baseline for overlapping supported contexts.
- [x] Commit a real-browser gate that generates and builds a representative
  typed document, then tests parsed structure and hostile-value inertness in
  Chrome rather than relying only on byte equality.
- [x] Extend semantic fuzzing across delimiters, HTML transitions, imports,
  paths, source maps, URL normalization, and filesystem operations.
- [ ] Resolve or explicitly accept every open item in
  `SECURITY_EVIDENCE.md`; no accepted item may contradict a public guarantee.
- [ ] Test delivery and reply through `security@sandwichhime.com`.
- [x] Define severity, advisory, retraction, and CVE-request handling.

## Milestone 3: measured performance and development UX

- [x] Commit a synthetic, repository-owned benchmark corpus comparing
  equivalent typed views and output with `html/template`.
- [x] Define “no material regression” before measuring the release candidate.
- [x] Measure the exact release candidate and preserve hardware, OS, Go version,
  commands, samples, allocations, and output equivalence with every result.
- [x] Commit a real-browser development-supervisor gate covering SSE
  diagnostics, reload, CSP behavior, fragment/API exclusions, caching, and
  child cleanup.
- [x] Execute the committed browser gate on the exact public candidate on both
  maintained hosts and preserve the browser identities and results.
- [ ] Remove any v1 development-supervisor guarantee that cannot be evidenced
  reliably instead of substituting prose for a test.

## Milestone 4: release rehearsal

- [x] Make version validation identical in the CLI, generated headers, scripts,
  and release artifacts; reject ambiguous build metadata.
- [x] Build the candidate compiler at its candidate version and prove its
  committed outputs are current under that exact binary.
- [x] Produce deterministic archives/binaries, checksums, SBOMs, signatures,
  and source/build provenance from a clean sanitized canonical checkout.
- [ ] Test release-key backup and two-person recovery for Gitea, domains,
  signing material, and publication instructions.
- [x] Make evidence gates validate content and commit identity rather than only
  the presence of non-empty files.
- [ ] Rehearse runtime-first publication and rollback without creating public
  semver tags.

## Milestone 5: release candidates and final launch

1. Export and review the sanitized canonical release tree.
2. Publish signed `sando/v1.0.0-rc.1`, then signed `v1.0.0-rc.1` from the same
   reviewed public Gitea commit.
3. Verify documented installs through fresh `GOPROXY=direct` and
   `proxy.golang.org` caches on supported Go versions under Linux/amd64 and
   Darwin/arm64.
4. Run the complete evidence suite again from the exact public commit.
5. Operate the official Sandwich Hime website on the RC runtime for a 14-day
   observation period with no unresolved Hime render, security, accessibility,
   or rollback regression. This is product dogfooding, not a dependency on
   another application's private repository.
6. Fix findings in a new RC; restart the observation period when the affected
   boundary warrants it.
7. Finalize the changelog, supported-version table, migration notes, release
   notes, legal/trademark review, checksums, SBOMs, and signatures.
8. Publish `sando/v1.0.0` first and `v1.0.0` second. Never move a tag.
9. Refresh the untagged GitHub discovery snapshot and point it to canonical
   Gitea releases and contribution channels.

## Explicitly deferrable after v1

Unless testing finds a release-blocking consequence, v1 need not include every
possible context, hostile-local filesystem hardening, typed trust-flow analysis,
complete dynamic cycle detection, an encrypted reporting key, or an external
audit. Those limits must remain visible and must not be contradicted by
marketing. New features do not outrank a small stable contract.

## Definition of confidence

“Ready for v1” means a reviewer can trace each promise to a stable public
contract, executable evidence from supported Linux environments, and a signed
artifact built from the exact canonical source. It does not mean perfect,
invulnerable, or finished forever.