@beyondwork/docx-react-component 1.0.105 → 1.0.108

package/src/runtime/scopes/index.ts

@@ -26,8 +26,24 @@ export type {
   ReplacementOperationKind,
   ReplacementPreservePolicy,
   ReplacementScope,
+  ScopeReplacementOperationKind,
   ScopeActionOperationKind,
   ScopeActionProposal,
+  ScopeCapabilities,
+  ScopeCapabilityStatus,
+  ScopeCapabilityVerdict,
+  ScopeContentControlEvidence,
+  ScopeContentControlEvidenceEntry,
+  ScopeContentControlEvidenceStatus,
+  ScopeEvidenceAvailability,
+  ScopeGeometryEvidence,
+  ScopeGeometryEvidencePrecision,
+  ScopeGeometryEvidenceRect,
+  ScopeGeometryEvidenceStatus,
+  ScopeLayoutContinuationEvidence,
+  ScopeLayoutEvidence,
+  ScopeVisualizationClass,
+  ScopeVisualizationHint,
   RuntimeOperationPlan,
   RuntimeOperationStep,
   RuntimeOperationStepKind,
@@ -35,6 +51,7 @@ export type {
   ScopeFormattingAction,
   ScopeFormattingClearTarget,
   ScopeFormattingScope,
+  ScopeActionPosture,
   ScopeBundle,
   ScopeBundleEvidence,
   ScopeBundleNeighborhood,
@@ -56,6 +73,33 @@ export type {
   ValidationIssue,
   ValidationResult,
 } from "./semantic-scope-types.ts";
+export { deriveScopeCapabilities } from "./capabilities.ts";
+export type { ScopeCapabilityContext } from "./capabilities.ts";
+export {
+  deriveScopeContentControlEvidence,
+  findContentControlsIntersectingRange,
+} from "./content-control-evidence.ts";
+export {
+  deriveScopeGeometryEvidence,
+  type ScopeGeometryEvidenceProvider,
+} from "./geometry-evidence.ts";
+export {
+  deriveScopeLayoutEvidence,
+  collectTopLevelTableBlockIdsFromRenderSnapshot,
+  createRuntimeTableFrameLayoutEvidenceProvider,
+  type RuntimeTableFrameLayoutEvidenceOptions,
+  type ScopeLayoutEvidenceEntry,
+  type ScopeLayoutEvidenceProvider,
+  type ScopeRuntimeLayoutEvidenceSource,
+  type ScopeRuntimeLayoutFragment,
+  type ScopeRuntimeRenderSnapshotLike,
+} from "./layout-evidence.ts";
+export {
+  MULTI_PARAGRAPH_REPLACEMENT_REFUSAL,
+  multiParagraphReplacementBlockers,
+} from "./multi-paragraph-refusal.ts";
+export type { MultiParagraphReplacementShape } from "./multi-paragraph-refusal.ts";
+export { deriveScopeVisualization } from "./visualization.ts";
 
 export {
   buildParagraphIndexMap,
@@ -153,6 +197,15 @@ export {
   type IssueSeverity,
   type IssueStatus,
 } from "./create-issue.ts";
+export {
+  resolveIssueLifecycleTarget,
+  transitionScopeIssueLifecycle,
+  type IssueLifecycleAction,
+  type IssueLifecycleRuntime,
+  type IssueLifecycleTarget,
+  type TransitionScopeIssueLifecycleInputs,
+  type TransitionScopeIssueLifecycleResult,
+} from "./issue-lifecycle.ts";
 export {
   createScopeCompilerService,
   type ApplyFormattingRequest,
@@ -161,5 +214,6 @@ export {
   type CompileScopeByIdResult,
   type CompilerServiceRuntime,
   type CreateIssueRequest,
+  type TransitionIssueLifecycleRequest,
   type ScopeCompilerService,
 } from "./compiler-service.ts";

package/src/runtime/scopes/issue-lifecycle.ts

@@ -0,0 +1,224 @@
+/**
+ * Layer 08 issue lifecycle binding.
+ *
+ * Layer 06 owns durable `ai.issue` metadata status transitions. This module
+ * adds the scope-compiler binding that future L09 `resolveIssue` /
+ * `reopenIssue` APIs need: find the issue's scope, require that scope to still
+ * compile, preserve the existing metadata entry id, and emit scope-shaped audit
+ * evidence for the lifecycle transition.
+ */
+
+import type { TelemetryBus } from "../debug/telemetry-bus.ts";
+import {
+  projectAIIssueLifecycleReadback,
+  transitionAIIssueLifecycle,
+  type AIIssueLifecycleAction,
+  type AIIssueLifecycleAuditEntry,
+  type AIIssueStatus,
+} from "../workflow/ai-issue-lifecycle.ts";
+import type {
+  WorkflowEventOrigin,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+} from "./_scope-dependencies.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  ReplacementScope,
+  ScopeActionAudit,
+  SemanticScope,
+  ValidationResult,
+} from "./semantic-scope-types.ts";
+
+export type IssueLifecycleAction = AIIssueLifecycleAction;
+
+export interface IssueLifecycleRuntime {
+  getCanonicalDocument(): CanonicalDocumentEnvelope;
+  getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  setWorkflowMetadataEntries(
+    entries: readonly WorkflowMetadataEntry[],
+    origin?: WorkflowEventOrigin,
+  ): void;
+}
+
+export interface IssueLifecycleTarget {
+  readonly issueId: string;
+  readonly entryId: string;
+  readonly scopeId: string;
+  readonly status: AIIssueStatus;
+}
+
+export interface TransitionScopeIssueLifecycleInputs {
+  readonly runtime: IssueLifecycleRuntime;
+  readonly documentBefore: CanonicalDocumentEnvelope;
+  readonly targetScopeSnapshot: SemanticScope;
+  readonly issueId: string;
+  readonly action: IssueLifecycleAction;
+  readonly actorId: string;
+  readonly origin: "ui" | "agent" | "host";
+  readonly emittedAtUtc: string;
+  readonly bus?: TelemetryBus;
+}
+
+export type TransitionScopeIssueLifecycleResult =
+  | {
+      readonly transitioned: true;
+      readonly issueId: string;
+      readonly entryId: string;
+      readonly scopeId: string;
+      readonly fromStatus: AIIssueStatus;
+      readonly toStatus: AIIssueStatus;
+      readonly lifecycleAudit: AIIssueLifecycleAuditEntry;
+      readonly targetScopeSnapshot: SemanticScope;
+      readonly audit: ScopeActionAudit;
+    }
+  | {
+      readonly transitioned: false;
+      readonly issueId: string;
+      readonly reason: string;
+      readonly blockers: readonly string[];
+      readonly scopeId?: string;
+      readonly targetScopeSnapshot?: SemanticScope;
+    };
+
+function documentHash(doc: CanonicalDocumentEnvelope): string {
+  let textLength = 0;
+  for (const block of doc.content.children) {
+    if (block.type !== "paragraph") continue;
+    for (const child of block.children) {
+      if (child.type === "text") textLength += child.text.length;
+    }
+  }
+  return `blocks:${doc.content.children.length}|text:${textLength}`;
+}
+
+function freezeBlocker(reason: string): readonly string[] {
+  return Object.freeze([reason]);
+}
+
+export function resolveIssueLifecycleTarget(
+  snapshot: WorkflowMetadataSnapshot,
+  issueIdOrEntryId: string,
+): IssueLifecycleTarget | null {
+  const readback = projectAIIssueLifecycleReadback(snapshot.entries).find(
+    (issue) =>
+      issue.issueId === issueIdOrEntryId || issue.entryId === issueIdOrEntryId,
+  );
+  if (!readback || !readback.scopeId) return null;
+  return {
+    issueId: readback.issueId,
+    entryId: readback.entryId,
+    scopeId: readback.scopeId,
+    status: readback.status,
+  };
+}
+
+function buildLifecycleAudit(
+  inputs: TransitionScopeIssueLifecycleInputs,
+  transition: {
+    readonly issueId: string;
+    readonly entryId: string;
+    readonly fromStatus: AIIssueStatus;
+    readonly toStatus: AIIssueStatus;
+    readonly audit: AIIssueLifecycleAuditEntry;
+  },
+): ScopeActionAudit {
+  const snapshot = inputs.targetScopeSnapshot;
+  const proposed: ReplacementScope = {
+    targetHandle: snapshot.handle,
+    operation: "annotate",
+    proposedContent: {
+      kind: "structured",
+      structured: {
+        metadataKind: "issue-lifecycle",
+        issueId: transition.issueId,
+        entryId: transition.entryId,
+        action: inputs.action,
+        fromStatus: transition.fromStatus,
+        toStatus: transition.toStatus,
+      },
+    },
+    proposedAtUtc: inputs.emittedAtUtc,
+  };
+  const validation: ValidationResult = {
+    safe: true,
+    posture: "supported",
+    blockedReasons: Object.freeze([]),
+    warnings: Object.freeze([]),
+  };
+  return {
+    actionId:
+      inputs.action === "resolve" ? "ai.resolveIssue" : "ai.reopenIssue",
+    actorId: inputs.actorId,
+    origin: inputs.origin,
+    documentHashBefore: documentHash(inputs.documentBefore),
+    documentHashAfter: documentHash(inputs.runtime.getCanonicalDocument()),
+    targetScopeSnapshot: snapshot,
+    proposed,
+    compiledOperations: Object.freeze([
+      {
+        kind:
+          inputs.action === "resolve"
+            ? "metadata-issue-resolve"
+            : "metadata-issue-reopen",
+        summary: `${inputs.action} issue ${transition.issueId} on scope ${snapshot.handle.scopeId}`,
+      },
+    ]),
+    validation,
+    emittedAtUtc: inputs.emittedAtUtc,
+  };
+}
+
+export function transitionScopeIssueLifecycle(
+  inputs: TransitionScopeIssueLifecycleInputs,
+): TransitionScopeIssueLifecycleResult {
+  const target = resolveIssueLifecycleTarget(
+    inputs.runtime.getWorkflowMetadataSnapshot(),
+    inputs.issueId,
+  );
+  if (!target) {
+    const reason = `issue-not-found:${inputs.issueId}`;
+    return {
+      transitioned: false,
+      issueId: inputs.issueId,
+      reason,
+      blockers: freezeBlocker(reason),
+    };
+  }
+
+  const transition = transitionAIIssueLifecycle(inputs.runtime, {
+    issueId: target.issueId,
+    action: inputs.action,
+    actorId: inputs.actorId,
+    at: inputs.emittedAtUtc,
+    origin: { source: inputs.origin, at: inputs.emittedAtUtc },
+  });
+
+  if (!transition.transitioned) {
+    const reason = `${transition.reason}:${transition.issueId}`;
+    return {
+      transitioned: false,
+      issueId: transition.issueId,
+      reason,
+      blockers: freezeBlocker(reason),
+      scopeId: target.scopeId,
+      targetScopeSnapshot: inputs.targetScopeSnapshot,
+    };
+  }
+
+  const audit = buildLifecycleAudit(inputs, transition);
+  inputs.bus?.emitLazy("scope", () => ({
+    type: "scope.action_audit",
+    payload: audit,
+  }));
+  return {
+    transitioned: true,
+    issueId: transition.issueId,
+    entryId: transition.entryId,
+    scopeId: target.scopeId,
+    fromStatus: transition.fromStatus,
+    toStatus: transition.toStatus,
+    lifecycleAudit: transition.audit,
+    targetScopeSnapshot: inputs.targetScopeSnapshot,
+    audit,
+  };
+}

package/src/runtime/scopes/layout-evidence.ts

@@ -0,0 +1,374 @@
+/**
+ * Scope layout evidence projection.
+ *
+ * Layer 08 only consumes layout evidence supplied by lower layers. When the
+ * seam is absent or cold, the bundle reports that explicitly instead of
+ * deriving page slices or continuation state from canonical content.
+ */
+
+import type {
+  ScopeLayoutContinuationEvidence,
+  ScopeLayoutEvidence,
+  ScopeTableFrameEvidence,
+  ScopeTableFramePageEvidence,
+} from "./semantic-scope-types.ts";
+
+export interface ScopeLayoutEvidenceEntry {
+  readonly status?: ScopeLayoutEvidence["status"];
+  readonly completeness?: ScopeLayoutEvidence["completeness"];
+  readonly reason?: string;
+  readonly pageSliceIds?: readonly string[];
+  readonly layoutObjectIds?: readonly string[];
+  readonly continuationState?: ScopeLayoutContinuationEvidence;
+  readonly divergenceIds?: readonly string[];
+  readonly tableFrame?: ScopeTableFrameEvidence;
+}
+
+export interface ScopeLayoutEvidenceProvider {
+  getScopeLayoutEvidence(scopeId: string): ScopeLayoutEvidenceEntry | null;
+}
+
+export interface ScopeRuntimeLayoutFragment {
+  readonly fragmentId: string;
+  readonly blockId: string;
+  readonly pageId: string;
+  readonly pageIndex: number;
+  readonly kind?: "whole" | "paragraph-slice" | "table-slice";
+  readonly tableRowRange?: {
+    readonly from: number;
+    readonly to: number;
+    readonly totalRows: number;
+  };
+  readonly continuation?: {
+    readonly kind: string;
+    readonly continuesFromPreviousPage?: boolean;
+    readonly continuesToNextPage?: boolean;
+    readonly repeatedHeaderRowIndexes?: readonly number[];
+    readonly splitRowCarry?: readonly {
+      readonly rowIndex: number;
+      readonly continuesFromPreviousPage: boolean;
+      readonly continuesToNextPage: boolean;
+    }[];
+    readonly verticalMergeCarry?: readonly {
+      readonly columnIndex: number;
+      readonly restartRowIndex: number;
+    }[];
+  };
+  readonly layoutObject?: {
+    readonly objectId?: string;
+  };
+}
+
+export interface ScopeRuntimeLayoutEvidenceSource {
+  getPageCount(): number;
+  getFragmentsForPage(pageIndex: number): readonly ScopeRuntimeLayoutFragment[];
+}
+
+export interface RuntimeTableFrameLayoutEvidenceOptions {
+  readonly layout: ScopeRuntimeLayoutEvidenceSource;
+  readonly tableBlockIdsByBlockIndex?: ReadonlyMap<number, string>;
+}
+
+export interface ScopeRuntimeRenderSnapshotLike {
+  readonly surface?: {
+    readonly blocks?: readonly {
+      readonly kind?: string;
+      readonly blockId?: string;
+    }[];
+  };
+}
+
+function freezeList<T>(values: readonly T[] | undefined): readonly T[] | undefined {
+  return values ? Object.freeze([...values]) : undefined;
+}
+
+function unique<T>(values: readonly T[]): readonly T[] {
+  return Object.freeze([...new Set(values)]);
+}
+
+function parseTableFamilyScopeId(scopeId: string):
+  | { readonly scopeKind: "table"; readonly blockIndex: number }
+  | { readonly scopeKind: "table-row"; readonly blockIndex: number; readonly rowIndex: number }
+  | {
+      readonly scopeKind: "table-cell";
+      readonly blockIndex: number;
+      readonly rowIndex: number;
+      readonly cellIndex: number;
+    }
+  | null {
+  const table = /^table:(\d+)$/.exec(scopeId);
+  if (table) return { scopeKind: "table", blockIndex: Number(table[1]) };
+  const row = /^row:(\d+):(\d+)$/.exec(scopeId);
+  if (row) {
+    return {
+      scopeKind: "table-row",
+      blockIndex: Number(row[1]),
+      rowIndex: Number(row[2]),
+    };
+  }
+  const cell = /^cell:(\d+):(\d+):(\d+)$/.exec(scopeId);
+  if (cell) {
+    return {
+      scopeKind: "table-cell",
+      blockIndex: Number(cell[1]),
+      rowIndex: Number(cell[2]),
+      cellIndex: Number(cell[3]),
+    };
+  }
+  return null;
+}
+
+function candidateTableBlockIds(
+  blockIndex: number,
+  mapped?: ReadonlyMap<number, string>,
+): readonly string[] {
+  const ids: string[] = [];
+  const mappedId = mapped?.get(blockIndex);
+  if (mappedId) ids.push(mappedId);
+  ids.push(`table-${blockIndex}`, `table:${blockIndex}`, `block-${blockIndex}`);
+  return unique(ids);
+}
+
+function rowInFragment(
+  fragment: ScopeRuntimeLayoutFragment,
+  rowIndex: number,
+): boolean {
+  const range = fragment.tableRowRange;
+  if (range && rowIndex >= range.from && rowIndex < range.to) return true;
+  return fragment.continuation?.repeatedHeaderRowIndexes?.includes(rowIndex) === true;
+}
+
+function fragmentMatchesScope(
+  fragment: ScopeRuntimeLayoutFragment,
+  parsed: NonNullable<ReturnType<typeof parseTableFamilyScopeId>>,
+): boolean {
+  if (parsed.scopeKind === "table") return true;
+  return rowInFragment(fragment, parsed.rowIndex);
+}
+
+function collectTableFragments(
+  layout: ScopeRuntimeLayoutEvidenceSource,
+  blockIds: readonly string[],
+  parsed: NonNullable<ReturnType<typeof parseTableFamilyScopeId>>,
+): readonly ScopeRuntimeLayoutFragment[] {
+  const matches: ScopeRuntimeLayoutFragment[] = [];
+  const blockIdSet = new Set(blockIds);
+  for (let pageIndex = 0; pageIndex < layout.getPageCount(); pageIndex += 1) {
+    for (const fragment of layout.getFragmentsForPage(pageIndex)) {
+      if (!blockIdSet.has(fragment.blockId)) continue;
+      if (fragment.kind !== undefined && fragment.kind !== "table-slice" && fragment.kind !== "whole") {
+        continue;
+      }
+      if (!fragmentMatchesScope(fragment, parsed)) continue;
+      matches.push(fragment);
+    }
+  }
+  return Object.freeze(matches);
+}
+
+function projectTableFramePage(
+  fragment: ScopeRuntimeLayoutFragment,
+): ScopeTableFramePageEvidence {
+  const repeated = fragment.continuation?.repeatedHeaderRowIndexes;
+  const splitRowCarry = fragment.continuation?.splitRowCarry;
+  const carry = fragment.continuation?.verticalMergeCarry;
+  return {
+    pageId: fragment.pageId,
+    pageIndex: fragment.pageIndex,
+    fragmentId: fragment.fragmentId,
+    ...(fragment.tableRowRange ? { rowRange: { ...fragment.tableRowRange } } : {}),
+    ...(fragment.continuation?.continuesFromPreviousPage !== undefined
+      ? { continuesFromPreviousPage: fragment.continuation.continuesFromPreviousPage }
+      : {}),
+    ...(fragment.continuation?.continuesToNextPage !== undefined
+      ? { continuesToNextPage: fragment.continuation.continuesToNextPage }
+      : {}),
+    ...(repeated ? { repeatedHeaderRowIndexes: unique(repeated) } : {}),
+    ...(splitRowCarry ? { splitRowCarry: Object.freeze(splitRowCarry.map((item) => ({ ...item }))) } : {}),
+    ...(carry ? { verticalMergeCarry: Object.freeze(carry.map((item) => ({ ...item }))) } : {}),
+  };
+}
+
+function projectTableFrame(
+  blockId: string,
+  parsed: NonNullable<ReturnType<typeof parseTableFamilyScopeId>>,
+  fragments: readonly ScopeRuntimeLayoutFragment[],
+): ScopeTableFrameEvidence {
+  const pageIds = unique(fragments.map((fragment) => fragment.pageId));
+  const pageSliceIds = unique(fragments.map((fragment) => fragment.fragmentId));
+  const layoutObjectIds = unique(
+    fragments
+      .map((fragment) => fragment.layoutObject?.objectId)
+      .filter((objectId): objectId is string => typeof objectId === "string" && objectId.length > 0),
+  );
+  const rowRangesByPage = Object.freeze(fragments.map(projectTableFramePage));
+  const repeatedHeaderRowIndexes = unique(
+    fragments.flatMap((fragment) => fragment.continuation?.repeatedHeaderRowIndexes ?? []),
+  );
+  const verticalMergeCarry = Object.freeze(
+    fragments
+      .flatMap((fragment) => fragment.continuation?.verticalMergeCarry ?? [])
+      .map((item) => ({ ...item })),
+  );
+  const splitRowCarry = Object.freeze(
+    fragments
+      .flatMap((fragment) => fragment.continuation?.splitRowCarry ?? [])
+      .map((item) => ({ ...item })),
+  );
+  return {
+    source: "runtime.layout.table-frame-continuation",
+    blockId,
+    scopeKind: parsed.scopeKind,
+    ...(parsed.scopeKind === "table-row" || parsed.scopeKind === "table-cell"
+      ? { rowIndex: parsed.rowIndex }
+      : {}),
+    ...(parsed.scopeKind === "table-cell" ? { cellIndex: parsed.cellIndex } : {}),
+    ...(pageIds.length > 0 ? { pageIds } : {}),
+    ...(pageSliceIds.length > 0 ? { pageSliceIds } : {}),
+    ...(layoutObjectIds.length > 0 ? { layoutObjectIds } : {}),
+    ...(rowRangesByPage.length > 0 ? { rowRangesByPage } : {}),
+    ...(repeatedHeaderRowIndexes.length > 0 ? { repeatedHeaderRowIndexes } : {}),
+    ...(splitRowCarry.length > 0 ? { splitRowCarry } : {}),
+    ...(verticalMergeCarry.length > 0 ? { verticalMergeCarry } : {}),
+  };
+}
+
+function continuationFromTableFrame(
+  fragments: readonly ScopeRuntimeLayoutFragment[],
+): ScopeLayoutContinuationEvidence {
+  const pageIds = unique(fragments.map((fragment) => fragment.pageId));
+  return {
+    ...(pageIds.length > 0 ? { pageIds } : {}),
+    pageCount: pageIds.length,
+    crossesPageBoundary: pageIds.length > 1,
+    continuedFromPreviousPage: fragments.some(
+      (fragment) => fragment.continuation?.continuesFromPreviousPage === true,
+    ),
+    continuesToNextPage: fragments.some(
+      (fragment) => fragment.continuation?.continuesToNextPage === true,
+    ),
+  };
+}
+
+export function createRuntimeTableFrameLayoutEvidenceProvider(
+  options: RuntimeTableFrameLayoutEvidenceOptions,
+): ScopeLayoutEvidenceProvider {
+  return {
+    getScopeLayoutEvidence(scopeId) {
+      const parsed = parseTableFamilyScopeId(scopeId);
+      if (!parsed) return null;
+
+      const blockIds = candidateTableBlockIds(
+        parsed.blockIndex,
+        options.tableBlockIdsByBlockIndex,
+      );
+      const fragments = collectTableFragments(options.layout, blockIds, parsed);
+      if (fragments.length === 0) return null;
+
+      const blockId = fragments[0]?.blockId ?? blockIds[0] ?? `table-${parsed.blockIndex}`;
+      const tableFrame = projectTableFrame(blockId, parsed, fragments);
+      const pageSliceIds = tableFrame.pageSliceIds;
+      const layoutObjectIds = tableFrame.layoutObjectIds;
+      const cellScoped = parsed.scopeKind === "table-cell";
+      return {
+        status: "available",
+        completeness: cellScoped ? "partial" : "complete",
+        reason: cellScoped
+          ? "l04-table-frame-row-level-evidence"
+          : "l04-table-frame-continuation",
+        ...(pageSliceIds ? { pageSliceIds } : {}),
+        ...(layoutObjectIds ? { layoutObjectIds } : {}),
+        continuationState: continuationFromTableFrame(fragments),
+        tableFrame,
+      };
+    },
+  };
+}
+
+export function collectTopLevelTableBlockIdsFromRenderSnapshot(
+  snapshot: ScopeRuntimeRenderSnapshotLike | null | undefined,
+): ReadonlyMap<number, string> {
+  const out = new Map<number, string>();
+  const blocks = snapshot?.surface?.blocks ?? [];
+  blocks.forEach((block, blockIndex) => {
+    if (block.kind === "table" && typeof block.blockId === "string") {
+      out.set(blockIndex, block.blockId);
+    }
+  });
+  return out;
+}
+
+function cloneTableFrame(
+  tableFrame: ScopeTableFrameEvidence,
+): ScopeTableFrameEvidence {
+  return {
+    ...tableFrame,
+    ...(tableFrame.pageIds ? { pageIds: freezeList(tableFrame.pageIds) } : {}),
+    ...(tableFrame.pageSliceIds ? { pageSliceIds: freezeList(tableFrame.pageSliceIds) } : {}),
+    ...(tableFrame.layoutObjectIds ? { layoutObjectIds: freezeList(tableFrame.layoutObjectIds) } : {}),
+    ...(tableFrame.rowRangesByPage
+      ? {
+          rowRangesByPage: Object.freeze(
+            tableFrame.rowRangesByPage.map((row) => ({
+              ...row,
+              ...(row.rowRange ? { rowRange: { ...row.rowRange } } : {}),
+              ...(row.repeatedHeaderRowIndexes
+                ? { repeatedHeaderRowIndexes: freezeList(row.repeatedHeaderRowIndexes) }
+                : {}),
+              ...(row.splitRowCarry
+                ? { splitRowCarry: Object.freeze(row.splitRowCarry.map((item) => ({ ...item }))) }
+                : {}),
+              ...(row.verticalMergeCarry
+                ? { verticalMergeCarry: Object.freeze(row.verticalMergeCarry.map((item) => ({ ...item }))) }
+                : {}),
+            })),
+          ),
+        }
+      : {}),
+    ...(tableFrame.repeatedHeaderRowIndexes
+      ? { repeatedHeaderRowIndexes: freezeList(tableFrame.repeatedHeaderRowIndexes) }
+      : {}),
+    ...(tableFrame.splitRowCarry
+      ? { splitRowCarry: Object.freeze(tableFrame.splitRowCarry.map((item) => ({ ...item }))) }
+      : {}),
+    ...(tableFrame.verticalMergeCarry
+      ? { verticalMergeCarry: Object.freeze(tableFrame.verticalMergeCarry.map((item) => ({ ...item }))) }
+      : {}),
+  };
+}
+
+export function deriveScopeLayoutEvidence(
+  scopeId: string,
+  provider?: ScopeLayoutEvidenceProvider,
+): ScopeLayoutEvidence {
+  if (!provider) {
+    return {
+      status: "unavailable",
+      completeness: "unavailable",
+      reason: "layout-evidence-provider-unavailable",
+    };
+  }
+
+  const entry = provider.getScopeLayoutEvidence(scopeId);
+  if (!entry) {
+    return {
+      status: "requires-rehydration",
+      completeness: "requires-rehydration",
+      reason: "scope-layout-evidence-unavailable",
+    };
+  }
+
+  const status = entry.status ?? "available";
+  return {
+    status,
+    completeness: entry.completeness ?? (status === "available" ? "complete" : status),
+    ...(entry.reason ? { reason: entry.reason } : {}),
+    ...(entry.pageSliceIds ? { pageSliceIds: freezeList(entry.pageSliceIds) } : {}),
+    ...(entry.layoutObjectIds ? { layoutObjectIds: freezeList(entry.layoutObjectIds) } : {}),
+    ...(entry.continuationState
+      ? { continuationState: { ...entry.continuationState } }
+      : {}),
+    ...(entry.divergenceIds ? { divergenceIds: freezeList(entry.divergenceIds) } : {}),
+    ...(entry.tableFrame ? { tableFrame: cloneTableFrame(entry.tableFrame) } : {}),
+  };
+}