@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/scopes/evidence.ts

@@ -0,0 +1,233 @@
+/**
+ * Slice 3 — scope-bundle evidence composer.
+ *
+ * Given a compiled `SemanticScope` + live document, collect the review
+ * items, overlapping workflow scopes, and formatting summary that ride
+ * alongside the scope in a `ScopeBundle`.
+ *
+ * Compatibility flags are left empty at Slice 3 — they land with the
+ * unified `ValidationResult` contract in Slice 4. Keeping the field on
+ * the returned shape (rather than omitting it) avoids a breaking shape
+ * change when Slice 4 fills it.
+ */
+
+import type {
+  CanonicalAnchor,
+  CanonicalDocument,
+  CommentThread,
+  RevisionRecord,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  WorkflowMetadataEntry,
+  WorkflowOverlay,
+} from "./_scope-dependencies.ts";
+
+import { AI_EXPLANATION_METADATA_ID } from "./attach-explanation.ts";
+import { AI_ISSUE_METADATA_ID } from "./create-issue.ts";
+import type { EnumeratedScope } from "./enumerate-scopes.ts";
+import { buildScopePositionMap, type ScopePositionRange } from "./position-map.ts";
+import { rangesOverlap, resolveScopeRange } from "./scope-range.ts";
+import type {
+  AIExplanationSummary,
+  AIIssueSummary,
+  ScopeBundleEvidence,
+  SemanticScope,
+} from "./semantic-scope-types.ts";
+
+function anchorRange(anchor: CanonicalAnchor): ScopePositionRange | null {
+  switch (anchor.kind) {
+    case "range":
+      return { from: anchor.range.from, to: anchor.range.to };
+    case "node":
+      return { from: anchor.at, to: anchor.at };
+    case "detached":
+      return anchor.lastKnownRange;
+    default:
+      return null;
+  }
+}
+
+function formattingSummaryOf(scope: SemanticScope): string {
+  const parts: string[] = [];
+  if (scope.formatting.paragraphStyleId) {
+    parts.push(`style=${scope.formatting.paragraphStyleId}`);
+  }
+  if (typeof scope.formatting.outlineLevel === "number") {
+    parts.push(`outline=${scope.formatting.outlineLevel}`);
+  }
+  if (scope.formatting.numbering) {
+    parts.push(
+      `numbering=${scope.formatting.numbering.numberingInstanceId}:${scope.formatting.numbering.level}`,
+    );
+  }
+  if (scope.formatting.tableRole) {
+    parts.push(`role=${scope.formatting.tableRole}`);
+  }
+  if (scope.formatting.emphasis && scope.formatting.emphasis.length > 0) {
+    parts.push(`emphasis=${scope.formatting.emphasis.join("+")}`);
+  }
+  return parts.join(" ") || "(none)";
+}
+
+export interface EvidenceInputs {
+  readonly scope: SemanticScope;
+  readonly document: Pick<CanonicalDocument, "content" | "review"> | CanonicalDocumentEnvelope;
+  readonly overlay?: WorkflowOverlay | null;
+  /**
+   * Pre-enumerated scopes used to resolve the bundle's own scope range +
+   * overlap with other scopes. When absent, the composer re-enumerates.
+   */
+  readonly scopes: readonly EnumeratedScope[];
+  /**
+   * Workflow-metadata entries to project into the bundle as
+   * `aiExplanations` + `aiIssues`. When absent, those fields are omitted.
+   * Callers that have a live runtime typically pass
+   * `runtime.getWorkflowMetadataSnapshot().entries` through here.
+   */
+  readonly workflowMetadataEntries?: readonly WorkflowMetadataEntry[];
+}
+
+function normalizeSeverity(raw: unknown): AIIssueSummary["severity"] {
+  if (raw === "warning" || raw === "error") return raw;
+  return "info";
+}
+
+function normalizeStatus(raw: unknown): AIIssueSummary["status"] {
+  if (raw === "resolved") return raw;
+  return "open";
+}
+
+function projectAIExplanation(
+  entry: WorkflowMetadataEntry,
+): AIExplanationSummary | null {
+  const value = entry.value as
+    | { explanationId?: string; text?: string; createdAtUtc?: string }
+    | undefined;
+  if (!value || typeof value.text !== "string") return null;
+  return {
+    explanationId:
+      typeof value.explanationId === "string" && value.explanationId.length > 0
+        ? value.explanationId
+        : entry.entryId,
+    text: value.text,
+    ...(typeof value.createdAtUtc === "string"
+      ? { createdAtUtc: value.createdAtUtc }
+      : {}),
+  };
+}
+
+function projectAIIssue(
+  entry: WorkflowMetadataEntry,
+): AIIssueSummary | null {
+  const value = entry.value as
+    | {
+        issueId?: string;
+        summary?: string;
+        severity?: unknown;
+        status?: unknown;
+        createdAtUtc?: string;
+      }
+    | undefined;
+  if (!value || typeof value.summary !== "string") return null;
+  return {
+    issueId:
+      typeof value.issueId === "string" && value.issueId.length > 0
+        ? value.issueId
+        : entry.entryId,
+    summary: value.summary,
+    severity: normalizeSeverity(value.severity),
+    status: normalizeStatus(value.status),
+    ...(typeof value.createdAtUtc === "string"
+      ? { createdAtUtc: value.createdAtUtc }
+      : {}),
+  };
+}
+
+function findEntryForScope(
+  scope: SemanticScope,
+  scopes: readonly EnumeratedScope[],
+): EnumeratedScope | null {
+  return scopes.find((entry) => entry.handle.scopeId === scope.handle.scopeId) ?? null;
+}
+
+export function composeEvidence(inputs: EvidenceInputs): ScopeBundleEvidence {
+  const { scope, document, overlay, scopes } = inputs;
+  const positionMap = buildScopePositionMap(document);
+  const entry = findEntryForScope(scope, scopes);
+  const selfRange = entry
+    ? resolveScopeRange(entry, scope.handle, positionMap)
+    : null;
+
+  const reviewItemIds: string[] = [];
+  const overlappingWorkflowScopeIds: string[] = [];
+  const compatibilityFlags: string[] = [];
+
+  if (selfRange) {
+    const review = (document as {
+      review?: {
+        comments?: Record<string, CommentThread>;
+        revisions?: Record<string, RevisionRecord>;
+      };
+    }).review;
+    if (review) {
+      for (const thread of Object.values(review.comments ?? {})) {
+        const range = anchorRange(thread.anchor);
+        if (range && rangesOverlap(selfRange, range)) {
+          reviewItemIds.push(thread.commentId);
+        }
+      }
+      for (const rev of Object.values(review.revisions ?? {})) {
+        const range = anchorRange(rev.anchor);
+        if (range && rangesOverlap(selfRange, range)) {
+          reviewItemIds.push(rev.changeId);
+        }
+      }
+    }
+
+    if (overlay?.scopes) {
+      for (const other of overlay.scopes) {
+        if (other.scopeId === scope.handle.scopeId) continue;
+        const markerRange = positionMap.markerScopes.get(other.scopeId);
+        if (markerRange && rangesOverlap(selfRange, markerRange)) {
+          overlappingWorkflowScopeIds.push(other.scopeId);
+        }
+      }
+    }
+  }
+
+  reviewItemIds.sort();
+  overlappingWorkflowScopeIds.sort();
+
+  // Adversarial-close item 1 — read-side join for ai.explanation + ai.issue.
+  // Filter workflow-metadata entries by scopeId + metadataId; project
+  // into narrow summary shapes. Empty arrays are OK to include (the
+  // consumer sees "no explanations yet" as explicit rather than "field
+  // not supported").
+  const aiExplanations: AIExplanationSummary[] = [];
+  const aiIssues: AIIssueSummary[] = [];
+  if (inputs.workflowMetadataEntries) {
+    for (const entry of inputs.workflowMetadataEntries) {
+      if (entry.scopeId !== scope.handle.scopeId) continue;
+      if (entry.metadataId === AI_EXPLANATION_METADATA_ID) {
+        const projected = projectAIExplanation(entry);
+        if (projected) aiExplanations.push(projected);
+      } else if (entry.metadataId === AI_ISSUE_METADATA_ID) {
+        const projected = projectAIIssue(entry);
+        if (projected) aiIssues.push(projected);
+      }
+    }
+  }
+  aiExplanations.sort((a, b) => a.explanationId.localeCompare(b.explanationId));
+  aiIssues.sort((a, b) => a.issueId.localeCompare(b.issueId));
+
+  return {
+    formattingSummary: formattingSummaryOf(scope),
+    reviewItemIds,
+    overlappingWorkflowScopeIds,
+    compatibilityFlags,
+    ...(inputs.workflowMetadataEntries
+      ? { aiExplanations, aiIssues }
+      : {}),
+  };
+}

package/src/runtime/scopes/index.ts

@@ -0,0 +1,150 @@
+/**
+ * Layer 08 — Semantic Scope Compiler · barrel.
+ *
+ * See `docs/architecture/08-semantic-scope-compiler.md` for the end-state
+ * spec. Slice 1 ships:
+ *
+ *   - core types (`semantic-scope-types.ts`)
+ *   - compile dispatcher + paragraph/heading/list-item kind files
+ *   - enumerate-scopes over the main-story paragraph stream
+ *   - replaceability first cut
+ *   - debug projector (producer-only; snapshot wiring is a follow-up)
+ *
+ * Purity invariant: this module must not import from src/api/v3, src/ui-,
+ * src/ui/, or src/io. Enforced by
+ * scripts/ci-check-scope-compiler-purity.mjs.
+ */
+
+export { isStructuredReplacementContent } from "./semantic-scope-types.ts";
+export type {
+  AIExplanationSummary,
+  AIIssueSummary,
+  StructuredReplacementContent,
+  GeometryRect,
+  Replaceability,
+  ReplaceabilityLevel,
+  ReplacementOperationKind,
+  ReplacementPreservePolicy,
+  ReplacementScope,
+  RuntimeOperationPlan,
+  RuntimeOperationStep,
+  RuntimeOperationStepKind,
+  ScopeActionAudit,
+  ScopeBundle,
+  ScopeBundleEvidence,
+  ScopeBundleNeighborhood,
+  ScopeCompilerDebugEntry,
+  ScopeHandle,
+  ScopeProvenance,
+  ScopeStableRef,
+  SemanticScope,
+  SemanticScopeAudit,
+  SemanticScopeContent,
+  SemanticScopeFormatting,
+  SemanticScopeGeometry,
+  SemanticScopeKind,
+  SemanticScopeLayout,
+  SemanticScopeLineSpan,
+  SemanticScopeNumbering,
+  SemanticScopeWorkflow,
+  ValidationApproval,
+  ValidationIssue,
+  ValidationResult,
+} from "./semantic-scope-types.ts";
+
+export {
+  buildParagraphIndexMap,
+  buildSectionIndexByBlockIndex,
+  compileScope,
+  type CompileScopeOptions,
+} from "./compile-scope.ts";
+export {
+  compileScopeBundle,
+  compileScopeBundleById,
+  type ScopeBundleInputs,
+} from "./compile-scope-bundle.ts";
+export {
+  enumerateScopes,
+  type CommentThreadEnumeratedScope,
+  type EnumerateScopesInputs,
+  type EnumeratedScope,
+  type FieldEnumeratedScope,
+  type ParagraphLikeEnumeratedScope,
+  type RevisionEnumeratedScope,
+  type TableCellEnumeratedScope,
+  type TableEnumeratedScope,
+  type TableRowEnumeratedScope,
+} from "./enumerate-scopes.ts";
+export { composeEvidence, type EvidenceInputs } from "./evidence.ts";
+export {
+  buildScopePositionMap,
+  computeBlockPositions,
+  type BlockPositionEntry,
+  type ScopePositionMap,
+  type ScopePositionRange,
+} from "./position-map.ts";
+export {
+  composeReviewBundle,
+  type ComposeReviewBundleInputs,
+  type ReviewBundle,
+  type ReviewBundleCommentSummary,
+  type ReviewBundleRevisionSummary,
+} from "./review-bundle.ts";
+export {
+  resolveReference,
+  type ResolveReferenceInputs,
+  type ResolveReferenceResult,
+  type ScopeReference,
+} from "./resolve-reference.ts";
+export { deriveReplaceability } from "./replaceability.ts";
+export {
+  composeScopeValidation,
+  type ComposeScopeValidationInputs,
+} from "./action-validation.ts";
+export {
+  computePreservationVerdict,
+  type PreservationVerdict,
+} from "./preservation-boundary.ts";
+export { projectScopeDebugEntry, type ProjectScopeOptions } from "./projector.ts";
+export {
+  buildScopeActionAudit,
+  emitScopeActionAudit,
+  type EmitScopeActionAuditInputs,
+} from "./audit-bundle.ts";
+export {
+  proposeReplacement,
+  type ReplacementProposalInput,
+} from "./replacement/propose.ts";
+export {
+  compileReplacement,
+  type CompileReplacementInputs,
+} from "./replacement/compile.ts";
+export {
+  applyScopeReplacement,
+  type ApplyScopeReplacementInputs,
+  type ApplyScopeReplacementResult,
+  type ApplyScopeReplacementSink,
+} from "./replacement/apply.ts";
+export {
+  attachExplanation,
+  AI_EXPLANATION_METADATA_ID,
+  type AttachExplanationInput,
+  type AttachExplanationResult,
+} from "./attach-explanation.ts";
+export {
+  createIssue,
+  AI_ISSUE_METADATA_ID,
+  type CreateIssueInput,
+  type CreateIssueResult,
+  type IssueSeverity,
+  type IssueStatus,
+} from "./create-issue.ts";
+export {
+  createScopeCompilerService,
+  type ApplyReplacementRequest,
+  type AttachExplanationRequest,
+  type CompileScopeByIdResult,
+  type CompilerServiceRuntime,
+  type CreateIssueRequest,
+  type ScopeCompilerService,
+} from "./compiler-service.ts";

package/src/runtime/scopes/position-map.ts

@@ -0,0 +1,214 @@
+/**
+ * Slice 3 — scope position map.
+ *
+ * Computes a `{ from, to }` range in PM-style document coordinates for every
+ * enumerated scope. Offset / range / marker-backed overlap lookups consume
+ * it. The algorithm mirrors `src/runtime/scope-resolver.ts::walkParagraphs`
+ * so derived and marker-backed positions line up byte-for-byte.
+ *
+ * Two precision tiers shipped here:
+ *   - Block ranges — one `[from, to]` per document-root block, matching the
+ *     canonical walker (`scope-resolver.ts::walkParagraphs`). Used for
+ *     paragraph-like and table-like kinds.
+ *   - Inline ranges — one `[from, to]` per paragraph-child slot. Used for
+ *     nested inline kinds (fields) so scope resolution can snap to the
+ *     actual field span inside a paragraph rather than the whole paragraph.
+ *
+ * Pagination / geometric enrichment lives in layers 04 + 05; this map is
+ * purely canonical walk arithmetic.
+ */
+
+import type {
+  CanonicalDocument,
+  DocumentRootNode,
+  InlineNode,
+  ParagraphNode,
+  TableNode,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+
+import { collectScopeLocations } from "../workflow/scope-resolver.ts";
+
+export interface ScopePositionRange {
+  readonly from: number;
+  readonly to: number;
+}
+
+function inlineLength(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "hyperlink":
+    case "field":
+      return node.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return 0;
+    default:
+      return 1;
+  }
+}
+
+export interface BlockPositionEntry {
+  readonly blockIndex: number;
+  readonly from: number;
+  readonly to: number;
+}
+
+/**
+ * Walk the root's block children and compute each block's start/end
+ * position. Matches the walker inside `scope-resolver.ts` — cursor starts
+ * at 0, each paragraph's content length adds to the cursor, and every
+ * non-last block adds 1 for its boundary.
+ */
+export function computeBlockPositions(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+): BlockPositionEntry[] {
+  const envelope = document as CanonicalDocumentEnvelope;
+  const root: DocumentRootNode =
+    "content" in envelope
+      ? (envelope.content as DocumentRootNode)
+      : (document as unknown as DocumentRootNode);
+
+  const out: BlockPositionEntry[] = [];
+  let cursor = 0;
+  for (let index = 0; index < root.children.length; index += 1) {
+    const block = root.children[index];
+    const from = cursor;
+    let length = 0;
+    if (block && block.type === "paragraph") {
+      length = (block as ParagraphNode).children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    } else {
+      // Tables + other block atoms occupy one slot in the document walker.
+      length = 1;
+    }
+    cursor += length;
+    const to = cursor;
+    out.push({ blockIndex: index, from, to });
+    if (index < root.children.length - 1) {
+      cursor += 1;
+    }
+  }
+  return out;
+}
+
+/**
+ * Build inline-offset ranges for every child of every paragraph. The key
+ * convention matches the `field` enumeration in `enumerate-scopes.ts`:
+ * `${blockIndex}:${inlineIndex}`. Zero-width inlines (bookmarks, markers)
+ * get `[cursor, cursor]`; real inlines get `[cursor, cursor + length]`.
+ */
+export function computeInlinePositions(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+  blocks: readonly BlockPositionEntry[],
+): Map<string, ScopePositionRange> {
+  const envelope = document as CanonicalDocumentEnvelope;
+  const root: DocumentRootNode =
+    "content" in envelope
+      ? (envelope.content as DocumentRootNode)
+      : (document as unknown as DocumentRootNode);
+  const out = new Map<string, ScopePositionRange>();
+  for (let idx = 0; idx < root.children.length; idx += 1) {
+    const block = root.children[idx];
+    if (!block || block.type !== "paragraph") continue;
+    const blockEntry = blocks[idx];
+    if (!blockEntry) continue;
+    let cursor = blockEntry.from;
+    const paragraph = block as ParagraphNode;
+    for (let i = 0; i < paragraph.children.length; i += 1) {
+      const child = paragraph.children[i] as InlineNode;
+      const length = inlineLength(child);
+      out.set(`${idx}:${i}`, { from: cursor, to: cursor + length });
+      cursor += length;
+    }
+  }
+  return out;
+}
+
+/**
+ * Range for a single table row, computed as a proportional subrange of the
+ * table's 1-slot canonical range. Tables are collapsed into a single walker
+ * slot (`+1`) so precise row/cell offsets do not exist in canonical
+ * coordinates; we synthesize deterministic non-overlapping subranges here
+ * using a scaled `[0, 1)` partitioning against `table.rows.length`.
+ *
+ * The returned range carries fractional `from` / `to`. Callers that need
+ * integer positions should treat the row's container block as authoritative
+ * and rely on specificity ordering (see `resolve-reference.ts`). These
+ * fractional ranges exist so `rangesOverlap` can distinguish one row from
+ * another within the same table.
+ */
+export function computeTableRowRange(
+  table: TableNode,
+  rowIndex: number,
+  tableRange: ScopePositionRange,
+): ScopePositionRange {
+  const rowCount = Math.max(1, table.rows.length);
+  const span = tableRange.to - tableRange.from;
+  if (span <= 0) {
+    // Degenerate — fall back to identity. This preserves the pre-fix
+    // behaviour (tie on range) but marks each row with a unique offset
+    // within the tie via `scopeSpecificity`.
+    return tableRange;
+  }
+  const step = span / rowCount;
+  const from = tableRange.from + step * rowIndex;
+  const to = tableRange.from + step * (rowIndex + 1);
+  return { from, to };
+}
+
+/**
+ * Range for a single cell, computed as a proportional subrange of the
+ * enclosing row's range.
+ */
+export function computeTableCellRange(
+  row: TableNode["rows"][number],
+  cellIndex: number,
+  rowRange: ScopePositionRange,
+): ScopePositionRange {
+  const cellCount = Math.max(1, row.cells.length);
+  const span = rowRange.to - rowRange.from;
+  if (span <= 0) return rowRange;
+  const step = span / cellCount;
+  const from = rowRange.from + step * cellIndex;
+  const to = rowRange.from + step * (cellIndex + 1);
+  return { from, to };
+}
+
+export interface ScopePositionMap {
+  /** Marker-backed scopeId → PM-position range. */
+  readonly markerScopes: ReadonlyMap<string, ScopePositionRange>;
+  /** Derived block scopeId → PM-position range. `blockIndex` is the key. */
+  readonly blocks: ReadonlyMap<number, ScopePositionRange>;
+  /** Inline-position ranges, keyed `${blockIndex}:${inlineIndex}`. */
+  readonly inlines: ReadonlyMap<string, ScopePositionRange>;
+}
+
+export function buildScopePositionMap(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+): ScopePositionMap {
+  const locations = collectScopeLocations(document);
+  const markerScopes = new Map<string, ScopePositionRange>();
+  for (const [scopeId, loc] of locations) {
+    if (loc.startPos === undefined || loc.endPos === undefined) continue;
+    markerScopes.set(scopeId, {
+      from: Math.min(loc.startPos, loc.endPos),
+      to: Math.max(loc.startPos, loc.endPos),
+    });
+  }
+  const blockEntries = computeBlockPositions(document);
+  const blocks = new Map<number, ScopePositionRange>();
+  for (const entry of blockEntries) {
+    blocks.set(entry.blockIndex, { from: entry.from, to: entry.to });
+  }
+  const inlines = computeInlinePositions(document, blockEntries);
+  return { markerScopes, blocks, inlines };
+}

package/src/runtime/scopes/preservation-boundary.ts

@@ -0,0 +1,91 @@
+/**
+ * Layer 08 — preservation-boundary helper (Slice 4 interim).
+ *
+ * Computes whether a scope's canonical range crosses any preserve-only
+ * boundary that would be destroyed by a replace/split/insert operation.
+ * Sources consulted:
+ *
+ *   - `document.preservation.opaqueFragments` — `OpaqueFragmentRecord[]`
+ *     with `lastKnownRange` + `featureClass: "preserve-only"`. Any
+ *     overlap is a blocker.
+ *   - `document.preservation.packageParts` — package-level parts
+ *     (image blobs, embed parts). Not range-keyed; their presence is
+ *     not by itself a scope-level blocker — the opaque-fragment records
+ *     are the scope-visible projection of package-level preservation.
+ *   - scope markers inside the target range (handled via the scope's own
+ *     range computation — scope markers that bracket THIS scope are the
+ *     scope's identity; markers *inside* the range would be destroyed by
+ *     a replace, and are surfaced here).
+ *
+ * Scope-local, plain-value, synchronous. Purity allowlist
+ * (`scripts/ci-check-scope-compiler-purity.mjs`) already permits imports
+ * from `src/model/**`.
+ *
+ * Slice 7 can extract this helper into `src/preservation/**` if a
+ * cross-layer home makes sense. Until then it stays scope-local so the
+ * composer has no cross-lane dependency.
+ */
+
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import { findOpaqueFragmentsIntersectingRange } from "../../preservation/store.ts";
+
+import type { ScopePositionMap, ScopePositionRange } from "./position-map.ts";
+
+export interface PreservationVerdict {
+  readonly replaceable: boolean;
+  readonly reasons: readonly string[];
+}
+
+/**
+ * Return the preservation verdict for a scope's canonical range. The
+ * returned `reasons` array carries stable suffix keys that the composer
+ * prefixes with `preserve:` before surfacing them on
+ * `ValidationResult.blockedReasons`.
+ *
+ * Callers without a position map or without a resolved range get a
+ * permissive verdict — the composer treats that as "preservation signal
+ * unavailable, no blockers from this source". The architecture contract
+ * (S4 — validate before apply) still requires callers to have a resolved
+ * scope range before any apply; this helper is not the place to enforce
+ * that, it's the composer's.
+ */
+export function computePreservationVerdict(
+  document: CanonicalDocument | null | undefined,
+  range: ScopePositionRange | null,
+  positionMap: ScopePositionMap | null | undefined,
+): PreservationVerdict {
+  if (!document || !range) {
+    return { replaceable: true, reasons: [] };
+  }
+  const reasons: string[] = [];
+
+  const fragments = findOpaqueFragmentsIntersectingRange(
+    document.preservation,
+    { from: range.from, to: range.to },
+  );
+  for (const fragment of fragments) {
+    reasons.push(
+      `opaque-fragment:${fragment.fragmentId}:${fragment.payloadKind}`,
+    );
+  }
+
+  if (positionMap) {
+    for (const [scopeId, markerRange] of positionMap.markerScopes) {
+      // A marker range strictly inside the target range would be
+      // destroyed by replace. Equality (marker pair bracketing the scope
+      // itself) is *not* a blocker — that marker IS the scope's identity.
+      if (
+        markerRange.from > range.from &&
+        markerRange.to < range.to
+      ) {
+        reasons.push(`scope-marker-inside:${scopeId}`);
+      }
+    }
+  }
+
+  reasons.sort();
+  return {
+    replaceable: reasons.length === 0,
+    reasons: Object.freeze(reasons),
+  };
+}