unaltraweb 0.7.0 → 0.7.2

data/scripts/manual/filters/practice-finish.lua

@@ -0,0 +1,36 @@
+-- Consume the core caption filter's output, preserving its short captions/credits.
+local continuation = "continued"
+local function metadata(meta)
+  continuation = pandoc.utils.stringify(meta["continuation-label"] or "continued")
+end
+
+local function figures(blocks)
+  local result, figure = pandoc.List(), nil
+  for _, block in ipairs(blocks) do
+    if block.t == "RawBlock" and block.text == "\\begin{figure}[H]\n\\centering" then
+      assert(not figure, "Nested practice figure")
+      figure = pandoc.List()
+    elseif figure and block.t == "RawBlock" and block.text == "\\end{figure}" then
+      assert(#figure == 2, "Practice figures require one caption and one image")
+      local caption = pandoc.write(pandoc.Pandoc({figure[1]}), "latex"):gsub("%s+$", "")
+      local image = pandoc.write(pandoc.Pandoc({figure[2]}), "latex"):gsub("%s+$", "")
+      result:insert(pandoc.RawBlock("latex", "\\PracticeFigure{" .. caption .. "}{" .. image .. "}"))
+      figure = nil
+    elseif figure then figure:insert(block)
+    else result:insert(block) end
+  end
+  assert(not figure, "Unclosed practice figure")
+  return result
+end
+
+local function table_caption(element)
+  assert(#element.caption.long > 0, "Practice tables require a Table: caption")
+  local rendered = pandoc.write(pandoc.Pandoc({element}), "latex")
+  local caption = pandoc.write(pandoc.Pandoc(element.caption.long), "latex"):gsub("%s+$", "")
+  rendered = rendered:gsub("\\endfirsthead", function()
+    return "\\endfirsthead\n\\caption[]{" .. caption .. " (" .. continuation .. ")}\\tabularnewline"
+  end, 1)
+  return pandoc.RawBlock("latex", rendered)
+end
+
+return {{Meta = metadata}, {Blocks = figures, Table = table_caption}}

data/scripts/manual/filters/practice-layout.lua

@@ -0,0 +1,84 @@
+-- Private practice PDFs use their own counters, pagination and image policy.
+local assets = {}
+
+local function metadata(meta)
+  for original, target in pairs(meta["practice-assets"] or {}) do
+    assets[original] = pandoc.utils.stringify(target)
+  end
+end
+
+local function image(element)
+  local target = assets[element.src]
+  assert(target, "Undeclared practice image: " .. element.src)
+  element.src = target
+  return element
+end
+
+local function figure(element)
+  assert(#element.content == 1 and element.content[1].content
+    and #element.content[1].content == 1 and element.content[1].content[1].t == "Image",
+    "Practice figures require one standalone image")
+  local picture = element.content[1].content[1]
+  picture.attributes.width = nil
+  picture.attributes.height = nil
+  if picture.title ~= "" then
+    element.caption.long = pandoc.read(picture.title, "markdown").blocks
+  end
+  assert(#element.caption.long > 0, "Practice figures require a caption")
+  return element
+end
+
+local function line_count(text)
+  local _, count = text:gsub("\n", "")
+  return count + 1
+end
+
+local function blocks(values)
+  local result = pandoc.List()
+  for index, element in ipairs(values) do
+    local needed = nil
+    if element.t == "Header" then
+      needed = 6
+      local following = values[index + 1]
+      if following and following.t == "Table" then needed = 9 end
+      if following and following.t == "CodeBlock" and line_count(following.text) <= 12 then
+        needed = line_count(following.text) + 7
+      end
+    elseif element.t == "CodeBlock" and line_count(element.text) <= 12 then
+      needed = line_count(element.text) + 4
+    end
+    if needed then
+      result:insert(pandoc.RawBlock("latex", "\\Needspace{" .. needed .. "\\baselineskip}"))
+    end
+    result:insert(element)
+  end
+  return result
+end
+
+local function table_widths(element)
+  if #element.colspecs < 3 then return nil end
+  for _, column in ipairs(element.colspecs) do
+    if column[2] and column[2] ~= 0 then return nil end
+  end
+  local weights, counts, longest = {}, {}, {}
+  for index in ipairs(element.colspecs) do weights[index], counts[index], longest[index] = 0, 0, 0 end
+  for _, body in ipairs(element.bodies) do
+    for _, row in ipairs(body.body) do
+      for index, cell in ipairs(row.cells) do
+        local text = pandoc.utils.stringify(cell.contents)
+        weights[index] = weights[index] + utf8.len(text)
+        counts[index] = counts[index] + 1
+        for word in text:gmatch("%S+") do longest[index] = math.max(longest[index], utf8.len(word)) end
+      end
+    end
+  end
+  local total = 0
+  for index in ipairs(weights) do
+    weights[index] = math.max(12, longest[index] * 0.9, math.min(90, weights[index] / math.max(1, counts[index]) * 0.65))
+    total = total + weights[index]
+  end
+  for index, weight in ipairs(weights) do element.colspecs[index] = {element.colspecs[index][1], weight / total} end
+  return element
+end
+
+return {{Meta = metadata}, {Image = image}, {Figure = figure, Table = table_widths}, {Blocks = blocks}}

data/scripts/manual/practice_pdf.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Consumer-bound entry point used by the factory Make contract."""
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+
+FACTORY = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(FACTORY / "src"))
+from unaltraweb_mcp.distribution import consumer_integration
+from unaltraweb_mcp.practice_pdf import build
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project", required=True)
+    args = parser.parse_args()
+    try:
+        result = build(Path(args.project), FACTORY, os.environ.get("PRACTICE_SOURCE", ""),
+                       os.environ.get("PRACTICE_VERSION", ""), run=os.environ.get("PRACTICE_RUN", ""),
+                       image=os.environ.get("MANUAL_PDF_IMAGE") or consumer_integration()["manual_pdf_image"],
+                       dry_run=os.environ.get("PRACTICE_DRY_RUN", "0") == "1")
+    except (OSError, ValueError, RuntimeError) as exc:
+        result = {"ok": False, "publishes": False, "error": str(exc)}
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/manual/render_practice.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Run only inside the bounded PDF toolchain with /source readonly and /out writable."""
+import json
+from pathlib import Path
+import re
+import subprocess
+from urllib.parse import unquote, urlsplit
+
+SOURCE = Path("/source")
+OUTPUT = Path("/out")
+MARKDOWN = "markdown+fenced_divs+pipe_tables+link_attributes-raw_tex-raw_html"
+
+
+def run(command, log):
+    subprocess.run(command, cwd=OUTPUT, check=True, stdout=log, stderr=subprocess.STDOUT)
+
+
+def effective_source(request, log):
+    """Apply the controller's authorised links to the actual Pandoc AST.
+
+    This is a lookup/fail-closed rendering pass, not another filesystem resolver.
+    The exact effective AST/Markdown are retained with the render artifacts.
+    """
+    assert request.get("portable_links") == "portable-links.json"
+    raw = (SOURCE / "portable-links.json").read_bytes()
+    if len(raw) > 1024*1024:
+        raise ValueError("Portable link context exceeds its bound")
+    links = json.loads(raw)
+    assert links["kind"] == "unaltraweb-practice-reading-links" and links["schema_version"] == 1
+    mapping = {entry["href"]: entry["target"] for entry in links["links"]}
+    run(["pandoc", str(SOURCE / "source.md"), "--from="+MARKDOWN, "--to=json", "--output=source.parsed.json"], log)
+    parsed = OUTPUT / "source.parsed.json"
+    if parsed.stat().st_size > 16*1024*1024:
+        raise ValueError("Practice AST exceeds its bound")
+    document = json.loads(parsed.read_bytes())
+    pending, count, applied = [(document, 0)], 0, []
+    while pending:
+        value, depth = pending.pop()
+        count += 1
+        if count > 200000 or depth > 128:
+            raise ValueError("Practice AST exceeds its structural bound")
+        if isinstance(value, dict):
+            if value.get("t") == "Link":
+                target = value["c"][-1]
+                href = target[0]
+                uri = urlsplit(href)
+                if href in mapping:
+                    target[0] = mapping[href]
+                    applied.append({"source_href": href, "target_href": target[0]})
+                elif not href.startswith("#") and uri.scheme.lower() not in {"https", "http", "mailto"}:
+                    raise ValueError("Pandoc found a local/unsupported reading link without an authorised portable mapping: " + href)
+            pending.extend((child, depth+1) for child in value.values())
+        elif isinstance(value, list):
+            pending.extend((child, depth+1) for child in value)
+    effective = OUTPUT / "source.effective.json"
+    effective.write_text(json.dumps(document, ensure_ascii=False, sort_keys=True)+"\n")
+    run(["pandoc", str(effective), "--from=json", "--to=markdown", "--wrap=none", "--output=source.effective.md"], log)
+    return links, applied
+
+
+def check_pdf_links(pdf, context):
+    allowed = {row["destination"] for row in context["targets"].values()}
+    observed = []
+    for page_number, page in enumerate(pdf.pages, 1):
+        for reference in page.get("/Annots", []):
+            annotation = reference.get_object()
+            if annotation.get("/Subtype") != "/Link" or annotation.get("/A") is None:
+                continue
+            action = annotation["/A"].get_object()
+            kind = str(action.get("/S"))
+            if kind == "/GoTo":
+                continue
+            if kind not in {"/URI", "/GoToR", "/Launch"}:
+                raise ValueError("Unsupported action in a reading link")
+            value = action.get("/URI") if kind == "/URI" else action.get("/F")
+            if hasattr(value, "get_object"):
+                value = value.get_object()
+            if isinstance(value, dict):
+                value = value.get("/UF") or value.get("/F")
+            if not isinstance(value, str):
+                raise ValueError("Reading link has no bounded file/URI target")
+            uri = urlsplit(value)
+            if uri.scheme.lower() in {"https", "http", "mailto"} or value.startswith("#"):
+                continue
+            if uri.scheme or uri.netloc or uri.query or unquote(uri.path, errors="strict") not in allowed:
+                raise ValueError("Final PDF contains a local target outside its portable recipient selection: " + value)
+            observed.append({"page": page_number, "kind": kind, "target": value})
+    return observed
+
+
+def main():
+    request = json.loads((SOURCE / "request.json").read_text())
+    basename = request["basename"]
+    assert basename in {"LLEGIU-ME", "LEEME", "README"}
+    filters = request["filters"]
+    assert filters == ["practice-layout.lua", "code-blocks.lua", "figure-captions.lua", "practice-finish.lua"]
+    with (OUTPUT / "render.log").open("x") as log:
+        context, applied = effective_source(request, log)
+        command = ["pandoc", str(OUTPUT / "source.effective.json"), "--standalone", "--from=json",
+                   "--number-sections", "--top-level-division=section", "--metadata-file=/source/metadata.yml",
+                   "--template=/source/practice.tex", "--resource-path=/source", "-t", "latex", "-o", "practice.tex"]
+        for name in filters:
+            command.append("--lua-filter=/source/" + name)
+        run(command, log)
+        for _ in range(3):
+            run(["xelatex", "-no-shell-escape", "-interaction=nonstopmode", "-halt-on-error", "practice.tex"], log)
+        run(["qpdf", "--deterministic-id", "--object-streams=generate", "--recompress-flate",
+             "--compression-level=9", "practice.pdf", basename + ".pdf"], log)
+        run(["pdftoppm", "-f", "1", "-singlefile", "-png", "-r", "110", basename + ".pdf", "preview"], log)
+    latex_log = (OUTPUT / "practice.log").read_text(errors="replace")
+    diagnostics = [line for line in latex_log.splitlines() if re.search(r"Overfull|Underfull|Warning:|Missing character", line)]
+    from pypdf import PdfReader
+    pdf = PdfReader(OUTPUT / (basename + ".pdf"))
+    if not pdf.pages or any(float(page.mediabox.width) < float(page.mediabox.height) for page in pdf.pages):
+        raise ValueError("Practice PDF must contain landscape pages")
+    local_links = check_pdf_links(pdf, context)
+    report = {"pages": len(pdf.pages), "diagnostics": diagnostics,
+               "portable_link_context": context["context"], "applied_links": applied, "local_pdf_links": local_links,
+              "review_required": True, "publishes": False}
+    (OUTPUT / "render-report.json").write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n")
+    print(json.dumps(report, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

data/scripts/manual/templates/practice.tex

@@ -0,0 +1,95 @@
+% Article wrapper appended to the factory-owned manual typographic preamble.
+\usepackage{fancyhdr}
+\usepackage{lastpage}
+\pagestyle{fancy}
+\fancyhf{}
+\fancyhead[L]{\small\sffamily\color{ManualMuted}$course-short-title$}
+\fancyhead[R]{\small\sffamily\color{ManualMuted}$short-title$}
+\fancyfoot[L]{\footnotesize\sffamily\color{ManualMuted}v$practice-version$ · $lang$}
+\fancyfoot[C]{\footnotesize\sffamily\color{ManualMuted}$if(draft)$$draft-label$$endif$}
+\fancyfoot[R]{\footnotesize\sffamily\color{ManualMuted}\thepage/\pageref*{LastPage}}
+\renewcommand{\headrulewidth}{0.2pt}
+\renewcommand{\footrulewidth}{0pt}
+\fancypagestyle{practicefirst}{\fancyhead{}\renewcommand{\headrulewidth}{0pt}}
+\titleformat{\section}{\normalfont\sffamily\Large\bfseries\color{ManualSecondary}}{\thesection}{0.55em}{}
+\titleformat{\subsection}{\normalfont\large\bfseries\color{ManualSecondary}}{\thesubsection}{0.6em}{}
+\titlespacing*{\section}{0pt}{1.1em}{0.45em}
+\titlespacing*{\subsection}{0pt}{0.9em}{0.35em}
+\setcounter{secnumdepth}{2}
+\setlength{\emergencystretch}{3em}
+\setlist[enumerate]{before=\raggedright}
+\setlength{\LTleft}{\fill}
+\setlength{\LTright}{\fill}
+\setlength{\LTcapwidth}{\textwidth}
+\captionsetup[figure]{format=plain,justification=centering,singlelinecheck=false,margin=0pt,aboveskip=0pt,belowskip=0pt}
+\captionsetup[table]{format=plain,justification=centering,singlelinecheck=false,margin=0pt,skip=14pt}
+
+% Measure the caption once, then fit the image to the remaining text rectangle.
+% The complete unit moves to the next page instead of shrinking into a page tail.
+\newsavebox{\PracticeCaptionBox}
+\newsavebox{\PracticeImageBox}
+\newsavebox{\PracticeFigureBox}
+\newlength{\PracticeImageHeight}
+\newlength{\PracticeFigureHeight}
+\newlength{\PracticeCaptionGap}
+\setlength{\PracticeCaptionGap}{14pt}
+\newcommand{\PracticeFigure}[2]{%
+  \par\begingroup
+  \setlength{\parskip}{0pt}%
+  \setbox\PracticeCaptionBox=\vbox{\hsize=\linewidth\captionsetup{type=figure}#1\par}%
+  \setlength{\PracticeImageHeight}{\dimexpr\textheight-\ht\PracticeCaptionBox-\dp\PracticeCaptionBox-\PracticeCaptionGap-2pt\relax}%
+  \ifdim\PracticeImageHeight<\baselineskip
+    \PackageError{unaltraweb-practice}{Figure caption exceeds the usable page height}{Shorten the caption or split the figure.}%
+  \fi
+  \setkeys{Gin}{width=\linewidth,height=\PracticeImageHeight,keepaspectratio}%
+  \sbox{\PracticeImageBox}{#2}%
+  \setbox\PracticeFigureBox=\vbox{%
+    \hsize=\linewidth\offinterlineskip
+    \hbox to\linewidth{\hfil\usebox{\PracticeCaptionBox}\hfil}%
+    \vskip\PracticeCaptionGap
+    \hbox to\linewidth{\hfil\usebox{\PracticeImageBox}\hfil}%
+  }%
+  \setlength{\PracticeFigureHeight}{\dimexpr\ht\PracticeFigureBox+\dp\PracticeFigureBox+2pt\relax}%
+  \Needspace{\PracticeFigureHeight}%
+  \nointerlineskip\usebox{\PracticeFigureBox}\par
+  \endgroup\addvspace{1em}%
+}
+
+\begin{document}
+\thispagestyle{practicefirst}
+{\setlength{\parskip}{0pt}%
+\noindent
+\begin{minipage}[c]{0.65\linewidth}
+  $if(series-logo)$
+  \begin{minipage}[c]{17mm}
+    \setlength{\fboxsep}{2mm}%
+    \colorbox{ManualBand}{\includegraphics[width=13mm,height=10.4mm,keepaspectratio]{$series-logo$}}%
+  \end{minipage}%
+  \hspace{3mm}%
+  $endif$
+  \begin{minipage}[c]{0.76\linewidth}
+    {\sffamily\bfseries\color{ManualPrimary}$series$}\par
+    {\small\sffamily\color{ManualMuted}$audience-label$}\par
+  \end{minipage}
+\end{minipage}%
+\hfill
+\begin{minipage}[c]{0.32\linewidth}
+  $if(cover-logo)$\raggedleft\includegraphics[width=58mm,height=26mm,keepaspectratio]{$cover-logo$}$endif$
+\end{minipage}\par
+\vspace{4mm}
+{\small\sffamily\bfseries\color{ManualSecondary}$subject$$if(subject-codes)$ ($subject-codes$)$endif$}\par
+\vspace{1mm}
+{\sffamily\fontsize{9.2}{11.6}\selectfont\color{ManualMuted}%
+$for(teaching-guides)$
+$teaching-guides.degree$\par
+$endfor$
+$if(institution-line)$$institution-line$\par$endif$
+$if(author)$$author$ · $endif$$practice-version-label$ $practice-version$\par
+}
+\vspace{2mm}{\color{ManualSecondary!40}\hrule}
+}
+\vspace{4mm}
+{\LARGE\sffamily\bfseries\color{ManualSecondary}$title$}\par
+\vspace{1mm}
+$body$
+\end{document}

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"])