Enterprise 에디션

AST 감사 추적 — 심층 참조

한눈에 보기

Enterprise AST 모듈은 문서 뮤테이션을 기록하고 문서를 검색 파이프라인에 맞게 준비합니다.

AstAuditTrailInterface는 Pro AST MutationLog 위에 문서별 추가 전용 감사 추적을 정의합니다.
AstAuditEntry는 하나의 뮤테이션에 대한 불변 레코드입니다. 노드 식별자, 뮤테이션 종류, 페이지, 전후 스냅샷, UTC 타임스탬프를 담습니다.
InMemoryAstAuditTrail은 추적 계약의 프로세스별 참조 구현입니다.
AstAwareChunker는 AST를 깊이 우선으로 순회하며 RAG 수집을 위한 인용 고정 AstChunk 값을 산출합니다.

제공 및 라이선스

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에 포함되며 Enterprise 등급 라이선스 봉투로 활성화됩니다. 해당 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션을 비교하고 라이선스 받기.

AST 감사 추적 표면은 enterprise.compliance.evidence 기능으로 라이선스가 부여됩니다. 거부된 권한은 기능을 거부합니다.

등급	제공
Core	AST 문서 모델(`AstDocument`, `AstNode`, `NodeId`)
Pro	AST 뮤테이션 흐름과 `MutationLog`
Enterprise	문서별 추가 전용 감사 추적; 인용 고정 청커

Enterprise 표면은 Pro 뮤테이션 로그를 소비합니다. AST 모델을 대체하지 않습니다.

composer require nextpdf/enterprise:^3

공개 API 표면

심볼	매개변수	기본 동작	반환	예외 또는 실패 조건	참고
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	로그의 각 뮤테이션 항목을 `AstAuditEntry`로 변환하여 추가	`void`	참조 구현에서는 없음	동일한 해시로 반복 호출하면 항목이 누적됨
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	한 문서에 대해 기록된 항목을 삽입 순서로 반환	`list<AstAuditEntry>`	참조 구현에서는 없음	해시와 일치하는 항목이 없으면 빈 목록
`AstAuditTrailInterface::count()`	없음	감사 항목 수를 셈	`int<0, max>`	참조 구현에서는 없음	문서별이 아니라 모든 문서에 걸친 총계
`InMemoryAstAuditTrail`	없음	현재 프로세스로 범위가 한정된 배열 기반 추적	`AstAuditTrailInterface` 구현	없음	지속적이지 않음; 단일 요청 수명 주기에 적합
`AstAuditEntry`	생성자가 모든 필드를 프로모션	불변 감사 레코드	값 객체	없음	`final readonly`; 아래 시그니처 펜스 참조
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	생성 시 청킹 범위를 검증	인스턴스	범위를 벗어난 구성에서 `InvalidArgumentException`	범위: `16 <= maxChunkChars <= 1048576`; `0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	깊이 우선 순회; 제목이 청크를 구분; 리프 텍스트가 누적됨	`list<AstChunk>`	없음	누적 가능한 텍스트가 없는 문서는 빈 목록
`AstChunk`	생성자가 모든 필드를 프로모션	인용 고정 청크 레코드	값 객체	없음	`final readonly`; 아래 시그니처 펜스 참조

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

동작 계약

감사 추적

추가 전용. 구현은 추가 전용이어야 합니다. 기록된 항목은 이 API를 통해 수정하거나 제거할 수 없습니다. 동일한 해시로 record()를 반복 호출하면 항목이 누적됩니다.
변환. record()는 Pro MutationLog의 각 항목을(MutationLog::all()을 통해) AstAuditEntry로 변환하여 추가합니다. 한 번의 record() 호출이 산출한 모든 항목은 하나의 UTC occurredAt 타임스탬프를 공유합니다.
문서별 격리. findByDocument()는 정확한 문서 소스 해시로 필터링하고 삽입 순서를 보존합니다. count()는 모든 문서에 걸친 총계입니다.
스냅샷. before와 after는 text_content를 키로 하는 속성 맵입니다. updated 뮤테이션은 양쪽을 모두 채우고, inserted는 before를 비워 두며, deleted는 after를 비워 둡니다. mutationType은 Pro MutationType 열거형의 문자열 값입니다: updated, inserted, deleted.
페이지 도출. pageIndex는 정규 노드 ID(ast:{hash}:{page}:{seq})에서 추출됩니다. 형식이 잘못된 노드 ID는 pageIndex 0을 산출하지만, 항목은 그래도 기록됩니다.

추가 전용은 암호화 속성이 아니라 구성된 저장소의 계약입니다. 변조 증거성과 부인 방지는 이 모듈 단독이 아니라, 추적이 어떻게 영속화되고 타임스탬프되는지(Evidence 모듈)에서 비롯됩니다.

청커

순회. chunk()는 문서 루트에서부터 AST를 깊이 우선으로 순회합니다.
텍스트 누적. Paragraph, ListItem, TableCell, Code, Annotation 유형의 리프 텍스트가 현재 버퍼에 누적됩니다. 컨테이너 유형(Document, Section, Artifact, FormField, Figure, Table, List, TableRow)은 텍스트를 산출하지 않고 순회됩니다.
구분자. Heading 노드는 현재 버퍼를 청크로 비우고 다음 버퍼를 제목 텍스트로 시작합니다.
분할. 누적된 텍스트가 maxChunkChars를 초과하려 하면, 청커는 남은 공간을 채우고 청크를 비운 다음, 마지막 overlapChars개의 문자에 오버플로를 더해 계속합니다. 길이 계산은 UTF-8 문자 기반입니다.
인용 앵커. 각 AstChunk는 첫 기여 노드의 nodeId, pageIndex, bbox, nodeType과 함께 문서 소스 해시 및 0부터 시작하는 순차 chunkIndex를 담습니다.
마무리. 공백이 아닌 내용을 담은 후행 버퍼는 마지막 청크로 비워집니다. 공백만 남은 잔여는 폐기되고, 청크 텍스트는 트리밍됩니다.

엣지 케이스 및 실패 모드

동일한 MutationLog를 두 번 기록하면 중복 항목이 누적됩니다. 멱등성은 상류에서 강제되어야 합니다.
새로 만든 공유되지 않은 InMemoryAstAuditTrail은 항상 비어 있습니다. 통합 계약은 뮤테이션을 생성하는 흐름과 감사를 읽는 소비자 양쪽에 하나의 공유 AstAuditTrailInterface 인스턴스를 전달하고, 각 성공적 쓰기 후에 record()를 호출하도록 요구합니다. 그 전까지 findByDocument()는 빈 목록을, count()는 0을 반환합니다.
인메모리 추적은 프로세스별이며 지속적이지 않습니다. 항목은 그것을 생성한 요청을 넘어 살아남지 못합니다. 프로덕션은 영속적 구현을 제공합니다.
정규 파싱에 실패하는 노드 ID는 기록을 중단시키지 않습니다. 해당 항목은 pageIndex 0으로 폴백합니다.
AstAwareChunker::__construct()는 퇴화된 구성(overlapChars >= maxChunkChars 또는 [16, 1048576] 범위를 벗어난 maxChunkChars)을 InvalidArgumentException으로 거부합니다. 이는 청킹 중 무한한 버퍼 증가를 방지합니다.
첫 기여 노드에 경계 상자가 없으면 AstChunk::$bbox는 null입니다.
누적 가능한 텍스트가 없는 문서는 빈 청크 목록을 산출합니다.
이 모듈은 어떤 암호화 작업도 수행하지 않습니다. 변조 증거성을 위한 해싱, 서명, 타임스탬핑은 Evidence, Security, Signature 모듈이 처리합니다. FIPS 모드 정책은 그곳에 있습니다.

적합성

Behavior	Reference
증분 업데이트 / 서명 무결성 컨텍스트	ISO 32000-2:2020 §12.8

감사 추적은 기록 관리 보조 수단입니다. 감사 형식의 증거 워크플로를 지원하지만, 인증이나 법적 증명이 아니며 NextPDF는 어떤 인증도 보유하지 않습니다.

개발 참고

요청 간 유지를 위해 지속적 AstAuditTrailInterface 구현을 제공하세요. 규정 준수가 불변성을 요구하는 경우 WORM 지원 저장소에 영속화하세요. 추가 전용 보장은 기반 저장소만큼만 강력합니다.
뮤테이션 스냅샷은 개인 데이터를 담을 수 있습니다. 데이터 레지던시는 운영자의 저장소를 따릅니다.
추적은 Pro 뮤테이션 로그를 산출된 대로 소비합니다. 문서 상태에서 뮤테이션을 재도출하지 않습니다.
청커 기본값(maxChunkChars 1500, overlapChars 150)은 일반적인 RAG 수집에 적합합니다. 컨텍스트 예산이 다른 임베딩 모델의 경우 문서화된 범위 내에서 조정하세요.
내부 메커니즘 세부 사항은 소스 저장소의 내부 문서에 남으며 이 매뉴얼의 범위 밖입니다.

배포 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위 밖입니다.