コンテンツにスキップ
NextPDF
getnextpdf.com

Enterprise エディション

AST 監査証跡 — 詳細リファレンス

概要

「概要」という見出しのセクション

Enterprise AST モジュールは、ドキュメントのミューテーションを記録し、ドキュメントを取得パイプライン向けに準備します。

  • AstAuditTrailInterface は、Pro AST の MutationLog の上に、追記専用でドキュメントごとの監査証跡を定義します。
  • AstAuditEntry は、1 つのミューテーションを表す不変のレコードです。ノード ID、ミューテーション種別、ページ、変更前/変更後のスナップショット、UTC タイムスタンプを保持します。
  • InMemoryAstAuditTrail は、証跡コントラクトのプロセス単位のリファレンス実装です。
  • AstAwareChunker は AST を深さ優先で走査し、RAG インジェスト向けに引用アンカー付きの AstChunk 値を出力します。

提供状況とライセンス

「提供状況とライセンス」という見出しのセクション

この機能は NextPDF Enterprise（nextpdf/enterprise）で提供され、Enterprise ティアのライセンスエンベロープでアクティベートされます。そのエンタイトルメントを持たないデプロイでは、機能のクラスがロードされません。エディションを比較してライセンスを取得する。

AST 監査証跡サーフェスは、enterprise.compliance.evidence 機能によってライセンスされます。エンタイトルメントが拒否されると、機能も拒否されます。

ティア提供内容
CoreAST ドキュメントモデル（AstDocument、AstNode、NodeId）
ProAST ミューテーションフローと MutationLog
Enterprise追記専用のドキュメントごとの監査証跡、引用アンカー付きチャンカー

Enterprise サーフェスは Pro のミューテーションログを消費します。AST モデルを置き換えるものではありません。

Terminal window
composer require nextpdf/enterprise:^3

パブリック API サーフェス

「パブリック API サーフェス」という見出しのセクション
シンボル引数既定の挙動戻り値スロー/失敗条件備考
AstAuditTrailInterface::record()string $documentSourceHash, MutationLog $logログ内の各ミューテーションエントリを AstAuditEntry に変換し、追記voidリファレンス実装ではなし同じハッシュで繰り返し呼び出すとエントリが蓄積
AstAuditTrailInterface::findByDocument()string $documentSourceHash1 つのドキュメントについて記録されたエントリを挿入順で返す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 に変換し、追記します。1 回の record() 呼び出しで生成されたすべてのエントリは、1 つの 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 を 2 回記録すると重複したエントリが蓄積されます。冪等性は上流で強制されなければなりません。
  • 新規で共有されていない InMemoryAstAuditTrail は常に空です。統合コントラクトでは、ミューテーションを生成するフローと監査を読み取るコンシューマの両方に、共有された 1 つの AstAuditTrailInterface インスタンスを渡し、各書き込み成功後に record() を呼び出すことが求められます。それまでは、findByDocument() は空のリストを返し、count() は 0 を返します。
  • インメモリ証跡はプロセス単位であり永続的ではありません。エントリは、それを作成したリクエストを超えて存続しません。本番では永続実装を供給します。
  • 正規解析に失敗するノード ID は記録を中止させません。該当するエントリは pageIndex 0 にフォールバックします。
  • AstAwareChunker::__construct() は、退化した設定（overlapChars >= maxChunkChars、または maxChunkChars が [16, 1048576] の範囲外）を InvalidArgumentException で拒否します。これにより、チャンク化中のバッファの無制限な増大が防止されます。
  • AstChunk::$bbox は、最初に寄与したノードが境界ボックスを持たない場合に null になります。
  • 蓄積可能なテキストがないドキュメントは、空のチャンクリストを生成します。
  • このモジュールは暗号操作を実行しません。改ざん検出可能性のためのハッシュ、署名、タイムスタンプは Evidence、Security、Signature の各モジュールが処理し、FIPS モードのポリシーはそこに存在します。

適合性

「適合性」という見出しのセクション
挙動参照
増分更新/署名完全性のコンテキストISO 32000-2:2020 §12.8

監査証跡は記録保持の補助です。監査スタイルの証拠ワークフローを支援しますが、認証でも法的証明でもなく、NextPDF はいかなる認証も保持していません。

開発上の注記

「開発上の注記」という見出しのセクション
  • クロスリクエストでの保持のために、耐久性のある AstAuditTrailInterface 実装を供給してください。コンプライアンスが不変性を要求する場合は、WORM 対応のストアに永続化してください。追記専用の保証は、背後のストアの強度と同程度でしかありません。
  • ミューテーションスナップショットは個人データを運ぶ場合があります。データレジデンシーはオペレーターのストアに従います。
  • 証跡は、生成された Pro ミューテーションログをそのまま消費します。ドキュメントの状態からミューテーションを再導出することはありません。
  • チャンカーの既定値（maxChunkChars 1500、overlapChars 150）は、一般的な RAG インジェストに適しています。異なるコンテキスト予算を持つ埋め込みモデルに対しては、文書化された境界内で調整してください。
  • 内部メカニズムの詳細は、ソースリポジトリの内部ドキュメントに留まり、本マニュアルの対象外です。

公開範囲の境界

「公開範囲の境界」という見出しのセクション

このページは、外部から観測できる挙動とサポートされるパブリック API サーフェスのみを文書化します。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットプレフィックスは対象外です。

関連項目

「関連項目」という見出しのセクション