Documentation Source Sitemap Source Markdown

Bootstrap Seed Contract

The bootstrap seed is the trusted stage0 entry point for rebuilding the Vitte toolchain without repo-hosted host-language sources.

Files

• Canonical readable source: toolchain/seed/src/main.vit
• Audited executable artifact: toolchain/seed/vittec0.seed
• Pinning manifest: toolchain/seed/manifest.txt

toolchain/seed/manifest.txt records the seed source path, artifact path, artifact SHA-256, and expected --version output. make seed-verify checks the manifest hash against the artifact and validates the version string.

The readable source is the canonical intent for review. The executable artifact is the stage0 trust root actually run by bootstrap scripts. make seed-verify keeps the two tied at the identity boundary by checking that source VERSION_TEXT, manifest version=..., and vittec0.seed --version match.

Change Rule

Any intentional seed rotation must update these contracts together:

• toolchain/seed/src/main.vit when the readable seed behavior changes.
• toolchain/seed/vittec0.seed when the executable seed artifact changes.
• toolchain/seed/manifest.txt when the artifact bytes or version change.
• tests/bootstrap_native/* snapshots when generated native output changes.
• CI must pass, including make seed-verify and make bootstrap-native-snapshots.

The seed artifact must not change on its own. A change to toolchain/seed/vittec0.seed without a matching toolchain/seed/manifest.txt change is treated as seed drift and fails make seed-contract-check.

Rotation Checklist

1. Modify toolchain/seed/src/main.vit.
2. Regenerate or edit toolchain/seed/vittec0.seed.
3. Run make seed-rotation-report to inspect the current artifact hash and version.
4. Run make seed-manifest-update to rewrite toolchain/seed/manifest.txt from the audited artifact and source VERSION_TEXT.
5. Run make bootstrap-native-snapshots.
6. Run make bootstrap-verify.
7. Run make seed-contract-check.

Local Checks

make seed-verify
make seed-rotation-report
make posix-seed-shell-check
make bootstrap-native-snapshots
make seed-contract-check
make bootstrap-native-drift-check
make bootstrap-posix-smoke

Bootstrap example

make stage0
make stage1
make stage2

Run this sequence in one workspace only. stage0 builds the trusted seed, stage1 rebuilds the compiler from that seed, and stage2 reconfirms the output by rebuilding it again.

Local Parallelism

CI jobs run in isolated workspaces, so their bootstrap artifacts do not collide. In one local worktree, bootstrap targets that rebuild the stage chain are not parallel-safe because they rewrite shared bin/vittec0, bin/vittec1, bin/vittec, and bin/vitte artifacts.

The single-workspace runner rule is:

• make bootstrap-native-snapshots installs the seed and mutates bin/vittec0.
• make bootstrap-verify rebuilds bin/vittec1, bin/vittec, and bin/vitte.
• make bootstrap-posix-smoke depends on bootstrap-all, so it also rebuilds the stage artifacts before running POSIX checks.
• make bootstrap-native-contract composes those flows and should be treated as an exclusive bootstrap runner in a local worktree.

tools/bootstrap_native_snapshots.sh and tools/bootstrap_posix_smoke.sh use per-run temporary directories under target/ and clean them on exit, but the shared bin/vittec* artifacts are intentionally not isolated. Avoid running bootstrap targets concurrently in the same worktree.

Source Coverage

The readable seed and stage sources should exercise the current bootstrap-native forms they rely on:

• toolchain/seed/src/main.vit must include named string constants, named int constants, proc main(args: list[string]) -> int, and a named constant return.
• toolchain/stage2/src/main.vit must include named VERSION_TEXT and BANNER_TEXT string constants, use a named string constant in version_text(), and define main.

This is checked by make bootstrap-source-coverage-check and is included in the bootstrap-native contract targets.

For CI or release checks, SEED_CONTRACT_BASE may be set to the base commit or branch used for the diff:

SEED_CONTRACT_BASE=origin/main make seed-contract-check

AWK Native Parser Contract

toolchain/seed/vittec0.seed contains a small AWK parser inside compile_native_ir(). This parser is not a general Vitte parser. Its contract is to recognize only the bootstrap-native subset documented in docs/bootstrap_native_ir.md, emit deterministic native_ir_v1 text, and fail closed on anything outside that subset.

Review rules for the AWK block:

• Keep accepted forms explicit and line-oriented.
• Prefer adding a fixture before widening a regular expression.
• Preserve source declaration order for const.</code> and <code>proc.int. records.
• Set diagnostic columns from the original raw line, not from the trimmed line.
• Any parser change must update at least one .ir.must or .err.must snapshot.
• Any generated binary behavior change must update emission.sha256.must.

Coverage can be inspected with:

tools/bootstrap_native_fixture_matrix.sh