unaltraweb 0.7.1 → 0.7.2

data/docs/agents/private-practice-verifier-98.md

@@ -0,0 +1,296 @@
+# Web #104 — native private QGIS delegation and independent-review corrections
+
+PR #104 source adaptation authorized after QGIS 0.6.0 release. No private QGIS wheel,
+parser or implementation is bundled into the public Web wheel/image. Acquisition
+and authenticated admission of the private controller/engine belong to the hub.
+The Web bridge only transports bounded structured requests to the existing native
+producer CLI. Independent review of the corrected HEAD and publication remain
+separate gates.
+
+## Exact, distinct identities
+
+The package-owned `practice-verifier-runtime.json` is exposed read-only through
+`web://practice-verifier-runtime`. It distinguishes:
+
+- Prepared private controller:
+  `sha256:1fe4a54a42cbac4a6eea596be73425985ab3bca5f28f5871d2fa66d7c0a05f8b`.
+- Native `practice-schema` installed-package identity: `unaltracaptura-qgis 0.6.0`,
+  revision `sha256:4dcd2c40bca4836a202c0c5cc400553b0f134925023b7300e0c0ff2fff1d8492`.
+- V1 schema `9bc7f15ede9d67b3e1209c329da13d9fcb08004090d05b27662a43de6edf3445`;
+  v2 schema `528c8be229c72c346f134ffaa60094f94224094a25b6fb11bcc87802ddc7fffb`.
+- Engine `sha256:1003721d96abe9607d8337b36851f9b29f84c2f8f92b377d1a73ff03c9d15cd2`.
+- Owner release source/tag: `ba68ebaf57d6066e1922bc79e76aec451c24084e`, `v0.6.0`.
+- Release practice-producer revision:
+  `sha256:2e4d6e1eb5a364162770921fc416f9cf64c60540868c0d4c907b993a779d0cc9`.
+- Release wheel: 331788 bytes,
+  `dde653f7a719d8dbb20b4471e3cdb7f9c99cbdfcb116647caba5a08e710c7b76`.
+
+The OCI source label is actually absent (`null`). It is not relabelled as the
+release Git commit. The release wheel and practice-producer identities are owner
+release declarations, not fabricated pip installation evidence. Native schemas
+report the verifier's installed-package revision `4dcd…`, independently confirmed
+by the hub; using producer revision `2e4…` as that verifier pin is refused.
+
+## External release receipt for H2
+
+`release.receipt` declares the producer's external private receipt:
+
+```text
+https://github.com/dosquartsdedocs/unaltracaptura-qgis/releases/download/v0.6.0/release.json
+Bytes: 1251
+SHA-256: 45db1e016e666126e5a51f157be0be1066aaa08f32042f5907d46e0e7da1e404
+```
+
+The authenticated asset bytes were checked against this hash. The receipt agrees
+on source, wheel, practice-producer revision and both image IDs above. Its
+`mcp_image.archive` identifies the private, two-image Docker-save asset
+`unaltracaptura-qgis-0.6.0-docker.tar.gz`: 1372004858 bytes, SHA-256
+`d8570bdf350d7fa59fef787aca3c4b1be841ac14e5246586748aefef51a1d31f`.
+
+The hub acquires and validates that receipt/archive through its authenticated
+preparation path before H2 loading and activation. Web ships only the external
+declaration; public CI does not fetch it. The receipt is QGIS-owned provenance,
+not a Web attestation or a claim that Web has republished those private bytes.
+The declared archive source also does not replace the actually absent OCI label.
+
+## Selection and native boundary
+
+The existing launcher accepts both startup-fixed entries together, as one JSON
+argument to `serve --worker-images` after the hub has prepared the images:
+
+```json
+{
+  "manual_pdf": {
+    "reference": "sha256:618163d3f924439792b2306617bd9612f566c5881166102fa544b4e782d569fa",
+    "expected_image_id": "sha256:618163d3f924439792b2306617bd9612f566c5881166102fa544b4e782d569fa"
+  },
+  "practice_verifier": {
+    "reference": "sha256:1fe4a54a42cbac4a6eea596be73425985ab3bca5f28f5871d2fa66d7c0a05f8b",
+    "expected_image_id": "sha256:1fe4a54a42cbac4a6eea596be73425985ab3bca5f28f5871d2fa66d7c0a05f8b"
+  }
+}
+```
+
+Configuration-ID references remain usable after Docker-save loading even when
+registry `RepoDigests` are absent. The published PDF digest and producer remain
+unchanged. A direct CLI uses the same package-owned accepted QGIS image; optional
+`PRACTICE_VERIFIER_IMAGE` must still resolve to that exact expected ID. For a direct
+CLI using the loaded PDF by ID, also set `MANUAL_PDF_IMAGE` explicitly. Edition
+content cannot choose an arbitrary executable or image implementation.
+
+The live `runtime_identity` tool/resource exposes these observations under
+`runtime.workers.manual_pdf` and `runtime.workers.practice_verifier`: `reference`,
+`expected_image_id`, `observed_image_id`, and `state` (`matched`, `missing`,
+`mismatch`, `unknown`), plus available `registry_digests`, `source_revision`, `os`
+and `architecture`. Observation inspects local images without pulling or invoking
+private code. A matched image is not a native schema, bundle or reopen acceptance.
+
+The QGIS engine is the descriptor's separate `engine.image_id`, not an additional
+Web worker selectable by `--worker-images`. The bridge checks that exact engine
+before explicit `reopen`; QGIS owns its execution and native observations.
+`web://practice-verifier-runtime` supplies declared release/package/profile pins,
+while schema calls and operation receipts retain the separate native observations.
+
+The bridge uses `python3 -I -B -m veure_qgis_mcp.cli` **inside** the private image:
+`practice-schema --profile ...`, `practice-check`, and explicit `practice-reopen`.
+Requests are built from bounded typed fields, not consumer command strings.
+There is no private Python import in Web and no local-wheel fallback.
+
+All invocations select an already prepared image with `--pull never`, network
+`none`, readonly container root, 2 CPU / 4 GiB / 512 PIDs and bounded output/time.
+Schema inspection has no consumer mount; checks have one readonly consumer mount
+and no Docker socket. Explicit reopen uses its own receiver workspace and a Docker
+socket to let the producer launch the already prepared engine. Reopen algorithms
+and engine resource handling remain QGIS-owned. Existing mount encoding, bounded
+subprocesses, startup consumer binding and token/session-scoped worker cleanup
+are reused; `practice-verifier` is an owned worker role, not a new manager.
+
+A missing private image returns an explicit authenticated-hub-preparation blocker.
+No pull, build, token lookup or credential forwarding is attempted. Cleanup must
+confirm exact-container absence before any successful operation is returned.
+
+## New edition origin and legacy preservation
+
+For a new v2 edition, the verifier portion is:
+
+```yaml
+gis:
+  profile: qgis-practice-v2
+  verifier:
+    origin: prepared-image
+    package: unaltracaptura-qgis
+    version: 0.6.0
+    revision: sha256:4dcd2c40bca4836a202c0c5cc400553b0f134925023b7300e0c0ff2fff1d8492
+    image_id: sha256:1fe4a54a42cbac4a6eea596be73425985ab3bca5f28f5871d2fa66d7c0a05f8b
+    schema_sha256: 528c8be229c72c346f134ffaa60094f94224094a25b6fb11bcc87802ddc7fffb
+```
+
+V1 uses its own profile/schema hash above. The independent `gis.bundle` and sender
+seal still refer to the original producer, including retained rc2/rc1 bundles.
+Legacy installed-wheel configuration shapes remain schema-valid but execution
+through this new public runtime explicitly refuses them. Keep their configuration,
+receipts and original candidate intact; create a new configuration/edition for the
+new origin instead of rewriting history or inventing a `direct_url`.
+
+Web validates the complete common bundle before any product selection. Native
+selection must agree with that inventory, include its complete dependency closure,
+and satisfy recipient policy. Receipts retain the original producer report and a
+separate image/native-execution origin, including bounded execution and teardown.
+
+## Public CI and local acceptance
+
+`Dockerfile.mcp` no longer installs QGIS. The private dependency is declared in
+the BOM as external release metadata; the runtime descriptor supplies image pins.
+`scripts/check_practice_verifier_runtime.py` checks metadata by default and reports
+private checks as `not_run`, even on a machine with private images already present.
+`--check-runtime --project ABSOLUTE_ROOT` explicitly opts into native schema/identity
+checks. Full bundle/reopen acceptance and independent review remain distinct gates.
+
+The owner built a new **local, unpublished public-Web probe image** from the
+already public 0.7.1 base, with only Web source/wheel changes and network disabled.
+Absence of the private distribution and `veure_qgis_mcp` module was asserted inside
+the public image. It then delegated to the prepared private image above.
+
+Local Web probe configuration ID:
+`sha256:555bea3744354cde3f64e5ac7e4a4fd01ff71d8cfcf923336bdb577c89ed809a`;
+public source snapshot:
+`0de3ebb5bffb0b93291b7144daa3e6b0fbd3f45beed64ed9580f13626fff91f8`.
+Its manifest is retained under `tmp/private-verifier-98/public-probe-02/`.
+This is an owner acceptance build, not a published or independently reviewed image.
+
+Earlier candidate-04 `17ef…` contains the old embedded private wheel and remains
+a private/local historical artifact. Its saved archive must not be attached to
+the public Web release. New public release archives must use the Web-only source
+boundary and provider-package-absence check exercised here.
+
+Local evidence:
+
+```text
+/home/benizar/git/unaltraweb/tmp/private-verifier-98/acceptance-01/evidence.json
+SHA-256 99878f6caa002dd3ab22f6559d462418465cc4b12fe36195b39c401065302b97
+/home/benizar/git/unaltraweb/tmp/private-verifier-98/acceptance-01/supplement.json
+SHA-256 9351c8e7943d7dafdb77f482acdef0e102b5f211c2dca68678bac9e494e7d27a
+```
+
+The native v2 composition produces the two PDF/ZIP pairs. Extracted ZIP bytes
+replace every selected resource in a new receiver before reopen. Observed engine
+mounts contain only the exact selected readonly packet plus provider controls and
+output, not the full private bundle/original consumer. Missing/altered final ZIP
+dependencies remain refused even after the ZIP hash is recalculated. Native
+observations confirm embedded `inici`, 600×640 MDT/ortho, themes and distinct
+15,000/75,000 layout frames. Retained v1 data also verifies through the same image.
+Wrong image/profile, a producer revision used as verifier identity, legacy origin
+and an unavailable runtime are refused. Original fixtures/rc2 configurations remain
+unchanged. This is local owner acceptance, not a public-CI or independent-review pass.
+
+## Independent review P2 corrections
+
+The review of PR #104 at `88dd2518` reported three issues; all reproduced before
+the fixes (`tmp/private-verifier-98/review-p2-before.log`):
+
+1. PDF delivery now uses hashes returned by the build's original PDF/receipt seal.
+   Composition checks and snapshots that seal immediately, before building the
+   other recipient. Late PDF edits or replacement/resealing of its receipt cannot
+   become authoritative new output hashes. Atomic no-replace publication remains.
+2. Existing TinyCSS2 tokenization now covers URL-bearing SVG presentation values,
+   including escaped `u\72l(...)`; escaped imports are rejected by token identity.
+   Declared local dependencies remain usable. No private producer parser was copied.
+3. The shared privacy check includes actual/mapped `_practices` roots, requires
+   exclusion and rejects explicit/glob includes, also in standalone PDF preparation.
+
+Regression negatives rehash the edited SVG and replace the PDF receipt to exercise
+real resealing attempts. Both output copies must match the original reading seal.
+The independent [re-review of `e16e2478`](https://github.com/dosquartsdedocs/unaltraweb/pull/104#pullrequestreview-5485508017)
+explicitly resolved these three findings. The external receipt reference was added
+after the retained local probe without changing its executable bridge/compositor
+bytes or accepted image/schema selections.
+
+## Create-stage teardown correction after e16e2478
+
+The same re-review identified [P2 4243700163](https://github.com/dosquartsdedocs/unaltraweb/pull/104#discussion_r4243700163):
+`docker create` could allocate a container and then time out or return a truncated
+or malformed reply before entering the cleanup guard. A never-started container
+is not retired by `--rm`.
+
+Creation, reply validation and start/attach now share the guarded lifecycle.
+The already minted project/token labels scope the existing native worker cleanup,
+including direct CLI calls without a session and creation with uncertain effects.
+Recovery uses the bounded exact-token daemon inventory; an untrusted reply or
+container name is never removal authority. Before `start`, the daemon-observed
+full CID, image, factory, role, project, token and session must match the invocation.
+The shared cleanup helper accepts the bridge's expected image/session, revalidates
+every listed CID and removes only positively verified objects. Objects already
+observed absent are not passed to `rm`.
+
+Inventory/removal timeouts, either truncated stream, Docker errors, ownership
+mismatches and unknown absence produce `teardown is unconfirmed`, with the worker
+token for diagnosis and the original operation failure retained in the exception
+chain. Cleanup must confirm known-CID absence and an empty scoped inventory.
+Observation is bounded; private execution, request arguments, mounts, limits and
+the selected image/profile pins retain their previous semantics.
+
+Regression evidence is create-only under `/tmp/opencode/web104-create-cleanup-01/`:
+
+- `red.log`: seven create-stage tests, 30 failing cases on the original executable
+  bytes; SHA-256 `de80dcba863548ceb2b530bb39a90c25bf3c7b1ef953f10e0fb52df9272b6699`.
+- `green.log`: all 18 bridge tests pass, including malformed/truncated/lost create
+  replies, allocation failure before create, cleanup failures, foreign CIDs,
+  ownership/image/session mismatches, Docker/absence errors and the positive
+  bounded reopen contract; SHA-256
+  `70925737a0e85516e4d349ceef54527a963bb48f9e0a350b0c7e573a39c14dcb`.
+- `lifecycle.log`: all 35 shared site/lifecycle tests pass; SHA-256
+  `74d62aeec13ef065365713a469238f4fd09c35956888dfa6066a0b504d638dec`.
+- `native.json`: actual prepared-image allocations followed by injected timeout,
+  truncated and malformed create replies, plus one successful native schema call.
+  All four exact CIDs are absent. No model, PDF or render was run. SHA-256
+  `8ae0fe6ead4b1cd93c721041fce70508c289fc61bcee2b3309aba734ed5e34ef`.
+- `full.log`: 729 tests, 701 passed / 28 optional skips, including an additional
+  stale-inventory regression that forbids removing a CID already observed absent.
+  SHA-256 `0d6bc4249c40346a4f01c3f4a8d6e005a0740e439c7dc050d9fa35c550f60f2d`.
+
+The hub's earlier independent Web-only identity/capabilities/binding/EOF probe
+remains retained at `/tmp/opencode/practice33-web-native-private-01/evidence.json`,
+SHA-256 `ced4a6262d87674b4ff2fa5cff7290e92d1cd33f834edfa1f694ced7d500c6cf`.
+That probe describes its original `555bea37…` image, not the new cleanup bytes or
+release acceptance. This lifecycle delta needs its own TIG review on the new HEAD;
+the earlier PDF/ZIP renders, descriptor `f17eec24…` and private receipt `45db1e01…`
+remain unchanged.
+
+## Real MCP resource-read correction after the 0.7.2 candidate
+
+PR #104 was integrated at `da4e1fcc875211c4eff75834b45d2c4887adec0b` with the
+reviewed tree. Its downloaded wheel `e16a7586…` and public image configuration
+`9bd8b6a8…` passed PDF/ZIP composition and exact-packet reopen, but native
+`resources/read` for `web://practice-verifier-runtime` failed with
+`NameError: name 'json' is not defined`. The callback was the module's only direct
+use of the `json` global; the adjacent practice-edition resource reads its packaged
+schema directly and the other JSON resources use the existing `tools.dumps` helper.
+
+The production correction adds only `import json` to `mcp_server.py`. The regression
+starts an actual CLI server subprocess over MCP stdio, then performs `initialize`,
+`resources/list` and `resources/read` for both practice resources. It parses the
+responses, compares them with the packaged JSON and checks the accepted image,
+native-package revision, producer revision, schema and external-receipt pins.
+The child has no external executables on `PATH`; the test needs neither a Docker
+daemon nor private QGIS data, images, downloads, renders or a site build. No callback
+or serializer is patched into the server. The same assertion is called by the
+installed-image MCP smoke, so listing a broken resource can no longer pass that gate.
+
+Create-only source regression evidence:
+
+- `/tmp/opencode/web98-resource-fix-01/red.log`: the unchanged `da4e1fcc` server
+  fails the real resource read with the recorded NameError; SHA-256
+  `c09ddc7e595b789580c44dad668a734d8b92c70b5c7f69078f01bab108d099cf`.
+- `/tmp/opencode/web98-resource-fix-01/green.log`: the same test passes after the
+  one-line import correction; SHA-256
+  `752562e45d6b624f56dd707f2f8756ebb8051c9d049974986cc4c44450a993ed`.
+- `/tmp/opencode/web98-resource-fix-01/full.log`: 730 tests, 702 passed / 28 optional
+  skips; the real MCP resource test runs and passes. SHA-256
+  `c5b77cd7abd1ae3d5cc20b50d2b88d2528e6e7ec7bc7f37d89485b3317fb1e33`.
+
+The blocked-candidate checkpoint
+`/tmp/opencode/unaltraweb-072-104/blocked-checkpoint.json` retains SHA-256
+`c51c6fbf2f0661804b9e241552cc16939f2efcbf61bdf6f9e4021c06be2b2189`.
+Those immutable candidates remain blocked; this source fix does not repair their
+bytes or authorize their release. Independent delta review, integration and new
+same-source candidates remain required before resuming 0.7.2 publication.

data/docs/agents/source-ci-98.md

@@ -0,0 +1,148 @@
+# Shared public-source CI — Web #98
+
+One implementation lives in `unaltraweb_mcp.source_checks`. The package-owned
+control `.github/workflows/source-checks.yml` is identical for the three manuals;
+only `.unaltraweb/source-checks.json` contains project-specific data. It is a
+source-conservation lane, not a site build or retained-input validation lane.
+
+## GitHub visibility and installation boundary
+
+[GitHub's reusable-workflow access table](https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations#access-to-reusable-workflows)
+allows public callers to use public workflows, not private ones. Cross-owner
+private access must therefore not be assumed. The repository API reported Web
+as `PUBLIC` during this inspection; the design does not depend on that visibility
+remaining public and no visibility setting was changed.
+
+The local scaffold control uses public, SHA-pinned GitHub actions and the public
+PyPI package. It does not call a private factory workflow or download code from a
+mutable factory checkout. Public PyPI 0.7.1 and anonymous access to the selected
+checker-image manifest were verified. The new runner is intended for **0.7.2**:
+the prepared 0.7.2 control must be activated after that package is published.
+Public 0.7.1 does not contain this entrypoint. A missing runner/install/report is
+a failed/incomplete job, never a successful omission.
+
+The runner is installed into a fresh runner-temporary venv with isolated Python
+and pip, `--only-binary=:all:`, and `--no-deps`. It uses the standard library and
+existing native subprocess/lifecycle helpers. Project `requirements.txt`, Python,
+R, shell, models and configuration programs are never executed to discover policy.
+
+The controller used for the existing checkers is independently pinned:
+
+```text
+ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:6aa20cff86c3891a876e37ba0548fa36f3c5633c9f22ba672e9f50123d677cf6
+```
+
+Acquisition of this public image is explicit in the workflow. During checking,
+containers use `--pull never`, network `none`, a readonly root and clone mount,
+no Docker socket, 2 CPU / 4 GiB / 512 PIDs and a bounded tmpfs. The existing exact
+session lifecycle handles their native labels/CIDs; the runner does not implement
+another resource manager.
+
+## Common control and site-owned parameters
+
+The source template is:
+
+```text
+src/unaltraweb_mcp/scaffolds/common/.github/workflows/source-checks.yml.tmpl
+```
+
+It is rendered once per package version and checker-image selection, without
+project title/language/profile substitutions. `new_web` includes it in the managed
+scaffold baseline. A changed local workflow remains protected by the existing
+no-clobber/conflict/CAS synchronization rules. The JSON policy is seeded for new
+sites but remains site-owned and is never overwritten by `scaffold_sync`.
+
+Example manual policy:
+
+```json
+{
+  "schema_version": 1,
+  "profile": "unaltremanual",
+  "public_roots": ["_chapters", "_pages"],
+  "practice_roots": ["practiques", "_practices"],
+  "data_roots": ["sandbox", "dist", "assets/pdf"],
+  "allow_empty_public_sources": false
+}
+```
+
+The exact schema is packaged as `source-check-policy-v1.schema.json`. Policy is
+bounded strict JSON in a regular, committed Git blob. Unknown keys (including
+commands), duplicate keys/roots, traversal and Git-internal roots are refused.
+Other site profiles use the same control with their declared public roots.
+
+Add every activity's data/output directory to `data_roots`, including directories
+holding JSON datasets. Within practice roots, source formats such as Markdown,
+JSON/YAML recipes, Python/R, notebooks, `.model3`, QML/SLD and authored SVG remain
+eligible. Other formats, including PDF/ZIP, raster/vector datasets and captures,
+are refused when new or modified. JSON or SVG cannot be semantically classified
+as code versus data by filename alone: declared data roots take precedence and
+block all new/changed files there. Reproduction sources belong outside those roots.
+
+Legacy means the **same path, mode, type and Git object** as the baseline. Such
+tracked data is listed as `legacy_unchanged`, not deleted or silently migrated.
+New copies/renames or modified binary bytes are not grandfathered. Deletions are
+allowed. Base and head data/practice roots are combined for the PR; the same PR
+cannot evade its baseline restrictions by narrowing policy. Public scope and the
+empty-coverage guard similarly retain the baseline requirement until a reviewed
+policy change becomes the next baseline.
+
+## Exact scope and reports
+
+The runner invokes the existing `profile-check` and `prose-check` CLIs. A separate
+`content-approval-inventory` call is an observation for the draft/status summary,
+not an approval check or promotion. The last call's bounded sample is explicitly
+marked partial when counts exceed the sample. Private handouts outside those
+native collections are not claimed as reviewed.
+
+The reports directory must be new and outside the checkout. It retains each raw
+structured checker result plus `summary.json` and `summary.md` containing:
+
+- explicit covered paths and declared public scope;
+- native exclusions, including unpublished/different-profile sources;
+- missing/unreported coverage, unsupported languages and figures `unverified`;
+- observed draft/status counts and bounded samples without changing statuses;
+- refused additions/changes and unchanged legacy files;
+- `not_run` for models, datasets, captures, PDF and ZIP validation.
+
+The guard requires real text sources in the declared roots; `_config.yml` alone
+does not count. An intentionally empty scope requires
+`allow_empty_public_sources: true` and a nonempty `empty_reason`, and is reported
+as `empty_declared`, never as checked prose. Unexpected omissions fail. Checked
+text and checker metadata must match their Git blobs; comparison reads bytes
+directly and does not run Git clean/textconv filters or project policy code.
+
+Source checks preserve warnings and partial coverage rather than interpreting a
+checker exit zero as full validation. Nonzero exit, `ok:false`, malformed or
+truncated output, timeout and unconfirmed exact teardown fail the source job.
+No `continue-on-error` masks these outcomes.
+
+The workflow listens to `pull_request` and optional manual dispatch, with only
+`contents: read`, no deployment secrets and no Pages job. PR baseline identity
+comes from the event's base commit. Manual dispatch requires an explicit full
+ancestor SHA. It uses the checkout's committed HEAD, not uncommitted work as a
+replacement baseline. The native `site-deploy.yml` and `reviewed_sha` remain
+separate; source-CI success does not authorize website/Moodle publication.
+
+## Minimal invocation and adoption
+
+After installing the containing public package and explicitly preparing the
+checker image:
+
+```bash
+python -I -m unaltraweb_mcp.source_checks \
+  --project /absolute/clean-clone \
+  --base-sha FULL_ANCESTOR_COMMIT_SHA \
+  --reports /absolute/reports-outside-clone
+```
+
+`unaltraweb-source-checks` exposes the same arguments. The runner itself never
+pulls or builds an image. It does not require private `sandbox`, dataset, PDF or
+ZIP deliveries to exist. Full scientific/output validation remains a separate
+retained-input lane, with its own source/pin/hash-bound evidence.
+
+For the existing manuals, owners can add the exact common workflow and their
+JSON policy in their authorized control change. They need not copy this Python
+implementation into each repository. Do not forge a new scaffold baseline or
+resolve an unrelated deployment-workflow conflict to add source CI: exact package
+control bytes can be adopted later by the normal baseline mechanism. Existing
+Geodisseny deployment/`reviewed_sha` customization remains untouched.

data/scripts/check_practice_verifier_runtime.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Validate the private-runtime declaration; native checks require explicit opt-in.
+
+There is deliberately no installation/download operation. Public build/CI checks
+metadata and unit fixtures only; the hub prepares the authenticated private images.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+from unaltraweb_mcp import practice_verifier
+from unaltraweb_mcp.distribution import distribution_contract
+
+COMPONENT = "qgis_practice_verifier"
+
+
+def required(contract):
+    return "manual-practice-compose" in contract.get("wheel_contract", {}).get("factory_required_mcp", [])
+
+
+def publication_errors(contract):
+    if not required(contract):
+        return []
+    try:
+        runtime = practice_verifier.runtime_contract()
+        item = contract["components"][COMPONENT]
+        if (item["kind"] != "companion" or item["name"] != runtime["provider"]["name"]
+                or item["version"] != runtime["provider"]["version"] or item["release_status"] != "released"
+                or item["release"] != runtime["release"]["tag"] or item["included_in_wheel"] is not False
+                or item["repository"] != runtime["release"]["repository"]
+                or item["reference"] != item["repository"] + ".git@" + item["release"]
+                or not set(runtime["profiles"]) <= set(item["features"])):
+            return ["Private QGIS runtime metadata differs from the accepted release declaration"]
+    except (KeyError, TypeError, OSError, ValueError) as exc:
+        return ["Private QGIS runtime declaration is incomplete: " + str(exc)]
+    return []
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check-runtime", action="store_true", help="Opt in to native checks on already hub-prepared private images")
+    parser.add_argument("--project", type=Path, help="Explicit bound workspace for the private check")
+    args = parser.parse_args(argv)
+    errors = publication_errors(distribution_contract())
+    result = {"ok": not errors, "errors": errors, "origin": "prepared-image",
+              "private_checks": {"state": "not_run", "reason": "Public CI does not acquire or execute the private QGIS runtime"}}
+    if args.check_runtime:
+        try:
+            if errors or args.project is None or not args.project.is_absolute():
+                raise ValueError("Native checking requires valid metadata and an explicit absolute project")
+            profiles = {}
+            for profile in practice_verifier.runtime_contract()["profiles"]:
+                observed = practice_verifier.call(args.project, "schema", profile=profile)
+                value = observed["result"]
+                profiles[profile] = {"package": value["installed_package"], "schema_sha256": value["schema_sha256"], "origin": observed["origin"]}
+            result["private_checks"] = {"state": "passed", "scope": "image/package/schema identity only; bundle/reopen acceptance is separate", "profiles": profiles}
+        except (OSError, ValueError, RuntimeError) as exc:
+            result.update(ok=False, errors=[*errors, str(exc)], private_checks={"state": "blocked", "reason": str(exc)})
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0 if result["ok"] else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/export_practice_runtime_archives.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Export two prepared images for the hub's existing Docker-save loader.
+
+No build, pull, load, retag, installation or resource manager is implemented here.
+The existing bounded exporter is reused; PDF provenance comes from its own BOM
+record rather than the controller's source commit.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import sys
+import tarfile
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT / "src"))
+from scripts.prepare_practice_candidate import export_image, image, sha256
+from unaltraweb_mcp.distribution import distribution_contract
+from unaltraweb_mcp.runtime_lifecycle import IMAGE_ID, immutable_reference
+
+
+def verify_archive(path, expected_id, expected_source):
+    """Inspect only Docker-save metadata/config; never extract or load layers."""
+    with tarfile.open(path, "r:gz") as archive:
+        records = archive.getmembers()
+        by_name = {entry.name: entry for entry in records}
+        if len(records) != len(by_name) or len(records) > 10000:
+            raise ValueError("Docker-save archive inventory is ambiguous or excessive")
+        def small_json(name):
+            entry = by_name.get(name)
+            if entry is None or not entry.isfile() or entry.size > 2*1024*1024:
+                raise ValueError("Docker-save metadata is missing or invalid")
+            with archive.extractfile(entry) as stream:
+                raw = stream.read()
+            return json.loads(raw), raw
+        manifest, _ = small_json("manifest.json")
+        if not isinstance(manifest, list) or len(manifest) != 1:
+            raise ValueError("Expected one immutable image per Docker-save archive")
+        item = manifest[0]
+        if item.get("RepoTags"):
+            raise ValueError("Export by configuration ID only; archive must not reassign tag aliases")
+        config, raw = small_json(item.get("Config"))
+        if "sha256:" + hashlib.sha256(raw).hexdigest() != expected_id:
+            raise ValueError("Docker-save config bytes differ from the expected image ID")
+        if config.get("config", {}).get("Labels", {}).get("org.opencontainers.image.revision") != expected_source:
+            raise ValueError("Docker-save image producer differs from its own expected source")
+        if (config.get("os"), config.get("architecture")) != ("linux", "amd64"):
+            raise ValueError("Archive must retain the selected Linux/amd64 platform")
+        for name in item.get("Layers", []):
+            if name not in by_name or not by_name[name].isfile():
+                raise ValueError("Docker-save layer is missing")
+    return {"config_id": expected_id, "source_revision": expected_source, "repo_tags": []}
+
+
+def write_new(path, value):
+    with path.open("x") as stream:
+        stream.write(json.dumps(value, indent=2, sort_keys=True) + "\n")
+        stream.flush()
+        os.fsync(stream.fileno())
+
+
+def prepare(output, controller_reference, controller_id, controller_source, pdf_id, *, controller_archive=None, controller_archive_sha256=None):
+    output = Path(output).absolute()
+    if (output.resolve() != output or not any(output.is_relative_to(root) for root in (ROOT / "tmp", Path("/tmp/opencode")))
+            or not output.parent.is_dir()):
+        raise ValueError("Select a new non-symlink export directory under factory tmp/ or /tmp/opencode/")
+    if os.path.lexists(output):
+        raise FileExistsError("Runtime archive delivery already exists")
+    if not immutable_reference(controller_reference) or not IMAGE_ID.fullmatch(controller_id) or not IMAGE_ID.fullmatch(pdf_id):
+        raise ValueError("Select immutable image references and full expected configuration IDs")
+    if not re.fullmatch(r"(?:[0-9a-f]{40}|sha256:[0-9a-f]{64})", controller_source):
+        raise ValueError("Controller source must be its exact Git or sealed snapshot identity")
+    if bool(controller_archive) != bool(controller_archive_sha256):
+        raise ValueError("Reusing a controller archive requires its exact SHA-256")
+    contract = distribution_contract()
+    pdf_reference = contract["consumer_integration"]["manual_pdf_image"]
+    producers = [row["producer_sha"] for row in contract["deployment_contract"]["manual_pdf_workers"] if row["reference"] == pdf_reference]
+    if len(producers) != 1:
+        raise ValueError("Selected PDF needs one provider-owned producer record")
+    selected = {"controller": image(controller_reference, controller_id), "manual_pdf": image(pdf_reference, pdf_id)}
+    if selected["controller"]["source_revision"] != controller_source or selected["manual_pdf"]["source_revision"] != producers[0]:
+        raise ValueError("Prepared controller/PDF does not match its own producer")
+    if controller_archive:
+        controller_archive = Path(controller_archive)
+        if controller_archive.is_symlink() or sha256(controller_archive) != controller_archive_sha256:
+            raise ValueError("Retained controller archive hash differs")
+        verify_archive(controller_archive, controller_id, controller_source)
+    if shutil.disk_usage(output.parent).free < sum(item["size"] for item in selected.values()) + 256*1024*1024:
+        raise RuntimeError("Insufficient space for the bounded archive export")
+    output.mkdir(mode=0o755)
+    exported = {}
+    for role, observed in selected.items():
+        destination = output / ("controller.docker.tar.gz" if role == "controller" else "manual-pdf.docker.tar.gz")
+        if role == "controller" and controller_archive:
+            with controller_archive.open("rb") as source, destination.open("xb") as target:
+                shutil.copyfileobj(source, target, 1024*1024)
+                target.flush()
+                os.fsync(target.fileno())
+            if sha256(destination) != controller_archive_sha256:
+                raise ValueError("Copied controller archive differs")
+            record = {"path": destination.name, "sha256": controller_archive_sha256, "bytes": destination.stat().st_size,
+                      "format": "docker-save-gzip", "reused_exact_bytes": True}
+        else:
+            record = export_image(observed["image_id"], destination)
+        archive_identity = verify_archive(destination, observed["image_id"], observed["source_revision"])
+        exported[role] = {"archive": record, "image": observed, "archive_identity": archive_identity,
+                          "offline_selection": {"reference": observed["image_id"], "expected_image_id": observed["image_id"]}}
+    manifest = {"schema_version": 1, "kind": "unaltraweb-practice-runtime-archives", "published": False, "images": exported,
+                "loading": "Existing hub H2 Docker-save loader; no Web loader or alias mutation",
+                "digest_note": "Registry digests are pre-export observations, not a claim that docker load restores RepoDigests."}
+    write_new(output / "runtime-archives.json", manifest)
+    files = [{"path": path.name, "sha256": sha256(path), "bytes": path.stat().st_size} for path in sorted(output.iterdir())]
+    write_new(output / "ready.json", {"schema_version": 1, "kind": "unaltraweb-runtime-archives-ready", "ready": True,
+                                      "manifest": "runtime-archives.json", "files": files, "published": False})
+    for row in files:
+        if sha256(output / row["path"]) != row["sha256"]:
+            raise ValueError("Runtime archive delivery changed before handoff")
+    return {"ok": True, "ready": str(output / "ready.json"), "sha256": sha256(output / "ready.json"), "images": exported}
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--controller-image", required=True)
+    parser.add_argument("--controller-id", required=True)
+    parser.add_argument("--controller-source", required=True)
+    parser.add_argument("--pdf-id", required=True)
+    parser.add_argument("--controller-archive", type=Path)
+    parser.add_argument("--controller-archive-sha256")
+    args = parser.parse_args()
+    print(json.dumps(prepare(args.output, args.controller_image, args.controller_id, args.controller_source, args.pdf_id,
+                             controller_archive=args.controller_archive, controller_archive_sha256=args.controller_archive_sha256), indent=2))