Skip to content
Zryna

Documentation bundles

The compiler repository owns normative language and compiler documentation. The website owns its presentation. An authenticated, deterministic, resource-bounded bundle is the planned contract between them.

Planned producer flow

Section titled “Planned producer flow”

The compiler will expose commands equivalent to:

Terminal window
zryna docs check
zryna docs export --channel next --output .zryna/out/docs/next

These commands are part of the planned compiler documentation exporter and are not available in the current proof release.

Bundle contract

Section titled “Bundle contract”

Each bundle contains:

  • manifest.json, using zryna.docs.bundle.v1;
  • manifest.sha256, covering the exact manifest bytes;
  • only the UTF-8 Markdown files listed in the manifest.

The manifest records a full compiler commit, Git ref, source version, channel, stable document IDs and paths, byte counts, and SHA-256 digests. Its canonical JSON serialization contains no generation timestamp; the executable contract tests that identical input produces identical manifest bytes.

manifest.sha256 detects accidental corruption but cannot authenticate itself. Ingestion therefore also requires the expected manifest digest and channel from an authenticated compiler workflow, signed release, or attestation. A bundle cannot choose its own trusted digest.

The website rejects unknown fields, unsorted or duplicate entries, symlinks, unlisted files, oversized documents, invalid UTF-8, and checksum mismatches. A local bundle can be checked with:

Terminal window
pnpm docs:check -- /path/to/bundle \
  --expected-manifest-sha256 <authenticated-sha256> \
  --expected-channel next

Publication channels

Section titled “Publication channels”
  • next must come from refs/heads/main and follows reviewed compiler development.
  • semantic-version bundle channels must equal source.version and come from the matching immutable refs/tags/v<version> tag.
  • stable will be a website alias to one already verified semantic-version bundle; it is not a mutable bundle channel.

The compiler currently has no release tags, so next is the only valid present-day channel. Until the exporter and authenticated delivery exist, the website links to reviewed compiler source material directly and does not ingest bundles.