Prepare Sandwich Hime v1 release candidate source

This commit is contained in:
2026-08-23 16:25:02 -04:00
parent c11552b87a
commit efd5b997ed
64 changed files with 5276 additions and 156 deletions
+22
View File
@@ -9,6 +9,28 @@ synthetic cases under the published method. Only reproduced improvements become
marketing claims. Microbenchmarks do not justify claims about request
throughput, database-heavy pages, or whole-application latency.
The threshold was fixed before measuring the RC. On each maintained native
platform and toolchain, ten benchmark samples use the exact output-equivalent
`BenchmarkV1Corpus*` pair. Sandwich Hime passes when its median `ns/op` and
`B/op` are each no more than 125% of `html/template`, and its median
allocations/op are no more than two allocations above `html/template`.
Any failed platform/toolchain pair is a material regression. Timing is reviewed
from raw samples rather than enforced in ordinary CI, where host contention
would turn a performance policy into a flaky correctness gate.
Run:
```sh
cd sando
go test -run '^TestBenchmarkCorpusEquivalent$' \
-bench '^BenchmarkV1Corpus' -benchmem -benchtime=2s -count=10
```
`benchmarkSandoComponent` intentionally mirrors generated writer calls and
captures the same typed view used by the parsed standard template. This is a
runtime renderer microbenchmark; it excludes parsing, compiler execution,
HTTP, routing, logging, databases, and deployment.
Benchmark fixtures must be self-contained, synthetic, reviewable, and committed
to this repository. Application-specific datasets and deployment measurements
belong with their applications and are neither copied here nor treated as core
+20 -5
View File
@@ -30,13 +30,28 @@ compiler versions; `himesan check` defines whether they are current. The
project makes no compatibility promise for internal packages, development SSE
payloads before final v1, or hand-edited generated files.
The v1 compatibility snapshots cover the exported `sando` API and values, CLI
help and exit-code classes, structured operation/version output, diagnostic
codes, `himesan.json`, and generated provenance. English diagnostic wording,
internal packages, temporary paths, and compiler implementation details are not
stable API.
An API deprecated after final v1 remains available for the rest of the v1
major line and may be removed in v2. A security correction may fail closed in
a patch release when retaining old behavior would contradict a published safety
guarantee; that exception receives an advisory and migration note rather than a
silent compatibility claim. Until a broader maintenance policy is announced,
only the latest stable v1 patch and the current prerelease receive fixes.
## Go and platform support
The current beta targets Go 1.25 and Go 1.26 on Linux/amd64. Required release
evidence runs in Linux CI and on Linux deployment hosts. WSL is treated as a
Linux development environment. Native Windows, macOS, and other targets are
not maintained release targets or release blockers; a successful build there
is useful portability evidence, not a compatibility promise. A Go or platform
The modules retain a `go 1.25` language directive for consumer compatibility.
The maintained v1 build and verification targets are Linux/amd64 and Apple
Silicon macOS/arm64 using the pinned patched Go 1.26.7 and Go 1.27.0 toolchains.
Both native targets are release blockers. A sleeping or unavailable Mac delays
the release gate rather than silently converting it into Linux or
cross-compilation evidence. Native Windows, Intel macOS, Linux/arm64, and other
targets may work but are not v1 compatibility promises. A Go or platform
support change is announced in release notes before it takes effect.
### Historical Beta 1 observations
+3
View File
@@ -8,6 +8,9 @@ The application must read its listen address from the configured environment var
## `himesan.json` schema version 1
The machine-readable contract is
[`contracts/himesan-config-v1.schema.json`](../contracts/himesan-config-v1.schema.json).
```json
{
"version": 1,
+24
View File
@@ -21,3 +21,27 @@ Code families are intentionally coarse compatibility surfaces:
| `HIM29xx` | Boundary warnings |
Scripts should consume the JSON `code`, `severity`, and location fields, not parse English messages. Message wording may improve within a compatible release.
The exact v1 code inventory is machine-checked against
[`contracts/diagnostic-codes-v1.txt`](../contracts/diagnostic-codes-v1.txt).
Adding, removing, or renumbering a code requires an explicit compatibility
review and snapshot update.
## CLI and structured-output contract
Command exit codes use three classes: `0` for success (including help and
warning-only results), `1` for a completed operation that failed validation or
runtime service, and `2` for invalid command usage or failure to encode the
requested CLI result. `gen` normalizes to `generate`; `bless` remains a named
read-only alias of `check` in structured output.
The v1 JSON shapes are published as closed schemas:
- [`himesan-operation-output-v1.schema.json`](../contracts/himesan-operation-output-v1.schema.json)
for `generate`, `check`, and `bless`;
- [`himesan-version-output-v1.schema.json`](../contracts/himesan-version-output-v1.schema.json)
for `version --json`.
Unknown output fields are not introduced in a compatible v1 patch without an
explicit schema/version decision. Consumers should still ignore English
message wording.
+48 -14
View File
@@ -25,8 +25,9 @@ is retained only as supplementary Linux evidence. Hostnames, network addresses,
account names, private paths, private repository identities, and private commit
mappings are intentionally absent from this public ledger. These platform
observations are historical evidence, not the current support matrix.
Linux/amd64 is now the maintained release target; WSL is a Linux development
environment, while native Windows and macOS are not release blockers.
Linux/amd64 and Darwin/arm64 are now the maintained v1 release targets. This
section retains historical Beta 1 evidence; the exact RC must supply new native
evidence on both targets. WSL and native Windows are not v1 release blockers.
## Beta 2 compiler publication addendum
@@ -82,11 +83,11 @@ baseline commit.
| Parser robustness smoke | Two bounded Go fuzz targets | Pass; no panic found |
| Deterministic generation | repeated generate/check/hash/mtime gates | Pass |
| Writer failures | runtime error/short-write/nil-writer tests | Pass |
| HTML text/attribute/RCDATA escaping | compiler and runtime adversarial cases | Pass for enumerated cases |
| URL scheme handling | ordinary/trusted URL test matrix | Pass for enumerated cases |
| HTML text/attribute/RCDATA escaping | compiler/runtime adversarial cases plus the committed `html/template` overlap corpus | Pass for the committed corpus; documented stricter invalid-UTF-8 handling remains intentional |
| URL scheme handling | ordinary/trusted URL matrices plus safe, unsafe, and intentionally divergent `html/template` cases | Pass for the committed corpus; control rejection and the explicit `tel` allowlist are documented policy differences |
| Filesystem boundaries | symlink, nested-module, VCS, ownership, stale-output tests | Pass for tested cases; see open findings |
| Development proxy browser boundary | Host, Origin, Fetch Metadata, CSP, fragment and response tests | Pass for tested cases |
| Platform behavior | Historical exact-candidate native Windows and executed Linux matrices | Windows/Linux passed for the tested lanes; current releases require Linux/amd64 evidence |
| Platform behavior | Historical exact-candidate native Windows and executed Linux matrices | Windows/Linux passed for the tested lanes; the v1 RC requires fresh Linux/amd64 and Darwin/arm64 evidence |
Coverage measures statements executed by tests. It is not branch completeness
and is not evidence that the executed behavior is secure.
@@ -105,7 +106,7 @@ independent audit.
| Windows 11/amd64, NTFS | 1.25.12, 1.26.5 | Native PowerShell verifier with race; root/runtime tests, vet, trimpath build, freshness, two generation passes, process-tree cleanup, watcher boundaries, and temporary consumer compilation | Pass. Symlink-output rejection skipped because the test account lacked symlink privilege; the read-only-directory case is POSIX-only |
| Ubuntu 20.04/amd64 under WSL2, native ext4 checkout | 1.25.12, 1.26.5 | Race-enabled verifier; root/runtime tests, vet, build, two generation passes, ten focused filesystem cases, five focused development-process/watcher cases, and license check | Pass. This is Linux execution under WSL2, not bare-metal or Linux/arm64 evidence |
| Linux/amd64 server containers | 1.25.12, 1.26.5 | Earlier pre-beta root/runtime tests, vet, builds, race, licensing, and deterministic generation in sequential isolated official Go containers | Pass on the earlier baseline only. Container resources were capped at 1 CPU and 2 GiB; this is supplementary evidence, not an exact Beta 1 lane or Linux/arm64 evidence |
| macOS | — | Cross-compilation only | No native Beta 1 evidence; not a maintained release target |
| macOS | — | Cross-compilation only | No native Beta 1 evidence; Darwin/arm64 becomes a maintained target at the v1 RC and requires fresh evidence |
The generated golden `basic.sando.go` was 1,399 bytes and had SHA-256
`63fa75a3049a3a8a12d769d7f9b6b510dfe763baacf706775b75cef2c57a984f`
@@ -118,7 +119,7 @@ architecture, `go version`, exact command, and a minimal reproduction.
Suspected vulnerabilities use the private route in
[SECURITY.md](../SECURITY.md). Such reports help find gaps but do not create a
support promise; maintainers remain responsible for security triage and fixes
on the supported Linux target.
on both supported native targets.
## Security-relevant design evidence
@@ -183,8 +184,13 @@ go test ./internal/compiler -run '^$' \
./scripts/verify-public-install.sh --version v1.0.0-beta.1
```
The fuzz targets currently assert process robustness and result bounds. They do
not yet prove semantic HTML safety.
Those historical Beta 1 fuzz targets asserted process robustness and result
bounds; they did not prove semantic HTML safety. The v1 compiler target now
also asserts deterministic diagnostics and generated Go, valid formatted Go,
source-digest binding, bounded public diagnostic shape, and sanitized source
map directives. A separate runtime target asserts deterministic, fail-closed
URL handling with no partial output. These properties still do not replace the
committed differential corpus or real-browser testing.
## Assessment findings and remediation status
@@ -207,8 +213,8 @@ and executed Linux matrices, and Windows/macOS cross-compilation on 2026-08-12.
Signed annotated runtime and compiler tags were then published from that commit
in that order. Fresh runtime-first installation passed through both direct Git
resolution and the public Go proxy after normal proxy propagation. Future
release decisions use the current Linux-only support policy rather than
requiring this historical multi-platform campaign.
release decisions require fresh evidence for the maintained Linux/amd64 and
Darwin/arm64 targets rather than reusing this historical campaign.
## Open assurance gaps
@@ -218,9 +224,10 @@ requiring this historical multi-platform campaign.
- the signed annotated Beta tags and their common peeled commit were verified;
prebuilt-artifact signing, checksums, SBOM, reproducible provenance, and key
recovery remain incomplete;
- Linux/arm64 and non-Linux portability are outside the current maintained
release target;
- browser-parser differential and semantic property testing need expansion;
- Linux/arm64, Darwin/amd64, Windows, and other targets are outside the current
maintained release set;
- the exact public candidate still needs the committed real-browser generated
document and development-supervisor campaign on both maintained hosts;
- compiler input size, CPU, and memory have no built-in hard budget;
- filesystem checks do not defend against a hostile local actor racing path
components between inspection and use;
@@ -234,6 +241,33 @@ requiring this historical multi-platform campaign.
- static cycle detection and trust-use warnings are best-effort analyses; and
- the project has no independent security audit or bug-bounty program.
## v1 disposition of open gaps
The list above intentionally mixes incomplete release evidence with boundaries
that are not promised by this product. The RC may not convert either category
into vague assurance. The following disposition is explicit and remains
subject to exact-public-candidate review:
| Gap | v1 disposition |
| --- | --- |
| Security mailbox delivery, backup, and recovery | Release blocker. Complete the delivery/reply and recovery drill before RC publication. Encrypted reporting may remain optional if the supported confidential channel and its limit are stated accurately. |
| Artifact signing, provenance, and key recovery | Release blocker. Complete deterministic native artifacts, Developer ID notarization, signed-tag rehearsal, and recovery evidence. |
| Maintained native matrix | Release blocker for Linux/amd64 and Darwin/arm64 only. Other architectures and operating systems are explicitly unsupported, not silently untested promises. |
| Real-browser parser and supervisor evidence | Release blocker. The repository-owned gate covers a generated typed document, parsed structure, hostile-value inertness, and supervisor behavior. Execute it against the exact public candidate on both maintained hosts before publication. |
| Compiler resource budgets | Accepted v1 boundary. The compiler is a trusted local build tool; operating-system and runner limits own CPU, memory, and input quotas. No hostile-input resource guarantee is made. |
| Hostile local filesystem races | Accepted v1 boundary. Symlinks and ownership are checked, but an actor able to mutate the workspace concurrently is outside the trust model. |
| Watcher integrity | Accepted v1 boundary. Watching is development convenience; explicit `check`, generation, Go tests, and builds remain release/deployment authority. |
| Human-readable child diagnostics | Accepted v1 boundary. They are bounded for resources but remain trusted local terminal output, not a sanitized telemetry format. |
| Development CSP rewriting | Accepted v1 boundary. It enables reload on trusted loopback pages and is not production CSP validation. |
| Deliberately detached descendants | Accepted v1 boundary. Ordinary process groups are terminated and waited for; adversarial detachment is outside the trusted-project development model. |
| Render recursion, output, panic, allocation, CPU, and deadlines | Accepted v1 boundary. Components are ordinary trusted Go; applications own recovery, deadlines, and resource policy. |
| Static cycles and trust warnings | Accepted v1 boundary. They are documented best-effort audit hints and never replace Go review/tests or explicit trust decisions. |
| Independent audit and bug bounty | Accepted disclosure, not a security claim. Neither exists for RC. Public tests, threat model, reporting, and correction policy must not be described as an independent audit. |
An accepted boundary is permitted only because matching compatibility, threat
model, and release copy already avoid the stronger promise. Any conflicting
marketing or documentation reopens the item as a release blocker.
## Interpreting this ledger
“Pass” means the named command or case produced its expected result in the named
+2 -1
View File
@@ -177,7 +177,8 @@ Sandwich Hime does not:
## Open release work
- broaden semantic and browser-parser differential testing;
- execute the Linux/amd64 security and process-lifecycle release matrix;
- execute the Linux/amd64 and Darwin/arm64 security and process-lifecycle
release matrices;
- complete signed release provenance, checksums, and SBOM evidence;
- test the confidential reporting and signing-key recovery procedures; and
- close or explicitly accept every finding listed in the evidence ledger before
+39 -32
View File
@@ -28,7 +28,7 @@ private history or an indiscriminate Git mirror.
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, Linux release, artifact, signing, or soak gates are complete.
v1 compatibility, native release, artifact, signing, or soak gates are complete.
### Demonstrated for Beta 1
@@ -38,8 +38,8 @@ Public commit `b7a84054d755e42285e50298e41e47f06a8325a5` (tree
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 is now the maintained release
target.
not the current support definition; Linux/amd64 and Darwin/arm64 are the
maintained v1 release targets.
Other demonstrated controls include:
@@ -53,15 +53,16 @@ Other demonstrated controls include:
### Not demonstrated yet
- final Linux/amd64 release-candidate evidence on the exact candidate;
- stable final-v1 API, CLI, schema, diagnostic, and generated snapshots;
- systematic browser-parser and `html/template` differential testing;
- final Linux/amd64 and Darwin/arm64 release-candidate evidence on the exact
canonical candidate;
- exact-public-candidate execution of the committed real-browser generated
document and development-supervisor gate on both maintained hosts;
- a long semantic fuzz campaign beyond bounded no-panic smoke;
- committed comparative benchmarks and predefined regression thresholds;
- complete real-browser development-supervisor evidence;
- exact-candidate comparative benchmark results on both maintained targets;
- deterministic prebuilt archives, checksums, SBOMs, signed binaries, and
tested signing/recovery procedures; or
- independently reproduced Linux release artifacts, checksums, and SBOMs.
- independently reproduced Linux and macOS release artifacts, checksums, and
SBOMs.
## Beta 1 publication lane
@@ -82,45 +83,50 @@ dependency, and its interfaces may change.
## Milestone 1: contract freeze
Required before security/Linux release-candidate work is declared complete:
Required before security/native release-candidate work is declared complete:
- [ ] Decide and specify whether generic component function signatures are v1.
- [ ] Inventory and freeze every exported `sando` symbol, trusted type,
- [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.
- [ ] Freeze CLI commands, exit-code meanings, diagnostic codes, JSON schemas,
- [x] Freeze CLI commands, exit-code meanings, diagnostic codes, JSON schemas,
`himesan.json` schema, and generated provenance fields.
- [ ] Specify nil/stringification behavior, supported HTML-context matrix,
- [x] Specify nil/stringification behavior, supported HTML-context matrix,
component trust boundary, URL semantics, and explicit unsupported cases.
- [ ] Add machine-checked public API, CLI, diagnostic, schema, and generated
- [x] Add machine-checked public API, CLI, diagnostic, schema, and generated
output compatibility snapshots.
- [ ] Define the v1 deprecation and security-support policy.
- [x] Define the v1 deprecation and security-support policy.
## Milestone 2: security and Linux release evidence
## Milestone 2: security and native release evidence
- [ ] Run the minimum supported Go line and the latest two stable Go lines on
Linux/amd64 runners and a Linux deployment-class host.
- [ ] Prove identical generated bytes across those Linux lanes and exercise
- [ ] 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.
- [ ] Prove identical generated bytes across both native platforms and exercise
path, replacement, permission, race, process-tree, and watcher behavior.
- [ ] Build a systematic differential corpus against Go's documented
- [x] Build a systematic differential corpus against Go's documented
`html/template` safety baseline for overlapping supported contexts.
- [ ] Parse representative outputs in real browsers and test structure/code
invariants rather than only byte equality.
- [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.
- [ ] 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`.
- [ ] Define severity, advisory, retraction, and CVE-request handling.
- [x] Define severity, advisory, retraction, and CVE-request handling.
## Milestone 3: measured performance and development UX
- [ ] Commit a synthetic, repository-owned benchmark corpus comparing
- [x] Commit a synthetic, repository-owned benchmark corpus comparing
equivalent typed views and output with `html/template`.
- [ ] Define “no material regression” before measuring the release candidate;
publish hardware, OS, Go version, commands, samples, allocations, and output
equivalence with every result.
- [ ] Test SSE reconnect, reload, diagnostic overlays, CSP changes, fragment/API
exclusions, caching, and child cleanup in a real browser on supported hosts.
- [x] Define “no material regression” before measuring the release candidate.
- [ ] Measure the exact release candidate and publish 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.
- [ ] 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.
@@ -134,7 +140,7 @@ Required before security/Linux release-candidate work is declared complete:
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.
- [ ] Make evidence gates validate content and commit identity rather than only
- [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.
@@ -145,7 +151,8 @@ Required before security/Linux release-candidate work is declared complete:
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.
`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,