Enterprise editie

AST audit trail — Diepe referentie

In één oogopslag

De Enterprise AST-module registreert documentmutaties en bereidt documenten voor op retrieval-pipelines.

AstAuditTrailInterface definieert een append-only, per-document audit trail over de Pro AST MutationLog.
AstAuditEntry is een onveranderlijke registratie van één mutatie: node-identiteit, mutatiesoort, pagina, voor/na-snapshots, UTC-tijdstempel.
InMemoryAstAuditTrail is de per-proces referentie-implementatie van het trail-contract.
AstAwareChunker doorloopt de AST depth-first en produceert citation-anchored AstChunk-waarden voor RAG-ingestie.

Beschikbaarheid en licentiëring

Deze capability wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop van de Enterprise-tier. Een deployment zonder dat entitlement laadt de classes van de capability niet. Vergelijk edities en verkrijg een licentie.

Het AST-audit-trail-oppervlak wordt gelicentieerd door de enterprise.compliance.evidence-capability. Een geweigerd entitlement weigert de functie.

Tier	Levert
Core	AST-documentmodel (`AstDocument`, `AstNode`, `NodeId`)
Pro	AST-mutatieflow en `MutationLog`
Enterprise	Append-only per-document audit trail; citation-anchored chunker

Het Enterprise-oppervlak consumeert het Pro-mutatielog. Het vervangt het AST-model niet.

composer require nextpdf/enterprise:^3

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	Converteert elke mutatievermelding in het log naar een `AstAuditEntry` en voegt die toe	`void`	Niets in de referentie-implementatie	Herhaalde aanroepen met dezelfde hash stapelen vermeldingen op
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	Retourneert de voor één document geregistreerde vermeldingen, in invoegvolgorde	`list<AstAuditEntry>`	Niets in de referentie-implementatie	Lege lijst wanneer geen vermeldingen bij de hash horen
`AstAuditTrailInterface::count()`	geen	Telt audit-vermeldingen	`int<0, max>`	Niets in de referentie-implementatie	Totaal over alle documenten, niet per document
`InMemoryAstAuditTrail`	geen	Array-backed trail beperkt tot het huidige proces	implementeert `AstAuditTrailInterface`	Niets	Niet duurzaam; geschikt voor single-request-levenscycli
`AstAuditEntry`	constructor promoot alle velden	Onveranderlijke audit-registratie	value object	Niets	`final readonly`; zie de signature-fence hieronder
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	Valideert de chunking-grenzen bij constructie	instance	`InvalidArgumentException` bij configuratie buiten bereik	Grenzen: `16 <= maxChunkChars <= 1048576`; `0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	Depth-first-doorloop; koppen begrenzen chunks; leaf-tekst accumuleert	`list<AstChunk>`	Niets	Lege lijst voor een document zonder accumuleerbare tekst
`AstChunk`	constructor promoot alle velden	Citation-anchored chunk-registratie	value object	Niets	`final readonly`; zie de signature-fence hieronder

namespace NextPDF\Enterprise\Ast;

use NextPDF\Pro\Ast\Mutation\MutationLog;

interface AstAuditTrailInterface
{
    public function record(string $documentSourceHash, MutationLog $log): void;

    /** @return list<AstAuditEntry> */
    public function findByDocument(string $documentSourceHash): array;

    /** @return int<0, max> */
    public function count(): int;
}

final readonly class AstAuditEntry
{
    public function __construct(
        public readonly string            $documentSourceHash,
        public readonly string            $nodeId,
        public readonly string            $mutationType,
        public readonly int               $pageIndex,
        public readonly array             $before,
        public readonly array             $after,
        public readonly DateTimeImmutable $occurredAt,
    ) {}
}

final class AstAwareChunker
{
    public function __construct(
        private readonly int $maxChunkChars = 1500,
        private readonly int $overlapChars = 150,
    ) {}

    /** @return list<AstChunk> */
    public function chunk(AstDocument $document): array {}
}

final readonly class AstChunk
{
    public function __construct(
        public readonly string $text,
        public readonly string $nodeId,
        public readonly int $pageIndex,
        public readonly ?array $bbox,
        public readonly string $nodeType,
        public readonly string $documentSourceHash,
        public readonly int $chunkIndex,
    ) {}
}

Gedragscontract

Audit trail

Append-only. Implementaties moeten append-only zijn: een geregistreerde vermelding kan niet via deze API worden gewijzigd of verwijderd. Herhaalde record()-aanroepen met dezelfde hash stapelen vermeldingen op.
Conversie. record() converteert elke vermelding van het Pro MutationLog (via MutationLog::all()) naar een AstAuditEntry en voegt die toe. Alle vermeldingen die door één record()-aanroep worden geproduceerd, delen één UTC occurredAt-tijdstempel.
Per-document-isolatie. findByDocument() filtert op de exacte document-source-hash en behoudt de invoegvolgorde. count() is het totaal over alle documenten.
Snapshots. before en after zijn attribuutmaps met text_content als sleutel. Een updated-mutatie vult beide zijden; inserted laat before leeg; deleted laat after leeg. mutationType is de string-waarde van de Pro MutationType-enum: updated, inserted of deleted.
Pagina-afleiding. pageIndex wordt uit de canonieke node-ID (ast:{hash}:{page}:{seq}) gehaald. Een misvormde node-ID levert pageIndex 0 op; de vermelding wordt toch geregistreerd.

Append-only is een contract van de geconfigureerde store, geen cryptografische eigenschap. Tamper-evidence en onweerlegbaarheid komen voort uit hoe de trail wordt gepersisteerd en getijdstempeld (Evidence-module), niet uit deze module alleen.

Chunker

Doorloop. chunk() doorloopt de AST depth-first vanaf de documentroot.
Tekstaccumulatie. Leaf-tekst van het type Paragraph, ListItem, TableCell, Code of Annotation accumuleert in de huidige buffer. Container-types (Document, Section, Artifact, FormField, Figure, Table, List, TableRow) worden doorlopen zonder tekst uit te geven.
Scheidingstekens. Een Heading-node flusht de huidige buffer als een chunk en initialiseert de volgende buffer met de kop-tekst.
Splitsing. Wanneer geaccumuleerde tekst maxChunkChars zou overschrijden, vult de chunker de resterende ruimte, flusht de chunk en gaat verder met de laatste overlapChars tekens plus de overloop. De lengtebepaling is gebaseerd op UTF-8-tekens.
Citatie-anker. Elke AstChunk draagt de nodeId, pageIndex, bbox en nodeType van zijn eerste bijdragende node, plus de document-source-hash en een sequentiële, 0-gebaseerde chunkIndex.
Finalisatie. Een resterende buffer met niet-witruimte-inhoud wordt als de laatste chunk geflusht; resten met alleen witruimte worden weggegooid en chunk-tekst wordt getrimd.

Randgevallen en faalmodi

Het tweemaal registreren van hetzelfde MutationLog stapelt dubbele vermeldingen op; idempotentie moet upstream worden afgedwongen.
Een verse, niet-gedeelde InMemoryAstAuditTrail is altijd leeg. Het integratiecontract vereist één gedeelde AstAuditTrailInterface-instance die aan zowel de mutatie-producerende flow als de audit-lezende consumer wordt gegeven, met record() aangeroepen na elke succesvolle schrijfactie. Tot dan retourneert findByDocument() een lege lijst en retourneert count() 0.
De in-memory trail is per-proces en niet duurzaam; vermeldingen overleven het verzoek dat ze aanmaakte niet. Productie levert een persistente implementatie.
Een node-ID die canonieke parsing niet doorstaat, breekt de registratie niet af; de betrokken vermelding valt terug op pageIndex 0.
AstAwareChunker::__construct() weigert ontaarde configuratie (overlapChars >= maxChunkChars, of maxChunkChars buiten [16, 1048576]) met InvalidArgumentException. Dit voorkomt onbegrensde buffergroei tijdens chunking.
AstChunk::$bbox is null wanneer de eerste bijdragende node geen bounding box draagt.
Een document zonder accumuleerbare tekst levert een lege chunk-lijst op.
Deze module voert geen cryptografische bewerkingen uit. Hashing, ondertekening en tijdstempeling voor tamper-evidence worden afgehandeld door de Evidence-, Security- en Signature-modules; FIPS-modusbeleid leeft daar.

Conformiteit

Gedrag	Referentie
Incremental-update- / handtekeningintegriteitscontext	ISO 32000-2:2020 §12.8

De audit trail is een hulpmiddel voor administratie. Ze ondersteunt audit-achtige bewijs-workflows; het is geen certificering en geen juridische attestatie, en NextPDF beschikt over geen enkele certificering.

Ontwikkelnotities

Lever een duurzame AstAuditTrailInterface-implementatie voor retentie over verzoeken heen. Persisteer die in een WORM-capable store waar compliance onveranderlijkheid vereist; de append-only-garantie is slechts zo sterk als de onderliggende store.
Mutatiesnapshots kunnen persoonsgegevens dragen; dataresidentie volgt de store van de operator.
De trail consumeert het Pro-mutatielog zoals het geproduceerd wordt; het leidt mutaties niet opnieuw af uit de documentstatus.
De chunker-standaardwaarden (maxChunkChars 1500, overlapChars 150) passen bij typische RAG-ingestie; stem ze af binnen de gedocumenteerde grenzen voor embedding-modellen met andere context-budgetten.
Interne mechanismedetails blijven in de interne documentatie van de source-repository en vallen buiten de scope van deze handleiding.

Publicatiegrens

Deze pagina documenteert uitsluitend extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-classes, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.