Implement repository-driven theme rendering

2026-07-23 17:49:10 -07:00
parent 68d76a59df
commit 884d182c86
32 changed files with 3040 additions and 1417 deletions
@@ -148,3 +148,37 @@ An unknown rendered-site route should return HTTP 404 and the generated `404.htm
 7. Remove the old private key only after the new path has been verified end to end.

 Do not overwrite the active private key in place during rotation; retaining the old key until verification provides a safe rollback path.
+
+## Repository theme build contract
+
+Production presentation is owned by `.theme/` in the repository selected by `packages/site-definition/site.yml`. There is no built-in production renderer or preview fallback. Configuration is Git-owned and read-only in control-plane v1; `PUT /api/site-config` returns `405 E_CONFIG_READ_ONLY`.
+
+Each build resolves `LABYRICORN_SITE_DEFINITION_REF` (default `HEAD`) once to a full commit and materializes an archive of that commit. Set these variables when the site definition is not the application checkout:
+
+```text
+LABYRICORN_SITE_DEFINITION_REPOSITORY=/srv/site-definition
+LABYRICORN_SITE_DEFINITION_REF=refs/heads/main
+LABYRICORN_SITE_DEFINITION_PATH=packages/site-definition
+LABYRICORN_BUILD_ROOT=/var/lib/website-engine/builds
+```
+
+The artifact ID is derived from the canonical input descriptor. Operational run IDs and execution time do not enter artifact bytes. The release layout is:
+
+```text
+<build-root>/
+├── releases/sha256-<input-digest>/
+├── staging -> releases/sha256-<input-digest>/
+└── current -> releases/sha256-<input-digest>/
+```
+
+Staging and promotion verify every entry in `checksums.json`. A modified artifact is rejected. Promotion updates `current`; it does not render or copy a second release. On startup, valid `staging` and `current` pointers are rediscovered and verified.
+
+### Theme failure behavior
+
+- Missing or invalid `.theme/theme.yml`: the build fails before a release directory is created.
+- Unknown manifest keys, unsafe paths, missing templates/assets, or strict-Liquid errors: the build fails closed.
+- No selected staging/live release: `/api/live-site/html` returns `503 E_RELEASE_UNAVAILABLE`.
+- Unknown route: the selected artifact's `404.html` is returned with HTTP 404.
+- Rollback activates a previously verified immutable release; it never recreates or mutates release bytes.
+
+Repository themes may contain Liquid templates and manifest-declared browser assets. They may not execute build programs, declare custom filters/tags, use dynamic includes, emit inline scripts/event handlers/styles, or reference undeclared local dependencies. HTTPS fonts require a pinned SHA-256 checksum and are cached only after verification.