Enterprise edición

Registro de auditoría del AST — Referencia detallada

De un vistazo

El módulo AST de Enterprise registra las mutaciones de un documento y prepara los documentos para las canalizaciones de recuperación.

AstAuditTrailInterface define un registro de auditoría de solo anexado, por documento, sobre el MutationLog del AST de Pro.
AstAuditEntry es un registro inmutable de una mutación: identidad del nodo, tipo de mutación, página, instantáneas de antes/después y marca de tiempo UTC.
InMemoryAstAuditTrail es la implementación de referencia por proceso del contrato del registro.
AstAwareChunker recorre el AST en profundidad y emite valores AstChunk anclados a citas para la ingesta de RAG.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin ese derecho de uso no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

La superficie del registro de auditoría del AST está licenciada por la capacidad enterprise.compliance.evidence. Un derecho de uso denegado deniega la función.

Nivel	Proporciona
Core	Modelo de documento AST (`AstDocument`, `AstNode`, `NodeId`)
Pro	Flujo de mutaciones del AST y `MutationLog`
Enterprise	Registro de auditoría de solo anexado por documento; segmentador anclado a citas

La superficie de Enterprise consume el registro de mutaciones de Pro. No reemplaza el modelo del AST.

composer require nextpdf/enterprise:^3

Superficie de la API pública

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	Convierte cada entrada de mutación del registro en un `AstAuditEntry` y la anexa	`void`	Nada en la implementación de referencia	Las llamadas repetidas con el mismo hash acumulan entradas
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	Devuelve las entradas registradas para un documento, en orden de inserción	`list<AstAuditEntry>`	Nada en la implementación de referencia	Lista vacía cuando ninguna entrada coincide con el hash
`AstAuditTrailInterface::count()`	ninguno	Cuenta las entradas de auditoría	`int<0, max>`	Nada en la implementación de referencia	Total en todos los documentos, no por documento
`InMemoryAstAuditTrail`	ninguno	Registro respaldado por un array y acotado al proceso actual	implementa `AstAuditTrailInterface`	Nada	No es duradero; adecuado para ciclos de vida de una sola petición
`AstAuditEntry`	el constructor promueve todos los campos	Registro de auditoría inmutable	objeto de valor	Nada	`final readonly`; véase la firma en el bloque de código a continuación
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	Valida los límites de segmentación en la construcción	instancia	`InvalidArgumentException` ante una configuración fuera de rango	Límites: `16 <= maxChunkChars <= 1048576`; `0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	Recorrido en profundidad; los encabezados delimitan los segmentos; el texto de las hojas se acumula	`list<AstChunk>`	Nada	Lista vacía para un documento sin texto acumulable
`AstChunk`	el constructor promueve todos los campos	Registro de segmento anclado a citas	objeto de valor	Nada	`final readonly`; véase la firma en el bloque de código a continuación

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 comportamiento

Registro de auditoría

Solo anexado. Las implementaciones deben ser de solo anexado: una entrada registrada no se puede modificar ni eliminar a través de esta API. Las llamadas repetidas a record() con el mismo hash acumulan entradas.
Conversión. record() convierte cada entrada del MutationLog de Pro (mediante MutationLog::all()) en un AstAuditEntry y la anexa. Todas las entradas producidas por una llamada a record() comparten una misma marca de tiempo UTC occurredAt.
Aislamiento por documento. findByDocument() filtra por el hash de origen exacto del documento y preserva el orden de inserción. count() es el total en todos los documentos.
Instantáneas. before y after son mapas de atributos indexados por text_content. Una mutación updated completa ambos lados; inserted deja before vacío; deleted deja after vacío. mutationType es el valor de cadena del enum MutationType de Pro: updated, inserted o deleted.
Derivación de la página. pageIndex se extrae del ID de nodo canónico (ast:{hash}:{page}:{seq}). Un ID de nodo malformado produce pageIndex 0; la entrada se registra igualmente.

El solo anexado es un contrato del almacén configurado, no una propiedad criptográfica. La evidencia de manipulación y el no repudio provienen de cómo se persiste y se marca temporalmente el registro (módulo Evidence), no de este módulo por sí solo.

Segmentador

Recorrido. chunk() recorre el AST en profundidad desde la raíz del documento.
Acumulación de texto. El texto de las hojas de tipo Paragraph, ListItem, TableCell, Code o Annotation se acumula en el búfer actual. Los tipos contenedor (Document, Section, Artifact, FormField, Figure, Table, List, TableRow) se recorren sin emitir texto.
Delimitadores. Un nodo Heading vacía el búfer actual como un segmento y siembra el siguiente búfer con el texto del encabezado.
División. Cuando el texto acumulado superaría maxChunkChars, el segmentador rellena el espacio restante, vacía el segmento y continúa con los últimos overlapChars caracteres más el desbordamiento. El cómputo de longitud se basa en caracteres UTF-8.
Ancla de cita. Cada AstChunk lleva el nodeId, pageIndex, bbox y nodeType de su primer nodo contribuyente, más el hash de origen del documento y un chunkIndex secuencial de base 0.
Finalización. Un búfer final con contenido no vacío se vacía como el segmento final; los restos de solo espacios en blanco se descartan, y el texto del segmento se recorta.

Casos límite y modos de fallo

Registrar el mismo MutationLog dos veces acumula entradas duplicadas; la idempotencia debe imponerse aguas arriba.
Un InMemoryAstAuditTrail recién creado y no compartido siempre está vacío. El contrato de integración requiere una única instancia de AstAuditTrailInterface compartida entregada tanto al flujo que produce las mutaciones como al consumidor que lee la auditoría, con record() llamado tras cada escritura correcta. Hasta entonces, findByDocument() devuelve una lista vacía y count() devuelve 0.
El registro en memoria es por proceso y no es duradero; las entradas no sobreviven a la petición que las creó. En producción se suministra una implementación persistente.
Un ID de nodo que no supera el análisis canónico no aborta el registro; la entrada afectada recurre a pageIndex 0.
AstAwareChunker::__construct() rechaza una configuración degenerada (overlapChars >= maxChunkChars, o maxChunkChars fuera de [16, 1048576]) con InvalidArgumentException. Esto evita el crecimiento ilimitado del búfer durante la segmentación.
AstChunk::$bbox es null cuando el primer nodo contribuyente no lleva un cuadro delimitador.
Un documento sin texto acumulable produce una lista de segmentos vacía.
Este módulo no realiza operaciones criptográficas. El hash, la firma y el marcado temporal para la evidencia de manipulación los gestionan los módulos Evidence, Security y Signature; la política del modo FIPS reside allí.

Conformidad

Comportamiento	Referencia
Contexto de actualización incremental / integridad de firma	ISO 32000-2:2020 §12.8

El registro de auditoría es una ayuda para el mantenimiento de registros. Respalda flujos de trabajo de evidencia de tipo auditoría; no es una certificación ni una atestación legal, y NextPDF no posee ninguna certificación.

Notas de desarrollo

Suministre una implementación duradera de AstAuditTrailInterface para la retención entre peticiones. Persístala en un almacén con capacidad WORM cuando el cumplimiento exija inmutabilidad; la garantía de solo anexado es tan fuerte como el almacén subyacente.
Las instantáneas de mutación pueden contener datos personales; la residencia de los datos sigue al almacén del operador.
El registro consume el registro de mutaciones de Pro tal como se produce; no vuelve a derivar las mutaciones a partir del estado del documento.
Los valores predeterminados del segmentador (maxChunkChars 1500, overlapChars 150) sirven para una ingesta de RAG típica; ajústelos dentro de los límites documentados para modelos de embeddings con presupuestos de contexto diferentes.
El detalle del mecanismo interno permanece en la documentación interna del repositorio de origen y queda fuera del alcance de este manual.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas de espacios de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbooks y los prefijos de tickets quedan fuera del alcance.