MEGAINFRA-WEBAPP/.superpowers/sdd/2026-09-18-hybrid-delivery-note-ingestion/task-2-report.md

Task 2 report: canonical page normalisation

RED evidence

Command:

npx vitest run src/lib/dn-pipeline/normalise-source.test.ts

Result: failed before collecting tests because ./normalise-source did not exist:

Error: Failed to load url ./normalise-source ... Does the file exist?
Test Files  1 failed (1)
Tests  no tests

GREEN evidence

Command:

npx vitest run src/lib/dn-pipeline/normalise-source.test.ts src/lib/dn-pipeline/split.test.ts

Result:

Test Files  2 passed (2)
Tests  11 passed (11)

Command:

npm run typecheck

Result:

> mega-infrastructure-dashboard@1.0.0 typecheck
> tsc --noEmit

Exit status: 0.

Implementation

• Added normaliseSource() and NormalisedPage in normalise-source.ts.
• Detects PDF content by %PDF- magic, renders every page with Poppler, and sends all raster output through Sharp.
• Decodes image metadata instead of trusting declared MIME, applies EXIF orientation, bounds output to 2200px without enlarging, and emits actual PNG bytes with dimensions and applied rotation.
• Rejects undecodable data and TIFF/HEIF codecs with unsupported_image_codec.
• Kept splitPages() as the legacy { page, png } adapter and made PDF page counting content-based.
• Added Sharp dependency and regression coverage for mismatched MIME, PDFs, invalid bytes, orientation, dimensions, and unsupported codecs.

Concerns

• PDF rendering requires the existing Poppler pdftoppm executable at runtime.
• npm install sharp reports existing audit vulnerabilities and an unrelated isolated-vm engine warning on Node 22; neither blocks this task's tests or typecheck.

Fix Round 1

Addressed review findings:

• extractPageRange() now detects PDF content using %PDF- magic bytes, independent of declared MIME, matching the normalizer and split adapter.
• Updated splitPages() documentation to describe decoding and canonical PNG output instead of pass-through behavior.
• Added a regression test proving a multi-page PDF declared as image/jpeg extracts only the requested range.

RED evidence:

npx vitest run src/lib/dn-pipeline/split.test.ts
...
× split (requires poppler + the fixture) > extracts a page range from a PDF despite an incorrect declared MIME
  → expected 4 to be 2
Test Files  1 failed (1)
Tests  1 failed | 5 passed (6)

GREEN and verification evidence:

npx vitest run src/lib/dn-pipeline/normalise-source.test.ts src/lib/dn-pipeline/split.test.ts
Test Files  2 passed (2)
Tests  12 passed (12)

npm run typecheck
> mega-infrastructure-dashboard@1.0.0 typecheck
> tsc --noEmit

git diff --check
exit status: 0