@beyondwork/docx-react-component 1.0.104 → 1.0.106

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.104",
+  "version": "1.0.106",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -177,9 +177,11 @@ export type {
   PublicBlockMeasurement,
   PublicFieldDirtinessReport,
   PublicLineBox,
+  PublicLayoutDivergence,
   PublicMeasurementFidelity,
   PublicNoteAllocation,
   PublicPageAnchor,
+  PublicPageFrame,
   PublicPageNode,
   PublicPageRegion,
   PublicPageRegions,
@@ -190,6 +192,7 @@ export type {
   PublicResolvedParagraphFormatting,
   PublicResolvedRunFormatting,
   PublicSectionNode,
+  PublicTwipsRect,
   // R0.5: named page-format + margin-preset catalogs
   PageFormatDefinition,
   ActivePageFormat,

package/src/api/v3/_create.ts

@@ -41,6 +41,7 @@ import { createReviewFamily as createAiReviewFamily } from "./ai/review.ts";
 import { createEvaluateFamily } from "./ai/evaluate.ts";
 import { createStatsFamily } from "./ai/stats.ts";
 import { createOutlineFamily } from "./ai/outline.ts";
+import type { AiPe2EvidenceOptions } from "./ai/_pe2-evidence.ts";
 
 import { createUiApi } from "./ui/_create.ts";
 import type { ApiV3Ui, UiControllerFactory } from "./ui/_types.ts";
@@ -108,6 +109,12 @@ export interface ApiV3 {
  */
 export interface CreateApiV3Opts {
   readonly ui?: UiControllerFactory;
+  /**
+   * Optional PE2 evidence bridge. Hosts/debug services that already have
+   * truth-oracle run metadata can inject it here; omitted means AI reads
+   * report `pe2Evidence.oracle.status: "not-wired"`.
+   */
+  readonly pe2Evidence?: AiPe2EvidenceOptions;
 }
 
 /**
@@ -119,9 +126,9 @@ export interface CreateApiV3Opts {
  */
 export function createApiV3(handle: RuntimeApiHandle, opts?: CreateApiV3Opts): ApiV3 {
   const ai: ApiV3Ai = {
-    ...createInspectFamily(handle),
+    ...createInspectFamily(handle, opts?.pe2Evidence),
     ...createResolveFamily(handle),
-    ...createBundleFamily(handle),
+    ...createBundleFamily(handle, opts?.pe2Evidence),
     ...createReplacementFamily(handle),
     ...createAttachFamily(handle),
     ...createExportFamily(handle),

package/src/api/v3/ai/_audit-reference.ts

@@ -0,0 +1,28 @@
+/**
+ * Compact AI-facing pointer to an emitted ScopeActionAudit.
+ *
+ * The full audit bundle remains on the `scope` telemetry channel. Mutation
+ * return values expose only enough provenance for agents to cite the action
+ * and correlate it with telemetry.
+ */
+
+import type { ScopeActionAudit } from "../../../runtime/scopes/index.ts";
+
+export interface AiActionAuditReference {
+  readonly actionId: string;
+  readonly actorId: string;
+  readonly origin: ScopeActionAudit["origin"];
+  readonly emittedAtUtc: string;
+}
+
+export function projectAuditReference(
+  audit: ScopeActionAudit | null | undefined,
+): AiActionAuditReference | undefined {
+  if (!audit) return undefined;
+  return {
+    actionId: audit.actionId,
+    actorId: audit.actorId,
+    origin: audit.origin,
+    emittedAtUtc: audit.emittedAtUtc,
+  };
+}

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

@@ -0,0 +1,419 @@
+/**
+ * Layer 09 PE2 evidence projection.
+ *
+ * The AI API should not leak the full runtime geometry index. Agents need a
+ * small, JSON-stable read model that says whether PE2 geometry evidence is
+ * available and, for scope reads, whether a replacement envelope exists for
+ * the requested scope.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ScopeHandle } from "../../../runtime/scopes/index.ts";
+import type {
+  GeometryIndexCoverage,
+  GeometryPrecision,
+  GeometryRehydrationStatus,
+  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;
+  readonly pageCount: number;
+  readonly regionCount: number;
+  readonly sliceCount: number;
+  readonly lineCount: number;
+  readonly anchorCount: number;
+  readonly hitTargetCount: number;
+  readonly semanticEntryCount: number;
+  readonly replacementEnvelopeCount: number;
+  readonly objectHandleCount: number;
+  readonly precision: {
+    readonly exact: number;
+    readonly "within-tolerance": number;
+    readonly heuristic: number;
+  };
+}
+
+export interface AiPe2DocumentEvidence {
+  readonly geometry: AiPe2GeometryCoverageEvidence;
+  readonly layout: AiPe2LayoutEvidence;
+  readonly oracle: AiPe2OracleEvidence;
+}
+
+export interface AiPe2ScopeReplacementEnvelopeEvidence {
+  readonly status: GeometryRehydrationStatus;
+  readonly precision: GeometryPrecision;
+  readonly rectCount: number;
+  readonly pageIds?: readonly string[];
+  readonly sourceIdentity?: GeometrySourceIdentity;
+}
+
+export interface AiPe2ScopeEvidence {
+  readonly geometry: {
+    readonly coverage: AiPe2GeometryCoverageEvidence;
+    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[];
+}
+
+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 AiPe2OracleEvidence {
+  readonly status: "available" | "not-wired";
+  readonly runIds: readonly string[];
+  readonly divergenceIds: readonly string[];
+  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 {
+  return {
+    status: coverage.status,
+    pageCount: coverage.pageCount,
+    regionCount: coverage.regionCount,
+    sliceCount: coverage.sliceCount,
+    lineCount: coverage.lineCount,
+    anchorCount: coverage.anchorCount,
+    hitTargetCount: coverage.hitTargetCount,
+    semanticEntryCount: coverage.semanticEntryCount,
+    replacementEnvelopeCount: coverage.replacementEnvelopeCount,
+    objectHandleCount: coverage.objectHandleCount,
+    precision: {
+      exact: coverage.precision.exact,
+      "within-tolerance": coverage.precision["within-tolerance"],
+      heuristic: coverage.precision.heuristic,
+    },
+  };
+}
+
+function copyEnvelope(
+  envelope: GeometryReplacementEnvelopeEntry,
+): AiPe2ScopeReplacementEnvelopeEvidence {
+  return {
+    status: envelope.status,
+    precision: envelope.precision,
+    rectCount: envelope.rects.length,
+    ...(envelope.pageIds ? { pageIds: [...envelope.pageIds] } : {}),
+    ...(envelope.sourceIdentity ? { sourceIdentity: { ...envelope.sourceIdentity } } : {}),
+  };
+}
+
+const UNAVAILABLE_COVERAGE: AiPe2GeometryCoverageEvidence = {
+  status: "unavailable",
+  pageCount: 0,
+  regionCount: 0,
+  sliceCount: 0,
+  lineCount: 0,
+  anchorCount: 0,
+  hitTargetCount: 0,
+  semanticEntryCount: 0,
+  replacementEnvelopeCount: 0,
+  objectHandleCount: 0,
+  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] } : {}),
+  };
+}
+
+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.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 {
+  const layout = projectLayoutEvidence(runtime);
+  const geometry = runtime.geometry
+    ? copyCoverage(runtime.geometry.getGeometryCoverage())
+    : UNAVAILABLE_COVERAGE;
+  return {
+    geometry,
+    layout,
+    oracle: projectOracleEvidence(runtime, options, { pageIds: layout.pageIds }),
+  };
+}
+
+export function projectScopePe2Evidence(
+  runtime: RuntimeApiHandle,
+  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 = 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,22 @@ import {
   emitScopeMetadataAudit,
   snapshotDocumentHash,
 } from "./_metadata-audit.ts";
+import {
+  projectAuditReference,
+  type AiActionAuditReference,
+} from "./_audit-reference.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 +92,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;
 }
 
@@ -141,10 +151,13 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
         explanation: input.explanation,
         explanationId,
       });
+      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: {
@@ -159,6 +172,7 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
           emittedAtUtc: new Date(0).toISOString(),
           documentHashBefore,
         });
+        auditReference = projectAuditReference(audit);
       }
       emitUxResponse(runtime, {
         apiFn: attachExplanationMetadata.name,
@@ -170,6 +184,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.
@@ -197,10 +212,13 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
         ...(input.severity ? { severity: input.severity } : {}),
         issueId,
       });
+      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: {
@@ -216,6 +234,7 @@ export function createAttachFamily(runtime: RuntimeApiHandle) {
           emittedAtUtc: new Date(0).toISOString(),
           documentHashBefore,
         });
+        auditReference = projectAuditReference(audit);
       }
       emitUxResponse(runtime, {
         apiFn: createIssueMetadata.name,
@@ -227,6 +246,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

@@ -24,6 +24,11 @@ import {
   type SemanticScope,
 } from "../../../runtime/scopes/index.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  projectScopePe2Evidence,
+  type AiPe2EvidenceOptions,
+  type AiPe2ScopeEvidence,
+} from "./_pe2-evidence.ts";
 
 /**
  * Handle-shaped input (architecture A3 — scope-handle-first targeting).
@@ -42,8 +47,9 @@ export interface GetScopeBundleInput {
   readonly nowUtc: string;
 }
 
-/** Re-export the runtime-side `ScopeBundle` so v3 consumers get the rich shape. */
-export type { RuntimeScopeBundle as ScopeBundle };
+export type ScopeBundle = RuntimeScopeBundle & {
+  readonly pe2Evidence: AiPe2ScopeEvidence;
+};
 
 export interface ScopeBundleNotFound {
   readonly notFound: true;
@@ -91,14 +97,17 @@ export const getScopeBundleMetadata: ApiV3FnMetadata = {
     boundedScope: "scope",
     auditCategory: "scope-bundle",
     contextPromptShape:
-      "Bundle content + formatting + layout + geometry + workflow + replaceability for prompt context.",
+      "Bundle content + formatting + layout + geometry + workflow + replaceability + PE2 geometry coverage/envelope evidence for prompt context.",
   },
   stateClass: "A-canonical",
   persistsTo: "canonical",
   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 {
@@ -110,7 +119,7 @@ export function createBundleFamily(runtime: RuntimeApiHandle) {
       return compiled?.scope ?? null;
     },
 
-    getScopeBundle(input: GetScopeBundleInput): RuntimeScopeBundle | ScopeBundleNotFound {
+    getScopeBundle(input: GetScopeBundleInput): ScopeBundle | ScopeBundleNotFound {
       // @endStateApi — live-with-adapter. Routes through the compiler-
       // service facade.
       //
@@ -126,7 +135,10 @@ export function createBundleFamily(runtime: RuntimeApiHandle) {
           reason: "no scope with this id in canonical document or review store",
         };
       }
-      return bundle;
+      return {
+        ...bundle,
+        pe2Evidence: projectScopePe2Evidence(runtime, input.handle, pe2Evidence),
+      };
     },
   };
 }