light-typesetting

name

light-typesetting

description

Build and preflight submission-ready LaTeX/PDF artifacts for Light stage 11. Use when receiving a paper-writing manuscript, figure delivery, citation delivery.json/references.bib/citekey-audit.json, or a venue/template profile; when selecting pdfLaTeX/XeLaTeX/LuaLaTeX and BibTeX/Biber; when diagnosing LaTeX errors or unresolved references; when checking page limits, double-blind identity, PDF metadata, template, page box, embedded fonts, TODOs, figures, tables, labels and citations; or when producing a reproducible compile manifest, PDF, compliance report, failure bundle and venue-matching handoff. Distinguishes PASS, manuscript ERROR, toolchain UNAVAILABLE and convergence UNRESOLVED without redoing citation authenticity or figure scientific QA.

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.