Jejak audit AST

Sekilas pandang

NextPDF Enterprise merekam setiap mutasi AST sebagai jejak audit per-dokumen yang hanya-tambah, dan menghasilkan potongan AST yang terbatas secara semantik dan berjangkar-sitasi untuk pipeline hilir. Jejak ini mendukung alur kerja audit dan keterlacakan. Jejak ini bukan atestasi hukum atau sertifikasi integritas dokumen.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan amplop lisensi tingkat Enterprise. Penerapan tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Pasang

composer require nextpdf/enterprise:^3

Tinjauan konseptual

AstAuditTrailInterface adalah kontrak perekaman. record($documentSourceHash, $log) mengonversi setiap entri dari MutationLog AST Pro menjadi AstAuditEntry dan menambahkannya; panggilan berulang dengan hash dokumen yang sama mengakumulasi entri. Implementasinya hanya-tambah menurut kontrak: setelah direkam, sebuah entri tidak dapat diubah atau dihapus. findByDocument($hash) mengembalikan entri untuk satu dokumen dalam urutan penyisipan; count() mengembalikan total di seluruh dokumen. InMemoryAstAuditTrail adalah implementasi rujukannya.

AstAuditEntry adalah catatan imutabel dari satu mutasi: hash sumber dokumen, id node kanonik, tipe mutasi (updated / inserted / deleted), indeks halaman berbasis-0, snapshot atribut sebelum/sesudah, dan waktu UTC saat entri direkam. Pengambilan dibatasi per hash dokumen, sehingga riwayat audit tetap terisolasi per dokumen.

AstAwareChunker menelusuri AST secara depth-first dan memancarkan instans AstChunk yang menghormati struktur dokumen: heading memulai potongan baru, teks daun terakumulasi hingga ukuran yang dikonfigurasi, dan jendela tumpang-tindih menjaga kontinuitas melintasi batas pemisahan. Setiap potongan membawa id node, indeks halaman, bounding box, dan tipe node dari node penyumbang pertamanya, sehingga sistem hilir dapat menyitasi lokasi sumber yang presisi.

Apa yang ditegaskan modul ini

Modul ini merekam riwayat mutasi dan menghasilkan potongan terstruktur. Modul ini tidak mensertifikasi integritas atau menyediakan atestasi hukum.

• Jejak audit bersifat hanya-tambah menurut kontrak di dalam penyimpanan yang dikonfigurasi. Bukti-rusak dan nirsangkal adalah properti dari di mana dan bagaimana Anda mempersistensikan dan menstempelnya (lihat Evidence), bukan jaminan yang dibuat modul ini sendiri.
• Merekam sebuah mutasi mendokumentasikan bahwa hal itu terjadi. Itu tidak memvalidasi atau mengotorisasi perubahan tersebut.
• Sitasi potongan menunjuk ke lokasi sumber; itu adalah alat bantu navigasi, bukan klaim kesesuaian.

Sebuah jejak audit mendukung alur kerja audit; jejak ini bukan atestasi hukum atau sertifikasi audit.

Batas tingkat

• AST NextPDF Core / Pro menyediakan model AST dan log mutasi.
• AST NextPDF Enterprise (halaman ini) menambahkan jejak audit per-dokumen yang hanya-tambah di atas mutasi tersebut dan chunker berjangkar-sitasi. Modul ini mengonsumsi log mutasi Pro; modul ini tidak menggantikan model AST.

Mengapa bekerja seperti ini

Keputusan yang menopang adalah pengendalian cakupan. Modul ini merekam bahwa sebuah mutasi terjadi; durabilitas, bukti-rusak, dan nirsangkal didelegasikan ke penyimpanan pendukung dan modul Evidence. Itu menjaga janjinya tetap jujur: alat bantu penyimpanan-catatan untuk auditor, bukan sertifikasi yang tidak dapat dibuktikan modul ini sendirian. Pengambilan dikunci oleh documentSourceHash, sehingga riwayat satu dokumen tidak pernah bocor ke dokumen lain. Chunker menjangkarkan setiap potongan ke node pertamanya dan memvalidasi maxChunkChars dan overlapChars di awal, sehingga sitasi tetap presisi. Persistensi dan residensi tetap berada di tangan operator, sehingga permukaan yang sama melayani penyimpanan evidence berdukungan-WORM maupun pipeline yang lebih ringan.

Latar belakang desain: Kepatuhan yang bisa Anda serahkan ke auditor.

Permukaan API

Class / Interface	Tanggung jawab
AstAuditTrailInterface	Kontrak perekaman hanya-tambah dan pengambilan per-dokumen.
AstAuditEntry	Catatan imutabel dari satu mutasi dengan snapshot sebelum/sesudah.
InMemoryAstAuditTrail	Implementasi jejak hanya-tambah rujukan.
AstAwareChunker	Chunker AST yang menghormati struktur dan berjangkar-sitasi.
AstChunk	Satu potongan dengan id node, indeks halaman, bbox, dan tipe node.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

$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).

Kasus tepi & jebakan

• Merekam MutationLog yang sama dua kali mengakumulasi entri; deduplikasi di hulu jika Anda memerlukan idempotensi.
• Jejak in-memory tidak durabel; penerapan produksi menyediakan AstAuditTrailInterface yang persisten.
• Hanya-tambah adalah kontrak dari penyimpanan, bukan properti kriptografi; pasangkan dengan pemaketan Evidence untuk bukti-rusak.

Kinerja

Perekaman linear terhadap jumlah entri mutasi. Pemotongan adalah satu penelusuran AST depth-first; biayanya berskala dengan jumlah node dan ukuran potongan yang dikonfigurasi.

Catatan keamanan

Snapshot sebelum/sesudah dapat berisi teks dokumen. Perlakukan jejak sebagai sensitif saat tersimpan. Kontrak hanya-tambah mencegah penyuntingan di tempat melalui API ini, tetapi durabilitas dan bukti-rusak bergantung pada penyimpanan pendukungnya.

Residensi data & mitigasi PII

Snapshot mutasi dapat membawa data pribadi yang diekstraksi dari dokumen. Persistensi didelegasikan ke implementasi jejak Anda, sehingga residensi mengikuti penyimpanan Anda. Terapkan kontrol retensi dan minimisasi pada snapshot yang direkam.

Telemetri aman & pembersihan log

Id node, tipe mutasi, indeks halaman, dan stempel waktu aman untuk dicatat. Snapshot sebelum/sesudah dapat berisi konten dokumen; redaksikan sebelum meneruskannya ke sink bersama.

Kesesuaian

Perilaku	Rujukan	Status
Konteks incremental-update / integritas	ISO 32000-2:2020 §12.8	Dirujuk (konteks untuk bukti-rusak)

Tabel ini mencatat konteks spesifikasi tempat modul ini beroperasi. Jejak audit adalah alat bantu penyimpanan-catatan, bukan sertifikasi atau atestasi hukum.

Perilaku mode-FIPS

Modul ini tidak melakukan operasi kriptografi. Hashing, penandatanganan, dan penstempelan-waktu untuk bukti-rusak ditangani oleh modul Evidence, Security, dan Signature.

Model ancaman

Masukannya adalah log mutasi. Mitigasi: kontrak perekaman hanya-tambah, pembatasan per-dokumen untuk mengisolasi riwayat, serta delegasi durabilitas dan bukti-rusak ke penyimpanan berkemampuan-WORM dan modul Evidence.

Kontrak perilaku

• Jejak audit bersifat hanya-tambah menurut kontrak di dalam penyimpanan yang dikonfigurasi: setelah direkam, sebuah entri tidak dapat diubah atau dihapus melalui API ini.
• Setiap entri adalah catatan imutabel dari satu mutasi (hash sumber dokumen, id node kanonik, tipe mutasi, indeks halaman, snapshot sebelum/sesudah, waktu UTC yang direkam); pengambilan dibatasi per hash dokumen.
• Merekam log mutasi yang sama dua kali mengakumulasi entri — deduplikasi di hulu jika idempotensi diperlukan.
• Chunker menelusuri AST secara depth-first dan memancarkan potongan yang menghormati struktur yang membawa id node, indeks halaman, bounding box, dan tipe node untuk sitasi sumber yang presisi.
• Merekam sebuah mutasi mendokumentasikan bahwa hal itu terjadi; itu tidak memvalidasi atau mengotorisasi perubahan tersebut, dan sitasi potongan adalah alat bantu navigasi, bukan klaim kesesuaian.

Batas publikasi

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

Fallback Core

AST NextPDF Core / Pro menyediakan model AST dan log mutasi. Jejak audit per-dokumen yang hanya-tambah dan chunker berjangkar-sitasi tidak memiliki padanan tingkat-Core; permukaan Enterprise mengonsumsi log mutasi, ia tidak menggantikan model AST.

Fallback Pro

AST NextPDF Pro menyediakan model AST dan log mutasi tetapi tidak ada jejak audit per-dokumen yang hanya-tambah dan tidak ada chunker berjangkar-sitasi. Itu disertakan hanya dalam paket nextpdf/enterprise; permukaan Enterprise mengonsumsi log mutasi Pro.

Catatan batas Enterprise

Kontrak perekaman, pengambilan per-dokumen, dan chunker dijelaskan pada tingkat perilaku. Jejak in-memory rujukan didokumentasikan; persistensi durabel disediakan oleh host, dan setiap internal penyimpanan internal berada di luar cakupan permukaan publik.

Batas penerapan

Hanya-tambah adalah kontrak dari penyimpanan, bukan properti kriptografi. Operator menyediakan implementasi jejak durabel dan bertanggung jawab mempersistensikannya dalam penyimpanan berdukungan-WORM untuk bukti-rusak; durabilitas dan nirsangkal bergantung pada penyimpanan tersebut dan pada modul Evidence, bukan pada modul ini saja. Snapshot mutasi dapat membawa data pribadi; residensi mengikuti penyimpanan operator.

Batas kepatuhan hukum

Tidak ada pembatasan kontrol-ekspor yang berlaku pada permukaan jejak-audit AST. Sebuah jejak audit mendukung alur kerja audit; jejak ini bukan atestasi hukum atau sertifikasi audit. Dokumentasi ini bukan opini hukum; konsultasikan dengan penasihat kepatuhan dan hukum Anda sendiri.

Lihat juga

• Evidence — menyegel dan menstempel-waktu jejak.
• Validation — pemeriksaan kebijakan struktural.
• Core AST — model AST.
• Jejak audit AST — Deep Reference — internal penyimpanan durabel dan permukaan API publik lengkap.