Enterprise edição

Trilha de auditoria de AST — Referência Profunda

Visão geral

O módulo AST do Enterprise registra as mutações de documentos e prepara documentos para pipelines de recuperação.

AstAuditTrailInterface define uma trilha de auditoria somente-acréscimo, por documento, sobre o MutationLog da AST do Pro.
AstAuditEntry é um registro imutável de uma mutação: identidade do nó, tipo de mutação, página, instantâneos antes/depois e carimbo de tempo em UTC.
InMemoryAstAuditTrail é a implementação de referência por processo do contrato da trilha.
AstAwareChunker percorre a AST em profundidade (depth-first) e emite valores AstChunk ancorados em citações para ingestão em RAG.

Disponibilidade e licenciamento

Este recurso é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença de nível Enterprise. Uma implantação sem esse direito de uso não carrega as classes do recurso. Compare as edições e obtenha uma licença.

A superfície de trilha de auditoria de AST é licenciada pela capacidade enterprise.compliance.evidence. Um direito de uso recusado recusa o recurso.

Nível	Fornece
Core	Modelo de documento AST (`AstDocument`, `AstNode`, `NodeId`)
Pro	Fluxo de mutação de AST e `MutationLog`
Enterprise	Trilha de auditoria somente-acréscimo por documento; chunker ancorado em citações

A superfície do Enterprise consome o log de mutações do Pro. Ela não substitui o modelo de AST.

composer require nextpdf/enterprise:^3

Superfície pública de API

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	Converte cada entrada de mutação do log em um `AstAuditEntry` e o acrescenta	`void`	Nada na implementação de referência	Chamadas repetidas com o mesmo hash acumulam entradas
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	Retorna as entradas registradas para um documento, na ordem de inserção	`list<AstAuditEntry>`	Nada na implementação de referência	Lista vazia quando nenhuma entrada corresponde ao hash
`AstAuditTrailInterface::count()`	nenhum	Conta as entradas de auditoria	`int<0, max>`	Nada na implementação de referência	Total entre todos os documentos, não por documento
`InMemoryAstAuditTrail`	nenhum	Trilha baseada em array com escopo no processo atual	implementa `AstAuditTrailInterface`	Nada	Não durável; adequada a ciclos de vida de requisição única
`AstAuditEntry`	o construtor promove todos os campos	Registro de auditoria imutável	value object	Nada	`final readonly`; veja o bloco de assinatura abaixo
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	Valida os limites de chunking na construção	instância	`InvalidArgumentException` em configuração fora do intervalo	Limites: `16 <= maxChunkChars <= 1048576`; `0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	Percurso em profundidade; cabeçalhos delimitam chunks; o texto de folha acumula	`list<AstChunk>`	Nada	Lista vazia para um documento sem texto acumulável
`AstChunk`	o construtor promove todos os campos	Registro de chunk ancorado em citação	value object	Nada	`final readonly`; veja o bloco de assinatura abaixo

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

Contrato de comportamento

Trilha de auditoria

Somente-acréscimo. As implementações devem ser somente-acréscimo: uma entrada registrada não pode ser modificada nem removida por meio desta API. Chamadas record() repetidas com o mesmo hash acumulam entradas.
Conversão. record() converte cada entrada do MutationLog do Pro (via MutationLog::all()) em um AstAuditEntry e o acrescenta. Todas as entradas produzidas por uma chamada record() compartilham um único carimbo de tempo occurredAt em UTC.
Isolamento por documento. findByDocument() filtra pelo hash de origem exato do documento e preserva a ordem de inserção. count() é o total entre todos os documentos.
Instantâneos. before e after são mapas de atributos indexados por text_content. Uma mutação updated preenche ambos os lados; inserted deixa before vazio; deleted deixa after vazio. mutationType é o valor de string do enum MutationType do Pro: updated, inserted ou deleted.
Derivação da página. pageIndex é extraído do ID canônico do nó (ast:{hash}:{page}:{seq}). Um ID de nó malformado resulta em pageIndex 0; a entrada ainda é registrada.

Somente-acréscimo é um contrato do repositório configurado, não uma propriedade criptográfica. A evidência de adulteração e o não repúdio vêm de como a trilha é persistida e carimbada no tempo (módulo Evidence), não apenas deste módulo.

Chunker

Percurso. chunk() percorre a AST em profundidade (depth-first) a partir da raiz do documento.
Acumulação de texto. O texto de folha do tipo Paragraph, ListItem, TableCell, Code ou Annotation acumula no buffer atual. Os tipos de contêiner (Document, Section, Artifact, FormField, Figure, Table, List, TableRow) são percorridos sem emitir texto.
Delimitadores. Um nó Heading descarrega o buffer atual como um chunk e semeia o próximo buffer com o texto do cabeçalho.
Divisão. Quando o texto acumulado excederia maxChunkChars, o chunker preenche o espaço restante, descarrega o chunk e continua com os últimos overlapChars caracteres mais o excedente. A contagem de tamanho é baseada em caracteres UTF-8.
Âncora de citação. Cada AstChunk carrega o nodeId, o pageIndex, a bbox e o nodeType do seu primeiro nó contribuinte, além do hash de origem do documento e um chunkIndex sequencial de base 0.
Finalização. Um buffer final com conteúdo não vazio é descarregado como o chunk final; restos compostos apenas de espaço em branco são descartados, e o texto do chunk é aparado.

Casos extremos e modos de falha

Registrar o mesmo MutationLog duas vezes acumula entradas duplicadas; a idempotência deve ser imposta a montante.
Uma InMemoryAstAuditTrail nova e não compartilhada está sempre vazia. O contrato de integração requer uma única instância AstAuditTrailInterface compartilhada, entregue tanto ao fluxo produtor de mutações quanto ao consumidor leitor de auditoria, com record() chamado após cada gravação bem-sucedida. Até então, findByDocument() retorna uma lista vazia e count() retorna 0.
A trilha em memória é por processo e não é durável; as entradas não sobrevivem à requisição que as criou. A produção fornece uma implementação persistente.
Um ID de nó que falha na análise canônica não aborta o registro; a entrada afetada recorre ao pageIndex 0.
AstAwareChunker::__construct() rejeita configuração degenerada (overlapChars >= maxChunkChars ou maxChunkChars fora de [16, 1048576]) com InvalidArgumentException. Isso evita o crescimento ilimitado do buffer durante o chunking.
AstChunk::$bbox é null quando o primeiro nó contribuinte não carrega nenhuma caixa delimitadora.
Um documento sem texto acumulável resulta em uma lista de chunks vazia.
Este módulo não realiza nenhuma operação criptográfica. O hashing, a assinatura e o carimbo de tempo para evidência de adulteração são tratados pelos módulos Evidence, Security e Signature; a política de modo FIPS reside ali.

Conformidade

Comportamento	Referência
Contexto de atualização incremental / integridade de assinatura	ISO 32000-2:2020 §12.8

A trilha de auditoria é um auxílio de manutenção de registros. Ela dá suporte a fluxos de trabalho de evidência de estilo auditoria; ela não é uma certificação nem uma atestação jurídica, e o NextPDF não detém nenhuma certificação.

Notas de desenvolvimento

Forneça uma implementação durável de AstAuditTrailInterface para retenção entre requisições. Persista-a em um repositório com capacidade WORM onde a conformidade exigir imutabilidade; a garantia somente-acréscimo é tão forte quanto o repositório subjacente.
Os instantâneos de mutação podem carregar dados pessoais; a residência de dados segue o repositório do operador.
A trilha consome o log de mutações do Pro como produzido; ela não re-deriva mutações a partir do estado do documento.
Os padrões do chunker (maxChunkChars 1500, overlapChars 150) atendem à ingestão típica de RAG; ajuste dentro dos limites documentados para modelos de embedding com orçamentos de contexto diferentes.
Detalhes internos de mecanismo permanecem na documentação interna do repositório de origem e estão fora do escopo deste manual.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismo, nomes de arquivos de runbook e prefixos de tickets estão fora do escopo.