docs(docs): R4.6 J2 recette (procedure, results grid, kit script), export harness phases and dist override, export series script, ledger targets of the app PDF suites, CLAUDE.md export flow; export driver publishes its User Timing split

This commit is contained in:
bchanot committed 2026-10-19 01:41:57 +02:00
1 parent 9cb3cb75d4
commit cdcdda8e1c
12 files changed
+679 -39

No files matched your search

+64 -10
View File
@@ -49,6 +49,47 @@ function assertNotAborted(signal: AbortSignal | undefined): void {
if (signal?.aborted) throw new DOMException('export aborted', 'AbortError')
}
/** Where the time went, for the DEV console and the browser harness (User Timing). */
interface ExportTiming {
startedAt: number
coreMs: number
rasterMs: number
requests: number
}
/** Runs a core call and charges its time. */
function timed<T>(timing: ExportTiming, call: () => T): T {
const started = performance.now()
try {
return call()
} finally {
timing.coreMs += performance.now() - started
}
}
/**
* One `performance.measure('faunosteo:export')` entry with the split in its detail:
* nothing the page shows, what the harness reads. Absent where User Timing lacks the
* options form.
*/
function publishTiming(timing: ExportTiming, parts: number, bytes: number): void {
try {
performance.measure('faunosteo:export', {
start: timing.startedAt,
end: performance.now(),
detail: {
coreMs: timing.coreMs,
rasterMs: timing.rasterMs,
requests: timing.requests,
parts,
bytes,
},
})
} catch {
// An older engine: no measure, nothing else changes.
}
}
/**
* One batch of the session's requests rasterised under `Promise.all`, as the engine did:
* a raster that fails is reported as it rejects (the warning order the engine recorded),
@@ -60,7 +101,10 @@ async function answerBatch(
session: CoreExportSession,
requests: RasterRequest[],
signal: AbortSignal | undefined,
timing: ExportTiming,
): Promise<void> {
timing.requests += requests.length
const rasterStarted = performance.now()
const settled = await Promise.all(
requests.map(async (request) => {
try {
@@ -71,15 +115,16 @@ async function answerBatch(
return { key: request.key, png }
} catch {
assertNotAborted(signal)
unwrap(session.rasterFailed(request.key))
unwrap(timed(timing, () => session.rasterFailed(request.key)))
return { key: request.key, png: null }
}
}),
)
timing.rasterMs += performance.now() - rasterStarted
for (const { key, png } of settled) {
if (!png) continue
assertNotAborted(signal)
unwrap(session.addRaster(key, png))
unwrap(timed(timing, () => session.addRaster(key, png)))
}
}
@@ -109,23 +154,32 @@ export async function exportReportToPdf(
exportedAt: new Date().toISOString(),
}
assertNotAborted(opts.signal)
const session = unwrap(openExportSession(coreRuntime(), JSON.stringify(input)))
const timing: ExportTiming = {
startedAt: performance.now(),
coreMs: 0,
rasterMs: 0,
requests: 0,
}
const text = JSON.stringify(input)
const session = unwrap(
timed(timing, () => openExportSession(coreRuntime(), text)),
)
try {
for (;;) {
assertNotAborted(opts.signal)
const step = unwrap(session.next())
const step = unwrap(timed(timing, () => session.next()))
if (step.step === 'done') break
await answerBatch(session, step.requests, opts.signal)
await answerBatch(session, step.requests, opts.signal, timing)
}
const parts = unwrap(session.finish())
const parts = unwrap(timed(timing, () => session.finish()))
const warnings = unwrap(session.warnings())
for (const warning of warnings) {
console.warn('PDF export warning', warning)
}
return {
pdf: new Blob(parts as BlobPart[], { type: 'application/pdf' }),
warnings,
}
const pdf = new Blob(parts as BlobPart[], { type: 'application/pdf' })
publishTiming(timing, parts.length, pdf.size)
if (import.meta.env.DEV) console.info('PDF export', timing)
return { pdf, warnings }
} finally {
session.free()
}
+1
View File
@@ -49,6 +49,7 @@ without the flag the same tests assert equality with the committed files.
| `r4/reports/{L,CAP}.json` | Synthetic Report v3 on the draft: 60 observations / 120 views (L) and 500 / 1,000 (CAP), the export memory inputs of plan §B.4 (O13). |
| `goldens/r4/draw.*.json` | Every drawing call of the export (text, image, line, rectangle, link) at full precision, per page and in call order, for the 12 Step 6 report × locale × logo combinations (O1). |
| `pdf/r3/` | The 12 PDFs the R3-era engine produced for those combinations, the store-path export with its `report.json`, and `real/v2full-obs1.fr.logos.pdf` with its two browser PNGs and manifest: the byte references of the writer port (O2). |
| `goldens/r4/pdf.*.sha256` | Digests of the Rust writer's own output on the 14 O2 runs (not an oracle of the TypeScript: the proof that the wasm module and the application path write the native bytes). Frozen at R4.5; rewritten once at R4.6 when the writer became incremental (catalog and page tree written last, upper-case hex strings as pdf-lib), every O2 comparison and the poppler render unchanged. `MAKE_R4_ORACLES=1 cargo test --test pdf_serialize r4_output_digests_are_frozen` rewrites them, never to hide a difference with O2. |
| `pdf/step6/envelope.*.pdf` | Three envelope PDFs from before R2 (O3). |
| `pdf/r4/tolerance/` | 51 PDFs, valid and hostile, with today's import outcome and message in `crates/core/tests/oracles/r4/tolerance.json` (O8). |
| `pdf/r4/read/`, `pdf/r4/inflate/` | 155 reader inputs and 24 zlib framing inputs, the bytes behind `read.json` and `inflate.json`; a `<slug>.gen.json` describes a large input by concatenation (O7, O9). |