unaltraweb 0.7.1 → 0.7.3

data/scripts/prepare_practice_candidate.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Explicit offline preparation of the approved #101 practice-PDF source slice.
+
+Produces a local candidate, never a release or registry publication. The source
+archive is taken from an exact committed revision; no W1 worktree files enter it.
+The prepared public controller/PDF images and existing host build dependencies
+are required. Normal consumer launch/build commands do not invoke this script.
+"""
+from __future__ import annotations
+
+import argparse
+import gzip
+import hashlib
+import importlib.util
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import threading
+import time
+
+ROOT = Path(__file__).resolve().parents[1]
+SOURCE = "d37ef4c64eb7d2f2e7ef83cf037640ff42a964e0"
+BASE = "ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:6aa20cff86c3891a876e37ba0548fa36f3c5633c9f22ba672e9f50123d677cf6"
+BASE_ID = "sha256:f0e7915527fa68a67448287e131ec431aeae902b8269856e4e219e67faade146"
+PDF = "ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:1bb3f2dafd741e96c28639ec1cc8ccaeb81cbaa73e649f787c0b4ef59997bd4b"
+PDF_ID = "sha256:618163d3f924439792b2306617bd9612f566c5881166102fa544b4e782d569fa"
+APPROVED_PDF_SHA256 = "c92ec8a0937e9c9c735171d889e5bbca19b7ccd9ccbe8d33da2b6c0e49f9a245"
+
+
+def sha256(path):
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as source:
+        while piece := source.read(1024*1024):
+            digest.update(piece)
+    return digest.hexdigest()
+
+
+def run(command, *, environment=None, timeout=300, log=None):
+    result = subprocess.run(command, cwd=ROOT, env=environment, capture_output=True, text=True, timeout=timeout)
+    if log is not None:
+        Path(log).write_text(result.stdout + result.stderr)
+    if result.returncode:
+        raise RuntimeError(f"Command failed ({result.returncode}): {command}\n{result.stdout[-12000:]}\n{result.stderr[-12000:]}")
+    return result.stdout
+
+
+def image(reference, expected=None):
+    value = json.loads(run(["docker", "image", "inspect", reference]))[0]
+    if expected and value["Id"] != expected:
+        raise RuntimeError("Prepared image differs from the expected immutable configuration ID")
+    if "@sha256:" in reference and reference not in (value.get("RepoDigests") or []):
+        raise RuntimeError("Prepared image does not retain the selected repository digest")
+    if (value["Os"], value["Architecture"]) != ("linux", "amd64"):
+        raise RuntimeError("This candidate acceptance selects Linux/amd64")
+    return {"reference": reference, "image_id": value["Id"], "repo_digests": value.get("RepoDigests") or [],
+            "source_revision": (value["Config"].get("Labels") or {}).get("org.opencontainers.image.revision"),
+            "size": value["Size"], "os": value["Os"], "architecture": value["Architecture"]}
+
+
+def export_image(identifier, destination):
+    """Stream a bounded Docker-save archive; never buffer image layers in RAM."""
+    process = subprocess.Popen(["docker", "image", "save", identifier], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    total, deadline = 0, time.monotonic()+600
+    watchdog = threading.Timer(600, process.kill)
+    watchdog.daemon = True
+    watchdog.start()
+    try:
+        with destination.open("xb") as raw, gzip.GzipFile(fileobj=raw, filename="", mode="wb", compresslevel=1, mtime=0) as output:
+            while piece := process.stdout.read(1024*1024):
+                total += len(piece)
+                if total > 8*1024**3 or time.monotonic() > deadline:
+                    raise RuntimeError("Image archive exceeds its preparation budget")
+                output.write(piece)
+        process.stdout.close()
+        error = process.stderr.read(32768).decode(errors="replace")
+        if process.wait(timeout=10):
+            raise RuntimeError("Docker image export failed: " + error)
+    except BaseException:
+        process.kill()
+        process.wait()
+        raise
+    finally:
+        watchdog.cancel()
+        process.stdout.close()
+        process.stderr.close()
+    return {"path": destination.name, "sha256": sha256(destination), "bytes": destination.stat().st_size,
+            "uncompressed_bytes": total, "format": "docker-save-gzip"}
+
+
+def prepare(output):
+    if Path(run(["git", "rev-parse", "--show-toplevel"]).strip()) != ROOT:
+        raise RuntimeError("Candidate preparation requires the authoritative factory checkout")
+    output = Path(output).absolute()
+    if output.resolve() != output or not output.is_relative_to(ROOT / "tmp"):
+        raise RuntimeError("Use a new, non-symlink candidate directory under the factory tmp/")
+    if os.path.lexists(output):
+        raise FileExistsError("Candidate destination already exists: " + str(output))
+    if any(importlib.util.find_spec(name) is None for name in ("setuptools", "wheel", "pip")):
+        raise RuntimeError("Prepare host setuptools/wheel/pip explicitly before this offline build")
+    base, pdf = image(BASE, BASE_ID), image(PDF, PDF_ID)
+    output.mkdir(parents=True, exist_ok=False)
+    packages = output / "packages"
+    packages.mkdir()
+    archive = output / "source.tar.gz"
+    run(["git", "archive", "--format=tar.gz", "--output", str(archive), SOURCE])
+    if archive.stat().st_size > 128*1024**2:
+        raise RuntimeError("Approved source archive exceeds the preparation bound")
+    epoch = run(["git", "show", "-s", "--format=%ct", SOURCE]).strip()
+    environment = {**os.environ, "PIP_NO_INDEX": "1", "SOURCE_DATE_EPOCH": epoch, "PYTHONHASHSEED": "0", "TZ": "UTC"}
+    run([sys.executable, "-m", "pip", "wheel", str(archive), "--no-index", "--no-deps", "--no-build-isolation",
+         "--wheel-dir", str(packages)], environment=environment, log=output / "wheel-build.log")
+    wheels = list(packages.glob("*.whl"))
+    if len(wheels) != 1 or wheels[0].name != "unaltraweb_mcp-0.7.1-py3-none-any.whl":
+        raise RuntimeError("Unexpected candidate wheel inventory")
+    dockerfile = ROOT / "packaging/practice-candidate/Dockerfile"
+    shutil.copyfile(dockerfile, output / "Dockerfile")
+    (output / ".dockerignore").write_text("*\n!Dockerfile\n!source.tar.gz\n!packages/\n!packages/*.whl\n")
+    if shutil.disk_usage(output).free < base["size"] + 1024**3:
+        raise RuntimeError("Insufficient free space for the bounded portable image export")
+    run(["docker", "build", "--pull=false", "--network", "none", "--build-arg", "BASE_MCP_IMAGE=" + BASE,
+                 "--build-arg", "SOURCE_SHA=" + SOURCE, "--iidfile", str(output / "image.id"),
+                 "--file", str(output / "Dockerfile"), str(output)], timeout=600, log=output / "image-build.log")
+    identifier = (output / "image.id").read_text().strip()
+    candidate_image = image(identifier, identifier)
+    if candidate_image["source_revision"] != SOURCE:
+        raise RuntimeError("Built controller does not identify the approved source")
+    exported = export_image(identifier, output / "controller.docker.tar.gz")
+    contract = json.loads(run(["git", "show", SOURCE + ":src/unaltraweb_mcp/component-contract.json"]))
+    checker_files = ("__init__.py", "distribution.py", "component-contract.schema.json", "artifact_imports.py",
+                     "artifact_handoff_v1.py", "artifact-handoff-v1.schema.json", "letter_bundle.py", "pdf_probe.py", "processes.py")
+    checker_hashes = {name: hashlib.sha256(run(["git", "show", SOURCE + ":src/unaltraweb_mcp/" + name]).encode()).hexdigest()
+                      for name in checker_files}
+    template_paths = ["scripts/manual/templates/practice.tex", "scripts/manual/templates/manual.tex",
+                      "scripts/manual/filters/practice-layout.lua", "scripts/manual/filters/practice-finish.lua"]
+    templates = {name: hashlib.sha256(run(["git", "show", SOURCE + ":" + name]).encode()).hexdigest() for name in template_paths}
+    manifest = {"kind": "unaltraweb.practice-pdf-candidate", "schema_version": 1, "published": False,
+                "candidate_id": "practice-pdf-98-" + SOURCE[:12], "source_revision": SOURCE,
+                "package_version": "0.7.1", "version_note": "Post-release source candidate; select by these hashes, never as the published 0.7.1 wheel/image",
+                "approved_review_pdf_sha256": APPROVED_PDF_SHA256, "template_hashes": templates,
+                "source_archive": {"path": archive.name, "sha256": sha256(archive), "bytes": archive.stat().st_size},
+                "wheel": {"path": "packages/" + wheels[0].name, "sha256": sha256(wheels[0]), "bytes": wheels[0].stat().st_size},
+                "controller": candidate_image, "controller_base": base, "controller_archive": exported, "pdf_worker": pdf,
+                "consumer_integration": contract["consumer_integration"], "checker_files": checker_hashes,
+                "preparation": {"network": "none", "implicit_pull": False, "builder_sha256": sha256(__file__), "dockerfile_sha256": sha256(dockerfile)}}
+    (output / "candidate.json").write_text(json.dumps(manifest, sort_keys=True, indent=2) + "\n")
+    (output / "install-requirements.txt").write_text(f"{wheels[0].resolve().as_uri()} --hash=sha256:{manifest['wheel']['sha256']}\n")
+    print(json.dumps({"ok": True, "candidate": str(output / "candidate.json"), "candidate_sha256": sha256(output / "candidate.json"),
+                      "controller_image_id": identifier, "wheel_sha256": manifest["wheel"]["sha256"]}, indent=2))
+    return manifest
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path, required=True)
+    arguments = parser.parse_args()
+    prepare(arguments.output)

data/scripts/prepare_practice_editions_candidate.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Explicit offline successor build: approved base + exact owner source overlays.
+
+No commit, publication, source worktree copy or runtime allocation is performed.
+The GIS domain code is installed only from the selected hash-bound producer wheel.
+Historical private/local acceptance only: its embedded-QGIS images must not be
+published as public Web images. The public build now delegates to a prepared image.
+"""
+from __future__ import annotations
+
+import argparse
+import gzip
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import shutil
+import sys
+import tarfile
+
+from prepare_practice_candidate import ROOT, SOURCE, BASE, BASE_ID, PDF, PDF_ID, image, run, sha256, export_image
+
+OVERLAYS = (
+    "Makefile", "mcp-factory.yml", "pyproject.toml",
+    "src/unaltraweb_mcp/practice_editions.py", "src/unaltraweb_mcp/practice-edition-v1.schema.json",
+    "src/unaltraweb_mcp/practice_pdf.py", "src/unaltraweb_mcp/editorial_sources.py",
+    "src/unaltraweb_mcp/site_tools.py", "src/unaltraweb_mcp/mcp_server.py", "src/unaltraweb_mcp/cli.py",
+    "src/unaltraweb_mcp/component-contract.json",
+    "scripts/manual/render_practice.py",
+)
+TRANSFER = Path("/tmp/opencode/practice32-qgis-0.6.0rc1-round32-r2")
+GIS_SHA = "82f2c6772fa8bb9aaae08237494af72df7e103038643fd6dfcdcd6f1ac45ed5f"
+
+
+def prepare(output, gis_wheel, gis_sha, profiles=("qgis-practice-v1",)):
+    if not profiles or len(profiles) != len(set(profiles)) or set(profiles) - {"qgis-practice-v1", "qgis-practice-v2"}:
+        raise ValueError("Select explicit supported producer profiles")
+    output = output.absolute()
+    if output.resolve() != output or not output.is_relative_to(ROOT / "tmp") or output.exists():
+        raise ValueError("Select a new confined candidate directory under tmp/")
+    if sha256(gis_wheel) != gis_sha:
+        raise ValueError("Producer wheel differs from the selected SHA-256")
+    base, pdf = image(BASE, BASE_ID), image(PDF, PDF_ID)
+    output.mkdir(parents=True, exist_ok=False)
+    packages = output / "packages"
+    packages.mkdir()
+    original = output / "approved-source.tar.gz"
+    run(["git", "archive", "--format=tar.gz", "--output", str(original), SOURCE])
+    epoch = int(run(["git", "show", "-s", "--format=%ct", SOURCE]).strip())
+    changes = {}
+    for name in OVERLAYS:
+        path = ROOT / name
+        if path.is_symlink() or not path.is_file() or path.stat().st_size > 2*1024*1024:
+            raise ValueError("Unsafe candidate overlay: " + name)
+        changes[name] = path.read_bytes()
+    source = output / "source.tar.gz"
+    with original.open("rb") as raw_source, tarfile.open(fileobj=raw_source, mode="r:gz") as previous, \
+            source.open("xb") as raw_dest, gzip.GzipFile(fileobj=raw_dest, mode="wb", filename="", mtime=0) as compressed, \
+            tarfile.open(fileobj=compressed, mode="w|") as snapshot:
+        for member in previous:
+            if member.name not in changes:
+                snapshot.addfile(member, previous.extractfile(member) if member.isfile() else None)
+        for name, raw in sorted(changes.items()):
+            info = tarfile.TarInfo(name)
+            info.size, info.mode, info.mtime = len(raw), 0o644, epoch
+            snapshot.addfile(info, io.BytesIO(raw))
+    source_sha = sha256(source)
+    env = {**os.environ, "PIP_NO_INDEX": "1", "SOURCE_DATE_EPOCH": str(epoch), "PYTHONHASHSEED": "0", "TZ": "UTC"}
+    run([sys.executable, "-m", "pip", "wheel", str(source), "--no-index", "--no-deps", "--no-build-isolation", "--wheel-dir", str(packages)],
+        environment=env, log=output / "wheel-build.log")
+    web_wheel = next(packages.glob("unaltraweb_mcp-*.whl"))
+    shutil.copyfile(gis_wheel, packages / gis_wheel.name)
+    dockerfile = ROOT / "packaging/practice-editions-candidate/Dockerfile"
+    shutil.copyfile(dockerfile, output / "Dockerfile")
+    (output / ".dockerignore").write_text("*\n!Dockerfile\n!source.tar.gz\n!packages/\n!packages/*.whl\n")
+    run(["docker", "build", "--pull=false", "--network", "none", "--build-arg", "BASE_MCP_IMAGE="+BASE,
+         "--build-arg", "SOURCE_SNAPSHOT_SHA256="+source_sha, "--iidfile", str(output / "image.id"), str(output)],
+        timeout=600, log=output / "image-build.log")
+    identifier = (output / "image.id").read_text().strip()
+    actual = image(identifier, identifier)
+    if actual["source_revision"] != "sha256:"+source_sha:
+        raise ValueError("Candidate source identity differs")
+    schema = json.loads(run(["docker", "run", "--rm", "--pull", "never", "--network", "none", "--read-only", "--entrypoint", "unaltracaptura-qgis", identifier, "practice-schema"]))
+    profile_records = {}
+    for profile in profiles:
+        observed = schema if profile == "qgis-practice-v1" else json.loads(run([
+            "docker", "run", "--rm", "--pull", "never", "--network", "none", "--read-only", "--entrypoint", "unaltracaptura-qgis", identifier,
+            "practice-schema", "--profile", profile]))
+        if observed.get("profile") != profile or observed.get("ok") is not True:
+            raise ValueError("Installed producer did not identify the requested domain profile")
+        profile_records[profile] = {"package": observed["installed_package"], "schema_sha256": observed["schema_sha256"]}
+    archive = export_image(identifier, output / "controller.docker.tar.gz")
+    contract = json.loads(changes["src/unaltraweb_mcp/component-contract.json"])
+    manifest = {"kind": "unaltraweb.practice-editions-candidate", "schema_version": 1, "published": False,
+        "source_base": SOURCE, "source_snapshot_sha256": source_sha,
+        "overlays": {name: hashlib.sha256(raw).hexdigest() for name, raw in sorted(changes.items())},
+        "version_note": "Unpublished hash-bound successor; package metadata remains 0.7.1 and is not the published 0.7.1 artifact",
+        "controller": actual, "controller_archive": archive, "controller_base": base, "pdf_worker": pdf,
+        "web_wheel": {"path": "packages/"+web_wheel.name, "sha256": sha256(web_wheel)},
+        "gis_wheel": {"path": "packages/"+gis_wheel.name, "sha256": gis_sha},
+        "gis_verifier": {"package": schema["installed_package"], "schema_sha256": schema["schema_sha256"]},
+        "gis_profiles": profile_records,
+        "composition_schema_sha256": sha256(ROOT / "src/unaltraweb_mcp/practice-edition-v1.schema.json"),
+        "consumer_integration": contract["consumer_integration"],
+        "builder_sha256": sha256(__file__), "dockerfile_sha256": sha256(dockerfile)}
+    (output / "candidate.json").write_text(json.dumps(manifest, sort_keys=True, indent=2)+"\n")
+    (output / "install-requirements.txt").write_text(f"{web_wheel.as_uri()} --hash=sha256:{sha256(web_wheel)}\n")
+    print(json.dumps({"ok": True, "candidate": str(output / "candidate.json"), "sha256": sha256(output / "candidate.json"), "image_id": identifier}, indent=2))
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--gis-wheel", type=Path, default=TRANSFER / "unaltracaptura_qgis-0.6.0rc1-py3-none-any.whl")
+    parser.add_argument("--gis-sha256", default=GIS_SHA)
+    parser.add_argument("--gis-profile", action="append", choices=["qgis-practice-v1", "qgis-practice-v2"])
+    args = parser.parse_args()
+    prepare(args.output, args.gis_wheel, args.gis_sha256, args.gis_profile or ["qgis-practice-v1"])

data/scripts/test_wheel_install.py

@@ -76,6 +76,11 @@ def main() -> int:
             for installed_path, source_path in launcher_files.items():
                 if archive.read(launcher_prefix + installed_path) != (ROOT / source_path).read_bytes():
                     raise RuntimeError(f"Wheel launcher asset differs from source: {installed_path}")
+            for name in ("component-contract.json", "practice-verifier-runtime.json"):
+                if archive.read("unaltraweb_mcp/" + name) != (ROOT / "src/unaltraweb_mcp" / name).read_bytes():
+                    raise RuntimeError(f"Wheel dependency declaration differs from source: {name}")
+            if any(name.startswith(("veure_qgis_mcp/", "unaltracaptura_annotations/")) for name in names):
+                raise RuntimeError("Private QGIS implementation leaked into the public wheel")
         forbidden_roots = {"docs", "scripts", "_layouts", "_includes", "_sass"}
         leaked = []
         for name in names:
@@ -103,6 +108,10 @@ def main() -> int:
             "unaltraweb_mcp/editorial_sources.py",
             "unaltraweb_mcp/image_backgrounds.py",
             "unaltraweb_mcp/image_probe.py",
+            "unaltraweb_mcp/source_checks.py",
+            "unaltraweb_mcp/source-check-policy-v1.schema.json",
+            "unaltraweb_mcp/practice_verifier.py",
+            "unaltraweb_mcp/practice-verifier-runtime.json",
             "unaltraweb_mcp/scaffolds/common/AGENTS.md.tmpl",
             "unaltraweb_mcp/scaffolds/common/Makefile.tmpl",
             "unaltraweb_mcp/scaffolds/common/README.md.tmpl",
@@ -117,6 +126,7 @@ def main() -> int:
             "unaltraweb_mcp/scaffolds/common/.github/dependabot.yml.tmpl",
             "unaltraweb_mcp/scaffolds/common/.github/pull_request_template.md",
             "unaltraweb_mcp/scaffolds/common/.github/workflows/deploy.yml.tmpl",
+            "unaltraweb_mcp/scaffolds/common/.github/workflows/source-checks.yml.tmpl",
         ]
         missing = [name for name in required if name not in names]
         if missing:
@@ -129,6 +139,10 @@ def main() -> int:
         python = environment / "bin/python"
         cli = environment / "bin/unaltraweb-mcp"
         run([str(python), "-m", "pip", "install", "--no-deps", str(wheels[0])], cwd=temp, env=env)
+        source_cli = environment / "bin/unaltraweb-source-checks"
+        source_help = run([str(source_cli), "--help"], cwd=temp).stdout
+        if "--base-sha" not in source_help or "--reports" not in source_help:
+            raise RuntimeError("Installed source-CI entrypoint is missing its bounded interface")
         docker_cli = environment / "bin/unaltraweb-mcp-docker"
         launcher = Path(run([str(docker_cli), "path"], cwd=temp).stdout.strip())
         if launcher != environment / "share/unaltraweb-launcher":
@@ -178,6 +192,11 @@ def main() -> int:
             ], cwd=temp).stdout)
             if not created["ok"]:
                 raise RuntimeError(f"new-web failed for {profile} from clean wheel: {created}")
+            source_policy = json.loads((profile_site / ".unaltraweb/source-checks.json").read_bytes())
+            if source_policy["profile"] != profile:
+                raise RuntimeError("Source-CI policy did not declare the generated profile")
+            if not (profile_site / ".github/workflows/source-checks.yml").is_file():
+                raise RuntimeError("Source-CI workflow control is missing")
             readme = (profile_site / "README.md").read_text(encoding="utf-8")
             agents = (profile_site / "AGENTS.md").read_text(encoding="utf-8")
             collaboration = (profile_site / ".github/CONTRIBUTING.md").read_text(encoding="utf-8")
@@ -317,6 +336,7 @@ def main() -> int:
                 "Gemfile.lock",
                 ".github/pull_request_template.md",
                 ".github/workflows/deploy.yml",
+                ".github/workflows/source-checks.yml",
             }
             if set(manifest["files"]) != expected_managed:
                 raise RuntimeError(f"generated {profile} scaffold baseline is incomplete: {manifest['files']}")

data/scripts/unaltraweb-mcp-bootstrap.sh

@@ -15,7 +15,7 @@ Managed mode requires an immutable reference or an expected full image ID.
 USAGE
 }
 
-image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:b84cdb404ba7bab5ff0b14fa8a7ee93d7293e829cf32e28ff0dacaa8afff4677}"
+image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:6aa20cff86c3891a876e37ba0548fa36f3c5633c9f22ba672e9f50123d677cf6}"
 project="${MCP_CONSUMER_WORKSPACE:-${UNALTRAWEB_PROJECT:-}}"
 operation=serve
 expected_image="${UNALTRAWEB_EXPECTED_IMAGE_ID:-}"

data/scripts/validate_distribution.py

@@ -41,6 +41,7 @@ from unaltraweb_mcp.distribution import (  # noqa: E402
     validate_component_contract,
 )
 from scripts.validate_workflows import DEPLOY_PDF_PROVENANCE_POLICY_SHA256, load_workflow_text, reusable_deploy_input_errors  # noqa: E402
+from scripts import check_practice_verifier_runtime as practice_verifier  # noqa: E402
 
 
 def load_yaml(path: Path) -> dict[str, Any]:
@@ -111,6 +112,9 @@ def validate(root: Path = ROOT) -> list[str]:
     required_components = {
         "gem", "wheel", "runtime", "mcp", "compute_python", "compute_r", "web_capture", "manual_pdf", "diavisuals", "vegavisuals"
     }
+    if practice_verifier.COMPONENT in contract.get("components", {}):
+        required_components.add(practice_verifier.COMPONENT)
+        errors.extend(practice_verifier.publication_errors(contract))
     if contract.get("schema_version") != 1:
         errors.append("component contract schema_version must be 1")
     if set(contract.get("components", {})) != required_components:
@@ -121,6 +125,10 @@ def validate(root: Path = ROOT) -> list[str]:
     if __version__ != version:
         errors.append(f"wheel version {__version__} != contract version {version}")
     errors.extend(component_version_errors(contract))
+    if practice_verifier.required(contract):
+        dockerfile = (root / "Dockerfile.mcp").read_text()
+        if "install_practice_verifier" in dockerfile or re.search(r"(?im)^\s*(?:RUN|COPY|ADD).*unaltracaptura", dockerfile):
+            errors.append("Public MCP image must not download or embed the private QGIS package")
     included = {name for name, item in contract["components"].items() if item["included_in_wheel"]}
     if included != {"wheel"}:
         errors.append(f"wheel must not bundle external components: {sorted(included)}")
@@ -212,6 +220,9 @@ def validate(root: Path = ROOT) -> list[str]:
     if make_value(root / "packaging/launcher/Makefile", "MCP_RELEASE_IMAGE") != component_reference("mcp"):
         errors.append("installed launcher must select its own package release image")
     project = pyproject.get("project", {})
+    dependencies = [*project.get("dependencies", []), *(entry for values in project.get("optional-dependencies", {}).values() for entry in values)]
+    if any(re.search(r"unaltracaptura[-_]qgis", str(entry), re.I) for entry in dependencies):
+        errors.append("Public Web wheel must not install the private QGIS package as a dependency")
     if "version" in project or project.get("dynamic") != ["version"]:
         errors.append("pyproject version must be derived from the package component contract")
     if pyproject.get("tool", {}).get("setuptools", {}).get("dynamic", {}).get("version", {}).get("attr") != "unaltraweb_mcp.__version__":
@@ -515,7 +526,7 @@ def publish_ref_errors(
     default_branch: str,
     component_ids: list[str],
 ) -> list[str]:
-    errors: list[str] = []
+    errors: list[str] = practice_verifier.publication_errors(contract)
     release = contract.get("release", {})
     version = str(release.get("version") or "")
     release_tag = str(release.get("tag") or "")
@@ -590,6 +601,10 @@ def main(argv: list[str] | None = None) -> int:
         component_id for component_id, selected in contract["components"].items()
         if selected["release_status"] == "pending"
     )
+    verifier_errors = practice_verifier.publication_errors(contract)
+    if verifier_errors and practice_verifier.COMPONENT not in pending:
+        pending.append(practice_verifier.COMPONENT)
+        pending.sort()
     unavailable = sorted(
         component_id for component_id, selected in contract["components"].items()
         if selected["release_status"] == "unavailable"
@@ -612,6 +627,8 @@ def main(argv: list[str] | None = None) -> int:
         "errors": errors,
         "pending_releases": pending,
         "unavailable_releases": unavailable,
+        "practice_verifier": {"selection_ready": not verifier_errors, "errors": verifier_errors, "origin": "prepared-image",
+                              "private_checks": {"state": "not_run", "reason": "Public CI uses metadata/unit fixtures; native private acceptance and review are separate required gates"}},
     }, indent=2, sort_keys=True))
     readiness_errors = release_tag_errors + candidate_receipt_errors
     structural_errors = [error for error in errors if error not in readiness_errors]

data/src/unaltraweb_mcp/component-contract.json

@@ -2,8 +2,8 @@
   "$schema": "component-contract.schema.json",
   "schema_version": 1,
   "release": {
-    "version": "0.7.1",
-    "tag": "v0.7.1"
+    "version": "0.7.3",
+    "tag": "v0.7.3"
   },
   "consumer_integration": {
     "schema_version": 1,
@@ -55,17 +55,17 @@
     "package_only_commands": ["doctor", "import-calibre", "new-web", "version"],
     "factory_required_commands": ["factory-dir"],
     "package_only_mcp": ["artifact-import-check", "import-artifact-bundle", "bibliography-add-entry", "bibliography-inventory", "build-health", "content-approval-inventory", "content-freshness-check", "content-inventory", "detect-site", "editorial-policy", "editorial-publication-check", "editorial-review-prepare", "editorial-review-record", "editorial-review-resolve", "editorial-status", "html-audit", "http-check", "image-background-check", "initialize-site", "language-policy", "list-tools", "manual-authoring-capabilities", "manual-editorial-quality-check", "manual-pdf-preview-clean", "manual-source-quality-check", "new-web", "preview-start", "preview-status", "preview-stop", "profile-check", "profile-prune", "profile-prune-plan", "prose-check", "scaffold-sync", "site-context", "site-doctor", "site-source-delete", "site-source-read", "site-source-write", "starter-templates", "translation-plan"],
-    "factory_required_mcp": ["bibliometrics-check", "bibliometrics-fetch-scimago", "bibliometrics-update", "build-site", "manual-computation-check", "manual-computation-render", "manual-computation-render-figures", "manual-computation-status", "manual-pdf-build", "manual-pdf-preview-prepare", "manual-pdf-publish", "manual-pdf-status", "manual-release-check", "manual-release-prepare", "manual-release-status", "prompts", "serve", "site-check", "web-capture-check", "web-capture-render", "web-capture-status"],
-    "not_bundled": ["gem", "runtime", "mcp", "compute_python", "compute_r", "web_capture", "manual_pdf", "diavisuals", "vegavisuals"]
+    "factory_required_mcp": ["bibliometrics-check", "bibliometrics-fetch-scimago", "bibliometrics-update", "build-site", "manual-computation-check", "manual-computation-render", "manual-computation-render-figures", "manual-computation-status", "manual-pdf-build", "manual-pdf-preview-prepare", "manual-pdf-publish", "manual-pdf-status", "manual-practice-compose", "manual-practice-pdf-build", "manual-release-check", "manual-release-prepare", "manual-release-status", "prompts", "serve", "site-check", "web-capture-check", "web-capture-render", "web-capture-status"],
+    "not_bundled": ["gem", "runtime", "mcp", "compute_python", "compute_r", "web_capture", "manual_pdf", "diavisuals", "vegavisuals", "qgis_practice_verifier"]
   },
   "components": {
     "gem": {
       "kind": "gem",
       "name": "unaltraweb",
-      "version": "0.7.1",
-      "release": "v0.7.1",
+      "version": "0.7.3",
+      "release": "v0.7.3",
       "release_status": "ready",
-      "reference": "unaltraweb (= 0.7.1)",
+      "reference": "unaltraweb (= 0.7.3)",
       "repository": "https://github.com/dosquartsdedocs/unaltraweb",
       "included_in_wheel": false,
       "features": ["jekyll-core", "site-build"]
@@ -73,21 +73,21 @@
     "wheel": {
       "kind": "python-wheel",
       "name": "unaltraweb-mcp",
-      "version": "0.7.1",
-      "release": "v0.7.1",
+      "version": "0.7.3",
+      "release": "v0.7.3",
       "release_status": "ready",
-      "reference": "unaltraweb-mcp==0.7.1",
+      "reference": "unaltraweb-mcp==0.7.3",
       "repository": "https://github.com/dosquartsdedocs/unaltraweb",
       "included_in_wheel": true,
-      "features": ["calibre-import", "doctor", "new-web", "offline-inspection", "mcp-control-plane"]
+      "features": ["calibre-import", "doctor", "new-web", "offline-inspection", "mcp-control-plane", "source-ci"]
     },
     "runtime": {
       "kind": "container",
       "name": "unaltraweb runtime",
-      "version": "0.7.1",
-      "release": "v0.7.1",
+      "version": "0.7.3",
+      "release": "v0.7.3",
       "release_status": "ready",
-      "reference": "ghcr.io/dosquartsdedocs/unaltraweb:0.7.1",
+      "reference": "ghcr.io/dosquartsdedocs/unaltraweb:0.7.3",
       "image_repository": "ghcr.io/dosquartsdedocs/unaltraweb",
       "repository": "https://github.com/dosquartsdedocs/unaltraweb",
       "included_in_wheel": false,
@@ -96,10 +96,10 @@
     "mcp": {
       "kind": "container",
       "name": "unaltraweb MCP runtime",
-      "version": "0.7.1",
-      "release": "v0.7.1",
+      "version": "0.7.3",
+      "release": "v0.7.3",
       "release_status": "ready",
-      "reference": "ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.7.1",
+      "reference": "ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.7.3",
       "image_repository": "ghcr.io/dosquartsdedocs/unaltraweb-mcp",
       "repository": "https://github.com/dosquartsdedocs/unaltraweb",
       "included_in_wheel": false,
@@ -153,6 +153,17 @@
       "included_in_wheel": false,
       "features": ["manual-pdf"]
     },
+    "qgis_practice_verifier": {
+      "kind": "companion",
+      "name": "unaltracaptura-qgis",
+      "version": "0.6.1",
+      "release": "v0.6.1",
+      "release_status": "released",
+      "reference": "https://github.com/dosquartsdedocs/unaltracaptura-qgis.git@v0.6.1",
+      "repository": "https://github.com/dosquartsdedocs/unaltracaptura-qgis",
+      "included_in_wheel": false,
+      "features": ["qgis-practice-v1", "qgis-practice-v2", "private-prepared-runtime"]
+    },
     "diavisuals": {
       "kind": "companion",
       "name": "diavisuals",

data/src/unaltraweb_mcp/editorial_sources.py

@@ -21,6 +21,8 @@ CONTENT_ROOTS = ("_pages", "_posts", "_news", "_projects", "_outputs", "_chapter
 TEXT_SUFFIXES = {".md", ".markdown", ".html", ".qmd", ".rmd"}
 PUBLIC_FIELDS = {"title", "short_title", "description", "excerpt", "summary", "bio", "caption", "alt"}
 GENRES = {"prose", "bio", "news", "chapter", "procedure", "reference", "preface", "quote", "example", "cv"}
+PRACTICE_SOURCE = re.compile(r"practiques/([a-z0-9][a-z0-9-]{0,63})/(ca|es|en)/(alumnat|docent)/(LLEGIU-ME|LEEME|README)\.md\Z")
+PRACTICE_NAMES = {"ca": "LLEGIU-ME", "es": "LEEME", "en": "README"}
 
 
 def default_language(config: dict[str, Any]) -> str:
@@ -107,6 +109,51 @@ def relative_path(raw: str) -> str:
     return raw
 
 
+def private_practice_readings(config: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """One bounded author-declared mapping shared by private review and PDFs."""
+    section = (config.get("unaltraweb") or {}).get("practices") or {}
+    if not isinstance(section, dict):
+        raise EditorialError("unaltraweb.practices must be a mapping")
+    rows = section.get("readings", [])
+    if not isinstance(rows, list) or len(rows) > 128:
+        raise EditorialError("Private reading mappings must be a bounded list")
+    result, identities, names = {}, set(), set()
+    for row in rows:
+        if (not isinstance(row, dict) or not {"source", "slug", "lang", "recipient"} <= row.keys()
+                or set(row) - {"source", "slug", "lang", "recipient", "bindings"}
+                or not all(isinstance(row[key], str) for key in ("source", "slug", "lang", "recipient"))):
+            raise EditorialError("Private reading mapping requires source/slug/lang/recipient")
+        if "bindings" in row and (not isinstance(row["bindings"], list) or len(row["bindings"]) > 200):
+            raise EditorialError("Reading resource bindings must be a bounded list")
+        source = relative_path(row["source"])
+        if (Path(source).parts[0] not in {"practiques", "_practices"} or Path(source).suffix != ".md"
+                or len(Path(source).parts) < 3 or any(part.startswith(".") for part in Path(source).parts)
+                or not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,63}", row["slug"])
+                or row["lang"] not in PRACTICE_NAMES or row["recipient"] not in {"alumnat", "docent"}):
+            raise EditorialError("Invalid confined private reading mapping")
+        identity = (row["slug"], row["lang"], row["recipient"])
+        canonical = PRACTICE_SOURCE.fullmatch(source)
+        if canonical and (canonical.groups()[:3] != identity or canonical[4] != PRACTICE_NAMES[row["lang"]]):
+            raise EditorialError("Mapping conflicts with the canonical reading identity")
+        other = "docent" if row["recipient"] == "alumnat" else "alumnat"
+        if other in Path(source).parts or source.casefold() in names or identity in identities:
+            raise EditorialError("Duplicate or cross-recipient private reading mapping")
+        result[source] = dict(row)
+        names.add(source.casefold())
+        identities.add(identity)
+    return result
+
+
+def private_practice_identity(config: dict[str, Any], source: str) -> dict[str, Any] | None:
+    declared = private_practice_readings(config)
+    if source in declared:
+        return declared[source]
+    match = PRACTICE_SOURCE.fullmatch(source)
+    if match and match[4] == PRACTICE_NAMES[match[2]]:
+        return {"source": source, "slug": match[1], "lang": match[2], "recipient": match[3]}
+    return None
+
+
 class Reader:
     """Descriptor-relative reads; never follows an input symlink or creates files."""
     def __init__(self, root: Path, *, max_bytes: int | None = None, max_total_bytes: int | None = None):
@@ -427,8 +474,10 @@ def corpus(reader: Reader, config: dict[str, Any], profile: str, target: str = "
     extra = config.get("collections") or {}
     if not manual_only and isinstance(extra, dict):
         roots.update("_" + key for key in extra if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]*", str(key)))
+    roots.difference_update({"practiques", "_practices"})
+    private = private_practice_identity(config, target) if target and profile == "unaltremanual" else None
     root_pages = reader.root_pages() if not manual_only else []
-    if target and target != "_config.yml" and target.split("/")[0] not in roots and target not in root_pages:
+    if target and not private and target != "_config.yml" and target.split("/")[0] not in roots and target not in root_pages:
         raise EditorialError("Editorial target must be reader-facing content or public metadata.")
     paths = ([target] if Path(target).suffix else reader.walk(target)) if target else [path for root in sorted(roots) for path in reader.walk(root)]
     if not target:
@@ -443,7 +492,7 @@ def corpus(reader: Reader, config: dict[str, Any], profile: str, target: str = "
         raise EditorialError("Site languages must be a list of language codes.")
     sources, fragments, skipped = {}, [], []
     for path in sorted(set(paths)):
-        if any(isinstance(pattern, str) and (fnmatch.fnmatch(path, pattern) or path.startswith(pattern.rstrip("/") + "/")) for pattern in excludes):
+        if not private and any(isinstance(pattern, str) and (fnmatch.fnmatch(path, pattern) or path.startswith(pattern.rstrip("/") + "/")) for pattern in excludes):
             skipped.append({"path": path, "reason": "excluded by site configuration"})
             continue
         suffix = Path(path).suffix.lower()
@@ -456,6 +505,8 @@ def corpus(reader: Reader, config: dict[str, Any], profile: str, target: str = "
             continue
         lang = next((part for part in Path(path).parts if part in languages), default_lang)
         genre = "news" if path.startswith(("_news/", "_posts/")) else "chapter" if path.startswith(f"_{collection}/") else "reference" if profile == "unaltredocs" else "prose"
+        if private:
+            lang, genre = private["lang"], "procedure"
         if metadata:
             if suffix == ".json":
                 data = strict_json(content)
@@ -469,12 +520,18 @@ def corpus(reader: Reader, config: dict[str, Any], profile: str, target: str = "
                 profiles = [profiles]
             if not isinstance(profiles, list) or any(not isinstance(item, str) for item in profiles):
                 raise EditorialError(f"Invalid profiles in {path}.")
-            if front.get("published") is False or (profiles and profile not in profiles):
+            if private and front.get("lang", lang) != lang:
+                raise EditorialError("Reading language differs from its declared mapping")
+            if not private and (front.get("published") is False or (profiles and profile not in profiles)):
                 skipped.append({"path": path, "reason": "not published in this profile"})
                 continue
             if manual_only and path.startswith("_pages/") and front.get("layout") not in {"manual-home", "manual-chapter"} and "unaltremanual" not in profiles:
                 continue
         sources[path] = {"path": path, "sha256": digest(content.encode()), "text": content, "editable_source": path}
+        if private:
+            sources[path].update(scope="private-practice", reading=private)
+            for unit in units:
+                unit["scope"] = "private-practice"
         fragments.extend(units)
         if len(fragments) > MAX_FRAGMENTS:
             raise EditorialError("Editorial fragment budget exceeded; select a smaller target.")
@@ -501,4 +558,5 @@ def corpus(reader: Reader, config: dict[str, Any], profile: str, target: str = "
     if target and not sources:
         raise EditorialError(f"No selected publishable sources for target: {target}")
     return {"sources": sources, "fragments": fragments, "skipped": skipped,
-            "coverage": "Markdown/HTML prose and public metadata fields; code, math and quotations require semantic/rendered review."}
+            "coverage": ("Explicitly selected private practice reading; no publication or author approval implied." if private else
+                         "Markdown/HTML prose and public metadata fields; code, math and quotations require semantic/rendered review.")}