alla-allaos-fullstack/docs/implementation/task-h51-pdf-integrity-audit.md

Task H.5.1: PDF Integrity Audit & Payload Parity

Files Added

• scripts/audit-template-version-integrity.ts
• scripts/audit-placeholder-integrity.ts
• scripts/audit-payload-parity.ts
• scripts/audit-approved-snapshot-parity.ts
• scripts/generate-pdf-integrity-report.ts
• docs/business/pdf-placeholder-registry.md
• docs/implementation/task-h51-pdf-integrity-audit.md

Files Modified

• package.json
• scripts/generate-pdf-audit-report.ts
• docs/implementation/pdf-parity-checklist.md
• docs/business/pdf-mapping-registry.md
• docs/implementation/technical-debt.md
• scripts/pdf-audit-utils.ts

Integrity Coverage

• template-version integrity checks active template uniqueness, active version uniqueness, orphan mappings, and approved template-version references
• placeholder integrity checks duplicate names, typo-like names, unmapped placeholders, dead mappings, and reserved dynamic topic names
• payload parity computes SHA256 hashes for preview, generation, and computed snapshot payloads
• approved snapshot parity compares stored snapshot payloads against computed snapshot payloads when they exist
• integrity summary writes machine-readable artifacts into artifacts/pdf-audit/

Verification Result

• npx tsc --noEmit passed
• npm run audit:pdf runs the full H.5 + H.5.1 stack
• current integrity result is expected to be WARNING when the audit fixture has not yet generated a persisted approved snapshot/artifact

Remaining Risks

• stored approved snapshot parity still depends on generating a real approved PDF artifact for QT-H5-AUDIT
• template field line is still treated as a tolerated designer-owned oddity rather than a normalized mapping field
• the audit stack validates payload integrity and runtime parity, not screenshot-level pixel parity

Follow-on Freeze Note

• quotation_price_data is now treated as the canonical PDFME table field for quotation price rendering
• quotation_price and currency remain supported only as scalar compatibility fields

H.5.3 Versioning Note

• integrity checks now accept retained inactive template versions as valid historical references for approved snapshots
• the active-version audit also verifies that the active DB schema matches the latest JSON source file for each organization template
• runtime payload integrity now includes explicit static-label checks so blank tel_label/email_label/att_label/project_label/site_label values fail the suite