# Task H.5.1: PDF Integrity Audit & Payload Parity

## Objective

Close all remaining PDFME reliability gaps before implementing signature capture.

This task freezes:

* template version integrity
* placeholder naming integrity
* runtime payload parity
* preview/generator consistency

and becomes the final audit layer before PDF feature freeze.

---

## 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/implementation/task-h51-pdf-integrity-audit.md

* docs/business/pdf-placeholder-registry.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

---

# H5.12 Template Version Integrity Audit

## Purpose

Validate active template version consistency.

Audit:

* crm_document_templates
* crm_document_template_versions
* crm_document_template_mappings

Checks:

### Active Template

Only one active template per:

* documentType
* productType
* fileType

### Active Version

Only one active version per template.

### Approved Snapshot Version

Verify:

approvedTemplateVersionId

exists and remains valid.

### Orphan Version Detection

Detect:

* deleted template
* active version without template
* mappings without version

---

# H5.13 Placeholder Integrity Audit

## Purpose

Detect naming issues before runtime generation.

Audit:

PDF schema field names

against

mapping registry.

Checks:

### Duplicate Placeholder

Example:

quotation_date
quotation_date_data

### Typo Detection

Example:

quotation_date_labe

quotation_code_lable

### Unmapped Placeholder

Exists in template but not mapping table.

### Dead Mapping

Exists in mapping table but not template.

### Reserved Dynamic Topic Names

Validate:

topic
data_topic

remain reserved template placeholders.

Reject:

topic_1
item_topic_1

being stored in mapping tables.

---

# H5.14 Runtime Payload Parity Audit

## Purpose

Ensure Preview PDF and Generated PDF use identical data.

Audit:

### Preview Payload

Output from:

buildInputs()

### Runtime Payload

Output from:

prepareDocument()

### Approved Snapshot Payload

Output from:

prepareApprovedQuotationSnapshot()

Checks:

* field count
* field names
* topic input keys
* signature keys
* exclusion data
* quotation totals
* customer values

---

# Payload Hash Validation

Generate hash:

SHA256(JSON.stringify(payload))

Compare:

preview hash
generation hash
snapshot hash

Result:

PASS
FAIL

---

# H5.15 Dynamic Topic Runtime Audit

## Purpose

Validate Topic Engine behavior.

Audit:

* topic count
* item count
* page count
* generated topic keys

Expected:

topic_0_0
topic_0_1

item_topic_0_0
item_topic_0_1

Checks:

* duplicate keys
* missing topic items
* empty topic sections
* page overflow risks

---

# H5.16 Signature Mapping Audit

## Purpose

Validate H.3 integration.

Audit:

app1
app1_position

app2
app2_position

app3
app3_position

Checks:

* resolved name
* resolved position
* timestamp
* snapshot persistence

---

# Reporting

Generate:

/artifacts/pdf-audit/

* template-version-report.json
* placeholder-integrity-report.json
* payload-parity-report.json
* topic-runtime-report.json
* signature-audit-report.json
* summary.md

---

# Acceptance Criteria

PASS:

* no orphan template version
* no orphan mappings
* no unresolved placeholder
* no placeholder typo
* preview payload = generation payload
* generation payload = approved snapshot payload
* dynamic topic keys generated correctly
* signature fields resolved correctly

FAIL:

* any hash mismatch
* unresolved placeholder
* duplicate active version
* orphan mapping
* missing signature field

---

# Out of Scope

* signature drawing
* signature image upload
* handwritten signature rendering
* PDF screenshot comparison
* OCR validation

These belong to Task H.4.

---

# Deliverable

After completion:

PDF Layer Status = Frozen

Ready for:

Task H.4 Signature Capture
Task K Report Center
Task L Approved Document Archive