AST audit trail — เอกสารอ้างอิงเชิงลึก

ภาพรวมโดยย่อ

โมดูล Enterprise AST บันทึกการกลายพันธุ์ของเอกสารและเตรียมเอกสารสำหรับไปป์ไลน์การดึงข้อมูล

• AstAuditTrailInterface กำหนด audit trail แบบ append-only ต่อเอกสารเหนือ MutationLog ของ Pro AST
• AstAuditEntry เป็นระเบียนที่ไม่เปลี่ยนแปลงได้ของการกลายพันธุ์หนึ่งรายการ ได้แก่ อัตลักษณ์ของโหนด ชนิดการกลายพันธุ์ หน้า สแนปช็อตก่อน/หลัง และการประทับเวลา UTC
• InMemoryAstAuditTrail เป็นการนำไปใช้อ้างอิงต่อโปรเซสของสัญญา trail
• AstAwareChunker เดิน AST แบบ depth-first และปล่อยค่า AstChunk ที่ยึดด้วยการอ้างอิงสำหรับการนำเข้า RAG

ความพร้อมใช้งานและการให้สิทธิ์การใช้งาน

ความสามารถนี้จัดส่งใน NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วย license envelope ระดับ Enterprise การปรับใช้ที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับสิทธิ์การใช้งาน

พื้นผิว AST audit-trail ได้รับสิทธิ์การใช้งานโดยความสามารถ enterprise.compliance.evidence สิทธิ์ที่ถูกปฏิเสธจะปฏิเสธฟีเจอร์

ระดับ	จัดหา
Core	โมเดลเอกสาร AST (AstDocument, AstNode, NodeId)
Pro	โฟลว์การกลายพันธุ์ AST และ MutationLog
Enterprise	audit trail แบบ append-only ต่อเอกสาร; chunker ที่ยึดด้วยการอ้างอิง

พื้นผิว Enterprise ใช้ mutation log ของ Pro มันไม่ได้แทนที่โมเดล AST

composer require nextpdf/enterprise:^3

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
AstAuditTrailInterface::record()	string $documentSourceHash, MutationLog $log	แปลงแต่ละรายการการกลายพันธุ์ใน log ให้เป็น AstAuditEntry และต่อท้ายมัน	void	ไม่มีในการนำไปใช้อ้างอิง	การเรียกซ้ำด้วยแฮชเดียวกันจะสะสมรายการ
AstAuditTrailInterface::findByDocument()	string $documentSourceHash	คืนรายการที่บันทึกไว้สำหรับเอกสารหนึ่งตามลำดับการแทรก	list<AstAuditEntry>	ไม่มีในการนำไปใช้อ้างอิง	รายการว่างเมื่อไม่มีรายการใดตรงกับแฮช
AstAuditTrailInterface::count()	ไม่มี	นับรายการ audit	int<0, max>	ไม่มีในการนำไปใช้อ้างอิง	ยอดรวมข้ามทุกเอกสาร ไม่ใช่ต่อเอกสาร
InMemoryAstAuditTrail	ไม่มี	trail ที่ใช้อาร์เรย์หนุนหลัง จำกัดขอบเขตอยู่ที่โปรเซสปัจจุบัน	นำ AstAuditTrailInterface ไปใช้	ไม่มี	ไม่คงทน; เหมาะกับวงจรชีวิตแบบคำขอเดียว
AstAuditEntry	constructor เลื่อนขั้นทุกฟิลด์	ระเบียน audit ที่ไม่เปลี่ยนแปลงได้	value object	ไม่มี	final readonly; ดู signature fence ด้านล่าง
AstAwareChunker::__construct()	int $maxChunkChars = 1500, int $overlapChars = 150	ตรวจสอบขอบเขตการทำ chunking ณ ตอนสร้าง	instance	InvalidArgumentException เมื่อการกำหนดค่าอยู่นอกช่วง	ขอบเขต: 16 <= maxChunkChars <= 1048576; 0 <= overlapChars < maxChunkChars
AstAwareChunker::chunk()	AstDocument $document	เดินแบบ depth-first; หัวข้อคั่น chunk; ข้อความ leaf สะสม	list<AstChunk>	ไม่มี	รายการว่างสำหรับเอกสารที่ไม่มีข้อความที่สะสมได้
AstChunk	constructor เลื่อนขั้นทุกฟิลด์	ระเบียน chunk ที่ยึดด้วยการอ้างอิง	value object	ไม่มี	final readonly; ดู signature fence ด้านล่าง

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

สัญญาด้านพฤติกรรม

ร่องรอยการตรวจสอบ

• Append-only การนำไปใช้ต้องเป็นแบบ append-only: รายการที่บันทึกแล้วไม่สามารถแก้ไขหรือลบผ่าน API นี้ได้ การเรียก record() ซ้ำด้วยแฮชเดียวกันจะสะสมรายการ
• การแปลง record() แปลงแต่ละรายการของ MutationLog ของ Pro (ผ่าน MutationLog::all()) ให้เป็น AstAuditEntry และต่อท้ายมัน ทุกรายการที่ถูกสร้างจากการเรียก record() หนึ่งครั้งใช้การประทับเวลา occurredAt แบบ UTC ร่วมกันหนึ่งค่า
• การแยกต่อเอกสาร findByDocument() กรองบนแฮชแหล่งที่มาของเอกสารที่ตรงกันพอดีและรักษาลำดับการแทรก count() คือยอดรวมข้ามทุกเอกสาร
• สแนปช็อต before และ after เป็นแมปแอตทริบิวต์ที่ใช้คีย์ text_content การกลายพันธุ์ updated เติมทั้งสองด้าน; inserted ทิ้งให้ before ว่างเปล่า; deleted ทิ้งให้ after ว่างเปล่า mutationType เป็นค่าสตริงของ enum MutationType ของ Pro ได้แก่ updated, inserted หรือ deleted
• การอนุมานหน้า pageIndex ถูกดึงจาก node ID แบบ canonical (ast:{hash}:{page}:{seq}) node ID ที่ผิดรูปแบบให้ผลลัพธ์ pageIndex เป็น 0; รายการยังคงถูกบันทึก

Append-only เป็นสัญญาของ store ที่กำหนดค่าไว้ ไม่ใช่คุณสมบัติเชิงการเข้ารหัส หลักฐานการแก้ไขดัดแปลงและการห้ามปฏิเสธความรับผิดมาจากวิธีที่ trail ถูกเก็บรักษาและประทับเวลา (โมดูล Evidence) ไม่ใช่จากโมดูลนี้เพียงลำพัง

Chunker

• การเดินผ่าน chunk() เดิน AST แบบ depth-first จากรากของเอกสาร
• การสะสมข้อความ ข้อความ leaf ชนิด Paragraph, ListItem, TableCell, Code หรือ Annotation สะสมเข้าสู่ buffer ปัจจุบัน ชนิดคอนเทนเนอร์ (Document, Section, Artifact, FormField, Figure, Table, List, TableRow) ถูกเดินผ่านโดยไม่ปล่อยข้อความ
• ตัวคั่น โหนด Heading ล้าง buffer ปัจจุบันออกเป็น chunk และหว่านเมล็ด buffer ถัดไปด้วยข้อความหัวข้อ
• การแยก เมื่อข้อความที่สะสมจะเกิน maxChunkChars chunker จะเติมพื้นที่ที่เหลือ ล้าง chunk ออก และดำเนินต่อด้วยอักขระ overlapChars ตัวสุดท้ายบวกส่วนที่ล้น การนับความยาวอิงตามอักขระ UTF-8
• จุดยึดการอ้างอิง AstChunk แต่ละรายการพกพา nodeId, pageIndex, bbox และ nodeType ของโหนดแรกที่มีส่วนร่วม บวกกับแฮชแหล่งที่มาของเอกสารและ chunkIndex แบบลำดับเริ่มที่ 0
• การสรุปปิดท้าย buffer ท้ายสุดที่มีเนื้อหาไม่ใช่ช่องว่างจะถูกล้างออกเป็น chunk สุดท้าย; ส่วนที่เหลือซึ่งเป็นช่องว่างล้วนจะถูกทิ้ง และข้อความ chunk จะถูกตัดขอบ

กรณีขอบและโหมดความล้มเหลว

• การบันทึก MutationLog เดียวกันสองครั้งจะสะสมรายการซ้ำ; ต้องบังคับใช้ idempotency ที่ต้นน้ำ
• InMemoryAstAuditTrail ที่สร้างใหม่และไม่ได้แชร์จะว่างเปล่าเสมอ สัญญาการรวมระบบต้องการอินสแตนซ์ AstAuditTrailInterface ที่แชร์ร่วมกันหนึ่งตัวซึ่งส่งมอบให้ทั้งโฟลว์ที่ผลิตการกลายพันธุ์และผู้บริโภคที่อ่าน audit โดยเรียก record() หลังการเขียนสำเร็จแต่ละครั้ง จนกว่าจะถึงตอนนั้น findByDocument() จะคืนรายการว่างและ count() จะคืน 0
• trail ในหน่วยความจำเป็นแบบต่อโปรเซสและไม่คงทน; รายการไม่คงอยู่พ้นคำขอที่สร้างมันขึ้นมา การใช้งานจริงจัดหาการนำไปใช้แบบ persistent
• node ID ที่แจงวิเคราะห์แบบ canonical ล้มเหลวจะไม่ยกเลิกการบันทึก; รายการที่ได้รับผลกระทบจะถอยกลับไปใช้ pageIndex 0
• AstAwareChunker::__construct() ปฏิเสธการกำหนดค่าที่เสื่อมสภาพ (overlapChars >= maxChunkChars หรือ maxChunkChars อยู่นอก [16, 1048576]) ด้วย InvalidArgumentException สิ่งนี้ป้องกันการเติบโตของ buffer แบบไร้ขอบเขตระหว่างการทำ chunking
• AstChunk::$bbox เป็น null เมื่อโหนดแรกที่มีส่วนร่วมไม่มี bounding box
• เอกสารที่ไม่มีข้อความที่สะสมได้ให้ผลลัพธ์เป็นรายการ chunk ว่าง
• โมดูลนี้ไม่ได้ทำการดำเนินการทางการเข้ารหัสใดๆ การแฮช การลงนาม และการประทับเวลาเพื่อหลักฐานการแก้ไขดัดแปลงถูกจัดการโดยโมดูล Evidence, Security และ Signature; นโยบายโหมด FIPS อยู่ที่นั่น

ความสอดคล้อง

พฤติกรรม	เอกสารอ้างอิง
บริบท Incremental-update / signature-integrity	ISO 32000-2:2020 §12.8

audit trail เป็นตัวช่วยในการเก็บบันทึก มันสนับสนุนเวิร์กโฟลว์หลักฐานแบบ audit; มันไม่ใช่การรับรองและไม่ใช่การรับรองทางกฎหมาย และ NextPDF ไม่ได้ถือการรับรองใดๆ

บันทึกการพัฒนา

• จัดหาการนำ AstAuditTrailInterface แบบคงทนไปใช้เพื่อการเก็บรักษาข้ามคำขอ เก็บรักษามันไว้ใน store ที่รองรับ WORM ในกรณีที่การปฏิบัติตามข้อกำหนดต้องการความไม่เปลี่ยนแปลง; การรับประกัน append-only แข็งแรงได้เพียงเท่าที่ store ที่หนุนหลังแข็งแรง
• สแนปช็อตการกลายพันธุ์อาจพกพาข้อมูลส่วนบุคคล; data residency เป็นไปตาม store ของผู้ดำเนินการ
• trail ใช้ mutation log ของ Pro ตามที่ถูกผลิต; มันไม่ได้อนุมานการกลายพันธุ์ใหม่จากสถานะเอกสาร
• ค่าเริ่มต้นของ chunker (maxChunkChars 1500, overlapChars 150) เหมาะกับการนำเข้า RAG ทั่วไป; ปรับภายในขอบเขตที่ระบุไว้สำหรับโมเดล embedding ที่มีงบประมาณบริบทต่างกัน
• รายละเอียดกลไกภายในคงอยู่ในเอกสารภายในของ repository ต้นทางและอยู่นอกขอบเขตของคู่มือนี้

ขอบเขตการเผยแพร่

หน้านี้จัดทำเอกสารเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ดูเพิ่มเติม

• AST audit trail — หน้าความสามารถ
• Evidence — เอกสารอ้างอิงเชิงลึก
• Validation — เอกสารอ้างอิงเชิงลึก
• Core AST