Enterprise edisi

Jejak audit AST — Referensi Mendalam

Sekilas

Modul AST Enterprise mencatat mutasi dokumen dan menyiapkan dokumen untuk pipeline retrieval.

AstAuditTrailInterface mendefinisikan jejak audit per-dokumen yang append-only di atas MutationLog AST Pro.
AstAuditEntry adalah rekaman immutable dari satu mutasi: identitas node, jenis mutasi, halaman, snapshot before/after, timestamp UTC.
InMemoryAstAuditTrail adalah implementasi referensi per-proses dari kontrak jejak tersebut.
AstAwareChunker menelusuri AST secara depth-first dan menghasilkan nilai AstChunk berbasis anchor sitasi untuk ingesti RAG.

Ketersediaan & lisensi

Kemampuan ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan envelope lisensi tier Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kemampuan ini. Bandingkan edisi dan dapatkan lisensi.

Permukaan jejak audit AST dilisensikan oleh kapabilitas enterprise.compliance.evidence. Entitlement yang ditolak menolak fitur ini.

Tier	Menyediakan
Core	Model dokumen AST (`AstDocument`, `AstNode`, `NodeId`)
Pro	Alur mutasi AST dan `MutationLog`
Enterprise	Jejak audit per-dokumen yang append-only; chunker berbasis anchor sitasi

Permukaan Enterprise mengonsumsi log mutasi Pro. Ia tidak menggantikan model AST.

composer require nextpdf/enterprise:^3

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	Mengonversi setiap entri mutasi dalam log menjadi `AstAuditEntry` dan menambahkannya	`void`	Tidak ada pada implementasi referensi	Panggilan berulang dengan hash yang sama mengakumulasi entri
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	Mengembalikan entri yang tercatat untuk satu dokumen, dalam urutan penyisipan	`list<AstAuditEntry>`	Tidak ada pada implementasi referensi	List kosong bila tidak ada entri yang cocok dengan hash
`AstAuditTrailInterface::count()`	tidak ada	Menghitung entri audit	`int<0, max>`	Tidak ada pada implementasi referensi	Total lintas semua dokumen, bukan per-dokumen
`InMemoryAstAuditTrail`	tidak ada	Jejak berbasis array yang dibatasi pada proses saat ini	mengimplementasikan `AstAuditTrailInterface`	Tidak ada	Tidak durable; cocok untuk siklus hidup single-request
`AstAuditEntry`	konstruktor mempromosikan semua field	Rekaman audit immutable	value object	Tidak ada	`final readonly`; lihat fence signature di bawah
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	Memvalidasi batas chunking saat konstruksi	instance	`InvalidArgumentException` pada konfigurasi di luar rentang	Batas: `16 <= maxChunkChars <= 1048576`; `0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	Penelusuran depth-first; heading membatasi chunk; teks leaf diakumulasi	`list<AstChunk>`	Tidak ada	List kosong untuk dokumen tanpa teks yang dapat diakumulasi
`AstChunk`	konstruktor mempromosikan semua field	Rekaman chunk berbasis anchor sitasi	value object	Tidak ada	`final readonly`; lihat fence signature di bawah

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

Kontrak perilaku

Jejak audit

Append-only. Implementasi harus append-only: entri yang tercatat tidak dapat dimodifikasi atau dihapus melalui API ini. Panggilan record() berulang dengan hash yang sama mengakumulasi entri.
Konversi. record() mengonversi setiap entri dari MutationLog Pro (via MutationLog::all()) menjadi AstAuditEntry dan menambahkannya. Semua entri yang dihasilkan oleh satu panggilan record() berbagi satu timestamp UTC occurredAt.
Isolasi per-dokumen. findByDocument() memfilter berdasarkan hash sumber dokumen yang tepat dan mempertahankan urutan penyisipan. count() adalah total lintas semua dokumen.
Snapshot. before dan after adalah peta atribut yang diindeks oleh text_content. Mutasi updated mengisi kedua sisi; inserted membiarkan before kosong; deleted membiarkan after kosong. mutationType adalah nilai string dari enum MutationType Pro: updated, inserted, atau deleted.
Derivasi halaman. pageIndex diekstrak dari ID node kanonis (ast:{hash}:{page}:{seq}). ID node yang malformed menghasilkan pageIndex 0; entri tetap dicatat.

Append-only adalah kontrak dari store yang dikonfigurasi, bukan properti kriptografis. Tamper-evidence dan non-repudiation berasal dari bagaimana jejak dipersistensikan dan diberi timestamp (modul Evidence), bukan dari modul ini sendiri.

Chunker

Traversal. chunk() menelusuri AST secara depth-first dari root dokumen.
Akumulasi teks. Teks leaf bertipe Paragraph, ListItem, TableCell, Code, atau Annotation diakumulasi ke buffer saat ini. Tipe kontainer (Document, Section, Artifact, FormField, Figure, Table, List, TableRow) ditelusuri tanpa menghasilkan teks.
Delimiter. Node Heading mem-flush buffer saat ini sebagai chunk dan menyemai buffer berikutnya dengan teks heading.
Splitting. Ketika teks yang terakumulasi akan melampaui maxChunkChars, chunker mengisi ruang yang tersisa, mem-flush chunk, dan melanjutkan dengan overlapChars karakter terakhir ditambah overflow. Perhitungan panjang berbasis karakter UTF-8.
Anchor sitasi. Setiap AstChunk membawa nodeId, pageIndex, bbox, dan nodeType dari node kontributor pertamanya, ditambah hash sumber dokumen dan chunkIndex sekuensial berbasis-0.
Finalisasi. Buffer akhir dengan konten non-whitespace di-flush sebagai chunk terakhir; sisa yang hanya whitespace dibuang, dan teks chunk di-trim.

Kasus tepi & mode kegagalan

Mencatat MutationLog yang sama dua kali mengakumulasi entri duplikat; idempotensi harus ditegakkan di hulu.
InMemoryAstAuditTrail yang baru dan tidak dibagikan selalu kosong. Kontrak integrasi mengharuskan satu instance AstAuditTrailInterface yang dibagikan diserahkan ke alur penghasil-mutasi dan konsumen pembaca-audit, dengan record() dipanggil setelah setiap penulisan yang berhasil. Hingga saat itu, findByDocument() mengembalikan list kosong dan count() mengembalikan 0.
Jejak in-memory bersifat per-proses dan tidak durable; entri tidak bertahan melewati request yang membuatnya. Produksi menyediakan implementasi yang persisten.
ID node yang gagal parsing kanonis tidak membatalkan pencatatan; entri yang terpengaruh jatuh kembali ke pageIndex 0.
AstAwareChunker::__construct() menolak konfigurasi degeneratif (overlapChars >= maxChunkChars, atau maxChunkChars di luar [16, 1048576]) dengan InvalidArgumentException. Ini mencegah pertumbuhan buffer yang tak terbatas selama chunking.
AstChunk::$bbox bernilai null ketika node kontributor pertama tidak membawa bounding box.
Dokumen tanpa teks yang dapat diakumulasi menghasilkan list chunk kosong.
Modul ini tidak melakukan operasi kriptografis. Hashing, signing, dan timestamping untuk tamper-evidence ditangani oleh modul Evidence, Security, dan Signature; kebijakan mode FIPS berada di sana.

Konformansi

Perilaku	Referensi
Konteks incremental-update / integritas-signature	ISO 32000-2:2020 §12.8

Jejak audit adalah alat bantu pencatatan. Ia mendukung alur kerja bukti bergaya audit; ia bukan sertifikasi dan bukan atestasi hukum, dan NextPDF tidak memegang sertifikasi apa pun.

Catatan pengembangan

Sediakan implementasi AstAuditTrailInterface yang durable untuk retensi lintas-request. Persistensikan dalam store berkemampuan WORM ketika compliance memerlukan immutabilitas; jaminan append-only hanya sekuat store pendukungnya.
Snapshot mutasi dapat membawa data pribadi; residensi data mengikuti store operator.
Jejak mengonsumsi log mutasi Pro sebagaimana dihasilkan; ia tidak menurunkan ulang mutasi dari state dokumen.
Default chunker (maxChunkChars 1500, overlapChars 150) cocok untuk ingesti RAG tipikal; sesuaikan dalam batas yang terdokumentasi untuk model embedding dengan budget konteks yang berbeda.
Detail mekanisme internal tetap berada di dokumentasi internal repositori sumber dan berada di luar cakupan manual ini.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.