Enterprise Edition

AST-Audit-Trail — Ausführliche Referenz

Auf einen Blick

Das Enterprise-AST-Modul zeichnet Dokumentmutationen auf und bereitet Dokumente für Retrieval-Pipelines vor.

AstAuditTrailInterface definiert einen Append-only-Audit-Trail je Dokument über dem Pro-AST-MutationLog.
AstAuditEntry ist ein unveränderlicher Datensatz einer Mutation: Knotenidentität, Mutationsart, Seite, Vorher-/Nachher-Snapshots, UTC-Zeitstempel.
InMemoryAstAuditTrail ist die prozessweise Referenzimplementierung des Trail-Vertrags.
AstAwareChunker durchläuft den AST tiefensuchend und gibt zitationsverankerte AstChunk-Werte für die RAG-Aufnahme aus.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit ist in NextPDF Enterprise (nextpdf/enterprise) enthalten und wird mit einem Lizenz-Envelope der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz erwerben.

Die AST-Audit-Trail-Oberfläche wird durch die Fähigkeit enterprise.compliance.evidence lizenziert. Eine verweigerte Berechtigung verweigert die Funktion.

Stufe	Stellt bereit
Core	AST-Dokumentmodell (`AstDocument`, `AstNode`, `NodeId`)
Pro	AST-Mutationsfluss und `MutationLog`
Enterprise	Append-only-Audit-Trail je Dokument; zitationsverankerter Chunker

Die Enterprise-Oberfläche konsumiert das Pro-Mutationslog. Sie ersetzt nicht das AST-Modell.

composer require nextpdf/enterprise:^3

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	Wandelt jeden Mutationseintrag im Log in einen `AstAuditEntry` um und hängt ihn an	`void`	Nichts in der Referenzimplementierung	Wiederholte Aufrufe mit demselben Hash sammeln Einträge an
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	Gibt die für ein Dokument aufgezeichneten Einträge in Einfügereihenfolge zurück	`list<AstAuditEntry>`	Nichts in der Referenzimplementierung	Leere Liste, wenn kein Eintrag zum Hash passt
`AstAuditTrailInterface::count()`	keine	Zählt Audit-Einträge	`int<0, max>`	Nichts in der Referenzimplementierung	Summe über alle Dokumente, nicht je Dokument
`InMemoryAstAuditTrail`	keine	Array-gestützter Trail, begrenzt auf den aktuellen Prozess	implementiert `AstAuditTrailInterface`	Nichts	Nicht dauerhaft; geeignet für Einzelanfrage-Lebenszyklen
`AstAuditEntry`	Konstruktor promotet alle Felder	Unveränderlicher Audit-Datensatz	Value Object	Nichts	`final readonly`; siehe Signatur-Fence unten
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	Validiert die Chunking-Grenzen bei der Konstruktion	Instanz	`InvalidArgumentException` bei Konfiguration außerhalb des Bereichs	Grenzen: `16 <= maxChunkChars <= 1048576`; `0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	Tiefensuche-Durchlauf; Überschriften begrenzen Chunks; Blatttext akkumuliert	`list<AstChunk>`	Nichts	Leere Liste für ein Dokument ohne akkumulierbaren Text
`AstChunk`	Konstruktor promotet alle Felder	Zitationsverankerter Chunk-Datensatz	Value Object	Nichts	`final readonly`; siehe Signatur-Fence unten

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,
    ) {}
}

Verhaltensvertrag

Audit-Trail

Append-only. Implementierungen müssen append-only sein: Ein aufgezeichneter Eintrag kann über diese API weder geändert noch entfernt werden. Wiederholte record()-Aufrufe mit demselben Hash sammeln Einträge an.
Konvertierung. record() wandelt jeden Eintrag des Pro-MutationLog (über MutationLog::all()) in einen AstAuditEntry um und hängt ihn an. Alle von einem record()-Aufruf erzeugten Einträge teilen sich einen einzigen UTC-occurredAt-Zeitstempel.
Isolation je Dokument. findByDocument() filtert auf den exakten Dokument-Source-Hash und wahrt die Einfügereihenfolge. count() ist die Summe über alle Dokumente.
Snapshots. before und after sind Attribut-Maps mit dem Schlüssel text_content. Eine updated-Mutation füllt beide Seiten; inserted lässt before leer; deleted lässt after leer. mutationType ist der String-Wert des Pro-MutationType-Enums: updated, inserted oder deleted.
Seitenherleitung. pageIndex wird aus der kanonischen Knoten-ID (ast:{hash}:{page}:{seq}) extrahiert. Eine fehlerhafte Knoten-ID ergibt pageIndex 0; der Eintrag wird dennoch aufgezeichnet.

Append-only ist ein Vertrag des konfigurierten Stores, keine kryptografische Eigenschaft. Manipulationssicherheit und Nichtabstreitbarkeit ergeben sich daraus, wie der Trail persistiert und mit Zeitstempeln versehen wird (Evidence-Modul), nicht aus diesem Modul allein.

Chunker

Durchlauf. chunk() durchläuft den AST tiefensuchend von der Dokumentwurzel aus.
Textakkumulation. Blatttext der Typen Paragraph, ListItem, TableCell, Code oder Annotation akkumuliert in den aktuellen Puffer. Containertypen (Document, Section, Artifact, FormField, Figure, Table, List, TableRow) werden durchlaufen, ohne Text auszugeben.
Trennzeichen. Ein Heading-Knoten leert den aktuellen Puffer als Chunk und initialisiert den nächsten Puffer mit dem Überschriftentext.
Aufteilung. Wenn der akkumulierte Text maxChunkChars überschreiten würde, füllt der Chunker den verbleibenden Raum, leert den Chunk und fährt mit den letzten overlapChars Zeichen plus dem Überlauf fort. Die Längenberechnung erfolgt zeichenbasiert nach UTF-8.
Zitationsanker. Jeder AstChunk trägt die nodeId, pageIndex, bbox und nodeType seines ersten beitragenden Knotens sowie den Dokument-Source-Hash und einen fortlaufenden, 0-basierten chunkIndex.
Finalisierung. Ein abschließender Puffer mit nicht-leerem Inhalt wird als letzter Chunk geleert; reine Whitespace-Reste werden verworfen, und der Chunk-Text wird getrimmt.

Randfälle & Fehlermodi

Das zweimalige Aufzeichnen desselben MutationLog sammelt doppelte Einträge an; Idempotenz muss vorgelagert durchgesetzt werden.
Ein frischer, nicht geteilter InMemoryAstAuditTrail ist stets leer. Der Integrationsvertrag verlangt eine einzige geteilte AstAuditTrailInterface-Instanz, die sowohl dem mutationserzeugenden Fluss als auch dem audit-lesenden Konsumenten übergeben wird, wobei record() nach jedem erfolgreichen Schreibvorgang aufgerufen wird. Bis dahin gibt findByDocument() eine leere Liste und count() 0 zurück.
Der In-Memory-Trail ist prozessweise und nicht dauerhaft; Einträge überdauern die Anfrage nicht, die sie erzeugt hat. Der Produktivbetrieb stellt eine persistente Implementierung bereit.
Eine Knoten-ID, die das kanonische Parsen nicht besteht, bricht die Aufzeichnung nicht ab; der betroffene Eintrag fällt auf pageIndex 0 zurück.
AstAwareChunker::__construct() weist entartete Konfigurationen (overlapChars >= maxChunkChars oder maxChunkChars außerhalb von [16, 1048576]) mit einer InvalidArgumentException ab. Dies verhindert unbegrenztes Pufferwachstum während des Chunkings.
AstChunk::$bbox ist null, wenn der erste beitragende Knoten keine Bounding-Box trägt.
Ein Dokument ohne akkumulierbaren Text ergibt eine leere Chunk-Liste.
Dieses Modul führt keine kryptografischen Operationen aus. Hashing, Signierung und Zeitstempelung für Manipulationssicherheit werden von den Modulen Evidence, Security und Signature übernommen; die FIPS-Mode-Richtlinie liegt dort.

Konformität

Verhalten	Referenz
Kontext für inkrementelle Aktualisierung / Signaturintegrität	ISO 32000-2:2020 §12.8

Der Audit-Trail ist eine Aufzeichnungshilfe. Er unterstützt audit-artige Nachweis-Workflows; er ist keine Zertifizierung und keine rechtliche Bescheinigung, und NextPDF hält keine Zertifizierung.

Entwicklungshinweise

Stellen Sie eine dauerhafte AstAuditTrailInterface-Implementierung für die anfrageübergreifende Aufbewahrung bereit. Persistieren Sie sie in einem WORM-fähigen Store, wo Compliance Unveränderlichkeit verlangt; die Append-only-Garantie ist nur so stark wie der zugrunde liegende Store.
Mutations-Snapshots können personenbezogene Daten enthalten; die Datenresidenz richtet sich nach dem Store des Betreibers.
Der Trail konsumiert das Pro-Mutationslog wie erzeugt; er leitet Mutationen nicht erneut aus dem Dokumentzustand ab.
Die Chunker-Standardwerte (maxChunkChars 1500, overlapChars 150) passen zur typischen RAG-Aufnahme; justieren Sie innerhalb der dokumentierten Grenzen für Embedding-Modelle mit abweichenden Kontextbudgets.
Interne Mechanismusdetails verbleiben in der internen Dokumentation des Quell-Repositorys und liegen außerhalb des Umfangs dieses Handbuchs.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.