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:

| 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

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.

6. Run the profile-driven desk-reject gate

python scripts/desk_reject_gate.py `
  --tex typesetting-build/source/paper.tex `
  --pdf typesetting-build/compile/paper.pdf `
  --bib typesetting-build/source/references.bib `
  --log typesetting-build/compile/paper.log `
  --profile venue-profile.json `
  --report desk-reject-findings.json

Objective profile breaches may be critical: over page limit, unanonymous

author/PDF Author metadata, wrong document class, missing required package,

wrong page size, or unembedded font. TODOs, acknowledgements, self-reference,

links and box warnings stay warnings unless the current authoritative profile

defines an objective hard rule.

Static checks cannot prove semantic anonymity, interpret ambiguous venue

language or judge final visual quality. Inspect the rendered PDF and current

official analyzer/instructions before submission.

7. Emit canonical artifacts

Require:

• build-manifest.json;
• compile-report.json and compile log;
• compliance-report.json and desk-reject findings;
• PDF when produced;
• failure.json for failed/unavailable runs;
• venue-handoff.json;
• delivery.json.

Only compile=PASS, compliance=PASS and zero compliance critical may become

DELIVERED.

Preserve failed reports; they prove the fail→fix transition.

8. Derive readiness without collapsing evidence

Build a local readiness packet and run:

python scripts/submission_readiness.py `
  --input templates/submission-readiness.example.json --as-of YYYY-MM-DD `
  --out submission-readiness-report.json

The public template is intentionally UNKNOWN and must exit 1. The state chain

is `INVENTORIED → SOURCE_BUILDABLE → TECHNICALLY_CHECKED →

VISUALLY_CHECKED → METADATA_MATCHED → VENUE_READY → USER_APPROVED`.

Compile exit 0 cannot skip unresolved references, compile page_count,

same-PDF binding, per-page render/review, metadata anonymity, current official

profile or exact article-type binding. visual.source_pdf_sha256,

metadata.source_pdf_sha256, compliance.source_pdf_sha256 and any

user_approval.pdf_sha256 must equal compile.pdf_sha256; visual.page_count

must equal compile.page_count; each visual page row needs render_sha256,

render_tool, review_status=PASS, reviewer/reviewer_id and non-future

reviewed_at. The compliance row must also name the same venue and

article_type as the profile. Artifact

Available/Functional/Reusable/Reproduced/Replicated remain separate; the script

records evidence and never awards an ACM or venue badge.

9. Run stage 11 and hand off

Run the compile command gate and desk_reject findings checkpoint:

python ../light-orchestrator/scripts/run_checkpoint.py `
  --file .light/passport.yaml --stage 11 `
  --gate "compile=python scripts/compile_driver.py --compile paper.tex --outdir build --json-out compile-report.json --quiet" `
  --findings desk-reject-findings.json --ts <ISO8601> --write

On critical fail, repair stage 11 and rerun to delivered. Hand

venue-matching the venue-handoff.json PDF path/hash, page count, page size,

profile source and compliance report. Do not claim ROUTES[11] or create a

back-edge. --quiet keeps the Windows command gate locale-neutral; the full

diagnostic record remains in compile-report.json.

ACT / ASK / NEVER

ACT:

• Snapshot declared inputs before modification.
• Run preflight, compile, rendered-PDF review, desk-reject gate and checkpoint.
• Preserve exact commands, hashes, statuses and failure artifacts.

ASK:

• Ask when a venue rule/source is missing or ambiguous.
• Ask before scientific-content cuts, changing bibliography systems, or

replacing the user's official template.

• Ask for human confirmation of semantic anonymity and borderline layout.

NEVER:

• Never claim a compile, convergence, page count or metadata check that did not

run.

• Never treat missing tools as a manuscript error or a successful delivery.
• Never redo citation authenticity, figure scientific QA or paper-writing.
• Never depend on paid Overleaf, private keys, browser plugins or npm-heavy

tooling for the core path.

Delivery self-check

• Input provenance and SHA-256 rows cover manuscript, figures, figure

manifests, citation delivery/BibTeX/audit/failure/review artifacts and

profile.

• Citation delivery status is DELIVERED; deliverable hashes match staged

files; citation failures and claim-review leftovers are empty.

• Figure source manifests declare the embedded output hash; empirical figures

carry confirmed result-analysis evidence binding.

• Engine/backend selection agrees with source and profile.
• Compile status is one of the four canonical states; PASS has a hashed PDF.
• Root cause has file/line when the compiler exposes it; warnings are separate.
• Citekeys, figures, labels and cross-references converge.
• Desk-reject criticals are zero or delivery is not marked delivered.
• Every visual/metadata/compliance/user-approval row is bound to the compiled

PDF hash; every PDF page has a render hash, render tool, reviewer/date and

review PASS row; profile is current and bound to the exact article type.

• Author-team repeatability was not relabelled independent reproduction/replication.
• Venue-matching receives real PDF/page/compliance facts.
• Stage 11 uses only compile and desk_reject; no route/back-edge was added.