@beyondwork/docx-react-component 1.0.105 → 1.0.108

package/src/runtime/scopes/multi-paragraph-refusal.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared KI-014 refusal facts for marker-backed multi-paragraph scopes.
+ *
+ * These blockers are evidence only: they describe why broad replacement is
+ * still disabled and which facts must exist before L08 can safely lower it.
+ */
+
+export type MultiParagraphReplacementShape = "text" | "fragment" | "unknown";
+
+export const MULTI_PARAGRAPH_REPLACEMENT_REFUSAL =
+  "compile-refused:scope:multi-paragraph-replace-not-implemented";
+
+function shapeBlocker(shape: MultiParagraphReplacementShape): string {
+  switch (shape) {
+    case "text":
+      return "compile-refused:scope:multi-paragraph-text-replace-not-implemented";
+    case "fragment":
+      return "compile-refused:scope:multi-paragraph-fragment-replace-not-implemented";
+    default:
+      return "compile-refused:scope:multi-paragraph-replace-shape-not-implemented";
+  }
+}
+
+export function multiParagraphReplacementBlockers(
+  shape: MultiParagraphReplacementShape = "unknown",
+): readonly string[] {
+  return Object.freeze([
+    MULTI_PARAGRAPH_REPLACEMENT_REFUSAL,
+    shapeBlocker(shape),
+    "capability:scope:block-granular-replacement-lowering-required",
+    "capability:scope:provenance:marker-backed-required",
+    "capability:scope:layout-completeness-required",
+    "capability:scope:geometry-completeness-required",
+    "capability:scope:continuation-state-required",
+    "capability:scope:preservation-verdict-required",
+  ]);
+}

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

@@ -2,7 +2,7 @@
  * 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.
+ * boundary that would be destroyed by a replacement operation.
  * Sources consulted:
  *
  *   - `document.preservation.opaqueFragments` — `OpaqueFragmentRecord[]`
@@ -29,6 +29,7 @@
 import type { CanonicalDocument } from "../../model/canonical-document.ts";
 import { findOpaqueFragmentsIntersectingRange } from "../../preservation/store.ts";
 
+import { findContentControlsIntersectingRange } from "./content-control-evidence.ts";
 import type { ScopePositionMap, ScopePositionRange } from "./position-map.ts";
 
 export interface PreservationVerdict {
@@ -69,6 +70,11 @@ export function computePreservationVerdict(
     );
   }
 
+  const contentControls = findContentControlsIntersectingRange(document, range);
+  for (const control of contentControls) {
+    reasons.push(`content-control:${control.evidenceId}`);
+  }
+
   if (positionMap) {
     for (const [scopeId, markerRange] of positionMap.markerScopes) {
       // A marker range strictly inside the target range would be

package/src/runtime/scopes/replacement/apply.ts

@@ -33,6 +33,10 @@ import { enumerateScopes } from "../enumerate-scopes.ts";
 import type { EnumeratedScope } from "../enumerate-scopes.ts";
 import { emitScopeActionAudit } from "../audit-bundle.ts";
 import { compileReplacement } from "./compile.ts";
+import {
+  MULTI_PARAGRAPH_REPLACEMENT_REFUSAL,
+  multiParagraphReplacementBlockers,
+} from "../multi-paragraph-refusal.ts";
 import type {
   ReplacementScope,
   RuntimeOperationPlan,
@@ -47,6 +51,7 @@ export interface ApplyScopeReplacementSink {
   readonly getInteractionGuardSnapshot: () => InteractionGuardSnapshot;
   readonly getCompatibilityReport: () => CompatibilityReport;
   readonly applyScopeReplacement: (plan: RuntimeOperationPlan) => void;
+  readonly verifyReadback?: boolean;
 }
 
 export interface ApplyScopeReplacementInputs {
@@ -80,19 +85,28 @@ export interface ApplyScopeReplacementResult {
 }
 
 function documentHash(doc: CanonicalDocumentEnvelope): string {
-  // Cheap structural hash — block-count + total text length. Good enough
-  // for the audit's "something changed" signal; later slices can swap in
-  // a canonical serializer-backed content hash.
-  const root = doc.content;
-  let textLength = 0;
-  for (const block of root.children) {
-    if (block.type === "paragraph") {
-      for (const child of block.children) {
-        if (child.type === "text") textLength += child.text.length;
-      }
-    }
+  // Structural content hash. This is intentionally stronger than length-only
+  // so same-length stale/no-op replacements do not report as successful edits.
+  return JSON.stringify(doc.content);
+}
+
+function compileScopeById(
+  document: CanonicalDocumentEnvelope,
+  overlay: WorkflowOverlay | undefined,
+  scopeId: string,
+): { readonly scope: SemanticScope; readonly entry: EnumeratedScope } | null {
+  const paragraphIndexByBlockIndex = buildParagraphIndexMap(document);
+  const enumerateInputs = overlay ? { overlay } : {};
+  for (const entry of enumerateScopes(document, enumerateInputs)) {
+    if (entry.handle.scopeId !== scopeId) continue;
+    const compiled = compileScope(entry, {
+      document,
+      ...(overlay ? { overlay } : {}),
+      paragraphIndexByBlockIndex,
+    });
+    if (compiled) return { scope: compiled, entry };
   }
-  return `blocks:${root.children.length}|text:${textLength}`;
+  return null;
 }
 
 export function applyScopeReplacement(
@@ -102,27 +116,18 @@ export function applyScopeReplacement(
   const docBefore = inputs.sink.getCanonicalDocument();
   const overlay = inputs.sink.getWorkflowOverlay() ?? undefined;
 
-  const paragraphIndexByBlockIndex = buildParagraphIndexMap(docBefore);
-  let resolvedScope: SemanticScope | null = null;
-  let resolvedEnumerated: EnumeratedScope | null = null;
-  const enumerateInputs = overlay ? { overlay } : {};
-  for (const entry of enumerateScopes(docBefore, enumerateInputs)) {
-    if (entry.handle.scopeId !== proposed.targetHandle.scopeId) continue;
-    const compiled = compileScope(entry, {
-      document: docBefore,
-      ...(overlay ? { overlay } : {}),
-      paragraphIndexByBlockIndex,
-    });
-    if (compiled) {
-      resolvedScope = compiled;
-      resolvedEnumerated = entry;
-      break;
-    }
-  }
+  const resolved = compileScopeById(
+    docBefore,
+    overlay,
+    proposed.targetHandle.scopeId,
+  );
+  const resolvedScope = resolved?.scope ?? null;
+  const resolvedEnumerated = resolved?.entry ?? null;
 
   if (!resolvedScope || !resolvedEnumerated) {
     const validation: ValidationResult = {
       safe: false,
+      posture: "hard-refusal",
       blockedReasons: Object.freeze([
         `scope-not-resolvable:${proposed.targetHandle.scopeId}`,
       ]),
@@ -207,15 +212,30 @@ export function applyScopeReplacement(
     // `blockers[0]` / `reason` see the actionable sub-reason directly
     // (rather than the bare `compile-refused:scope`). Grammar matches
     // §10 `compile-refused:<kind>:<sub-reason>` (74a45eaf, 2026-04-23).
-    const blocker =
+    const blockers =
       resolvedScope.kind === "scope"
-        ? "compile-refused:scope:multi-paragraph-replace-not-implemented"
+        ? multiParagraphReplacementBlockers(
+            proposed.proposedContent.kind === "structured" ? "fragment" : "text",
+          )
+        : paragraphLike &&
+            proposed.operation === "replace" &&
+            proposed.preserve?.opaqueFragments === true
+          ? [
+              `compile-refused:${resolvedScope.kind}:opaque-preserving-text-target-unavailable`,
+            ]
         : paragraphLike && proposed.operation !== "replace"
-          ? `compile-refused:${resolvedScope.kind}:operation-not-implemented:${proposed.operation}`
-          : `compile-refused:${resolvedScope.kind}`;
+          ? [
+              `compile-refused:${resolvedScope.kind}:operation-not-implemented:${proposed.operation}`,
+            ]
+          : [`compile-refused:${resolvedScope.kind}`];
+    const blocker =
+      resolvedScope.kind === "scope"
+        ? MULTI_PARAGRAPH_REPLACEMENT_REFUSAL
+        : blockers[0] ?? `compile-refused:${resolvedScope.kind}`;
     const refused: ValidationResult = {
       safe: false,
-      blockedReasons: Object.freeze([blocker]),
+      posture: "hard-refusal",
+      blockedReasons: Object.freeze([...blockers]),
       warnings: verdict.warnings,
     };
     // Coord-08 U5 — `reason` mirrors `blockers[0]` for symmetry. Agents
@@ -251,6 +271,49 @@ export function applyScopeReplacement(
 
   const docAfter = inputs.sink.getCanonicalDocument();
   const documentHashAfter = documentHash(docAfter);
+  const readback = compileScopeById(
+    docAfter,
+    inputs.sink.getWorkflowOverlay() ?? undefined,
+    proposed.targetHandle.scopeId,
+  );
+  const proposedText =
+    proposed.proposedContent.kind === "text"
+      ? proposed.proposedContent.text ?? ""
+      : null;
+  const shouldVerifyReadback =
+    inputs.sink.verifyReadback === true &&
+    proposed.preserve?.opaqueFragments === true;
+  const readbackFailureReason =
+    shouldVerifyReadback &&
+    documentHashAfter === documentHashBefore &&
+    posture === "direct-edit" &&
+    !readback
+      ? `apply-readback-unresolvable:${proposed.targetHandle.scopeId}`
+      : shouldVerifyReadback &&
+          documentHashAfter === documentHashBefore &&
+          posture === "direct-edit" &&
+          proposed.operation === "replace" &&
+          proposedText !== null &&
+          proposedText !== resolvedScope.content.text &&
+          readback?.scope.content.text === resolvedScope.content.text
+        ? `apply-readback-unchanged:${proposed.targetHandle.scopeId}`
+        : undefined;
+
+  if (readbackFailureReason) {
+    return {
+      applied: false,
+      reason: readbackFailureReason,
+      validation: {
+        safe: false,
+        posture: "hard-refusal",
+        blockedReasons: Object.freeze([readbackFailureReason]),
+        warnings: verdict.warnings,
+      },
+      plan,
+      scope: readback?.scope ?? resolvedScope,
+      authoredRevisionIds: Object.freeze([]),
+    };
+  }
 
   const authoredRevisionIds: string[] = [];
   for (const id of Object.keys(docAfter.review.revisions ?? {})) {

package/src/runtime/scopes/scope-kinds/paragraph.ts

@@ -128,6 +128,55 @@ function longestTextOnlyRangeInParagraph(
   return best;
 }
 
+function textInParagraphRange(
+  paragraph: ParagraphLikeEnumeratedScope["paragraph"],
+  paragraphFrom: number,
+  target: { readonly from: number; readonly to: number },
+): string {
+  let cursor = paragraphFrom;
+  const parts: string[] = [];
+
+  const appendText = (text: string, from: number, to: number) => {
+    const clippedFrom = Math.max(from, target.from);
+    const clippedTo = Math.min(to, target.to);
+    if (clippedTo <= clippedFrom) return;
+    const localFrom = clippedFrom - from;
+    const localTo = clippedTo - from;
+    parts.push(Array.from(text).slice(localFrom, localTo).join(""));
+  };
+
+  const walkInline = (node: InlineNode, from: number): number => {
+    switch (node.type) {
+      case "text": {
+        const chars = Array.from(node.text);
+        appendText(node.text, from, from + chars.length);
+        return chars.length;
+      }
+      case "tab":
+        appendText("\t", from, from + 1);
+        return 1;
+      case "hard_break":
+        appendText("\n", from, from + 1);
+        return 1;
+      case "hyperlink":
+      case "field": {
+        let local = from;
+        for (const child of node.children as readonly InlineNode[]) {
+          local += walkInline(child, local);
+        }
+        return local - from;
+      }
+      default:
+        return inlineLengthLocal(node);
+    }
+  };
+
+  for (const child of paragraph.children) {
+    cursor += walkInline(child, cursor);
+  }
+  return parts.join("");
+}
+
 export interface CompileParagraphOptions {
   readonly document?: CanonicalDocument;
   readonly paragraphIndex?: number;
@@ -198,13 +247,17 @@ export interface CompileParagraphReplacementOptions {
  * Slice 5 — lower a paragraph-scope replacement proposal into a
  * `RuntimeOperationPlan`. Handles two content kinds:
  *
- *   - `kind: "text"` → single `text-replace` step spanning the
- *     paragraph's canonical block range; passes a flat string through
- *     the existing `text.insert` runtime command.
+ *   - `replace` + `kind: "text"` → single `text-replace` step spanning
+ *     the paragraph's effective scope range; passes a flat string
+ *     through the existing `text.insert` runtime command.
+ *   - `insert-before` / `insert-after` + `kind: "text"` → single
+ *     collapsed `text-replace` (or tracked insert in suggest mode) at
+ *     the effective scope edge.
  *   - `kind: "structured"` → single `fragment-replace` step carrying
  *     a `CanonicalDocumentFragment` payload; dispatches via the
- *     runtime's `insertFragment` pipeline with the block range as
- *     selection. Unblocked 2026-04-22 once L02 shipped
+ *     runtime's `insertFragment` pipeline with the effective range as
+ *     selection for replace, or a collapsed edge for insert-before /
+ *     insert-after. Unblocked 2026-04-22 once L02 shipped
  *     `CanonicalDocumentFragment` (`src/model/canonical-document.ts`).
  *
  * Determinism (S3): the plan is a pure projection of (blockIndex,
@@ -215,7 +268,13 @@ export function compileParagraphReplacement(
   proposed: ReplacementScope,
   options: CompileParagraphReplacementOptions,
 ): RuntimeOperationPlan | null {
-  if (proposed.operation !== "replace") return null;
+  if (
+    proposed.operation !== "replace" &&
+    proposed.operation !== "insert-before" &&
+    proposed.operation !== "insert-after"
+  ) {
+    return null;
+  }
 
   const blocks = computeBlockPositions(options.document);
   const blockRange = blocks.find((b) => b.blockIndex === entry.blockIndex);
@@ -259,7 +318,10 @@ export function compileParagraphReplacement(
   // replace range to the longest contiguous text-only sub-range so
   // opaque inlines (images, charts, preserve-only fragments) survive
   // the apply at their original positions.
-  if (proposed.preserve?.opaqueFragments === true) {
+  if (
+    proposed.operation === "replace" &&
+    proposed.preserve?.opaqueFragments === true
+  ) {
     const textOnly = longestTextOnlyRangeInParagraph(
       entry.paragraph,
       blockRange.from,
@@ -276,8 +338,22 @@ export function compileParagraphReplacement(
     rangeKind = "opaque-preserving-text";
   }
 
+  const operationRange =
+    proposed.operation === "insert-before"
+      ? { from: effectiveRange.from, to: effectiveRange.from }
+      : proposed.operation === "insert-after"
+        ? { from: effectiveRange.to, to: effectiveRange.to }
+        : effectiveRange;
+
   if (proposed.proposedContent.kind === "text") {
     const text = proposed.proposedContent.text ?? "";
+    if (
+      proposed.operation === "replace" &&
+      proposed.preserve?.opaqueFragments === true &&
+      textInParagraphRange(entry.paragraph, blockRange.from, operationRange) === text
+    ) {
+      return null;
+    }
     const stepKind =
       options.posture === "suggest-mode" ? "text-insert-tracked" : "text-replace";
     const summaryScope =
@@ -286,6 +362,16 @@ export function compileParagraphReplacement(
         : rangeKind === "opaque-preserving-text"
           ? `paragraph #${entry.blockIndex} opaque-preserving text range [${effectiveRange.from}..${effectiveRange.to}]`
           : `paragraph #${entry.blockIndex}`;
+    const actionVerb =
+      proposed.operation === "insert-before"
+        ? "insert before"
+        : proposed.operation === "insert-after"
+          ? "insert after"
+          : "replace";
+    const actionSummary =
+      proposed.operation === "replace"
+        ? `${actionVerb} ${summaryScope} text (len ${text.length})`
+        : `${actionVerb} ${summaryScope} text at ${operationRange.from} (len ${text.length})`;
     return {
       scopeId: entry.handle.scopeId,
       targetKind: "paragraph",
@@ -295,9 +381,9 @@ export function compileParagraphReplacement(
           kind: stepKind,
           summary:
             stepKind === "text-replace"
-              ? `replace ${summaryScope} text (len ${text.length})`
-              : `suggest-mode ${summaryScope} text replace (len ${text.length})`,
-          range: { from: effectiveRange.from, to: effectiveRange.to },
+              ? actionSummary
+              : `suggest-mode ${actionSummary}`,
+          range: { from: operationRange.from, to: operationRange.to },
           text,
           ...(proposed.formatting ? { formatting: proposed.formatting } : {}),
         },
@@ -325,6 +411,16 @@ export function compileParagraphReplacement(
         : rangeKind === "opaque-preserving-text"
           ? `paragraph #${entry.blockIndex} opaque-preserving text range [${effectiveRange.from}..${effectiveRange.to}]`
           : `paragraph #${entry.blockIndex}`;
+    const actionVerb =
+      proposed.operation === "insert-before"
+        ? "insert before"
+        : proposed.operation === "insert-after"
+          ? "insert after"
+          : "replace";
+    const actionSummary =
+      proposed.operation === "replace"
+        ? `${actionVerb} ${summaryScope} with structured fragment (${blockCount} block(s))`
+        : `${actionVerb} ${summaryScope} structured fragment at ${operationRange.from} (${blockCount} block(s))`;
     return {
       scopeId: entry.handle.scopeId,
       targetKind: "paragraph",
@@ -332,8 +428,8 @@ export function compileParagraphReplacement(
       steps: Object.freeze([
         {
           kind: "fragment-replace",
-          summary: `replace ${summaryScope} with structured fragment (${blockCount} block(s))`,
-          range: { from: effectiveRange.from, to: effectiveRange.to },
+          summary: actionSummary,
+          range: { from: operationRange.from, to: operationRange.to },
           fragment,
         },
       ]),