unaltraweb 0.5.1 → 0.7.0

data/docs/agents/owner-closeout-80.md

@@ -0,0 +1,185 @@
+# unaltraweb 0.6.0 delivery closeout
+
+Published **2026-10-02 17:28:14 UTC**:
+[v0.6.0](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.6.0).
+Owner coordination: [issue 80](https://github.com/dosquartsdedocs/unaltraweb/issues/80).
+This report supersedes the pending delivery state in the chronological
+[preparation record](retained-letter-import.md). Issue 76 and release 0.5.1
+remain closed and immutable.
+
+## Review, source and integration
+
+The owner explicitly authorized commits, push, PR review/integration, signed
+candidate workflows, gated publication and the post-release launcher pin. The
+checkout was reconciled against all existing unit-80 paths; no unrelated edits
+were found. Work used one checkout and ordinary serial branches.
+
+| Role | Revision / evidence |
+| --- | --- |
+| Reviewed implementation | `7af652fb83629e959af05c407a34a2f5a15f7936` |
+| Integrated core selected by consumers | `5cf9817489c8dc47cee726bfe42fe3071cd32b85`, [PR 81](https://github.com/dosquartsdedocs/unaltraweb/pull/81) |
+| Immutable core/PDF selection | `8e93b8b808204faef54cccaee622699f04a11805` |
+| Final artifact-producing source | `de52db351490e94939aac20c6af264f22a6a1678`, [PR 82](https://github.com/dosquartsdedocs/unaltraweb/pull/82) |
+| Receipt-only child | `3ce7606bc6148aee19d067c559823d8c5b52db5d` |
+| Receipt integration and tag target | `ec6dcb28e890d32718aa173934527a7b4213a042`, [PR 83](https://github.com/dosquartsdedocs/unaltraweb/pull/83) |
+| Annotated tag object | `1605578861a1a09157037e6085020baad4948d72` |
+
+All three PRs have explicit agent review records and protected CI; those records
+do not claim human review. Merge commits preserve the reviewed core's ancestry.
+The receipt integration's first parent is exactly the artifact-producing source,
+and its first-parent diff contains only `release-candidates.json`.
+
+Review closed independent metadata-reference validation, malformed Pandoc-link
+handling, internal PDF OpenAction destinations, and direct signed-runtime
+acceptance. The vendored v1 verifier/schema still match the established hub pin
+byte for byte; 26 reference conformance tests passed against matching fixtures.
+Source checks reported 587 Python cases with 30 optional skips. Ruby, actual PDF,
+MCP, wheel/gem, workflow/distribution, docs and reproducibility gates passed.
+
+## Receipt and published identities
+
+[Tagged native receipt](https://github.com/dosquartsdedocs/unaltraweb/blob/v0.6.0/release-candidates.json):
+
+```text
+schema_version: 1
+release: v0.6.0
+source_commit: de52db351490e94939aac20c6af264f22a6a1678
+receipt SHA-256: 5ed4e6dd615367927e6ea8a3541c9e7dca9dad73a738851705f563e0e6895280
+```
+
+Exactly the four `ready` components are bound to that source:
+
+| Component | Registry artifact | SHA-256 / OCI index digest |
+| --- | --- | --- |
+| Gem | `unaltraweb-0.6.0.gem` | `276d04a71d1170220c3881cce8d0800633c42b0ee7ad07a376f80996c6afd177` |
+| Wheel | `unaltraweb_mcp-0.6.0-py3-none-any.whl` | `3effb471ffd264f7fb2a8c88dd6536bc86639eae52806527c2d872653944c85a` |
+| Base runtime | `ghcr.io/dosquartsdedocs/unaltraweb` | `sha256:a4e9d82b0e9a72e519c44e09ca449b2dc37964fbb9953ae6e4adff648e39b94b` |
+| Full MCP | `ghcr.io/dosquartsdedocs/unaltraweb-mcp` | `sha256:736c4ddd0a543454e3edaeac2e9cfd97a1279ce472923ac54e326c1281b2ba05` |
+
+Both `0.6.0` and `v0.6.0` OCI aliases were inspected anonymously and match those
+index digests. The MCP's local configuration ID is
+`sha256:73320210b19597243c7183ef255ffa1cbc36a07157e6ab4e1b3d9349fa89a063`;
+its revision label is the exact artifact source above. Configuration IDs and
+registry index digests are distinct identities.
+
+The selected PDF 0.6.0 is the already-published, signed and tested specialization:
+`ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:0ba267cb87f53ebaca4e31805fe00610cd61fdf97a8d2c3692f4655700dceaed`.
+It was produced from core `5cf9817489c8dc47cee726bfe42fe3071cd32b85` by the
+[initial signed image run](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37029374441),
+and its local configuration ID is
+`sha256:d7e7d3243616270fc9e6eed7f8238c412dbe3d9ffc18d2832d17d66ca630d139`.
+The BOM, generated consumer tuple and Make default select that same digest.
+It is reused as `released`, outside the four-component coordinated receipt.
+The later image workflow also tested a verification-only PDF candidate
+`sha256:9b3ae6fe1f04ff7de6c81c258d7c16f79cc7f2857c9b46b0829fc71812ace11f`;
+that candidate is not the selected worker and received no coordinated semver
+promotion. No self-digest or fabricated core SHA was introduced.
+
+Computation, capture, Diavisuals and Vegavisuals retain the tested 0.4.0 selections.
+Their exact immutable references remain in the BOM, and earlier published
+artifacts and receipts remain at their original tags.
+
+## CI, signing and publication
+
+| Gate | Successful run |
+| --- | --- |
+| Implementation PR CI / CodeQL | [37027921742](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37027921742) / [37027922332](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37027922332) |
+| Core integration CI | [37028677932](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37028677932) |
+| Tuple PR CI / CodeQL | [37032368507](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37032368507) / [37032368609](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37032368609) |
+| Final source CI / CodeQL | [37033064607](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37033064607) / [37033064633](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37033064633) |
+| Signed final image build/test | [37033593312](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37033593312) |
+| Package preparation | [37033596931](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37033596931) |
+| Receipt PR CI / CodeQL | [37038403708](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37038403708) / [37038403802](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37038403802) |
+| Receipt/tag target CI / CodeQL | [37039075585](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37039075585) / [37039075748](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37039075748) |
+| Tag CI | [37039786598](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37039786598) |
+| Semver image promotion | [37040420721](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37040420721) |
+| PyPI/RubyGems Trusted Publishing | [37040424945](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37040424945) |
+
+The signed image workflows checked exact OCI digests, signer workflow, source
+revision and labels before executing candidates. Promotion reverified those
+bindings and reused the tested manifests without rebuilding. The package
+authorizer bound workflow/run/source, immutable artifact ID `11237594327`, exact
+inventory and checksums to the receipt. Its archive digest is
+`sha256:79a67d7a8370468abe1f0265b248f3e9d6cf6187ac0bc891a0b3801e5a9931a6`.
+OIDC jobs published only the staged verified gem and wheel.
+
+The actual receipt-only branch, merged target and annotated tag passed strict
+`distribution-release-check` and publication-ref/ancestry gates. Native package
+run authorization, exact staging and `verify_package_publish.py release` passed
+before privileged publication. Strict release checks apply to the receipt/tag
+revision, not subsequent ordinary post-release source commits.
+
+## Real retained-letter and rollback proofs
+
+Acceptance consumed the authenticated published Carta 0.3.0rc1 packet, not a local
+producer checkout or synthetic unit fixture. The sender bundle hash is
+`aeaa757ee1be19bfe56dc9af8dd1178032929b4a2bec2dad2ebb621b158ad999`.
+All 12 seal files remain under `.unaltraweb/artifacts/carta/bundle/`.
+The mapping `payload/output/letter.pdf` → `assets/documents/carta.pdf` retains
+SHA-256 `4a661740a18fe1cf75b84aa0d8532511fd105eb5484a5af700e11e8e30828ea4`.
+The native chapter is `_chapters/en/carta.md`, with its separate binding and
+standard-v1 integration record outside the seal.
+
+The downloaded final CI wheel ran against the exact signed MCP and selected PDF
+digests above, without deriving another controller image. Both copied producer
+and incoming trees were removed, author prose survived an identical reimport,
+and the receiver was moved before native/generic verification and a forced PDF
+rebuild. Web/HTTP checks passed at both locations. The complete original letter
+appears on page 10 of an 11-page composed manual. Both composed PDFs have hash
+`416e96f66bb6608b1e20bf5e36b6b16133bd4018c17e6c079e8987b736fe9cae`.
+The integration record hash is
+`ebe07ee10ad740a2bbbd36d532f336374cf4bb19ccb373b6590b2279f664a222`.
+Generic verification confirms one bundle, one mapping and 14 verified files;
+the native checker additionally binds the source and rendered page.
+
+Local evidence root: `/tmp/opencode/unaltraweb-closeout-060/`.
+
+| Retained evidence | SHA-256 |
+| --- | --- |
+| `candidate-letter-proof/evidence.json` | `618573b1a867daf6b1f3023e0d5700c27a6de429abea160b4c51ff8699f86f9c` |
+| `candidate-roundtrip/evidence.json` | `23ec8885e8306931fb8ee4899e95b7bff4b3d23d2b63cdd3321e3f68722c3bb8` |
+| `published-packages/verified.json` | `073d7ca1bbe46b8be5d89211501ca8fc7b71297d7eb542c4c9cc27ff167aa91e` |
+
+The roundtrip exercised all four profiles using immutable MCP references:
+0.4.0 `sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9`,
+unpatched 0.5.0 `sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98`,
+then the new 0.6.0 digest. The unpatched failure was reproduced on a separate
+copy. Two builds and a preview passed at 0.6.0 and again after returning to 0.4.0.
+All six author/cache files retained their hashes; no caches were emptied.
+
+## Public downloads and post-release selection
+
+Anonymous PyPI and RubyGems metadata and package bytes match the receipt exactly.
+GitHub Release assets were downloaded again and pass `SHA256SUMS`, whose own hash
+is `60d80d6e0803154a7b5c98c1731f4bec905def3a481152d4e59d7daf8932fc1a`.
+A fresh public-wheel venv passed default `prepare`, `check` and real stdio `smoke`,
+selecting the expected MCP configuration ID without a local factory dependency.
+That public installation rechecked the relocated receiver and rendered mapping.
+The public gem installed into an isolated gem home and activated as 0.6.0 using
+the runtime's existing Ruby dependencies; this is not a network-fresh dependency
+installation claim. The downloaded candidate gem also passed isolated native
+helper-closure inspection.
+
+The source-only post-release branch `chore/80-pin-published-mcp-0.6.0` selects the
+published MCP digest in `Makefile` and `scripts/unaltraweb-mcp-bootstrap.sh`, updates
+the pin regression and current docs, and accompanies this report. Its PR/merge
+and final clean-main confirmation are recorded in issue 80 after protected CI.
+It does not rebuild or alter the published receipt, tag or packages.
+
+The post-pin local recheck passed 587 Python cases (558 passed, 29 optional
+skips), distribution/workflow/wheel and prose checks, `mcp-check`, real
+`mcp-smoke` with the selected public PDF, docs build and whitespace checks.
+Development builds used only `unaltraweb-closeout-060-*:post-pin` resources.
+The actual `MCP_CONSUMER_WORKSPACE`-bound `make mcp-stdio` transport also initialized
+a fresh synthetic consumer and exposed both native import tools; Docker inspection
+confirmed the published MCP configuration ID above. Its retained result is
+`/tmp/opencode/unaltraweb-closeout-060/post-pin-proof/evidence.json` and the session
+exited normally. `mcp-build` and the bootstrap's `--check` selected the public
+runtime directly.
+
+Acceptance covers the exact Linux/amd64 tuple and published English one-page
+Carta sample. The generic conformance tests do not establish Diapora composition
+or other domain imports. Active IDE processes keep their loaded runtime until
+reconnected. No real manual, author artifact, client registration or helper
+selection was migrated. Consumer adoption and hub catalogue integration remain
+separate owner actions; this report supplies their verified intake evidence.

data/docs/agents/retained-letter-import.md

@@ -0,0 +1,235 @@
+# Native retained-letter import — issue 80
+
+Delivery completed on 2026-10-02; see [the 0.6.0 closeout](owner-closeout-80.md)
+for final revisions, receipts, registry downloads and the post-release pin.
+The following sections retain the chronological preparation and review evidence.
+
+## Scope and release state
+
+This is a separate 0.6.0 development increment after the administrative closeout
+of issue 76. Gem, wheel, runtime, MCP and PDF worker are pending. The 0.5.1 release,
+receipt and active checkout launcher pin remain unchanged. Consumer core/PDF
+integration and publication need their own reviewed immutable selections. The
+tested computation, capture and visual companion selections remain 0.4.0.
+
+The native receiver accepts Carta 0.3.0rc1 leaf `letter-pdf-v1` units. It retains
+the entire bundle, maps the original PDF byte for byte, creates a native draft
+page/chapter and checks its source and rendered references. The manual PDF
+builder includes all pages with `pdfpages`; every retained dependency and checker
+contributes to freshness. Nothing executes the retained producer recipe.
+Composite profiles, edited PDF variants and Diapora are outside this acceptance.
+
+## Protocol and provenance
+
+The wire v1 verifier and schema are byte-identical copies pinned to hub revision
+`9167e3efb5968a64bb9100792163a179c1491860` (integration
+`fc8745db950b04013c73eb49acf6781a26eb83f8`). Their respective SHA-256 values are
+`48368035f242f4d4446cbbe1363f8a01a7c17fa164ffef21abadd878b288d82d` and
+`b52a32b3bcfeed28cf34a9ec1557665a94466b51c451ccad47d2e87f6e23f9aa`.
+No envelope fields were added. `binding.json` is a separate native record.
+The integration actor identifies the importer by a hash of its code inventory,
+not an invented or uncommitted Git revision.
+
+Acceptance uses the final published
+[Carta v0.3.0rc1 packet](https://github.com/dosquartsdedocs/unaltracarta/releases/tag/v0.3.0rc1),
+revision `84258b6869689ea5f1a49a55abc2b865573fb512`:
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `distribution.json` | `9d94b918db086b445e4d8a3ece2435622e0f9f9893bcd50708b4d13f5ca0ad44` |
+| `acceptance-0.3.0rc1.json` | `1bc7c467f3e35abf9fa5c27583dd8cc3ad4d4372f930c4be60ed142122158504` |
+| `acceptance-0.3.0rc1.tar.gz` | `8764a717bda33e15b48b3a06fe6fbe5dc075abedf4fd52bd37fdf4ed70896179` |
+| Published wheel | `0afab176ea0815d242f6e19021232bafdc63f9bb68cbacbd63b73f99b666b7c3` |
+| Wheel bundle manifest | `aeaa757ee1be19bfe56dc9af8dd1178032929b4a2bec2dad2ebb621b158ad999` |
+| Retained original PDF | `4a661740a18fe1cf75b84aa0d8532511fd105eb5484a5af700e11e8e30828ea4` |
+
+The original producer job was
+`.unaltracarta-handoff/jobs/a0794f7909a943eb844c87bb14002691/bundle/`.
+Its renderer identity is
+`sha256:ba2453fb42542433f68efd8888d628b95f256cefb9c545b3b35034d33296e340`.
+The installed test authenticates the packet before bounded extraction and checks
+every declared evidence file. Earlier release-candidate bytes are not inputs.
+
+## Installed acceptance
+
+`test/artifact_import_smoke.py` uses a wheel-installed CLI and Docker launcher,
+without a host factory dependency. It creates a synthetic manual, imports the
+published wheel bundle, edits surrounding prose, verifies an identical reimport
+preserves that prose and removes both the extracted producer copy and incoming
+copy. It then builds the web and PDF, checks the served page/PDF, moves the
+receiver, runs both native and generic v1 checks, and explicitly rebuilds the
+PDF in the moved receiver. Every original page must occur in order in the
+composed PDF; comparison uses the original font encoding, including ligatures.
+
+The passing local run is retained at
+`/tmp/opencode/unaltraweb-import-80/installed-proof-final/evidence.json`.
+Its receiver is `relocated-receiver/` in that directory. This is local owner
+evidence from development images, not a signed release receipt.
+
+| Tested identity | Value |
+| --- | --- |
+| Installed unaltraweb wheel SHA-256 | `407b1275d1de558da891f391454287d1b3e76fbef0e45460695e9731932b9e39` |
+| Controller image ID | `sha256:81f1da616455c7378ba3400b9d638eb8e67fce9605f18353d49a796020d9b6fa` |
+| PDF worker image ID | `sha256:b7b8f5b774a528cadb2ab7aa313b9ddbffa6d54c9d3b42bd6ff59a664be8ccf6` |
+| Integration record SHA-256 | `79ede9c8701eedf6ca4f182dc4fd1c9df3b56581138c677e0315310d8b998d1c` |
+| Composed PDF before and after relocation | `14b0ef586874704b6d1b045d6dde1f32ee08c8a9107006e06cfe2e8147f54621` |
+
+The receiver retains all 12 seal files under
+`.unaltraweb/artifacts/carta/bundle/`. Its mapping is
+`payload/output/letter.pdf` → `assets/documents/carta.pdf`, with native content at
+`_chapters/en/carta.md` and permalink `/en/retained/carta/` under `/letter-proof`.
+The original one-page letter appears on page 10 of the 11-page composed manual.
+Both web/HTTP checks passed; the non-web archive was absent from `_site`.
+Generic verification after relocation passed with one bundle, one mapping and
+14 verified files. Preview copies were cleaned through their exact receipts.
+
+Intermediate failures are retained separately: missing explicit gem plugin
+registration, an overly broad rendered-HTML scan, mismatched controller/worker
+checker bytes, and an assertion that ignored the original PDF's ligature
+encoding. Corrections preserve strict integrity/freshness gates. In particular,
+the installed-image fixture force-reinstalls its supplied wheel even when its
+development version equals the base image's version.
+
+## Reproduction and boundaries
+
+Prepare an installed wheel, the matching source-containing MCP image, and a PDF
+worker built from the repository root with `scripts/manual/Dockerfile`. The test
+controller in `test/artifact_import.Dockerfile` binds `MANUAL_PDF_IMAGE` to the
+worker image ID. Then run:
+
+```bash
+python test/artifact_import_smoke.py \
+  --packet "$PUBLISHED_CARTA_PACKET" --output "$NEW_EVIDENCE_DIRECTORY" \
+  --cli "$INSTALLED/bin/unaltraweb-mcp" \
+  --launcher "$INSTALLED/bin/unaltraweb-mcp-docker" \
+  --image "$TEST_CONTROLLER" --pdf-image "$TEST_PDF_WORKER"
+```
+
+The output directory must not exist. Only copies created by the test are retired.
+Unit-test bundles in `test/test_artifact_imports.py` are synthetic security and
+transaction fixtures, not published-producer acceptance. They cover tampering,
+incomplete resources, hidden references, symlinks/hardlinks, no-overwrite,
+interruption/retry, generated-source ownership, PDF action aliases/chains,
+rendered URL binding, native PDF inclusion and dependency closure.
+
+The imported unit is portable because its seal, record, mapped PDF and content
+all use receiver-relative paths. The integration does not depend on the incoming
+directory, producer process, absolute source location or ignored recovery tree.
+Failed publication retains prepared and partial files; there is no destructive
+rollback. Reimport adopts only identical existing bytes and preserves authored
+prose when the binding remains valid.
+
+Final release gates must additionally bind the reviewed core/PDF consumer tuple
+and same-source package/image candidates. A local acceptance run does not update
+those pins, authenticate a public 0.6.0 release, authorize real-manual adoption,
+or grant author approval to the draft content.
+
+The gem and PDF worker include a regular Python package initializer and its
+stdlib-only version/contract module. This prevents an unrelated installed wheel
+from shadowing the gem's helpers. The extracted-gem gate asserts the actual
+module paths. Checker code and schemas enter PDF freshness; the validated BOM's
+worker/self pins do not, avoiding a worker that would need to contain its own
+future digest. The integration actor separately hashes the full BOM metadata.
+
+## Owner regression gates
+
+- Python suite: 584 tests, 30 environment-dependent skips, no failures. The
+  focused importer suite covers 22 cases; the PDF builder suite covers 88.
+- Ruby plugin suites: 64 tests and 334 assertions, no failures.
+- Actual PDF toolchain integrations: 16 tests, no failures.
+- `distribution-check`, `workflow-check`, `wheel-check`, `gem-check`,
+  `mcp-check`, `mcp-smoke`, `docs-build`, and fixed-epoch
+  `reproducible-site-check` passed on local owner resources. Distribution remains
+  structurally valid and explicitly not release-ready.
+- The extracted-gem package gate exercises synthetic native retention using only
+  the gem's Python helper closure, with isolated Python and no wheel/core path.
+  Native deployment installs its parser dependencies before PDF/Jekyll checks.
+- Populated Bundler roundtrip passed for `unaltreselfie`, `unaltreprojecte`,
+  `unaltredocs` and `unaltremanual`, with two builds and a preview per runtime.
+  It first reproduces the published unpatched 0.5.0 `google-protobuf (4.36.1)`
+  failure on a separate copy, then tests 0.4.0 → development 0.6.0 → 0.4.0.
+  The historical driver labels its patched step `fixed-050`; the recorded
+  image is the 0.6.0 test controller. All six retained author/cache paths keep
+  their initial hashes; no cache cleaning is used to obtain a pass.
+
+Roundtrip evidence is retained at
+`/tmp/opencode/unaltraweb-import-80/bundler-roundtrip-final/evidence.json`, using
+the same final controller and worker IDs as the installed letter acceptance.
+The source discovery descriptor additionally declares `.unaltraweb/artifacts`
+as optional versioned source state with `cleanup: never`; `tmp` keeps its existing
+ignored, explicit-cleanup policy. This final metadata-only addition is checked by
+the path-policy and fresh-wheel gates and does not alter the tested import code.
+
+## Closeout review — 2026-10-02
+
+The owner explicitly authorized the full 0.6.0 commit/PR/integration, signed
+candidate, gated publication and post-release pin flow. The session preflight
+reported only the known unit-80 working tree and no competing session. Review
+covered every tracked/untracked unit path; no unrelated changes were identified.
+
+The two vendored protocol files match the exact established Git pin. The pinned
+reference tests and fixture payloads were also checked (the later fixture README
+only renames the integrated contract), and all 26 conformance tests pass. These
+generic synthetic tests do not add a composite domain to the native importer.
+The retained installed wheel/PDF hashes above and the moved receiver's native
+web/PDF mapping were independently rechecked before editing.
+
+Resolved review findings:
+
+- Metadata could contain a local link or image while retained Pandoc evidence
+  remained stale. Renderable metadata now receives the independent text-reference
+  check; effective metadata rejects render-option fields outside the supported
+  author/stamp projection. Malformed Pandoc link evidence returns a structured
+  domain failure instead of an uncaught indexing error.
+- A PDF OpenAction internal destination array was treated as an action array.
+  Internal destinations are supported while chained action arrays retain their
+  stricter checks. Regression tests cover both cases.
+- The acceptance driver required a derived test-controller image. It now also
+  verifies the immutable PDF selection declared by the actual installed MCP image
+  and records the exact image references and source label, allowing signed bytes
+  to be exercised directly.
+
+The corrected source passes 587 Python tests (30 optional skips), including 25
+native import cases, plus distribution/workflow/fresh-wheel gates. The historical
+local evidence above remains retained; signed-candidate and public-download
+acceptance must record their own revisions and hashes. The consumer core/PDF
+tuple is closed only after the reviewed integrated core and signed PDF digest
+exist; no guessed source or self-digest is inserted into the BOM.
+
+## Reviewed immutable consumer tuple
+
+PR [81](https://github.com/dosquartsdedocs/unaltraweb/pull/81) integrated reviewed
+implementation `7af652fb83629e959af05c407a34a2f5a15f7936` as
+`5cf9817489c8dc47cee726bfe42fe3071cd32b85`. Protected PR CI
+[37027921742](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37027921742)
+and CodeQL [37027922332](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37027922332)
+passed, followed by integrated-source CI
+[37028677932](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37028677932)
+and CodeQL [37028678347](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37028678347).
+The PR contains an explicit agent review, not an attributed human approval.
+
+Signed image workflow
+[37029374441](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37029374441)
+then published, attested and tested the PDF from that exact source. Its read-only
+test job verified the signer workflow/source digest before executing the exact
+image, including 16 PDF integrations and real MCP preparation. The selected
+PDF 0.6.0 identity is
+`ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:0ba267cb87f53ebaca4e31805fe00610cd61fdf97a8d2c3692f4655700dceaed`.
+The BOM and Make contract now select that same digest and integrated core SHA.
+
+That public signed PDF is recorded as `released` and reused by digest. The four
+core/package components are `ready` for final same-commit candidates; their strict
+gate still requires a new receipt-only child of the final artifact source.
+Subsequent verification-only PDF builds are not substituted for this selected
+worker or promoted under an assumed identity. The earlier 0.5.1 receipt and
+active launcher pin remain intact until the authorized 0.6.0 closeout completes.
+
+The tuple was exercised before its pin PR using an installed wheel and a local
+MCP containing the new BOM with the actual signed PDF above. Evidence is retained
+at `/tmp/opencode/unaltraweb-closeout-060/tuple-letter-proof/evidence.json`:
+integration `ebe07ee10ad740a2bbbd36d532f336374cf4bb19ccb373b6590b2279f664a222`,
+composed PDF `416e96f66bb6608b1e20bf5e36b6b16133bd4018c17e6c079e8987b736fe9cae`
+both before and after the forced relocated rebuild. The PDF's inspected local
+image ID is `sha256:d7e7d3243616270fc9e6eed7f8238c412dbe3d9ffc18d2832d17d66ca630d139`,
+with the exact integrated source revision label. This preparation proof does not
+substitute for the final signed MCP and downloaded package acceptance.

data/lib/unaltraweb.rb

@@ -21,6 +21,7 @@ require_relative "unaltraweb/version"
   content_search_index
   manual_release_metadata
   reproducible_build_time
+  retained_documents
   profile-pages
   remove-accents
   search-data

data/requirements.txt

@@ -3,3 +3,5 @@ scholarly
 requests
 bibtexparser
 rdata
+pypdf>=6,<7
+markdown-it-py>=3,<5

data/scripts/manual/Dockerfile

@@ -23,9 +23,12 @@ RUN printf '%s\n' \
     && rm -rf /var/lib/apt/lists/* \
     && pip install --no-cache-dir PyYAML==6.0.2
 
-COPY build_pdf.py /opt/unaltraweb/manual/build_pdf.py
-COPY Dockerfile /opt/unaltraweb/manual/Dockerfile
-COPY filters /opt/unaltraweb/manual/filters
-COPY templates /opt/unaltraweb/manual/templates
+RUN pip install --no-cache-dir 'pypdf>=6,<7' 'markdown-it-py>=3,<5'
+COPY scripts/manual/build_pdf.py /opt/unaltraweb/manual/build_pdf.py
+COPY scripts/manual/Dockerfile /opt/unaltraweb/manual/Dockerfile
+COPY scripts/manual/filters /opt/unaltraweb/manual/filters
+COPY scripts/manual/templates /opt/unaltraweb/manual/templates
+COPY src/unaltraweb_mcp/__init__.py src/unaltraweb_mcp/distribution.py src/unaltraweb_mcp/component-contract.json src/unaltraweb_mcp/component-contract.schema.json src/unaltraweb_mcp/artifact_handoff_v1.py src/unaltraweb_mcp/artifact-handoff-v1.schema.json src/unaltraweb_mcp/artifact_imports.py src/unaltraweb_mcp/letter_bundle.py src/unaltraweb_mcp/pdf_probe.py src/unaltraweb_mcp/processes.py /opt/unaltraweb/src/unaltraweb_mcp/
+ENV PYTHONPATH=/opt/unaltraweb/src
 
 ENTRYPOINT ["python3", "/opt/unaltraweb/manual/build_pdf.py"]

data/scripts/manual/build_pdf.py

@@ -26,6 +26,10 @@ except ImportError as exc:  # pragma: no cover - supplied by the builder image
 
 
 SCRIPT_ROOT = Path(__file__).resolve().parent
+for _source_root in (SCRIPT_ROOT.parent.parent / "src", SCRIPT_ROOT.parent / "src"):
+    if (_source_root / "unaltraweb_mcp" / "artifact_imports.py").is_file():
+        sys.path.insert(0, str(_source_root))
+        break
 DEFAULT_DOCKERFILE = SCRIPT_ROOT / "Dockerfile"
 DEFAULT_TEMPLATE = SCRIPT_ROOT / "templates" / "manual.tex"
 DEFAULT_BIBLIOGRAPHY_FILTER = SCRIPT_ROOT / "filters" / "bibliography.lua"
@@ -36,6 +40,7 @@ BIB_CUSTOM_URL_RE = re.compile(r'(?im)^\s*(?:manual_url|website)\s*=\s*(?:\{([^}
 FRONT_MATTER_RE = re.compile(r"\A---[ \t]*\r?\n(.*?)^---[ \t]*(?:\r?\n|\Z)", re.MULTILINE | re.DOTALL)
 CITE_RE = re.compile(r"{%\s*cite\s+([^%]+?)\s*%}")
 INCLUDE_RE = re.compile(r"{%\s*include\s+([^%]+?)\s*%}")
+RETAINED_DOCUMENT_RE = re.compile(r"{%\s*retained_document\s+([a-z][a-z0-9-]{0,63})\s*%}")
 LIQUID_RE = re.compile(r"({[{%].*?[}%]})", re.DOTALL)
 INLINE_CODE_RE = re.compile(r"<code>(.*?)</code>", re.IGNORECASE | re.DOTALL)
 FENCED_CODE_BLOCK_RE = re.compile(r"^[ \t]*(`{3,}|~{3,})[^\n]*\n.*?^[ \t]*\1[ \t]*$", re.MULTILINE | re.DOTALL)
@@ -947,6 +952,17 @@ def transform_markdown(
             citation_keys.extend(key for key in keys if key not in citation_keys)
         return "[" + "; ".join(f"@{key}" for key in keys) + "]"
 
+    def retained_document(match: re.Match[str]) -> str:
+        from unaltraweb_mcp.artifact_imports import check_imports
+
+        result = check_imports(project, match.group(1))
+        if result.get("ok") is not True:
+            raise ManualPdfError(f"Retained document verification failed: {result.get('error')}")
+        path = result["imports"][0]["pdf"]
+        # The native import layout uses an ASCII slug and fixed project-relative
+        # path; no bundle text is interpolated into TeX or executed.
+        return protect("```{=latex}\n\\includepdf[pages=-,pagecommand={}]" + "{" + path + "}\n```")
+
     def table(match: re.Match[str]) -> str:
         body = match.group("body").strip()
         credit, _ = caption_source_attribute(match.group("attrs") or "")
@@ -1137,6 +1153,7 @@ def transform_markdown(
     transformed = transformed.replace(r"\begin{equation\*}", r"\begin{equation*}")
     transformed = transformed.replace(r"\end{equation\*}", r"\end{equation*}")
     transformed = BASEURL_RE.sub("", transformed)
+    transformed = RETAINED_DOCUMENT_RE.sub(retained_document, transformed)
     transformed = transformed.replace("{% include manual-bibliography.liquid %}", "::: {#refs}\n:::")
     transformed = CITE_RE.sub(citations, transformed)
     transformed = CALLOUT_BLOCK_RE.sub(callout, transformed)
@@ -1481,6 +1498,17 @@ def build_dependencies(project: Path, metadata: dict[str, Any], source_paths: li
     ]
     for path in source_paths:
         dependencies.append((f"source:{path.relative_to(project)}", path))
+    if any(RETAINED_DOCUMENT_RE.search(path.read_text(encoding="utf-8")) for path in source_paths if path.suffix.lower() == ".md"):
+        from unaltraweb_mcp import artifact_imports
+
+        imports = artifact_imports.check_imports(project)
+        if imports.get("ok") is not True:
+            raise ManualPdfError(f"Retained document verification failed: {imports.get('error')}")
+        for item in imports["imports"]:
+            dependencies.extend((f"retained:{relative}", project / relative) for relative in item["inputs"])
+        checker_root = Path(artifact_imports.__file__).parent
+        for name in artifact_imports.CHECKER_FILES:
+            dependencies.append((f"import-check:{name}", checker_root / name))
     if csl:
         dependencies.append((f"csl:{csl.relative_to(project)}", csl))
     for key in ["cover-image", "cover-logo", "series-logo"]:

data/scripts/manual/templates/manual.tex

@@ -10,6 +10,7 @@
 \usepackage{float}
 \usepackage{framed}
 \usepackage{graphicx}
+\usepackage{pdfpages}
 \usepackage{grffile}
 \usepackage{longtable}
 \usepackage{array}

data/scripts/test_gem_build.py

@@ -64,6 +64,9 @@ def inspect_gem(path: Path) -> None:
     editorial_files = ["scripts/editorial_check.py", "src/unaltraweb_mcp/editorial.py", "src/unaltraweb_mcp/editorial_sources.py"]
     inspection_files = editorial_files + ["src/unaltraweb_mcp/bundler_runtime.py", "scripts/image_background_check.py", "src/unaltraweb_mcp/image_backgrounds.py",
                                           "src/unaltraweb_mcp/image_probe.py", "src/unaltraweb_mcp/processes.py"]
+    inspection_files += [f"src/unaltraweb_mcp/{name}" for name in (
+        "__init__.py", "distribution.py", "component-contract.json", "component-contract.schema.json",
+        "artifact_imports.py", "artifact_handoff_v1.py", "artifact-handoff-v1.schema.json", "letter_bundle.py", "pdf_probe.py")]
     with tarfile.open(path, mode="r") as package:
         data_member = package.extractfile("data.tar.gz")
         if data_member is None:
@@ -83,6 +86,7 @@ def inspect_gem(path: Path) -> None:
         "_plugins/figure_captions.rb",
         "_plugins/manual_release_metadata.rb",
         "_plugins/reproducible_build_time.rb",
+        "_plugins/retained_documents.rb",
         "assets/js/content-search-match.js",
         "assets/js/content-search.js",
         "_config.yml",
@@ -134,6 +138,29 @@ def inspect_gem(path: Path) -> None:
         inspection = json.loads(run(image_command, cwd=site).stdout)
         if not inspection["ok"] or inspection["images"][0]["state"] != "transparent" or not inspection["warnings"]:
             raise RuntimeError(f"Gem-native SVG background inspection failed: {inspection}")
+        # This is the synthetic domain fixture, not published-Carta acceptance.
+        # Only its data crosses into the isolated extracted-gem subprocess.
+        sys.path.insert(0, str(ROOT / "test"))
+        from test_artifact_imports import fixture
+
+        bundle_sha, template_sha = fixture(site / "incoming/letter")
+        (site / ".gitignore").write_text("tmp/\n", encoding="utf-8")
+        run(["git", "init", "--quiet"], cwd=site)
+        isolated = """
+import json, sys
+from pathlib import Path
+sys.path.insert(0, sys.argv[1])
+from unaltraweb_mcp import artifact_imports, letter_bundle, artifact_handoff_v1, distribution, processes
+for module in (artifact_imports, letter_bundle, artifact_handoff_v1, distribution, processes):
+    assert Path(module.__file__).is_relative_to(Path(sys.argv[1])), module.__file__
+letter_bundle.TEMPLATES['default-letter.latex'] = sys.argv[4]
+project = Path(sys.argv[2])
+result = artifact_imports.import_bundle(project, 'incoming/letter/bundle.json', sys.argv[3],
+    'letter', '_pages/en/letter.md', dry_run=False, confirm_import=True)
+print(json.dumps(result))
+raise SystemExit(0 if result['ok'] else 1)
+"""
+        run([sys.executable, "-I", "-c", isolated, str(core / "src"), str(site), bundle_sha, template_sha], cwd=site)
 
 
 def main() -> int:

data/scripts/test_wheel_install.py

@@ -90,6 +90,11 @@ def main() -> int:
         required = [
             "unaltraweb_mcp/calibre_import.py",
             "unaltraweb_mcp/bundler_runtime.py",
+            "unaltraweb_mcp/artifact_imports.py",
+            "unaltraweb_mcp/artifact_handoff_v1.py",
+            "unaltraweb_mcp/artifact-handoff-v1.schema.json",
+            "unaltraweb_mcp/letter_bundle.py",
+            "unaltraweb_mcp/pdf_probe.py",
             "unaltraweb_mcp/component-contract.json",
             "unaltraweb_mcp/component-contract.schema.json",
             "unaltraweb_mcp/manual_pdf_preview.py",
@@ -137,14 +142,14 @@ def main() -> int:
         fake_bin = temp / "fake-bin"
         fake_bin.mkdir()
         fake_docker = fake_bin / "docker"
-        fake_docker.write_text("#!/bin/sh\n[ \"$1 $2\" = 'image inspect' ] || exit 99\n[ \"$5\" = \"$EXPECTED_IMAGE\" ] || exit 98\nprintf 'sha256:fixture\\n'\n", encoding="utf-8")
+        fake_docker.write_text("#!/bin/sh\n[ \"$1 $2\" = 'image inspect' ] || exit 99\n[ \"$5\" = \"$EXPECTED_IMAGE\" ] || exit 98\nprintf 'sha256:1111111111111111111111111111111111111111111111111111111111111111\\n'\n", encoding="utf-8")
         fake_docker.chmod(0o755)
         expected_image = json.loads((ROOT / "src/unaltraweb_mcp/component-contract.json").read_text())["components"]["mcp"]["reference"]
         launcher_env = {**no_consumer_env, "PATH": f"{fake_bin}:{env['PATH']}", "EXPECTED_IMAGE": expected_image}
         launcher_env.pop("UNALTRAWEB_MCP_IMAGE", None)
         launcher_env.pop("MCP_RELEASE_IMAGE", None)
         prepared_image = run([str(docker_cli), "prepare"], cwd=temp, env=launcher_env).stdout.strip()
-        if prepared_image != "sha256:fixture":
+        if prepared_image != "sha256:" + "1" * 64:
             raise RuntimeError("Installed preparation did not use the packaged bootstrap")
         run(["make", "--silent", "--no-print-directory", "-C", str(launcher), "mcp-build"], cwd=temp, env=launcher_env)
         run([str(docker_cli), "prepare", "--image", "explicit:override"], cwd=temp,