Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Build this documentation

The publication is a deterministic static assembly:

docs/book/                    mdBook guide source
crate-level Rust comments     themed API + standard Rustdoc source
docs/evidence/manifest.json   evidence index source
docs/site/                    404, policy metadata, headers, redirects
            │
            └── bun run docs:build ──> site/

The build requires mdBook 0.5.4 and checks that exact version. It generates the guide at /, the project API portal and themed Rustdoc at /api/, a separate standard Rustdoc tree at /rustdoc/ with a native workspace crate index, evidence pages at /evidence/, a sitemap, and the top-level static policy files.

Local validation

bun install --frozen-lockfile
bun run docs:test
bun run docs:build:no-api
bun run docs:check

The no-API build is the lightweight content loop. A publication candidate uses the single sequential gate bun run docs:release; it runs a fresh Rustdoc build and then the release checker, stopping if either step fails. The build emits site/build-metadata.json with the full source commit, full source tree, dirty state, and API mode. Fresh Rustdoc also carries an independent file-count and aggregate tree digests at site/api/build-metadata.json and site/rustdoc/build-metadata.json. Release mode recomputes both inventories, requires the same crate roots in both trees, and requires all metadata files to name the same clean commit and tree. Release mode requires a clean current checkout, exact commit/tree agreement, dirty=false, and api_mode=fresh-rustdoc. Because site/, the Cargo documentation target, and installed Bun packages are ignored, generated output cannot make this provenance check circular.

docs:check rejects missing expected routes or fragments, broken local links, a soft-404 meta refresh, unrendered Mermaid, leaked coordination/local paths, malformed evidence, inaccessible producing narratives, and Markdown link syntax accidentally trapped inside raw HTML. Every evidence record links to a generated privacy-sanitized projection of its producing narrative. That projection keeps the repository-relative source path and cryptographic subject commit separately from the narrative checkout commit and dirty state. Its digest identifies the pre-sanitization narrative bytes read by that documentation build—not necessarily the narrative at the subject commit—and every local-path or private-host substitution is visibly labeled.

The checker also audits every iframe title, the no-JavaScript table-of-contents document title, the same-origin framing headers, and high-risk machine-local identifiers in rendered Rust source pages.

Cloudflare Pages

wrangler.jsonc uses the shipped Wrangler v4 schema and identifies ./site as pages_build_output_dir. The project is static and has no bindings or Functions. _redirects contains only named legacy routes and no catch-all. Cloudflare Pages therefore uses the real top-level 404.html for unknown paths.

The repository does not contain account IDs, API tokens, or DNS credentials. Deployment and custom-domain attachment are separate authorized operations.

Release deployment transaction

Build and validate a release from the exact clean commit first:

bun run docs:release
git rev-parse HEAD
bun run docs:deploy --commit <the-full-40-character-HEAD-above>

docs:deploy does not build or repair the site. Before opening any credential file, it requires a completely clean checkout, an exact --commit match, fresh Rustdoc metadata bound to that commit and tree, canonical evidence bytes, a symlink-free site/, a passing release checker, and the pinned local Wrangler. It invokes bunx --no-install wrangler as an argument vector, never through a shell.

At runtime only, the tool opens the fixed KEYS file in the deployment user’s home directory without following symlinks. The file must be owned by the invoking user, have mode 0600, have one hard link, and contain exactly one assignment for each required entry:

SAHASTA_PERSONAL_CLOUDFLARE_ACCOUNT_ID=<account-id>
SAHASTA_PERSONAL_CLOUDFLARE_API_TOKEN=<API-token>

The file is parsed as data and is never sourced. Inherited Cloudflare, CF_*, and Wrangler environment variables are removed before the local Wrangler process receives only the verified account and token. Neither value is printed.

The transaction verifies the token through the account-scoped endpoint, idempotently inspects or creates project hashsigsdocs with production branch main, deploys the explicit clean commit, and independently checks that the successful canonical deployment has that commit. It then attaches and polls hashsigsdocs.sahastasai.com through the Pages custom-domain API.

The immutable deployment URL is checked before domain attachment. The tool then checks hashsigsdocs.pages.dev and the custom hostname. Each smoke verifies metadata and evidence byte equality, core routes and named redirects, the real 404 response, security headers, the no-JavaScript table of contents, immutable Rustdoc caching, and conditional ETag behavior.

Rollback is deliberately narrow. A content mismatch can restore the previously successful production deployment, but only after confirming that the failed deployment is still canonical. API failures, DNS or network reachability, domain activation failures, and concurrent deployments never trigger an automatic rollback. Those failures stop with the current remote state intact for an operator to inspect.