Light Typesetting

Typesetting · stage 11

Turn approved author artifacts into a reproducible PDF submission bundle. The job is not merely to make LaTeX compile: preserve provenance, select a coherent engine/backend, preflight dependencies, compile to convergence, locate the first root cause, run profile-driven desk-reject checks, and hand exact PDF/page facts to venue-matching.

Read typesetting-resource-map.md before running a real build. Read references/build_contract.md before writing or consuming machine artifacts. Use references/latex_errors.md only after the first source-located error is known. Use a venue template under templates/ only when it matches the current author kit; the bundled copy is a starting point, not current venue truth.

Non-negotiable boundaries

• Consume citation delivery.json, references.bib and citekey-audit.json. Require delivery.status=DELIVERED, declared deliverable_hashes, empty citation failures and empty claim-review leftovers. Declared citation deliverables must be relative paths inside the citation delivery directory, and the build snapshot must preserve the audit, failure and claim-review sidecars under provenance. Check staged keys and compilation. Do not re-decide DOI existence, metadata conflicts, retractions or claim relevance.
• Consume figure files, declared dimensions/DPI and source manifest. Require the manifest to be light.figure_delivery.v1 or light.figure_build.v1 and require the embedded file hash to match a declared output hash. For empirical figure deliveries, require confirmed result-analysis evidence binding. Check presence, embedding, float/layout and compilation. Do not redo visual honesty, scientific content or publication-size generation.
• Consume the approved paper-writing manuscript. Do not invent claims, references, experiments or numbers to close a page budget.
• Take page, anonymity, template, font and page-box rules only from user input or current authoritative instructions with URL/date provenance. Never embed a universal venue limit.
• Keep tool/resource failure as UNAVAILABLE. Never call it manuscript ERROR, never call it PASS, and never mark the delivery DELIVERED.
• Keep stage-11 critical scope to typesetting. Security/network/tool unavailability does not enlarge it. ROUTES has no key 11; repair failures inside stage 11 and never invent a back-edge.

Local LaTeX environment contract

For a real PDF build, detect the local toolchain before claiming success:

• core: Python stdlib plus a LaTeX distribution such as TeX Live, MiKTeX, MacTeX or TinyTeX;
• compile driver: prefer latexmk; use tectonic only when its supported backend matches the manuscript;
• engines: pdflatex, xelatex and lualatex as selected from source/profile triggers;
• bibliography: bibtex for traditional \bibliography{} and biber for biblatex unless explicitly declared otherwise;
• PDF checks: pdfinfo and pdffonts when page box, page count or embedded font facts are required.

If the compiler, engine, backend, package or PDF inspector is missing, mark the state UNAVAILABLE, explain the missing component, and ask the user whether to install/configure it or switch toolchains. Never silently install system tools, never call a missing toolchain a manuscript error, and never report a PDF as delivered unless the build actually produced and checked that PDF.

Workflow

1. Freeze the input contract

Copy templates/typesetting_input.json. Record:

• the paper-writing entrypoint plus every required source file;
• each figure source, target relative path, dimensions/DPI and delivery/build manifest;
• citation delivery.json and desired staged BibTeX filename; the delivery must be regenerated after citation edits so hashes match the referenced files;
• light.typesetting_venue_profile.v1, including source kind, URL if any, check date and rules.

If a venue rule is unknown, keep it null, 0 or absent. Do not infer it from another venue or last year's template.

2. Preflight before compilation

python scripts/build_submission.py --spec typesetting-input.json --preflight-only

Require a provenance-preserving source/ snapshot. Check missing inputs, \input/\include, graphics, labels/refs, citation-delivery schema/status, deliverable hashes, delivered citekey audit, empty citation failure/review handoffs, live staged citekeys, figure manifest output hashes, empirical figure evidence binding, document class, required packages and local package availability. Use a new/empty output directory per iteration; the builder refuses stale run directories.

Classify:

3. Select engine and bibliography backend

Detect XeLaTeX for fontspec, xeCJK, ctex, unicode-math or polyglossia; LuaLaTeX for Lua triggers; otherwise pdfLaTeX. Detect traditional \bibliography as BibTeX and biblatex as Biber unless its backend= option says otherwise.

If the profile engine conflicts with a hard XeLaTeX/LuaLaTeX source trigger, or its backend differs from the source, stop with a root-cause ERROR; do not mix BibTeX and Biber. A profile may deliberately select XeLaTeX for otherwise pdfLaTeX-compatible source. Record the absolute executable path, version probe, working directory, command array and shell rendering.

4. Compile and classify convergence

python scripts/build_submission.py --spec typesetting-input.json

Prefer local latexmk; use Tectonic only when its supported backend matches. Compile from the snapshot's manuscript directory so relative inputs resolve. Save latexmk rule/run records, log/PDF SHA-256 and page count.

Use exactly four compile states:

• PASS: return code zero, PDF exists, no remaining undefined cite/ref or rerun signal.
• ERROR: manuscript/backend/input caused a nonzero build or no PDF.
• UNAVAILABLE: required local tool/resource could not launch/finish.
• UNRESOLVED: PDF exists but citation/reference convergence remains.

ERROR and UNRESOLVED exit 1. UNAVAILABLE exits 0 for the command-gate boundary but remains undelivered.

5. Diagnose from the first root cause

Read compile-report.json, then the full log. Report the first file.tex:line, compiler message and plain-language cause before secondary warnings. Fix the earliest error first; recompile after one minimal repair. Never silently rewrite prose, remove data or add fabricated bibliography.

When a fix loop repeats the same signature, stop and report UNRESOLVED instead of making speculative edits.