AST audit trail — Deep Reference (Gated)

Gated content notice. This page is part of the gated reference surface. Distribution restricted by NDA. Do not mirror to public channels.

Edition gate

Requires NextPDF Enterprise. Get a license.

License feature flag

The AST audit-trail surface is gated by the enterprise.compliance.evidence capability (Enterprise edition tier). A denied entitlement denies the feature.

Behavior contract

AstAuditTrailInterface::record(string $documentSourceHash, MutationLog $log): void converts each entry of a Pro AST MutationLog into an AstAuditEntry and appends it. Externally observable rules:

Append-only. Implementations must be append-only: a recorded entry cannot be modified or removed through this API. Repeated record calls with the same hash accumulate entries.
Per-document isolation. findByDocument(string $documentSourceHash): list<AstAuditEntry> returns entries for one document in insertion order. count: int<0,max> is the total across all documents.
Immutable entries. AstAuditEntry carries documentSourceHash, nodeId (ast:{hash}:{page}:{seq}), mutationType (updated/inserted/deleted), pageIndex, before/after attribute snapshots (empty on the opposite side for insert/delete), and occurredAt (UTC).
Chunking. AstAwareChunker walks the AST depth-first; headings start a new chunk, leaf text accumulates to a max size, an overlap window preserves continuity. Each AstChunk carries the nodeId, pageIndex, bbox, and nodeType of its first contributing node for precise source citation.

Append-only is a contract of the configured store. Tamper-evidence and non-repudiation come from how the trail is persisted and timestamped (Evidence), not from this module alone.

Public API surface

composer require nextpdf/enterprise:^3

namespace NextPDF\Enterprise\Ast;

interface AstAuditTrailInterface {
    public function record(string $documentSourceHash, \NextPDF\Pro\Ast\Mutation\MutationLog $log): void;
    public function findByDocument(string $documentSourceHash): array;
    public function count: int;
}

final readonly class AstAuditEntry {
    public string $documentSourceHash;
    public string $nodeId;
    public string $mutationType;
    public int $pageIndex;
    public array $before;
    public array $after;
    public \DateTimeImmutable $occurredAt;
}

final class InMemoryAstAuditTrail implements AstAuditTrailInterface { /* reference impl */ }
final class AstAwareChunker { /* depth-first, citation-anchored */ }

Conformance

Behavior	Reference
Incremental-update / signature-integrity context	ISO 32000-2:2020 §12.8

The audit trail is a record-keeping aid. It is not a certification or a legal attestation.

Edge cases & FIPS-mode behavior

Recording the same MutationLog twice accumulates entries; idempotency must be enforced upstream.
The in-memory trail is not durable; production supplies a persistent implementation.
This module performs no cryptographic operations. Hashing, signing, and timestamping for tamper-evidence are handled by the Evidence, Security, and Signature modules; FIPS-mode policy lives there.

NDA scan status

This gated page references the public package contract and externally observable behavior only. It contains no internal namespace paths beyond the public supported class names already listed, no internal trait names, no internal store internals, no runbook filenames, and no internal ticket prefixes. Attested in the co-located NDA checklist.

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 and are not reproduced here.

Deployment boundary

Append-only is a contract of the configured store, not a cryptographic property. The operator supplies a durable trail implementation, is responsible for persisting it in a WORM-capable store, and enforces upstream idempotency. Tamper-evidence and non-repudiation come from how the trail is persisted and timestamped (Evidence module), not from this module alone. Mutation snapshots can carry personal data; residency follows the operator’s store.

Legal-compliance boundary

This module is flagged export_control_class: none; no export-control legal gate applies. The audit trail is a record-keeping aid; it is not a certification or a legal attestation. This reference is not a legal opinion.