Files
faunosteo/apps/app/tests/unit/r4.tolerance-oracles.test.ts
T

777 lines
22 KiB
TypeScript

/**
* R4 freeze O8 (plan 2026-10-17 §B.5.1): the differential tolerance corpus.
* Each case is a PDF shaped like a Faunosteo export (one A4 page, the
* archive keyword, fixed dates, no object streams) whose attachments are
* byte- or text-level mutations of a real envelope or of the bare v3 demo
* report. The outcome is the full R3 import path as HomeRoute runs it for a
* PDF: `readAttachment` (TS byte scan, TextDecoder, JSON.parse) then
* `importAttachment` (JSON.stringify, core `archive.import` in wasm) on the
* bundled draft sheet. The UTF-8 validity and JSON.parse columns, and the
* candidate the scanner chose, serve the Rust differential test (R4.2).
* `MAKE_R4_ORACLES=1` writes `apps/app/tests/fixtures/pdf/r4/tolerance/` and
* `crates/core/tests/oracles/r4/tolerance.json`; never without the owner.
*/
import { createHash } from 'node:crypto'
import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { AFRelationship, PDFDocument } from 'pdf-lib'
import { beforeAll, describe, expect, it } from 'vitest'
import type { ArchiveImport } from '@faunosteo/core-wasm/types'
import {
ArchiveReadError,
PDF_KEYWORD,
readAttachmentBytes,
} from '@faunosteo/pdf'
import { importAttachment, ImportError, readAttachment } from '@/pdf/import'
import type { SheetIndex } from '@/services/sheetIndex'
import { loadTestSheet } from '../helpers/sheet'
const HERE = dirname(fileURLToPath(import.meta.url))
const ROOT = resolve(HERE, '../../../..')
const PDF_DIR_REL = 'apps/app/tests/fixtures/pdf/r4/tolerance'
const PDF_DIR = resolve(ROOT, PDF_DIR_REL)
const OUT = resolve(ROOT, 'crates/core/tests/oracles/r4/tolerance.json')
const MAKE = process.env.MAKE_R4_ORACLES === '1'
const BASE_FILES = {
'report-v3.demo.json': 'apps/app/tests/fixtures/report-v3.demo.json',
'envelope.demo.fr.nologos.json':
'apps/app/tests/fixtures/goldens/r2/envelope.demo.fr.nologos.json',
} as const
type BaseName = keyof typeof BASE_FILES | 'none'
type Bases = Record<keyof typeof BASE_FILES, string>
/** Every date of the PDF and its attachments: the corpus is byte-stable. */
const FIXED_DATE = new Date('2026-10-18T09:00:00.000Z')
const A4: [number, number] = [595.28, 841.89]
const ATTACHMENT = 'osteo-report.json'
const DECOY = 'osteo-report-decoy.json'
interface AttachmentSpec {
name: string
bytes: Uint8Array
}
interface CaseSpec {
id: string
description: string
base: BaseName
attachments: AttachmentSpec[]
}
// ---------------------------------------------------------------------------
// Text and byte mutations (the base text is never re-serialised)
const utf8 = (text: string): Uint8Array => new TextEncoder().encode(text)
const sha256 = (bytes: Uint8Array | string): string =>
createHash('sha256').update(bytes).digest('hex')
function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
const out = new Uint8Array(parts.reduce((n, p) => n + p.byteLength, 0))
let at = 0
for (const part of parts) {
out.set(part, at)
at += part.byteLength
}
return out
}
function anchorEnd(text: string, anchor: string): number {
const at = text.indexOf(anchor)
if (at < 0) throw new Error(`anchor not found: ${anchor}`)
return at + anchor.length
}
/** The first occurrence of `from` replaced; a missing anchor is a generator bug. */
function replaceFirst(text: string, from: string, to: string): string {
const end = anchorEnd(text, from)
return text.slice(0, end - from.length) + to + text.slice(end)
}
/** The UTF-8 bytes with `raw` inserted right after the first `anchor`, searched as bytes. */
function bytesAfter(
source: Uint8Array | string,
anchor: string,
raw: number[],
): Uint8Array {
const bytes = typeof source === 'string' ? utf8(source) : source
const needle = utf8(anchor)
const at = Buffer.from(bytes).indexOf(needle)
if (at < 0) throw new Error(`anchor not found: ${anchor}`)
const end = at + needle.byteLength
const inserted = Uint8Array.from(raw)
return concatBytes([bytes.subarray(0, end), inserted, bytes.subarray(end)])
}
/** Members written before the object's first member (they come first in JS order too). */
function leadingMembers(text: string, members: string): string {
if (!text.startsWith('{')) throw new Error('base is not an object')
return `{${members},${text.slice(1)}`
}
/** Members written after the object's last member. */
function trailingMembers(text: string, members: string): string {
const close = text.lastIndexOf('}')
return `${text.slice(0, close)},\n ${members}\n${text.slice(close)}`
}
const single = (
id: string,
description: string,
base: BaseName,
bytes: Uint8Array | string,
): CaseSpec => ({
id,
description,
base,
attachments: [
{
name: ATTACHMENT,
bytes: typeof bytes === 'string' ? utf8(bytes) : bytes,
},
],
})
// ---------------------------------------------------------------------------
// Cases
const BARE = 'report-v3.demo.json' satisfies BaseName
const ENVELOPE = 'envelope.demo.fr.nologos.json' satisfies BaseName
/** Inside the conclusion string of the bare report (and of the envelope's report). */
const IN_CONCLUSION = '"conclusion": "Dysfonction'
const CONCLUSION_END = 'associée.'
const FIRST_INDEX = '"index": 3'
const SECOND_INDEX = '"index": 4'
const SNAPSHOT_CX = '"cx": 1523,'
function controlCases(b: Bases): CaseSpec[] {
return [
single(
'control-bare-v3',
'the bare v3 demo report, unmodified',
BARE,
b[BARE],
),
single(
'control-envelope',
'the R2 demo envelope, unmodified',
ENVELOPE,
b[ENVELOPE],
),
]
}
function utf8Cases(b: Bases): CaseSpec[] {
const bare = b[BARE]
return [
single(
'utf8-lone-continuation',
'byte 80 inside the conclusion',
BARE,
bytesAfter(bare, IN_CONCLUSION, [0x80]),
),
single(
'utf8-overlong',
'overlong C0 AF and E0 80 AF inside the conclusion',
BARE,
bytesAfter(bare, IN_CONCLUSION, [0xc0, 0xaf, 0x20, 0xe0, 0x80, 0xaf]),
),
single(
'utf8-truncated',
'E2 82 before a space and F0 9F 98 before the closing quote',
BARE,
bytesAfter(
bytesAfter(bare, CONCLUSION_END, [0xf0, 0x9f, 0x98]),
IN_CONCLUSION,
[0xe2, 0x82],
),
),
single(
'utf8-encoded-surrogate',
'ED A0 80 (U+D800 encoded) inside the conclusion',
BARE,
bytesAfter(bare, IN_CONCLUSION, [0xed, 0xa0, 0x80]),
),
single(
'utf8-above-max',
'F4 90 80 80 (above U+10FFFF) inside the conclusion',
BARE,
bytesAfter(bare, IN_CONCLUSION, [0xf4, 0x90, 0x80, 0x80]),
),
single(
'utf8-invalid-in-key',
'byte FF inside the "conclusion" key',
BARE,
bytesAfter(bare, '"conclu', [0xff]),
),
single(
'utf8-invalid-in-unknown-key',
'byte FF inside an extra member key',
BARE,
bytesAfter(leadingMembers(bare, '"extra": true'), '"ext', [0xff]),
),
single(
'utf8-invalid-outside-string',
'byte 80 between tokens after the opening brace',
BARE,
bytesAfter(bare, '{', [0x80]),
),
]
}
function bomCases(b: Bases): CaseSpec[] {
const bare = b[BARE]
const bom = [0xef, 0xbb, 0xbf]
return [
single(
'bom-leading',
'one UTF-8 BOM before the text',
BARE,
concatBytes([Uint8Array.from(bom), utf8(bare)]),
),
single(
'bom-double',
'two UTF-8 BOMs before the text',
BARE,
concatBytes([Uint8Array.from([...bom, ...bom]), utf8(bare)]),
),
single(
'bom-middle-whitespace',
'a BOM between tokens after the opening brace',
BARE,
bytesAfter(bare, '{', bom),
),
single(
'bom-in-string',
'a BOM inside the conclusion string',
BARE,
bytesAfter(bare, IN_CONCLUSION, bom),
),
]
}
function numberCases(b: Bases): CaseSpec[] {
const [bare, envelope] = [b[BARE], b[ENVELOPE]]
return [
single(
'overflow-version-bare',
'bare report "version": 1e400',
BARE,
replaceFirst(bare, '"version": 3', '"version": 1e400'),
),
single(
'overflow-envelope-version',
'envelope "envelopeVersion": 1e400',
ENVELOPE,
replaceFirst(
envelope,
'"envelopeVersion": 1,',
'"envelopeVersion": 1e400,',
),
),
single(
'overflow-snapshot-coordinate',
'a snapshot circle "cx": 1e400',
ENVELOPE,
replaceFirst(envelope, SNAPSHOT_CX, '"cx": 1e400,'),
),
single(
'overflow-duplicate-overwritten',
'vertebra "index": 1e400 overwritten by a later "index": 3',
BARE,
replaceFirst(bare, FIRST_INDEX, `"index": 1e400, ${FIRST_INDEX}`),
),
single(
'overflow-negative-content',
'vertebra "index": -1e400',
BARE,
replaceFirst(bare, SECOND_INDEX, '"index": -1e400'),
),
single(
'overflow-boundary-finite',
'"version": 1.7976931348623158e308 (rounds to the largest finite double)',
BARE,
replaceFirst(bare, '"version": 3', '"version": 1.7976931348623158e308'),
),
single(
'overflow-boundary-infinite',
'"version": 1.7976931348623159e308 (past the halfway point: Infinity)',
BARE,
replaceFirst(bare, '"version": 3', '"version": 1.7976931348623159e308'),
),
]
}
function surrogateCases(b: Bases): CaseSpec[] {
const bare = b[BARE]
const inConclusion = (escape: string) =>
replaceFirst(bare, IN_CONCLUSION, `${IN_CONCLUSION} ${escape}`)
return [
single(
'surrogate-content',
'escape \\ud800 inside the conclusion',
BARE,
inConclusion('\\ud800'),
),
single(
'surrogate-version-overwritten',
'"version": "\\ud800" overwritten by the later "version": 3',
BARE,
leadingMembers(bare, '"version": "\\ud800"'),
),
single(
'surrogate-content-overwritten',
'OD-4: "conclusion": "\\ud800 …" overwritten by the later conclusion',
BARE,
leadingMembers(bare, '"conclusion": "\\ud800 écrasée"'),
),
single(
'surrogate-paired',
'escape pair \\ud83d\\ude00 inside the conclusion',
BARE,
inConclusion('\\ud83d\\ude00'),
),
single(
'surrogate-reversed-pair',
'escapes \\ude00\\ud83d (two lone halves)',
BARE,
inConclusion('\\ude00\\ud83d'),
),
single(
'surrogate-in-key',
'an extra member whose key is "\\udfff"',
BARE,
leadingMembers(bare, '"\\udfff": true'),
),
single(
'surrogate-escaped-backslash',
'literal text \\\\ud800 (an escaped backslash)',
BARE,
inConclusion('\\\\ud800'),
),
]
}
function duplicateCases(b: Bases): CaseSpec[] {
const bare = b[BARE]
return [
single(
'dup-version-string-then-number',
'"version": "3" then "version": 3',
BARE,
leadingMembers(bare, '"version": "3"'),
),
single(
'dup-version-number-then-string',
'"version": 3 then "version": "3"',
BARE,
trailingMembers(bare, '"version": "3"'),
),
single(
'dup-content-last-wins',
'a second "conclusion" after the last member',
BARE,
trailingMembers(bare, '"conclusion": "Valeur finale"'),
),
single(
'dup-snapshot-key',
'snapshot "status": 42 then "status": "draft"',
ENVELOPE,
replaceFirst(
b[ENVELOPE],
'"status": "draft",',
'"status": 42, "status": "draft",',
),
),
]
}
function integerCases(b: Bases): CaseSpec[] {
const bare = b[BARE]
const index = (literal: string) =>
replaceFirst(bare, FIRST_INDEX, `"index": ${literal}`)
return [
single(
'int-2pow53-plus-1',
'vertebra "index": 9007199254740993',
BARE,
index('9007199254740993'),
),
single(
'int-u64-overflow',
'vertebra "index": 18446744073709551616',
BARE,
index('18446744073709551616'),
),
single(
'negative-zero',
'a snapshot circle "cx": -0',
ENVELOPE,
replaceFirst(b[ENVELOPE], SNAPSHOT_CX, '"cx": -0,'),
),
single('float-integer-index', 'vertebra "index": 3.0', BARE, index('3.0')),
single(
'float-integer-version',
'"version": 3.0',
BARE,
replaceFirst(bare, '"version": 3', '"version": 3.0'),
),
]
}
function keyCases(b: Bases): CaseSpec[] {
const bare = b[BARE]
return [
single(
'proto-key',
'"__proto__": { "polluted": true } in the report',
BARE,
leadingMembers(bare, '"__proto__": { "polluted": true }'),
),
single(
'integer-like-keys',
'"1" and "0" members in the report',
BARE,
leadingMembers(bare, '"1": "un", "0": "zéro"'),
),
]
}
/** An extra member nesting arrays so the document's depth is `depth`. */
function nested(text: string, depth: number): string {
const arrays = depth - 1
return leadingMembers(
text,
`"deep": ${'['.repeat(arrays)}${']'.repeat(arrays)}`,
)
}
function depthCases(b: Bases): CaseSpec[] {
return [
single(
'depth-64',
'an extra member nesting the document to depth 64',
BARE,
nested(b[BARE], 64),
),
single(
'depth-65',
'an extra member nesting the document to depth 65',
BARE,
nested(b[BARE], 65),
),
]
}
/** A full report JSON.parse accepts with a numeric version; its raw text keeps \ud800. */
function overwrittenSurrogateDecoy(bare: string): Uint8Array {
const marked = replaceFirst(bare, IN_CONCLUSION, '"conclusion": "Leurre')
return utf8(leadingMembers(marked, '"version": "\\ud800"'))
}
function multiFileCases(b: Bases): CaseSpec[] {
const decoy = overwrittenSurrogateDecoy(b[BARE])
const [envelope, bare] = [utf8(b[ENVELOPE]), utf8(b[BARE])]
const pair = (
id: string,
description: string,
base: BaseName,
files: AttachmentSpec[],
): CaseSpec => ({ id, description, base, attachments: files })
return [
pair(
'two-files-decoy-first',
'decoy report (overwritten "\\ud800" version, conclusion ' +
'"Leurre") then the envelope',
ENVELOPE,
[
{ name: DECOY, bytes: decoy },
{ name: ATTACHMENT, bytes: envelope },
],
),
pair('two-files-real-first', 'the envelope then the same decoy', ENVELOPE, [
{ name: ATTACHMENT, bytes: envelope },
{ name: DECOY, bytes: decoy },
]),
pair(
'two-files-surrogate-decoy-first',
'decoy {"version":3,"conclusion":"\\ud800"} ' + 'then the bare report',
BARE,
[
{ name: DECOY, bytes: utf8('{"version": 3, "conclusion": "\\ud800"}') },
{ name: ATTACHMENT, bytes: bare },
],
),
pair(
'two-files-invalid-first',
'decoy {"version": 3,} (JSON.parse fails) then the ' + 'bare report',
BARE,
[
{ name: DECOY, bytes: utf8('{"version": 3,}') },
{ name: ATTACHMENT, bytes: bare },
],
),
]
}
function shapeCases(b: Bases): CaseSpec[] {
const bare = b[BARE]
return [
single(
'whitespace-padded',
'spaces, tab, CR and LF before the opening brace',
BARE,
` \n\t\r\n ${bare}`,
),
single(
'top-level-array',
'the report wrapped in an array',
BARE,
`[${bare}]`,
),
single('top-level-number', 'the number 3 alone', 'none', '3'),
single('trailing-content', 'the report followed by "x"', BARE, `${bare}x`),
]
}
/** OD-3 classes: value counts recorded before R4.2 sets the budget. */
function budgetCases(b: Bases): CaseSpec[] {
const values = (count: number) =>
leadingMembers(
b[BARE],
`"values": [${new Array(count).fill('0').join(',')}]`,
)
return [
single(
'values-100k',
'an extra member holding 100,000 zeros',
BARE,
values(100_000),
),
single(
'values-1m',
'an extra member holding 1,000,000 zeros',
BARE,
values(1_000_000),
),
]
}
function buildCases(b: Bases): CaseSpec[] {
return [
...controlCases(b),
...utf8Cases(b),
...bomCases(b),
...numberCases(b),
...surrogateCases(b),
...duplicateCases(b),
...integerCases(b),
...keyCases(b),
...depthCases(b),
...multiFileCases(b),
...shapeCases(b),
...budgetCases(b),
]
}
function loadBases(): Bases {
const read = (rel: string) => readFileSync(resolve(ROOT, rel), 'utf8')
return {
'report-v3.demo.json': read(BASE_FILES['report-v3.demo.json']),
'envelope.demo.fr.nologos.json': read(
BASE_FILES['envelope.demo.fr.nologos.json'],
),
}
}
// ---------------------------------------------------------------------------
// PDF and outcome
/** Shaped like `exportReportArchive`'s output: same keyword, attachment options, save flags. */
async function buildPdf(
attachments: readonly AttachmentSpec[],
): Promise<Uint8Array> {
const doc = await PDFDocument.create()
doc.addPage(A4)
doc.setKeywords([PDF_KEYWORD])
doc.setCreationDate(FIXED_DATE)
doc.setModificationDate(FIXED_DATE)
for (const { name, bytes } of attachments) {
await doc.attach(bytes, name, {
mimeType: 'application/json',
description: 'Faunosteo report archive v1',
creationDate: FIXED_DATE,
modificationDate: FIXED_DATE,
afRelationship: AFRelationship.Data,
})
}
return doc.save({ useObjectStreams: false })
}
function jsonParses(bytes: Uint8Array): boolean {
try {
JSON.parse(new TextDecoder().decode(bytes))
return true
} catch {
return false
}
}
function isValidUtf8(bytes: Uint8Array): boolean {
try {
new TextDecoder('utf-8', { fatal: true }).decode(bytes)
return true
} catch {
return false
}
}
function attachmentRow({ name, bytes }: AttachmentSpec) {
return {
name,
sha256: sha256(bytes),
byteLength: bytes.byteLength,
validUtf8: isValidUtf8(bytes),
jsonParse: jsonParses(bytes),
}
}
/** Index of the attachment the TS scanner retains; null when it retains none. */
async function chosenAttachment(pdf: Uint8Array, digests: readonly string[]) {
try {
const at = digests.indexOf(sha256(await readAttachmentBytes(pdf)))
if (at < 0) throw new Error('scanner returned bytes of no attachment')
return at
} catch (err) {
if (err instanceof ArchiveReadError) return null
throw err
}
}
function importedRow({ read, rebase }: ArchiveImport) {
return {
ok: true,
reportSha256: sha256(JSON.stringify(rebase.report)),
archiveSha256: read.archive ? sha256(JSON.stringify(read.archive)) : null,
conclusion: rebase.report.conclusion,
read: {
origin: read.origin,
migrated: read.migrated,
unresolvedZones: read.unresolvedZones,
unresolvedFindings: read.unresolvedFindings,
snapshotRejected: read.snapshotRejected ?? null,
},
rebase: {
rebased: rebase.rebased,
unresolvedZones: rebase.unresolvedZones,
unresolvedFindings: rebase.unresolvedFindings,
},
}
}
function failureRow(err: unknown) {
if (err instanceof ImportError) {
const found =
err.foundVersion === undefined ? {} : { foundVersion: err.foundVersion }
return { ok: false, kind: err.kind, ...found }
}
if (err instanceof Error)
return { ok: false, kind: 'error', message: err.message }
throw err
}
/** HomeRoute's PDF branch (`readImport`), size pre-check aside: scan, then core import. */
async function r3Outcome(pdf: Uint8Array, sheet: SheetIndex) {
try {
const attachment = await readAttachment(pdf)
return importedRow(importAttachment(attachment, sheet))
} catch (err) {
return failureRow(err)
}
}
async function caseRow(spec: CaseSpec, pdf: Uint8Array, sheet: SheetIndex) {
const attachments = spec.attachments.map(attachmentRow)
return {
id: spec.id,
description: spec.description,
base: spec.base,
pdf: `${PDF_DIR_REL}/${spec.id}.pdf`,
pdfSha256: sha256(pdf),
attachments,
chosen: await chosenAttachment(
pdf,
attachments.map((a) => a.sha256),
),
outcome: await r3Outcome(pdf, sheet),
}
}
const pdfPath = (id: string) => resolve(PDF_DIR, `${id}.pdf`)
function refuseFieldCorpus(): void {
if (process.env.FAUNOSTEO_FIELD_CORPUS) {
throw new Error('refused: FAUNOSTEO_FIELD_CORPUS is set (plan §B.5.2)')
}
}
// ---------------------------------------------------------------------------
describe('R4 O8 tolerance corpus on the R3 import path', () => {
let sheet: SheetIndex
let cases: CaseSpec[]
beforeAll(async () => {
if (MAKE) refuseFieldCorpus()
sheet = await loadTestSheet()
cases = buildCases(loadBases())
})
it('has unique case ids', () => {
const ids = cases.map((c) => c.id)
expect(new Set(ids).size).toBe(ids.length)
})
it('builds byte-identical PDFs (written under MAKE_R4_ORACLES)', async () => {
if (MAKE) mkdirSync(PDF_DIR, { recursive: true })
for (const spec of cases) {
const pdf = await buildPdf(spec.attachments)
if (MAKE) writeFileSync(pdfPath(spec.id), pdf)
else
expect(sha256(pdf), spec.id).toBe(
sha256(readFileSync(pdfPath(spec.id))),
)
}
const expected = cases.map((c) => `${c.id}.pdf`).sort()
expect(readdirSync(PDF_DIR).sort()).toEqual(expected)
}, 60_000)
it('records the R3 outcome of every committed PDF', async () => {
const rows = []
for (const spec of cases) {
const pdf = new Uint8Array(readFileSync(pdfPath(spec.id)))
rows.push(await caseRow(spec, pdf, sheet))
}
const oracle = { oracle: 'O8', sheet: sheet.sheet.ref, cases: rows }
if (MAKE) {
mkdirSync(dirname(OUT), { recursive: true })
writeFileSync(OUT, JSON.stringify(oracle, null, 2) + '\n')
}
expect(oracle).toEqual(JSON.parse(readFileSync(OUT, 'utf8')))
}, 120_000)
it('imports both controls with their archive state', async () => {
const oracle = JSON.parse(readFileSync(OUT, 'utf8'))
const row = (id: string) =>
oracle.cases.find((c: { id: string }) => c.id === id)
expect(row('control-bare-v3').outcome).toMatchObject({
ok: true,
archiveSha256: null,
})
expect(row('control-envelope').outcome).toMatchObject({ ok: true })
expect(row('control-envelope').outcome.archiveSha256).not.toBeNull()
})
})