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

```powershell
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:

| Evidence | State |
|---|---|
| missing manuscript/figure/BibTeX/key/label, stale upstream hash, open citation review, unconfirmed empirical-figure evidence or backend conflict | `ERROR` |
| required engine/backend/package/tool absent or cannot execute | `UNAVAILABLE` |
| no blocker | `PASS` |

### 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

```powershell
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 coun