# Catnip LaTeX Technical Report

This directory contains the redesigned Catnip engineering report. The report is
organized as a chronological experiment narrative:

1. action;
2. profiling or measured result;
3. analysis;
4. next decision;
5. a separate success/reject/blocked/invalid/not-run ledger.

All charts are generated from `data/report_metrics.json`; Markdown tables are
not scraped during the build.

## Build

```bash
cd /workspace/catnip-technical-report-latex
./build.sh
```

Output:

- `CATNIP_TECHNICAL_REPORT.pdf`: final report;
- `index.html`: self-contained web edition, with all figures, styles, scripts, and
  the report PDF embedded for deployment;
- `build/main.log`: XeLaTeX log;
- `build/main.fls`: complete TeX input list;
- `figures/*.pdf`: vector charts;
- `SHA256SUMS`: report bundle manifest.

The build requires XeLaTeX, `ctex`, Noto CJK fonts, `latexmk`, `pdfinfo`, and
Python with Matplotlib. It prefers `/workspace/LTX/.venv/bin/python`; override
that path with `CATNIP_REPORT_PYTHON=/path/to/python`. It does not enable shell
escape.

`SOURCE_DATE_EPOCH` defaults to `1785196800` (2026-07-28 00:00:00 UTC), so PDF
metadata and generated figures are reproducible. Override it only when the
report release date intentionally changes. `BUILD_PROVENANCE.txt` records the
effective timestamp and tool versions.

The build is fail-closed. It exits nonzero on text overflow, undersized
headers, duplicate PDF destinations, unresolved references/citations,
cross-reference rerun requests, or `xdvipdfmx` warnings. Ordinary `Underfull`
line-break notices and harmless math-font size substitutions remain visible in
`build/main.log` but do not fail the build.

## Verify

```bash
cd /workspace/catnip-technical-report-latex
sha256sum -c SHA256SUMS
pdfinfo CATNIP_TECHNICAL_REPORT.pdf
pdffonts CATNIP_TECHNICAL_REPORT.pdf
bash -n build.sh
```

For a clean reproducibility check:

```bash
./build.sh clean
./build.sh
sha256sum -c SHA256SUMS
```

## Layout

- `main.tex`: document entry point;
- `catnip-report.sty`: typography, color, headers, experiment cards;
- `sections/`: chronological narrative, attempt ledger, reproduction, evidence;
- `data/report_metrics.json`: chart input with canonical source paths;
- `scripts/generate_figures.py`: deterministic chart generator;
- `scripts/build_index_html.py`: deterministic self-contained web-report builder;
- `figures/`: PDF and PNG chart outputs.
- `BUILD_PROVENANCE.txt`: deterministic build epoch and tool versions.

## Metric Boundaries

- Current engineering baseline:
  `catnip-k32-vdirect-single-tile-compile-portrait-480x832-v2`, adopted
  2026-07-28. Three paired Phase 3 candidate runs at 480×832 report
  `34.392314 generated FPS` and `37.557043 stable-DiT FPS`; generated-FPS
  population CV is 0.085863%. This is a warm steady-state engineering baseline.
  Fresh-process wall is 10.802722% slower at the paired median, so no cold-start
  speedup or formal ground-truth quality acceptance is claimed.
- The default inference command is
  `/workspace/LTX/.venv/bin/python /workspace/catnip-portrait-baseline/run_baseline.py`.
  The 2026-07-26 v1 result remains historical evidence and is not overwritten.
- Historical strict causal comparisons remain in the report but do not replace the
  Portrait KPI: K32 versus tensorwise (stable-DiT median +14.103774%) and Week 9
  V-direct-BSH versus its 832×480 control (stable-DiT median +1.289408%).
- `generated FPS` is 489 frames divided by sampling plus pipelined video decode.
  `stable-DiT FPS` is `288 / sum(dit_wall for chunks 5..10)`. Different numerator AND
  different denominator — never mix them. Playback remains 25 FPS. Portrait versus
  landscape orientation is not a contemporaneous paired causal speedup comparison.
- Historical: O7 `27.104924`, Week 3 workspace `27.370839`, Week 7 SM120 r04 `28.084266773`.
  Playback remains 25 FPS.
- Nsys instrumentation lowers stable-DiT and generated FPS by about 1.533% and 2.040%;
  instrumented runs must never be quoted as production throughput.
- Outside the generated-FPS denominator: text encoder 801.745 ms, condition copy 6.417 ms,
  audio decode 313.123 ms, media write/encode 7,424.061 ms (no CUDA kernel in that range).
- K32 is a warm-throughput candidate. Its cold compile warmup is 23.342073% slower than
  tensorwise (327.122399 s vs 265.215584 s) and the whole fresh process is 14.350753643505222%
  slower. Do not read the steady-state gain as a cold-start gain.
- Attention's 168.677600 TFLOP/s (80.5144% fixed-spec, 68.6384% measured-clock) describes the
  2026-07-20 all-PyTorch-Flash-SDPA state, not the current self-built SM120 MXFP8 `attn1` path.
  Neither ratio is SM occupancy; NCU occupancy remains permission-blocked (`ERR_NVGPUCTRPERM`).
- End-to-end latent trajectory rel-L2 is **no longer an acceptance criterion**. It was falsified
  on 2026-07-22 (cross-cell sign flips, placebo beating treatment). It survives only as a
  descriptive measure of trajectory divergence; local single-forward oracle-L2 remains valid.
  Acceptance authority is the reference-free decoded-media artifact panel.