@beyondwork/docx-react-component 1.0.59 → 1.0.60

package/package.json

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

package/src/api/public-types.ts

@@ -1257,6 +1257,7 @@ export type EditorWarningCode =
   | "export_roundtrip_risk"
   | "comment_anchor_detached"
   | "revision_anchor_detached"
+  | "workflow_scope_invalidated"
   | "large_document_degraded"
   | "font_substitution"
   | "image_missing"
@@ -1350,6 +1351,7 @@ export type EditorDiagnosticCode =
   | "export.roundtrip_risk"
   | "review.comment_anchor_detached"
   | "review.revision_anchor_detached"
+  | "runtime.workflow_scope_invalidated"
   | "runtime.large_document_degraded"
   | "runtime.font_substitution"
   | "runtime.image_missing"

package/src/core/state/editor-state.ts

@@ -31,6 +31,7 @@ export type EditorWarningCode =
   | "export_roundtrip_risk"
   | "comment_anchor_detached"
   | "revision_anchor_detached"
+  | "workflow_scope_invalidated"
   | "large_document_degraded"
   | "font_substitution"
   | "image_missing"
@@ -51,6 +52,7 @@ export interface EditorWarning {
   affectedAnchor?: EditorAnchorProjection;
   featureEntryId?: string;
   details?: Record<string, unknown>;
+  diagnostic?: import("../../api/public-types.ts").EditorDiagnostic;
 }
 
 export interface EditorError {

package/src/io/ooxml/workflow-payload.ts

@@ -13,6 +13,7 @@ import type {
   WorkflowWorkItem,
 } from "../../api/public-types.ts";
 import type { EditorStateNamespace, EditorStateLocation } from "../../api/editor-state-types.ts";
+import { sha256Hex } from "../source-package-provenance.ts";
 import {
   validateWorkflowPayloadEnvelope,
   type ValidatorIssue,
@@ -42,6 +43,8 @@ export interface EditorStatePayload {
   unknownNamespaces?: Array<{ name: string; rawXml: string }>;
 }
 
+const workflowAnchorHashEncoder = new TextEncoder();
+
 // ---------------------------------------------------------------------------
 // Schema 1.1 parser helpers (fail-closed per spec §8.2)
 // ---------------------------------------------------------------------------
@@ -747,7 +750,9 @@ function createAnchorBindingHash(
   from: number,
   to: number,
 ): string {
-  return `${serializeStoryTargetKey(storyTarget)}:${from}:${to}`;
+  return sha256Hex(
+    workflowAnchorHashEncoder.encode(`${serializeStoryTargetKey(storyTarget)}:${from}:${to}`),
+  );
 }
 
 function getPreservedExtensionsXml(sourcePackage: OpcPackage, payloadPartPath: string): string {

package/src/model/snapshot.ts

@@ -28,6 +28,7 @@ export type EditorWarningCode =
   | "export_roundtrip_risk"
   | "comment_anchor_detached"
   | "revision_anchor_detached"
+  | "workflow_scope_invalidated"
   | "large_document_degraded"
   | "font_substitution"
   | "image_missing"
@@ -235,6 +236,7 @@ const EDITOR_WARNING_CODES = new Set<EditorWarningCode>([
   "export_roundtrip_risk",
   "comment_anchor_detached",
   "revision_anchor_detached",
+  "workflow_scope_invalidated",
   "large_document_degraded",
   "font_substitution",
   "image_missing",

package/src/runtime/diagnostics/build-diagnostic.ts

@@ -131,6 +131,7 @@ export function buildDiagnosticFromLegacyWarningCode(
     | "export_roundtrip_risk"
     | "comment_anchor_detached"
     | "revision_anchor_detached"
+    | "workflow_scope_invalidated"
     | "large_document_degraded"
     | "font_substitution"
     | "image_missing",
@@ -143,6 +144,7 @@ export function buildDiagnosticFromLegacyWarningCode(
     export_roundtrip_risk: "export.roundtrip_risk",
     comment_anchor_detached: "review.comment_anchor_detached",
     revision_anchor_detached: "review.revision_anchor_detached",
+    workflow_scope_invalidated: "runtime.workflow_scope_invalidated",
     large_document_degraded: "runtime.large_document_degraded",
     font_substitution: "runtime.font_substitution",
     image_missing: "runtime.image_missing",

package/src/runtime/diagnostics/code-metadata-table.ts

@@ -80,6 +80,15 @@ export const CODE_METADATA_TABLE: Readonly<
   "review.revision_anchor_detached": row("review", "info",
     "A tracked change's anchor was invalidated by a structural edit.",
     "retry-safe", { kind: "none" }, ["review", "tracked-change"], "review-revision-anchor-detached"),
+  "runtime.workflow_scope_invalidated": row("runtime", "warning",
+    "A workflow scope lost its trusted anchor and is no longer enforcing against live text.",
+    "requires-input",
+    {
+      kind: "fallback",
+      suggestion:
+        "Use warning.details.scopeId + warning.details.lastKnownRange to relocate the intended text, then reapply the scope.",
+    },
+    ["runtime", "workflow", "scope"], "runtime-workflow-scope-invalidated"),
   "runtime.large_document_degraded": row("runtime", "warning",
     "The document is large enough that some rendering optimizations have been relaxed.",
     "retry-safe", { kind: "none" }, ["runtime", "perf"], "runtime-large-document-degraded"),

package/src/runtime/document-runtime.ts

@@ -150,6 +150,7 @@ import {
   findScopesIntersecting,
   resolveScope,
 } from "./scope-resolver.ts";
+import { buildDiagnosticFromLegacyWarningCode } from "./diagnostics/build-diagnostic.ts";
 import {
   projectScopeQueryResults,
   queryScopes as runQueryScopes,
@@ -872,6 +873,7 @@ export function createDocumentRuntime(
     options.initialSessionState?.workflowMetadata?.entries
     ?? options.initialSnapshot?.workflowMetadata?.entries
     ?? [];
+  let markerBackedScopeIds = new Set<string>();
   let hostAnnotationOverlay: HostAnnotationOverlay | null = null;
   // §C7 — local view-state for scope chrome visibility; never collab-replicated.
   let scopeChromeVisibilityState: ScopeChromeVisibilityState = { mode: "all" };
@@ -909,6 +911,32 @@ export function createDocumentRuntime(
   storySelections.set(storyTargetKey(MAIN_STORY_TARGET), state.selection);
   lastHeadingFingerprint = computeHeadingFingerprint(state.document);
 
+  function syncMarkerBackedScopeIds(
+    document: CanonicalDocumentEnvelope,
+    overlay: WorkflowOverlay | null,
+  ): void {
+    const presentScopeIds = new Set(collectScopeLocations(document).keys());
+    if (!overlay) {
+      markerBackedScopeIds = presentScopeIds;
+      return;
+    }
+    const overlayScopeIds = new Set(overlay.scopes.map((scope) => scope.scopeId));
+    const next = new Set<string>();
+    for (const scopeId of markerBackedScopeIds) {
+      if (overlayScopeIds.has(scopeId)) {
+        next.add(scopeId);
+      }
+    }
+    for (const scopeId of presentScopeIds) {
+      if (overlayScopeIds.has(scopeId)) {
+        next.add(scopeId);
+      }
+    }
+    markerBackedScopeIds = next;
+  }
+
+  syncMarkerBackedScopeIds(state.document, workflowOverlay);
+
   // Runtime-owned paginated layout engine (Phase 1+ of the layout facet work).
   // The engine caches graph + resolved-formatting + fragment mapper keyed on
   // (content, styles, subParts).  It is the single internal source of truth
@@ -1924,19 +1952,37 @@ export function createDocumentRuntime(
         return scope;
       }
       const location = locations.get(scope.scopeId);
+      const isMarkerBacked = markerBackedScopeIds.has(scope.scopeId);
+      let nextAnchor: EditorAnchorProjection | null = null;
       if (
-        !location ||
-        location.startPos === undefined ||
-        location.endPos === undefined
+        location &&
+        location.startPos !== undefined &&
+        location.endPos !== undefined
       ) {
+        nextAnchor = {
+          kind: "range",
+          from: Math.min(location.startPos, location.endPos),
+          to: Math.max(location.startPos, location.endPos),
+          assoc: { start: -1, end: 1 },
+        };
+      } else if (isMarkerBacked) {
+        const lastKnownRange =
+          scope.anchor.kind === "range"
+            ? { from: scope.anchor.from, to: scope.anchor.to }
+            : scope.anchor.kind === "node"
+              ? { from: scope.anchor.at, to: scope.anchor.at }
+              : scope.anchor.lastKnownRange;
+        nextAnchor = {
+          kind: "detached",
+          reason:
+            location && (location.startPos !== undefined || location.endPos !== undefined)
+              ? "deleted"
+              : "invalidatedByStructureChange",
+          lastKnownRange,
+        };
+      } else {
         return scope;
       }
-      const nextAnchor: EditorAnchorProjection = {
-        kind: "range",
-        from: Math.min(location.startPos, location.endPos),
-        to: Math.max(location.startPos, location.endPos),
-        assoc: { start: -1, end: 1 },
-      };
       if (workflowAnchorsEqual(scope.anchor, nextAnchor)) {
         return scope;
       }
@@ -1966,6 +2012,161 @@ export function createDocumentRuntime(
     return normalizeWorkflowOverlayForDocument(state.document, workflowOverlay);
   }
 
+  function buildWarningSignature(warning: InternalEditorWarning): string {
+    return JSON.stringify({
+      code: warning.code,
+      severity: warning.severity,
+      message: warning.message,
+      source: warning.source,
+      featureEntryId: warning.featureEntryId ?? null,
+      details: warning.details ?? null,
+      affectedAnchor: warning.affectedAnchor ?? null,
+    });
+  }
+
+  function mergeDetachedWorkflowScopeWarnings(
+    overlay: WorkflowOverlay | null,
+    existingWarnings: readonly InternalEditorWarning[],
+  ): {
+    nextWarnings: InternalEditorWarning[];
+    added: InternalEditorWarning[];
+    cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
+  } {
+    const detachedScopesById = new Map<string, WorkflowScope>();
+    for (const scope of overlay?.scopes ?? []) {
+      if (scope.anchor.kind === "detached") {
+        detachedScopesById.set(scope.scopeId, scope);
+      }
+    }
+
+    const retainedWarnings = existingWarnings.filter(
+      (warning) => warning.code !== "workflow_scope_invalidated",
+    );
+    const existingDetachedWarnings = existingWarnings.filter(
+      (warning) => warning.code === "workflow_scope_invalidated",
+    );
+    const existingById = new Map(
+      existingDetachedWarnings.map((warning) => [warning.warningId, warning] as const),
+    );
+    const desiredById = new Map(
+      [...detachedScopesById.values()].map((scope) => {
+        const warning = createInvalidatedWorkflowScopeWarning(scope);
+        return [warning.warningId, warning] as const;
+      }),
+    );
+
+    const added: InternalEditorWarning[] = [];
+    const cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }> = [];
+
+    for (const [warningId, existingWarning] of existingById) {
+      const desiredWarning = desiredById.get(warningId);
+      if (!desiredWarning) {
+        cleared.push({ warningId, code: existingWarning.code });
+        continue;
+      }
+      if (buildWarningSignature(existingWarning) !== buildWarningSignature(desiredWarning)) {
+        cleared.push({ warningId, code: existingWarning.code });
+        added.push(desiredWarning);
+      }
+    }
+
+    for (const [warningId, desiredWarning] of desiredById) {
+      if (!existingById.has(warningId)) {
+        added.push(desiredWarning);
+      }
+    }
+
+    return {
+      nextWarnings: [...retainedWarnings, ...desiredById.values()],
+      added,
+      cleared,
+    };
+  }
+
+  function createInvalidatedWorkflowScopeWarning(
+    scope: WorkflowScope,
+  ): InternalEditorWarning {
+    const anchor = scope.anchor.kind === "detached" ? scope.anchor : null;
+    const subject = scope.label
+      ? `Workflow scope "${scope.label}" (${scope.scopeId})`
+      : `Workflow scope ${scope.scopeId}`;
+    const reasonPhrase =
+      anchor?.reason === "deleted"
+        ? "its anchored text was deleted"
+        : anchor?.reason === "invalidatedByStructureChange"
+          ? "document structure changed around it"
+          : "its anchor could not be resolved unambiguously";
+    const modePhrase =
+      scope.mode === "view"
+        ? "read-only enforcement"
+        : `${scope.mode} enforcement`;
+
+    return {
+      warningId: `warning:workflow-scope-invalidated:${scope.scopeId}`,
+      code: "workflow_scope_invalidated",
+      severity: "warning",
+      message: `${subject} was invalidated because ${reasonPhrase}. Reapply the scope before relying on ${modePhrase}.`,
+      source: "runtime",
+      affectedAnchor: anchor ? toInternalAnchorProjection(anchor) : undefined,
+      diagnostic: buildDiagnosticFromLegacyWarningCode("workflow_scope_invalidated", {
+        diagnosticId: `warning-diag:workflow-scope-invalidated:${scope.scopeId}`,
+        technical: {
+          message: `${subject} lost its trusted anchor and is now detached.`,
+          source: "runtime",
+        },
+        details: {
+          scopeId: scope.scopeId,
+          label: scope.label,
+          mode: scope.mode,
+          reason: anchor?.reason,
+          lastKnownRange: anchor?.lastKnownRange,
+          storyTarget: scope.storyTarget,
+          reapplySuggested: true,
+        },
+        affectedAnchor: anchor ? scope.anchor : undefined,
+        llmMetadata: {
+          userSummary: `${subject} is no longer attached to trusted document content. Reapply the scope before relying on it.`,
+          remediation: {
+            kind: "fallback",
+            suggestion:
+              "Locate the intended text using warning.details.scopeId and warning.details.lastKnownRange, then call addScope again for the repaired range.",
+          },
+          recoveryClass: "requires-input",
+          echoedInput: {
+            scopeId: scope.scopeId,
+            lastKnownRange: anchor?.lastKnownRange,
+          },
+        },
+      }),
+      details: {
+        scopeId: scope.scopeId,
+        label: scope.label,
+        mode: scope.mode,
+        reason: anchor?.reason,
+        lastKnownRange: anchor?.lastKnownRange,
+        storyTarget: scope.storyTarget,
+        reapplySuggested: true,
+        actionabilityNote:
+          "Resolve the intended text again, then reapply the scope; the previous anchor is no longer trusted.",
+      },
+    };
+  }
+
+  function syncDetachedWorkflowScopeWarningsInState(): {
+    added: InternalEditorWarning[];
+    cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
+  } {
+    const { nextWarnings, added, cleared } = mergeDetachedWorkflowScopeWarnings(
+      getNormalizedWorkflowOverlay(),
+      state.warnings,
+    );
+    if (added.length === 0 && cleared.length === 0) {
+      return { added, cleared };
+    }
+    state = { ...state, warnings: nextWarnings };
+    return { added, cleared };
+  }
+
   function deriveWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
     const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
     if (!normalizedWorkflowOverlay) return null;
@@ -2529,6 +2730,7 @@ export function createDocumentRuntime(
     return snapshot;
   }
 
+  syncDetachedWorkflowScopeWarningsInState();
   let cachedRenderSnapshot = refreshRenderSnapshot();
 
   emit({
@@ -3351,17 +3553,29 @@ export function createDocumentRuntime(
       });
 
       if (params.persistence && params.persistence !== "runtime-only") {
+        const requestedMetadata = params.metadata ?? {};
+        const entryPersistence =
+          requestedMetadata.metadataPersistence ??
+          (params.persistence === "session" ? "external" : "internal");
         const entry: WorkflowMetadataEntry = {
-          entryId: `scope-metadata-${scopeId}`,
-          metadataId: "workflow.scope",
+          entryId: requestedMetadata.entryId ?? `scope-metadata-${scopeId}`,
+          metadataId: requestedMetadata.metadataId ?? "workflow.scope",
           anchor: publicAnchor,
+          ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
           scopeId,
-          value:
-            params.persistence === "document-metadata"
-              ? { ...(params.metadata?.value ?? {}), label: params.label }
-              : params.metadata?.value,
-          metadataPersistence:
-            params.persistence === "session" ? "external" : "internal",
+          ...(requestedMetadata.workItemId ? { workItemId: requestedMetadata.workItemId } : {}),
+          ...(requestedMetadata.value !== undefined
+            ? { value: requestedMetadata.value }
+            : params.persistence === "document-metadata" && params.label
+              ? { value: { label: params.label } }
+              : {}),
+          metadataPersistence: entryPersistence,
+          ...(requestedMetadata.storageRef !== undefined
+            ? { storageRef: requestedMetadata.storageRef }
+            : {}),
+          ...(requestedMetadata.metadataVersion !== undefined
+            ? { metadataVersion: requestedMetadata.metadataVersion }
+            : {}),
         };
         this.dispatch({
           type: "workflow.set-metadata-entries",
@@ -3951,16 +4165,42 @@ export function createDocumentRuntime(
           overlay: workflowOverlay,
           entries: workflowMetadataEntries,
           document: state.document,
+          markerBackedScopeIds,
         },
         filter,
       );
     },
     subscribeToScopeQuery(filter, callback) {
+      const buildAnchorKey = (anchor: EditorAnchorProjection): string => {
+        switch (anchor.kind) {
+          case "range":
+            return `range:${anchor.from}:${anchor.to}:${anchor.assoc.start}:${anchor.assoc.end}`;
+          case "node":
+            return `node:${anchor.at}`;
+          case "detached":
+            return `detached:${anchor.reason}:${anchor.lastKnownRange.from}:${anchor.lastKnownRange.to}`;
+          default:
+            return "unknown";
+        }
+      };
+
       const buildKey = (results: ScopeQueryResult[]) =>
         results
           .map(
             (r) =>
-              `${r.scope.scopeId}:${r.scope.version ?? 0}:${r.scope.visibility ?? "visible"}`,
+              [
+                r.scope.scopeId,
+                r.scope.version ?? 0,
+                r.scope.visibility ?? "visible",
+                buildAnchorKey(r.scope.anchor),
+                r.workItem?.workItemId ?? "",
+                r.entries
+                  .map(
+                    (entry) =>
+                      `${entry.entryId}:${entry.metadataVersion ?? 0}:${buildAnchorKey(entry.anchor)}`,
+                  )
+                  .join("|"),
+              ].join(":"),
           )
           .join(",");
 
@@ -4027,7 +4267,12 @@ export function createDocumentRuntime(
       if (pos === null) return [];
       const hits = findAllScopesAt(state.document, pos);
       return projectScopeQueryResults(
-        { overlay: workflowOverlay, entries: workflowMetadataEntries, document: state.document },
+        {
+          overlay: workflowOverlay,
+          entries: workflowMetadataEntries,
+          document: state.document,
+          markerBackedScopeIds,
+        },
         hits.map((h) => h.scopeId),
         options,
       );
@@ -4036,7 +4281,12 @@ export function createDocumentRuntime(
       if (range.kind !== "range") return [];
       const hits = findScopesIntersecting(state.document, range.from, range.to, options?.mode);
       return projectScopeQueryResults(
-        { overlay: workflowOverlay, entries: workflowMetadataEntries, document: state.document },
+        {
+          overlay: workflowOverlay,
+          entries: workflowMetadataEntries,
+          document: state.document,
+          markerBackedScopeIds,
+        },
         hits.map((h) => h.scopeId),
         options,
       );
@@ -4249,6 +4499,8 @@ export function createDocumentRuntime(
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
     perfCounters.increment("commit.finalizeState.us", Math.round((performance.now() - tFinalize0) * 1000));
     storySelections.set(storyTargetKey(activeStory), state.selection);
+    syncMarkerBackedScopeIds(state.document, workflowOverlay);
+    const detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
 
     const tInvalidate0 = performance.now();
     if (transaction.markDirty && transaction.mapping.steps.length > 0) {
@@ -4319,7 +4571,20 @@ export function createDocumentRuntime(
     perfCounters.increment("commit.refresh.us", Math.round((performance.now() - tRefresh0) * 1000));
 
     const tNotify0 = performance.now();
-    notify(previous, state, transaction);
+    notify(previous, state, {
+      ...transaction,
+      effects: {
+        ...transaction.effects,
+        warningsAdded: [
+          ...transaction.effects.warningsAdded,
+          ...detachedWorkflowScopeWarnings.added,
+        ],
+        warningsCleared: [
+          ...transaction.effects.warningsCleared,
+          ...detachedWorkflowScopeWarnings.cleared,
+        ],
+      },
+    });
     perfCounters.increment("commit.notify.us", Math.round((performance.now() - tNotify0) * 1000));
     perfCounters.increment("commit.total.us", Math.round((performance.now() - tApply0) * 1000));
   }
@@ -4948,10 +5213,18 @@ export function createDocumentRuntime(
   function applyRuntimeStateOverlayCommand(
     command: RuntimeStateOverlayCommand,
   ): void {
+    let detachedWorkflowScopeWarnings:
+      | {
+          added: InternalEditorWarning[];
+          cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
+        }
+      | null = null;
     switch (command.type) {
       case "workflow.set-overlay": {
         workflowOverlay = structuredClone(command.overlay);
+        syncMarkerBackedScopeIds(state.document, workflowOverlay);
         cachedNormalizedWorkflowOverlay = undefined;
+        detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
         cachedRenderSnapshot = refreshRenderSnapshot();
         const snapshot = deriveWorkflowScopeSnapshot()!;
         emit({
@@ -4970,7 +5243,9 @@ export function createDocumentRuntime(
       }
       case "workflow.clear-overlay": {
         workflowOverlay = null;
+        syncMarkerBackedScopeIds(state.document, workflowOverlay);
         cachedNormalizedWorkflowOverlay = undefined;
+        detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
         cachedRenderSnapshot = refreshRenderSnapshot();
         emit({
           type: "workflow_active_work_item_changed",
@@ -5045,6 +5320,25 @@ export function createDocumentRuntime(
         break;
       }
     }
+    if (detachedWorkflowScopeWarnings) {
+      for (const warning of detachedWorkflowScopeWarnings.added) {
+        const publicWarning = toPublicWarning(warning);
+        emit({
+          type: "warning_added",
+          documentId: state.documentId,
+          warning: publicWarning,
+        });
+        options.onWarning?.(publicWarning);
+      }
+      for (const cleared of detachedWorkflowScopeWarnings.cleared) {
+        emit({
+          type: "warning_cleared",
+          documentId: state.documentId,
+          warningId: cleared.warningId,
+          code: cleared.code,
+        });
+      }
+    }
     for (const listener of listeners) {
       listener();
     }
@@ -5533,11 +5827,42 @@ function toPublicCompatibilityFeatureEntry(
 }
 
 function toPublicWarning(warning: InternalEditorWarning): EditorWarning {
+  const diagnostic =
+    warning.diagnostic ??
+    (() => {
+      switch (warning.code) {
+        case "unsupported_ooxml_preserved":
+        case "unsupported_ooxml_locked":
+        case "import_normalized":
+        case "export_roundtrip_risk":
+        case "comment_anchor_detached":
+        case "revision_anchor_detached":
+        case "workflow_scope_invalidated":
+        case "large_document_degraded":
+        case "font_substitution":
+        case "image_missing":
+          return buildDiagnosticFromLegacyWarningCode(warning.code, {
+            diagnosticId: `warning-diag:${warning.warningId}`,
+            emittedAt: new Date(0).toISOString(),
+            technical: {
+              message: warning.message,
+              source: warning.source,
+            },
+            details: warning.details,
+            affectedAnchor: warning.affectedAnchor
+              ? toPublicAnchorProjection(warning.affectedAnchor)
+              : undefined,
+          });
+        default:
+          return undefined;
+      }
+    })();
   return {
     ...warning,
     affectedAnchor: warning.affectedAnchor
       ? toPublicAnchorProjection(warning.affectedAnchor)
       : undefined,
+    diagnostic,
   };
 }
 

package/src/runtime/query-scopes.ts

@@ -1,4 +1,5 @@
 import type {
+  EditorAnchorProjection,
   EditorStoryTarget,
   ScopeQueryFilter,
   ScopeQueryResult,
@@ -31,10 +32,97 @@ function storyTargetsEqual(a: EditorStoryTarget, b: EditorStoryTarget): boolean
 
 const MAIN_STORY: EditorStoryTarget = { kind: "main" };
 
+function workflowAnchorsEqual(
+  left: EditorAnchorProjection,
+  right: EditorAnchorProjection,
+): boolean {
+  if (left.kind !== right.kind) return false;
+  switch (left.kind) {
+    case "range":
+      return (
+        right.kind === "range" &&
+        left.from === right.from &&
+        left.to === right.to &&
+        left.assoc.start === right.assoc.start &&
+        left.assoc.end === right.assoc.end
+      );
+    case "node":
+      return right.kind === "node" && left.at === right.at;
+    case "detached":
+      return (
+        right.kind === "detached" &&
+        left.reason === right.reason &&
+        left.lastKnownRange.from === right.lastKnownRange.from &&
+        left.lastKnownRange.to === right.lastKnownRange.to
+      );
+    default:
+      return false;
+  }
+}
+
+function buildScopeIdCounts(overlay: WorkflowOverlay): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const scope of overlay.scopes) {
+    counts.set(scope.scopeId, (counts.get(scope.scopeId) ?? 0) + 1);
+  }
+  return counts;
+}
+
+function normalizeScopeAnchor(
+  scope: WorkflowScope,
+  scopeIdCounts: ReadonlyMap<string, number>,
+  locations: ReadonlyMap<string, { startPos?: number; endPos?: number }>,
+  markerBackedScopeIds: ReadonlySet<string>,
+): WorkflowScope {
+  if ((scopeIdCounts.get(scope.scopeId) ?? 0) !== 1) {
+    return scope;
+  }
+
+  const location = locations.get(scope.scopeId);
+  let nextAnchor: EditorAnchorProjection | null = null;
+  if (
+    location &&
+    location.startPos !== undefined &&
+    location.endPos !== undefined
+  ) {
+    nextAnchor = {
+      kind: "range",
+      from: Math.min(location.startPos, location.endPos),
+      to: Math.max(location.startPos, location.endPos),
+      assoc: { start: -1, end: 1 },
+    };
+  } else if (markerBackedScopeIds.has(scope.scopeId)) {
+    const lastKnownRange =
+      scope.anchor.kind === "range"
+        ? { from: scope.anchor.from, to: scope.anchor.to }
+        : scope.anchor.kind === "node"
+          ? { from: scope.anchor.at, to: scope.anchor.at }
+          : scope.anchor.lastKnownRange;
+    nextAnchor = {
+      kind: "detached",
+      reason:
+        location && (location.startPos !== undefined || location.endPos !== undefined)
+          ? "deleted"
+          : "invalidatedByStructureChange",
+      lastKnownRange,
+    };
+  } else {
+    return scope;
+  }
+
+  return workflowAnchorsEqual(scope.anchor, nextAnchor)
+    ? scope
+    : {
+        ...scope,
+        anchor: nextAnchor,
+      };
+}
+
 export interface ScopeQueryInputs {
   readonly overlay: WorkflowOverlay | null;
   readonly entries: readonly WorkflowMetadataEntry[];
   readonly document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope;
+  readonly markerBackedScopeIds?: ReadonlySet<string>;
 }
 
 /**
@@ -53,9 +141,17 @@ export function projectScopeQueryResults(
   if (!overlay) return [];
   const includeHidden = options.includeHidden === true;
   const includeInvisible = options.includeInvisible === true;
+  const scopeIdCounts = buildScopeIdCounts(overlay);
+  const locations = collectScopeLocations(inputs.document);
+  const markerBackedScopeIds = inputs.markerBackedScopeIds ?? new Set<string>();
 
   const scopesById = new Map<string, WorkflowScope>();
-  for (const scope of overlay.scopes) scopesById.set(scope.scopeId, scope);
+  for (const scope of overlay.scopes) {
+    scopesById.set(
+      scope.scopeId,
+      normalizeScopeAnchor(scope, scopeIdCounts, locations, markerBackedScopeIds),
+    );
+  }
 
   const entriesByScope = new Map<string, WorkflowMetadataEntry[]>();
   for (const entry of inputs.entries) {
@@ -128,6 +224,8 @@ export function queryScopes(
   }
 
   const locations = collectScopeLocations(inputs.document);
+  const scopeIdCounts = buildScopeIdCounts(overlay);
+  const markerBackedScopeIds = inputs.markerBackedScopeIds ?? new Set<string>();
 
   const candidates: Array<{ scope: WorkflowScope; startPos: number }> = [];
   for (const scope of overlay.scopes) {
@@ -162,7 +260,10 @@ export function queryScopes(
     const loc = locations.get(scope.scopeId);
     const startPos =
       loc?.startPos ?? loc?.endPos ?? Number.POSITIVE_INFINITY;
-    candidates.push({ scope, startPos });
+    candidates.push({
+      scope: normalizeScopeAnchor(scope, scopeIdCounts, locations, markerBackedScopeIds),
+      startPos,
+    });
   }
 
   candidates.sort((a, b) => {