AST audit trail

At a glance

NextPDF Enterprise records every AST mutation as an append-only, per-document audit trail, and produces semantically bounded, citation-anchored chunks of an AST for downstream pipelines. The trail supports audit and traceability workflows.

Availability & licensing

This capability ships in NextPDF Enterprise (nextpdf/enterprise) and activates with an Enterprise-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

Install

composer require nextpdf/enterprise:^3

Conceptual overview

AstAuditTrailInterface is the recording contract. record($documentSourceHash, $log) converts each entry from a Pro AST MutationLog into an AstAuditEntry and appends it; repeated calls with the same document hash accumulate entries. The implementation is append-only by contract: once recorded, an entry cannot be modified or removed. findByDocument($hash) returns the entries for one document in insertion order; count() returns the total across all documents. InMemoryAstAuditTrail is the reference implementation.

AstAuditEntry is an immutable record of one mutation: the document source hash, the canonical node id, the mutation type (updated / inserted / deleted), the 0-based page index, before/after attribute snapshots, and the UTC time the entry was recorded. Retrieval is scoped per document hash, so audit history stays isolated per document.

AstAwareChunker walks an AST depth-first and emits AstChunk instances that respect document structure: headings start a new chunk, leaf text accumulates up to a configured size, and an overlap window preserves continuity across split boundaries. Each chunk carries the node id, page index, bounding box, and node type of its first contributing node, so downstream systems can cite a precise source location.

What this module asserts

This module records mutation history and produces structured chunks.

• The audit trail is append-only by contract within the configured store. Tamper-evidence and non-repudiation are properties of where and how you persist and timestamp it (see Evidence).
• Recording a mutation documents that it happened. It does not validate or authorize the change.
• Chunk citations point to source locations; they are navigation aids.

An audit trail supports audit workflows.

Tier boundary

• NextPDF Core / Pro AST provide the AST model and the mutation log.
• NextPDF Enterprise AST (this page) adds the append-only per-document audit trail over those mutations and the citation-anchored chunker. It consumes the Pro mutation log; it does not replace the AST model.

Why it works this way

The load-bearing decision is scope restraint. This module records that a mutation happened; durability, tamper-evidence, and non-repudiation are delegated to the backing store and the Evidence module. Retrieval is keyed by documentSourceHash, so one document’s history never bleeds into another’s. The chunker anchors every chunk to its first node and validates maxChunkChars and overlapChars up front, so citations stay precise. Persistence and residency stay in operator hands, so the same surface serves WORM-backed evidence stores and lighter pipelines alike.

Design background: Compliance you can hand to an auditor.

API surface

Class / Interface	Responsibility
AstAuditTrailInterface	Append-only recording and per-document retrieval contract.
AstAuditEntry	Immutable record of one mutation with before/after snapshots.
InMemoryAstAuditTrail	Reference append-only trail implementation.
AstAwareChunker	Structure-respecting, citation-anchored AST chunker.
AstChunk	One chunk with node id, page index, bbox, and node type.

Code sample — Quick start

$trail->record($documentSourceHash, $mutationLog);
$entries = $trail->findByDocument($documentSourceHash);

Code sample — Production

$trail->record($documentSourceHash, $mutationLog);

foreach ($trail->findByDocument($documentSourceHash) as $entry) {
    $logger->info('ast.audit', [
        'node'     => $entry->nodeId,
        'type'     => $entry->mutationType,
        'page'     => $entry->pageIndex,
        'recorded' => $entry->occurredAt->format(DATE_RFC3339),
    ]);
}
// Persist the trail in a WORM-backed store for tamper-evidence (see Evidence).

Edge cases & gotchas

• Recording the same MutationLog twice accumulates entries; dedupe upstream if you need idempotency.
• The in-memory trail is not durable; production deployments supply a persistent AstAuditTrailInterface.
• Append-only is a contract of the store, not a cryptographic property; pair with Evidence packaging for tamper-evidence.

Performance

Recording is linear in the number of mutation entries. Chunking is a single depth-first AST walk; cost scales with node count and the configured chunk size.

Security notes

Before/after snapshots may contain document text. Treat the trail as sensitive at rest. The append-only contract prevents in-place edits through this API, but durability and tamper-evidence depend on the backing store.

Data residency & PII mitigations

Mutation snapshots can carry personal data extracted from documents. Persistence is delegated to your trail implementation, so residency follows your store. Apply retention and minimization controls to recorded snapshots.

Safe telemetry & log scrubbing

Node ids, mutation types, page indices, and timestamps are safe to log. Before/after snapshots may contain document content; redact them before forwarding to shared sinks.

Conformance

Behavior	Reference	Status
Incremental-update / integrity context	ISO 32000-2:2020 §12.8	Referenced (context for tamper-evidence)

This table records the specification context this module operates within. The audit trail is a record-keeping aid.

FIPS-mode behavior

This module performs no cryptographic operations. Hashing, signing, and timestamping for tamper-evidence are handled by the Evidence, Security, and Signature modules.

Threat model

The input is a mutation log. Mitigations: append-only recording contract, per-document scoping to isolate histories, and delegation of durability and tamper-evidence to a WORM-capable store and the Evidence module.

Behavior contract

• The audit trail is append-only by contract within the configured store: once recorded, an entry cannot be modified or removed through this API.
• Each entry is an immutable record of one mutation (document source hash, canonical node id, mutation type, page index, before/after snapshots, recorded UTC time); retrieval is scoped per document hash.
• Recording the same mutation log twice accumulates entries — dedupe upstream if idempotency is required.
• The chunker walks the AST depth-first and emits structure-respecting chunks carrying node id, page index, bounding box, and node type for precise source citation.
• Recording a mutation documents that it happened; it does not validate or authorize the change, and chunk citations are navigation aids.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

Core fallback

NextPDF Core / Pro AST provide the AST model and the mutation log. The append-only per-document audit trail and the citation-anchored chunker have no Core-tier equivalent; the Enterprise surface consumes the mutation log, it does not replace the AST model.

Pro fallback

NextPDF Pro AST provides the AST model and the mutation log but no append-only per-document audit trail and no citation-anchored chunker. Those ship in the nextpdf/enterprise package only; the Enterprise surface consumes the Pro mutation log.

Enterprise boundary note

The recording contract, per-document retrieval, and the chunker are described at the behavior level. The reference in-memory trail is documented; durable persistence is supplied by the host, and any internal store internals are out of scope for the public surface.

Deployment boundary

Append-only is a contract of the store, not a cryptographic property. The operator supplies a durable trail implementation and is responsible for persisting it in a WORM-backed store for tamper-evidence; durability and non-repudiation depend on that store and on the Evidence module, not on this module alone. Mutation snapshots can carry personal data; residency follows the operator’s store.

Legal-compliance boundary

No export-control restriction applies to the AST audit-trail surface. An audit trail supports audit workflows. Consult your own compliance and legal advisers.

See also

• Evidence — seal and timestamp the trail.
• Validation — structural policy checks.
• Core AST — the AST model.
• AST audit trail — Deep Reference — durable store internals and the full public API surface.