@beyondwork/docx-react-component 1.0.105 → 1.0.108

package/src/api/v3/ai/_pe2-evidence.ts

@@ -8,6 +8,7 @@
  */
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ScopeHandle } from "../../../runtime/scopes/index.ts";
 import type {
   GeometryIndexCoverage,
   GeometryPrecision,
@@ -15,6 +16,12 @@ import type {
   GeometryReplacementEnvelopeEntry,
   GeometrySourceIdentity,
 } from "../../../runtime/geometry/index.ts";
+import type { PublicLayoutDivergence } from "../../../runtime/layout/public-facet.ts";
+import {
+  createHeaderFooterStoryKey,
+  createNoteStoryKey,
+  MAIN_STORY_KEY,
+} from "../../../model/canonical-layout-inputs.ts";
 
 export interface AiPe2GeometryCoverageEvidence {
   readonly status: GeometryRehydrationStatus;
@@ -36,6 +43,8 @@ export interface AiPe2GeometryCoverageEvidence {
 
 export interface AiPe2DocumentEvidence {
   readonly geometry: AiPe2GeometryCoverageEvidence;
+  readonly layout: AiPe2LayoutEvidence;
+  readonly oracle: AiPe2OracleEvidence;
 }
 
 export interface AiPe2ScopeReplacementEnvelopeEvidence {
@@ -52,6 +61,72 @@ export interface AiPe2ScopeEvidence {
     readonly replacementEnvelope?: AiPe2ScopeReplacementEnvelopeEvidence;
     readonly reason?: "geometry-index-unavailable" | "scope-envelope-not-found";
   };
+  readonly layout: AiPe2LayoutEvidence;
+  readonly oracle: AiPe2OracleEvidence;
+}
+
+export interface AiPe2LayoutDivergenceEvidence {
+  readonly divergenceId: string;
+  readonly kind: string;
+  readonly source: string;
+  readonly severity: string;
+  readonly message: string;
+  readonly regionKinds?: readonly string[];
+  readonly fragmentIds?: readonly string[];
+  readonly objectIds?: readonly string[];
+}
+
+export interface AiPe2LayoutEvidence {
+  readonly status: "realized" | "unavailable";
+  readonly pageCount: number;
+  readonly pageIds: readonly string[];
+  readonly pagesWithDivergences: readonly string[];
+  readonly divergenceIds: readonly string[];
+  readonly divergences: readonly AiPe2LayoutDivergenceEvidence[];
+  readonly reason?: "scope-page-evidence-not-found";
+}
+
+export type AiPe2OracleVerdict =
+  | "match"
+  | "divergent"
+  | "blocked"
+  | "oracle-incomplete"
+  | "runtime-projection-not-wired"
+  | "not-compared";
+
+export interface AiPe2GraphOracleReference {
+  readonly mode: "static" | "live";
+  readonly cacheKey: string;
+  readonly lane?: string;
+  readonly docId?: string;
+  readonly pageCount?: number;
+  readonly paragraphCount?: number;
+  readonly pdfSha256?: string;
+  readonly sourceSha256?: string;
+  readonly backendIdentityTag?: string;
+}
+
+export interface AiPe2OracleEvidence {
+  readonly status: "available" | "not-wired";
+  readonly runIds: readonly string[];
+  readonly divergenceIds: readonly string[];
+  readonly graphOracleReferences?: readonly AiPe2GraphOracleReference[];
+  readonly verdict?: AiPe2OracleVerdict;
+  readonly reason?: "truth-adapter-unavailable" | "truth-adapter-error";
+}
+
+export interface AiPe2OracleEvidenceProviderInput {
+  readonly documentId: string;
+  readonly scopeId?: string;
+  readonly pageIds: readonly string[];
+}
+
+export type AiPe2OracleEvidenceProvider = (
+  input: AiPe2OracleEvidenceProviderInput,
+) => AiPe2OracleEvidence | null | undefined;
+
+export interface AiPe2EvidenceOptions {
+  readonly oracle?: AiPe2OracleEvidenceProvider;
 }
 
 function copyCoverage(coverage: GeometryIndexCoverage): AiPe2GeometryCoverageEvidence {
@@ -100,54 +175,283 @@ const UNAVAILABLE_COVERAGE: AiPe2GeometryCoverageEvidence = {
   precision: { exact: 0, "within-tolerance": 0, heuristic: 0 },
 };
 
+function copyLayoutDivergence(
+  divergence: PublicLayoutDivergence,
+): AiPe2LayoutDivergenceEvidence {
+  return {
+    divergenceId: divergence.divergenceId,
+    kind: divergence.kind,
+    source: divergence.source,
+    severity: divergence.severity,
+    message: divergence.message,
+    ...(divergence.regionKinds ? { regionKinds: [...divergence.regionKinds] } : {}),
+    ...(divergence.fragmentIds ? { fragmentIds: [...divergence.fragmentIds] } : {}),
+    ...(divergence.objectIds ? { objectIds: [...divergence.objectIds] } : {}),
+  };
+}
+
+function copyGraphOracleReference(
+  reference: AiPe2GraphOracleReference,
+): AiPe2GraphOracleReference {
+  return {
+    mode: reference.mode,
+    cacheKey: reference.cacheKey,
+    ...(reference.lane ? { lane: reference.lane } : {}),
+    ...(reference.docId ? { docId: reference.docId } : {}),
+    ...(reference.pageCount !== undefined ? { pageCount: reference.pageCount } : {}),
+    ...(reference.paragraphCount !== undefined
+      ? { paragraphCount: reference.paragraphCount }
+      : {}),
+    ...(reference.pdfSha256 ? { pdfSha256: reference.pdfSha256 } : {}),
+    ...(reference.sourceSha256 ? { sourceSha256: reference.sourceSha256 } : {}),
+    ...(reference.backendIdentityTag
+      ? { backendIdentityTag: reference.backendIdentityTag }
+      : {}),
+  };
+}
+
+function projectLayoutEvidence(
+  runtime: RuntimeApiHandle,
+  pageIds?: readonly string[],
+): AiPe2LayoutEvidence {
+  if (typeof runtime.layout?.getPageCount !== "function") {
+    return {
+      status: "unavailable",
+      pageCount: 0,
+      pageIds: [],
+      pagesWithDivergences: [],
+      divergenceIds: [],
+      divergences: [],
+    };
+  }
+  const pageCount = runtime.layout.getPageCount();
+  const selectedPageIds = pageIds ? new Set(pageIds) : null;
+  const pageIdOut: string[] = [];
+  const pagesWithDivergences: string[] = [];
+  const divergenceIds = new Set<string>();
+  const divergencesById = new Map<string, AiPe2LayoutDivergenceEvidence>();
+
+  for (let pageIndex = 0; pageIndex < pageCount; pageIndex += 1) {
+    const page = runtime.layout.getPage(pageIndex);
+    if (!page) continue;
+    if (selectedPageIds && !selectedPageIds.has(page.pageId)) continue;
+    pageIdOut.push(page.pageId);
+
+    for (const divergenceId of page.frame?.divergenceIds ?? []) {
+      divergenceIds.add(divergenceId);
+    }
+    for (const divergence of page.divergences ?? []) {
+      divergenceIds.add(divergence.divergenceId);
+      divergencesById.set(divergence.divergenceId, copyLayoutDivergence(divergence));
+    }
+    if ((page.frame?.divergenceIds.length ?? 0) > 0 || (page.divergences?.length ?? 0) > 0) {
+      pagesWithDivergences.push(page.pageId);
+    }
+  }
+
+  return {
+    status: pageIdOut.length > 0 ? "realized" : "unavailable",
+    pageCount: pageIdOut.length,
+    pageIds: pageIdOut,
+    pagesWithDivergences,
+    divergenceIds: [...divergenceIds],
+    divergences: [...divergencesById.values()],
+    ...(selectedPageIds && pageIdOut.length === 0
+      ? { reason: "scope-page-evidence-not-found" as const }
+      : {}),
+  };
+}
+
+function copyOracleEvidence(evidence: AiPe2OracleEvidence): AiPe2OracleEvidence {
+  return {
+    status: evidence.status,
+    runIds: [...evidence.runIds],
+    divergenceIds: [...evidence.divergenceIds],
+    ...(evidence.graphOracleReferences
+      ? { graphOracleReferences: evidence.graphOracleReferences.map(copyGraphOracleReference) }
+      : {}),
+    ...(evidence.verdict ? { verdict: evidence.verdict } : {}),
+    ...(evidence.reason ? { reason: evidence.reason } : {}),
+  };
+}
+
+function canonicalStoryKeyForHandle(handle: ScopeHandle): string {
+  const target = handle.storyTarget;
+  switch (target.kind) {
+    case "main":
+      return MAIN_STORY_KEY;
+    case "header":
+      return createHeaderFooterStoryKey({
+        kind: "header",
+        relationshipId: target.relationshipId,
+        variant: target.variant,
+        ...(target.sectionIndex !== undefined ? { sectionIndex: target.sectionIndex } : {}),
+      });
+    case "footer":
+      return createHeaderFooterStoryKey({
+        kind: "footer",
+        relationshipId: target.relationshipId,
+        variant: target.variant,
+        ...(target.sectionIndex !== undefined ? { sectionIndex: target.sectionIndex } : {}),
+      });
+    case "footnote":
+      return createNoteStoryKey("footnote", target.noteId);
+    case "endnote":
+      return createNoteStoryKey("endnote", target.noteId);
+  }
+}
+
+function semanticMainBlockPath(handle: ScopeHandle): string | null {
+  const path = handle.semanticPath;
+  if (path[0] !== "body") return null;
+  if (path[1] === "paragraph" || path[1] === "heading" || path[1] === "list-item") {
+    const blockIndex = path[path.length - 1];
+    return typeof blockIndex === "string" && /^\d+$/u.test(blockIndex)
+      ? `${MAIN_STORY_KEY}/block[${blockIndex}]`
+      : null;
+  }
+  if (path[1] === "table" && typeof path[2] === "string" && /^\d+$/u.test(path[2])) {
+    return `${MAIN_STORY_KEY}/block[${path[2]}]`;
+  }
+  return null;
+}
+
+function scoreEnvelopeForHandle(
+  envelope: GeometryReplacementEnvelopeEntry,
+  handle: ScopeHandle,
+  storyKey: string,
+): number {
+  if (envelope.scopeId !== handle.scopeId) return -1;
+  const source = envelope.sourceIdentity;
+  if (!source) return 0;
+
+  let score = 1;
+  if (source.scopeId === handle.scopeId) score += 2;
+  if (source.storyKey === storyKey) score += 8;
+  if (source.scopeKey === `${storyKey}:scope:${handle.scopeId}` ||
+      source.scopeKey?.startsWith(`${storyKey}:scope:${handle.scopeId}:`)) {
+    score += 4;
+  }
+
+  const blockPath = semanticMainBlockPath(handle);
+  if (blockPath && source.blockPath === blockPath) score += 2;
+
+  return score;
+}
+
+function findReplacementEnvelopeForHandle(
+  envelopes: readonly GeometryReplacementEnvelopeEntry[],
+  handle: ScopeHandle,
+): GeometryReplacementEnvelopeEntry | undefined {
+  const storyKey = canonicalStoryKeyForHandle(handle);
+  let best: GeometryReplacementEnvelopeEntry | undefined;
+  let bestScore = -1;
+  for (const envelope of envelopes) {
+    const score = scoreEnvelopeForHandle(envelope, handle, storyKey);
+    if (score > bestScore) {
+      best = envelope;
+      bestScore = score;
+    }
+  }
+  return bestScore >= 0 ? best : undefined;
+}
+
+function projectOracleEvidence(
+  runtime: RuntimeApiHandle,
+  options: AiPe2EvidenceOptions | undefined,
+  input: Omit<AiPe2OracleEvidenceProviderInput, "documentId">,
+): AiPe2OracleEvidence {
+  const provider = options?.oracle;
+  if (provider) {
+    try {
+      const evidence = provider({
+        documentId: runtime.getSessionState().documentId,
+        ...input,
+      });
+      if (evidence) return copyOracleEvidence(evidence);
+    } catch {
+      return {
+        status: "not-wired",
+        runIds: [],
+        divergenceIds: [],
+        reason: "truth-adapter-error",
+      };
+    }
+  }
+  return {
+    status: "not-wired",
+    runIds: [],
+    divergenceIds: [],
+    reason: "truth-adapter-unavailable",
+  };
+}
+
 export function projectDocumentPe2Evidence(
   runtime: RuntimeApiHandle,
+  options?: AiPe2EvidenceOptions,
 ): AiPe2DocumentEvidence {
-  if (!runtime.geometry) {
-    return { geometry: UNAVAILABLE_COVERAGE };
-  }
+  const layout = projectLayoutEvidence(runtime);
+  const geometry = runtime.geometry
+    ? copyCoverage(runtime.geometry.getGeometryCoverage())
+    : UNAVAILABLE_COVERAGE;
   return {
-    geometry: copyCoverage(runtime.geometry.getGeometryCoverage()),
+    geometry,
+    layout,
+    oracle: projectOracleEvidence(runtime, options, { pageIds: layout.pageIds }),
   };
 }
 
 export function projectScopePe2Evidence(
   runtime: RuntimeApiHandle,
-  scopeId: string,
+  handle: ScopeHandle,
+  options?: AiPe2EvidenceOptions,
 ): AiPe2ScopeEvidence {
+  const { scopeId } = handle;
   if (!runtime.geometry) {
+    const layout = projectLayoutEvidence(runtime, []);
     return {
       geometry: {
         coverage: UNAVAILABLE_COVERAGE,
         reason: "geometry-index-unavailable",
       },
+      layout,
+      oracle: projectOracleEvidence(runtime, options, { scopeId, pageIds: layout.pageIds }),
     };
   }
   const coverage = copyCoverage(runtime.geometry.getGeometryCoverage());
   const index = runtime.geometry.getGeometryIndex();
   if (!index) {
+    const layout = projectLayoutEvidence(runtime, []);
     return {
       geometry: {
         coverage,
         reason: "geometry-index-unavailable",
       },
+      layout,
+      oracle: projectOracleEvidence(runtime, options, { scopeId, pageIds: layout.pageIds }),
     };
   }
 
-  const envelope = index.replacementEnvelopes.find((entry) => entry.scopeId === scopeId);
+  const envelope = findReplacementEnvelopeForHandle(index.replacementEnvelopes, handle);
   if (!envelope) {
+    const layout = projectLayoutEvidence(runtime, []);
     return {
       geometry: {
         coverage,
         reason: "scope-envelope-not-found",
       },
+      layout,
+      oracle: projectOracleEvidence(runtime, options, { scopeId, pageIds: layout.pageIds }),
     };
   }
 
+  const layout = projectLayoutEvidence(runtime, envelope.pageIds);
   return {
     geometry: {
       coverage,
       replacementEnvelope: copyEnvelope(envelope),
     },
+    layout,
+    oracle: projectOracleEvidence(runtime, options, { scopeId, pageIds: layout.pageIds }),
   };
 }

package/src/api/v3/ai/attach.ts

@@ -37,15 +37,23 @@ import {
   emitScopeMetadataAudit,
   snapshotDocumentHash,
 } from "./_metadata-audit.ts";
+import {
+  projectAuditReference,
+  type AiActionAuditReference,
+} from "./_audit-reference.ts";
+import { currentAuditTimestamp } from "./_audit-time.ts";
 
 export interface AttachExplanationInput {
   readonly scopeId: string;
   readonly explanation: string;
+  readonly actorId?: string;
+  readonly origin?: "ui" | "agent" | "host";
 }
 
 export interface AttachExplanationResult {
   readonly explanationId: string;
   readonly attached: boolean;
+  readonly auditReference?: AiActionAuditReference;
   /**
    * Present when `attached: false`. Mirrors the primitive's refusal
    * reason (`scope-not-resolvable:<scopeId>` post-coord-06 §13c;
@@ -85,11 +93,14 @@ export interface CreateIssueInput {
   readonly scopeId: string;
   readonly summary: string;
   readonly severity?: "info" | "warning" | "error";
+  readonly actorId?: string;
+  readonly origin?: "ui" | "agent" | "host";
 }
 
 export interface CreateIssueResult {
   readonly issueId: string;
   readonly created: boolean;
+  readonly auditReference?: AiActionAuditReference;
   readonly reason?: string;
 }
 
@@ -136,15 +147,20 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
       );
       const preScope = captureScopeSnapshot(runtime, input.scopeId);
       const documentHashBefore = snapshotDocumentHash(runtime);
+      const emittedAtUtc = currentAuditTimestamp(runtime);
       const primitiveResult = compiler.attachExplanation({
         scopeId: input.scopeId,
         explanation: input.explanation,
         explanationId,
+        createdAtUtc: emittedAtUtc,
       });
+      let auditReference: AiActionAuditReference | undefined;
       if (primitiveResult.attached && preScope) {
-        emitScopeMetadataAudit({
+        const audit = emitScopeMetadataAudit({
           runtime,
           actionId: attachExplanationMetadata.name,
+          ...(input.actorId ? { actorId: input.actorId } : {}),
+          ...(input.origin ? { origin: input.origin } : {}),
           scopeId: input.scopeId,
           targetScopeSnapshot: preScope,
           proposedContent: {
@@ -156,9 +172,10 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
           },
           compiledOperationKind: "metadata-attach-explanation",
           compiledOperationSummary: `attach explanation ${primitiveResult.explanationId} to scope ${input.scopeId}`,
-          emittedAtUtc: new Date(0).toISOString(),
+          emittedAtUtc,
           documentHashBefore,
         });
+        auditReference = projectAuditReference(audit);
       }
       emitUxResponse(runtime, {
         apiFn: attachExplanationMetadata.name,
@@ -170,6 +187,7 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
       return {
         explanationId: primitiveResult.explanationId,
         attached: primitiveResult.attached,
+        ...(auditReference ? { auditReference } : {}),
         // §1.17 — surface primitive's reason on refusal for symmetry
         // with CreateIssueResult. The primitive returns `reason` only
         // when `attached: false`; passthrough preserves that contract.
@@ -191,16 +209,21 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
       );
       const preScope = captureScopeSnapshot(runtime, input.scopeId);
       const documentHashBefore = snapshotDocumentHash(runtime);
+      const emittedAtUtc = currentAuditTimestamp(runtime);
       const primitiveResult = compiler.createIssue({
         scopeId: input.scopeId,
         summary: input.summary,
         ...(input.severity ? { severity: input.severity } : {}),
         issueId,
+        createdAtUtc: emittedAtUtc,
       });
+      let auditReference: AiActionAuditReference | undefined;
       if (primitiveResult.created && preScope) {
-        emitScopeMetadataAudit({
+        const audit = emitScopeMetadataAudit({
           runtime,
           actionId: createIssueMetadata.name,
+          ...(input.actorId ? { actorId: input.actorId } : {}),
+          ...(input.origin ? { origin: input.origin } : {}),
           scopeId: input.scopeId,
           targetScopeSnapshot: preScope,
           proposedContent: {
@@ -213,9 +236,10 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
           },
           compiledOperationKind: "metadata-attach-issue",
           compiledOperationSummary: `create issue ${primitiveResult.issueId} on scope ${input.scopeId}`,
-          emittedAtUtc: new Date(0).toISOString(),
+          emittedAtUtc,
           documentHashBefore,
         });
+        auditReference = projectAuditReference(audit);
       }
       emitUxResponse(runtime, {
         apiFn: createIssueMetadata.name,
@@ -227,6 +251,7 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
       const out: CreateIssueResult = {
         issueId: primitiveResult.issueId,
         created: primitiveResult.created,
+        ...(auditReference ? { auditReference } : {}),
         ...(primitiveResult.created ? {} : { reason: primitiveResult.reason }),
       };
       return out;

package/src/api/v3/ai/bundle.ts

@@ -26,6 +26,7 @@ import {
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import {
   projectScopePe2Evidence,
+  type AiPe2EvidenceOptions,
   type AiPe2ScopeEvidence,
 } from "./_pe2-evidence.ts";
 
@@ -103,7 +104,10 @@ export const getScopeBundleMetadata: ApiV3FnMetadata = {
   rwdReference: "§AI API § ai.getScopeBundle",
 };
 
-export function createBundleFamily(runtime: RuntimeApiHandle) {
+export function createBundleFamily(
+  runtime: RuntimeApiHandle,
+  pe2Evidence?: AiPe2EvidenceOptions,
+) {
   const compiler = createScopeCompilerService(runtime);
   return {
     getScope(input: GetScopeInput): SemanticScope | null {
@@ -133,7 +137,7 @@ export function createBundleFamily(runtime: RuntimeApiHandle) {
       }
       return {
         ...bundle,
-        pe2Evidence: projectScopePe2Evidence(runtime, scopeId),
+        pe2Evidence: projectScopePe2Evidence(runtime, input.handle, pe2Evidence),
       };
     },
   };

package/src/api/v3/ai/inspect.ts

@@ -18,6 +18,7 @@ import {
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import {
   projectDocumentPe2Evidence,
+  type AiPe2EvidenceOptions,
   type AiPe2DocumentEvidence,
 } from "./_pe2-evidence.ts";
 
@@ -84,7 +85,10 @@ function buildKindDistribution(
   return out;
 }
 
-export function createInspectFamily(runtime: RuntimeApiHandle) {
+export function createInspectFamily(
+  runtime: RuntimeApiHandle,
+  pe2Evidence?: AiPe2EvidenceOptions,
+) {
   const compiler = createScopeCompilerService(runtime);
   return {
     inspectDocument(): InspectDocumentResult {
@@ -102,7 +106,7 @@ export function createInspectFamily(runtime: RuntimeApiHandle) {
         scopeCount: scopes.length,
         semanticSummary: summary,
         kindDistribution,
-        pe2Evidence: projectDocumentPe2Evidence(runtime),
+        pe2Evidence: projectDocumentPe2Evidence(runtime, pe2Evidence),
       };
     },