@beyondwork/docx-react-component 1.0.83 → 1.0.84

package/package.json

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

package/src/api/public-types.ts

@@ -2512,6 +2512,16 @@ export interface AddScopeParams {
   storyTarget?: EditorStoryTarget;
   /** Optional display label for the scope card / rail. */
   label?: string;
+  /**
+   * Optional per-scope visibility. Controls chrome/query presentation only;
+   * edit enforcement is controlled by `guardPolicy`.
+   */
+  visibility?: ScopeVisibility;
+  /**
+   * Optional edit-enforcement posture. Absent means advisory for
+   * edit/suggest/comment scopes and read-only for `mode: "view"`.
+   */
+  guardPolicy?: WorkflowScopeGuardPolicy;
 }
 
 export interface AddScopeResult {
@@ -2591,6 +2601,19 @@ export interface ExportResult {
 
 export type WorkflowScopeMode = "edit" | "suggest" | "comment" | "view";
 
+/**
+ * Explicit scope enforcement axis. Visibility is presentation-only.
+ *
+ * - `"none"`: advisory/metadata/chrome scope; direct editing is unaffected.
+ * - `"insert-only"`: allowlist scope; when any active insert-only scope
+ *   exists, selection-driven edits outside insert-only scopes are blocked.
+ * - `"read-only"`: deny edits inside this scope; outside content is unaffected.
+ *
+ * When absent, `mode: "view"` scopes default to `"read-only"` for
+ * compatibility; all other modes default to `"none"`.
+ */
+export type WorkflowScopeGuardPolicy = "none" | "insert-only" | "read-only";
+
 /**
  * §C7 — Local chrome visibility mode. Never collab-replicated.
  * - `"all"`:      show all scope rail entries + decorations (default).
@@ -2615,8 +2638,8 @@ export interface ScopeChromeVisibilityState {
  *
  * - `"visible"`:   rail entry + card + inline decoration (current behavior).
  * - `"hidden"`:    in the rail but muted; card opens on explicit click; no decoration.
- * - `"invisible"`: never rendered; only queryable via API. Does NOT contribute
- *   to InteractionGuard unless `mode === "view"` (explicit host opt-in).
+ * - `"invisible"`: never rendered; only queryable via API. Visibility never
+ *   contributes to InteractionGuard.
  */
 export type ScopeVisibility = "visible" | "hidden" | "invisible";
 
@@ -2639,6 +2662,12 @@ export interface WorkflowScope {
   domain?: "legal" | "commercial" | "finance" | "other";
   metadataRefs?: string[];
   metadata?: WorkflowScopeMetadataField[];
+  /**
+   * Explicit edit-enforcement posture. Absent means:
+   * - `mode: "view"` -> `"read-only"` (legacy read-only behavior).
+   * - all other modes -> `"none"` (advisory/chrome/metadata only).
+   */
+  guardPolicy?: WorkflowScopeGuardPolicy;
   /**
    * Schema 1.1 — override the overlay default for this scope.
    * `"inherit"` defers to the overlay; absent is equivalent to
@@ -4571,8 +4600,9 @@ export interface WordReviewEditorRef {
   removeScope(scopeId: string): void;
   /**
    * §C8 — Convenience: adds a scope with `visibility: "invisible"` atomically.
-   * Mode defaults to `"comment"` — invisible scopes carry no InteractionGuard
-   * constraint unless `mode: "view"` is passed explicitly.
+   * Mode defaults to `"comment"`. Visibility is presentation-only; edit
+   * gating is controlled by `guardPolicy` (`mode: "view"` still defaults to
+   * read-only for compatibility unless `guardPolicy: "none"` is set).
    */
   addInvisibleScope(
     params: Omit<AddScopeParams, "mode"> & { mode?: WorkflowScopeMode },
@@ -4587,6 +4617,20 @@ export interface WordReviewEditorRef {
    * scopes or when the `visibility` field has never been set.
    */
   getScopeVisibility(scopeId: string): ScopeVisibility;
+  /**
+   * Set a scope's edit-enforcement posture. Collab-replicated through the
+   * workflow overlay; visibility remains purely presentational.
+   */
+  setScopeGuardPolicy(
+    scopeId: string,
+    guardPolicy: WorkflowScopeGuardPolicy,
+  ): void;
+  /**
+   * Get a scope's effective guard policy. Returns `"read-only"` for legacy
+   * `mode: "view"` scopes with no explicit policy and `"none"` for unknown
+   * scopes.
+   */
+  getScopeGuardPolicy(scopeId: string): WorkflowScopeGuardPolicy;
   /**
    * §C7 — Set the local chrome-visibility state. Local view-state only —
    * never collab-replicated. Controls whether the scope rail / decorations

package/src/api/v3/_runtime-handle.ts

@@ -70,6 +70,8 @@ export type RuntimeApiHandle = Pick<
   // live seam. `getWorkflowMetadataSnapshot` is the read side the
   // metadata writer inspects before merging its entry.
   | "addScope"
+  | "setScopeGuardPolicy"
+  | "getScopeGuardPolicy"
   | "setWorkflowMetadataEntries"
   | "getWorkflowMetadataSnapshot"
   // W10 overlay-visibility policy (state-classes X1). Class-A canonical
@@ -155,6 +157,8 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   getInteractionGuardSnapshot: true,
   getWorkflowOverlay: true,
   addScope: true,
+  setScopeGuardPolicy: true,
+  getScopeGuardPolicy: true,
   setWorkflowMetadataEntries: true,
   getWorkflowMetadataSnapshot: true,
   getVisibilityPolicy: true,

package/src/api/v3/runtime/workflow.ts

@@ -2,7 +2,8 @@
  * @endStateApi v3 — `runtime.workflow` family.
  *
  * queryScopes (live) / getMarkup (live) / getGuard (live) /
- * createScope (live-with-adapter) / attachMetadata (live-with-adapter) /
+ * createScope (live-with-adapter) / setScopeGuardPolicy (live) /
+ * attachMetadata (live-with-adapter) /
  * getVisibilityPolicy · getVisibilityPolicies · setVisibilityPolicy ·
  * clearVisibilityPolicy (live — W10 state-classes X1) /
  * scopeTags (live — coord-10 L11-4 tag-catalog read).
@@ -14,6 +15,8 @@ import type {
   EditorStoryTarget,
   OverlayKind,
   OverlayVisibilityPolicy,
+  ScopeVisibility,
+  WorkflowScopeGuardPolicy,
   WorkflowMarkupModePolicy,
 } from "../../public-types.ts";
 import { emitUxResponse } from "../_ux-response.ts";
@@ -82,6 +85,13 @@ export interface CreateScopeInput {
   readonly blockId: string;
   readonly mode?: "edit" | "suggest" | "comment" | "view";
   readonly label?: string;
+  /** Per-scope visibility. Controls chrome/query presentation only. */
+  readonly visibility?: ScopeVisibility;
+  /**
+   * Explicit edit-enforcement posture. Use `"insert-only"` for
+   * template-slot allowlists; use `"read-only"` to lock the scope range.
+   */
+  readonly guardPolicy?: WorkflowScopeGuardPolicy;
   /**
    * Coord-06 §13d — per-scope edge stickiness. Defaults to
    * `{ start: 1, end: -1 }` (greedy — absorbs boundary inserts, the
@@ -112,10 +122,24 @@ export interface CreateScopeInput {
     | "runtime-handle";
 }
 
-export interface CreateScopeResult {
-  readonly scopeId: string;
-  readonly status: "created" | "block-not-found";
-}
+export type CreateScopeResult =
+  | { readonly scopeId: string; readonly status: "created" }
+  | { readonly scopeId: ""; readonly status: "block-not-found" }
+  | {
+      readonly scopeId: "";
+      readonly status: "range-invalid";
+      readonly reason:
+        | "range-exceeds-story-length"
+        | "non-paragraph-target"
+        | "empty-document";
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+      readonly blockIndex?: number;
+      readonly blockKind?: string;
+      readonly message: string;
+      readonly nextStep: string;
+    };
 
 /**
  * Input for `createScopeFromAnchor` — sub-block marker-backed scope.
@@ -144,6 +168,8 @@ export interface CreateScopeFromAnchorInput {
   };
   readonly mode?: "edit" | "suggest" | "comment" | "view";
   readonly label?: string;
+  readonly visibility?: ScopeVisibility;
+  readonly guardPolicy?: WorkflowScopeGuardPolicy;
   readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
   readonly stableRefHint?:
     | "scope-id"
@@ -174,6 +200,22 @@ export type CreateScopeFromAnchorResult =
       readonly nextStep: string;
     };
 
+export interface SetScopeGuardPolicyInput {
+  readonly scopeId: string;
+  readonly guardPolicy: WorkflowScopeGuardPolicy;
+}
+
+export type SetScopeGuardPolicyResult =
+  | {
+      readonly status: "updated";
+      readonly scopeId: string;
+      readonly guardPolicy: WorkflowScopeGuardPolicy;
+    }
+  | {
+      readonly status: "scope-not-found";
+      readonly scopeId: string;
+    };
+
 export const createScopeMetadata: ApiV3FnMetadata = {
   name: "runtime.workflow.createScope",
   status: "live-with-adapter",
@@ -216,6 +258,51 @@ export const createScopeFromAnchorMetadata: ApiV3FnMetadata = {
     "§Runtime API § runtime.workflow.createScopeFromAnchor. Companion to createScope({blockId}) for sub-block ranges. Consumes from/to once to plant inline scope_marker_start/end; the returned scopeId is the durable reference (KI-P9).",
 };
 
+export const getScopeGuardPolicyMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.getScopeGuardPolicy",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/workflow-create-scope-live.test.ts",
+    commit: "guard-policy-setter",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "scope-policy",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.getScopeGuardPolicy",
+};
+
+export const setScopeGuardPolicyMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.setScopeGuardPolicy",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/workflow-create-scope-live.test.ts",
+    commit: "guard-policy-setter",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta:
+      "scope edit-enforcement policy updates and interaction guard recalculates",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "scope",
+    auditCategory: "scope-policy",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "§Runtime API § runtime.workflow.setScopeGuardPolicy",
+};
+
 export interface AttachMetadataInput {
   readonly scopeId: string;
   readonly metadataId: string;
@@ -476,6 +563,8 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
         blockId: input.blockId,
         mode: input.mode,
         label: input.label,
+        ...(input.visibility ? { visibility: input.visibility } : {}),
+        ...(input.guardPolicy ? { guardPolicy: input.guardPolicy } : {}),
         ...(input.assoc ? { assoc: input.assoc } : {}),
         ...(input.stableRefHint
           ? { stableRefHint: input.stableRefHint }
@@ -493,11 +582,68 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
             : undefined,
       });
       if (adapterResult.status !== "created") {
-        return { scopeId: "", status: adapterResult.status };
+        if (adapterResult.status === "block-not-found") {
+          return { scopeId: "", status: "block-not-found" };
+        }
+        return {
+          scopeId: "",
+          status: "range-invalid",
+          reason: adapterResult.reason,
+          from: adapterResult.from,
+          to: adapterResult.to,
+          storyLength: adapterResult.storyLength,
+          ...(adapterResult.blockIndex !== undefined
+            ? { blockIndex: adapterResult.blockIndex }
+            : {}),
+          ...(adapterResult.blockKind !== undefined
+            ? { blockKind: adapterResult.blockKind }
+            : {}),
+          message: adapterResult.message,
+          nextStep: adapterResult.nextStep,
+        };
       }
       return { scopeId: adapterResult.scopeId, status: "created" };
     },
 
+    getScopeGuardPolicy(scopeId: string): WorkflowScopeGuardPolicy {
+      // @endStateApi — live.
+      return runtime.getScopeGuardPolicy(scopeId);
+    },
+
+    setScopeGuardPolicy(
+      input: SetScopeGuardPolicyInput,
+    ): SetScopeGuardPolicyResult {
+      // @endStateApi — live. Mutates the scope's explicit guard axis in the
+      // workflow overlay. Visibility stays presentation-only.
+      const overlay = runtime.getWorkflowOverlay();
+      const existingScope = overlay?.scopes.find(
+        (scope) => scope.scopeId === input.scopeId,
+      );
+      if (!existingScope) {
+        return { status: "scope-not-found", scopeId: input.scopeId };
+      }
+      runtime.setScopeGuardPolicy(input.scopeId, input.guardPolicy);
+      emitUxResponse(runtime, {
+        apiFn: setScopeGuardPolicyMetadata.name,
+        intent: setScopeGuardPolicyMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: setScopeGuardPolicyMetadata.uxIntent.expectedDelta,
+        actualDelta: {
+          kind: "inline-change",
+          payload: {
+            scopeId: input.scopeId,
+            guardPolicy: input.guardPolicy,
+          },
+        },
+      });
+      return {
+        status: "updated",
+        scopeId: input.scopeId,
+        guardPolicy: input.guardPolicy,
+      };
+    },
+
     createScopeFromAnchor(
       input: CreateScopeFromAnchorInput,
     ): CreateScopeFromAnchorResult {
@@ -510,6 +656,8 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
         anchor: input.anchor,
         mode: input.mode,
         label: input.label,
+        ...(input.visibility ? { visibility: input.visibility } : {}),
+        ...(input.guardPolicy ? { guardPolicy: input.guardPolicy } : {}),
         ...(input.assoc ? { assoc: input.assoc } : {}),
         ...(input.stableRefHint
           ? { stableRefHint: input.stableRefHint }

package/src/io/export/serialize-main-document.ts

@@ -89,6 +89,14 @@ interface SerializationState {
   usedTextIds: Set<string>;
   /** Deterministic PRNG-less counter used when we mint fresh ids. */
   mintedParaIdCounter: number;
+  /**
+   * Scope markers export as OOXML bookmarks. `w:bookmarkStart/@w:id` is a
+   * decimal number in WordprocessingML, so scope ids cannot be written into
+   * it directly.
+   */
+  usedBookmarkIds: Set<string>;
+  scopeBookmarkIds: Map<string, string>;
+  nextScopeBookmarkId: number;
 }
 
 interface InlineSerializationResult {
@@ -117,6 +125,61 @@ function serializePerformanceNow(): number {
   return Date.now();
 }
 
+function collectNumericBookmarkIds(content: DocumentRootNode): Set<string> {
+  const used = new Set<string>();
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== "object") return;
+    const typed = node as {
+      type?: string;
+      bookmarkId?: unknown;
+      children?: unknown;
+      rows?: unknown;
+      cells?: unknown;
+    };
+    if (
+      (typed.type === "bookmark_start" || typed.type === "bookmark_end") &&
+      typeof typed.bookmarkId === "string"
+    ) {
+      const normalized = normalizeDecimalBookmarkId(typed.bookmarkId);
+      if (normalized !== null) used.add(normalized);
+    }
+
+    if (Array.isArray(typed.children)) {
+      for (const child of typed.children) visit(child);
+    }
+    if (Array.isArray(typed.rows)) {
+      for (const row of typed.rows) visit(row);
+    }
+    if (Array.isArray(typed.cells)) {
+      for (const cell of typed.cells) visit(cell);
+    }
+  };
+
+  visit(content);
+  return used;
+}
+
+function normalizeDecimalBookmarkId(id: string): string | null {
+  if (!/^\d+$/u.test(id)) return null;
+  const stripped = id.replace(/^0+/u, "");
+  return stripped.length > 0 ? stripped : "0";
+}
+
+function scopeBookmarkIdFor(state: SerializationState, scopeId: string): string {
+  const existing = state.scopeBookmarkIds.get(scopeId);
+  if (existing !== undefined) return existing;
+
+  let next = state.nextScopeBookmarkId;
+  while (state.usedBookmarkIds.has(String(next))) {
+    next += 1;
+  }
+  const bookmarkId = String(next);
+  state.nextScopeBookmarkId = next + 1;
+  state.usedBookmarkIds.add(bookmarkId);
+  state.scopeBookmarkIds.set(scopeId, bookmarkId);
+  return bookmarkId;
+}
+
 export function serializeMainDocument(
   content: DocumentRootNode,
   preservation: PreservationStore = { opaqueFragments: {}, packageParts: {} },
@@ -150,6 +213,9 @@ export function serializeMainDocument(
     usedParaIds: new Set<string>(),
     usedTextIds: new Set<string>(),
     mintedParaIdCounter: 0,
+    usedBookmarkIds: collectNumericBookmarkIds(content),
+    scopeBookmarkIds: new Map<string, string>(),
+    nextScopeBookmarkId: 100000,
   };
   const suffix = `</w:body>\n</w:document>`;
   const bodyPieces: string[] = [];
@@ -679,9 +745,9 @@ function serializeTableInlineNode(
       return `<w:bookmarkEnd w:id="${escapeXmlAttribute(node.bookmarkId)}"/>`;
     case "scope_marker_start": {
       // S1 — scope markers export as w:bookmarkStart with the reserved
-      // `bw:scope:` name prefix. The synthetic w:id is keyed on scopeId so
-      // the matching end element references the same id.
-      const bkId = `scope-${node.scopeId}`;
+      // `bw:scope:` name prefix. The synthetic w:id is numeric because
+      // WordprocessingML bookmark ids are ST_DecimalNumber values.
+      const bkId = scopeBookmarkIdFor(state, node.scopeId);
       const name = `${SCOPE_MARKER_BOOKMARK_PREFIX}${node.scopeId}`;
       return (
         `<w:bookmarkStart w:id="${escapeXmlAttribute(bkId)}"` +
@@ -689,7 +755,7 @@ function serializeTableInlineNode(
       );
     }
     case "scope_marker_end": {
-      const bkId = `scope-${node.scopeId}`;
+      const bkId = scopeBookmarkIdFor(state, node.scopeId);
       return `<w:bookmarkEnd w:id="${escapeXmlAttribute(bkId)}"/>`;
     }
     case "footnote_ref": {
@@ -1258,7 +1324,7 @@ function serializeInlineNode(
     case "scope_marker_start": {
       // S1 — mirror the bookmark_start shape with the reserved `bw:scope:`
       // name prefix. See serializeInline() above for the same convention.
-      const bkId = `scope-${node.scopeId}`;
+      const bkId = scopeBookmarkIdFor(state, node.scopeId);
       const name = `${SCOPE_MARKER_BOOKMARK_PREFIX}${node.scopeId}`;
       const xml =
         `<w:bookmarkStart w:id="${escapeXmlAttribute(bkId)}"` +
@@ -1269,7 +1335,7 @@ function serializeInlineNode(
       return { xml, cursor, boundaries };
     }
     case "scope_marker_end": {
-      const bkId = `scope-${node.scopeId}`;
+      const bkId = scopeBookmarkIdFor(state, node.scopeId);
       const xml = `<w:bookmarkEnd w:id="${escapeXmlAttribute(bkId)}"/>`;
       const boundaries = new Map<number, number>();
       boundaries.set(cursor, xmlOffset);

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

@@ -40,6 +40,8 @@ export interface ValidatorIssue {
 
 const OVERLAY_PERSISTENCE_VALUES = ["internal", "external"] as const;
 const SCOPE_PERSISTENCE_VALUES = ["internal", "external", "inherit"] as const;
+const SCOPE_VISIBILITY_VALUES = ["visible", "hidden", "invisible"] as const;
+const SCOPE_GUARD_POLICY_VALUES = ["none", "insert-only", "read-only"] as const;
 
 export function validateWorkflowPayloadEnvelope(xml: string): ValidatorIssue[] {
   const issues: ValidatorIssue[] = [];
@@ -82,6 +84,28 @@ export function validateWorkflowPayloadEnvelope(xml: string): ValidatorIssue[] {
   for (const scope of findAll(xml, /<bw:scope\b([^>]*?)>([\s\S]*?)<\/bw:scope>/gu)) {
     const scopeAttrs = parseAttrs(scope.attrs);
     const scopeId = scopeAttrs.id ?? "?";
+    if (
+      scopeAttrs.visibility !== undefined &&
+      !(SCOPE_VISIBILITY_VALUES as readonly string[]).includes(scopeAttrs.visibility)
+    ) {
+      issues.push({
+        code: "unknown_enum_value",
+        path: `bw:scope[@id='${scopeId}']/@visibility`,
+        value: scopeAttrs.visibility,
+        severity: "warning",
+      });
+    }
+    if (
+      scopeAttrs.guardPolicy !== undefined &&
+      !(SCOPE_GUARD_POLICY_VALUES as readonly string[]).includes(scopeAttrs.guardPolicy)
+    ) {
+      issues.push({
+        code: "unknown_enum_value",
+        path: `bw:scope[@id='${scopeId}']/@guardPolicy`,
+        value: scopeAttrs.guardPolicy,
+        severity: "warning",
+      });
+    }
     let scopePersistence: string | undefined = scopeAttrs.metadataPersistence;
     if (scopePersistence !== undefined) {
       if (

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

@@ -927,6 +927,8 @@ function buildWorkflowScopeXml(scope: WorkflowScope): string {
     scope.workItemId ? ` workItemRef="${escapeXml(scope.workItemId)}"` : "",
     scope.label ? ` label="${escapeXml(scope.label)}"` : "",
     scope.domain ? ` domain="${escapeXml(scope.domain)}"` : "",
+    scope.visibility ? ` visibility="${escapeXml(scope.visibility)}"` : "",
+    scope.guardPolicy ? ` guardPolicy="${escapeXml(scope.guardPolicy)}"` : "",
     scope.metadataPersistence && scope.metadataPersistence !== "inherit"
       ? ` metadataPersistence="${escapeXml(scope.metadataPersistence)}"`
       : "",
@@ -1166,6 +1168,14 @@ function parseWorkflowScope(attributesSource: string, body: string): WorkflowSco
     attributes.metadataPersistence,
     ["internal", "external", "inherit"] as const,
   );
+  const visibility = parseClosedEnum(
+    attributes.visibility,
+    ["visible", "hidden", "invisible"] as const,
+  );
+  const guardPolicy = parseClosedEnum(
+    attributes.guardPolicy,
+    ["none", "insert-only", "read-only"] as const,
+  );
 
   return {
     scopeId: attributes.id,
@@ -1177,6 +1187,8 @@ function parseWorkflowScope(attributesSource: string, body: string): WorkflowSco
     label: attributes.label,
     domain: attributes.domain as WorkflowScope["domain"],
     metadata: parseWorkflowScopeMetadata(body),
+    ...(visibility !== undefined ? { visibility } : {}),
+    ...(guardPolicy !== undefined ? { guardPolicy } : {}),
     ...(scopeMetadataPersistence !== undefined ? { metadataPersistence: scopeMetadataPersistence } : {}),
   };
 }

package/src/runtime/document-runtime.ts

@@ -94,6 +94,7 @@ import type {
   ScopeQueryFilter,
   ScopeQueryResult,
   ScopeVisibility,
+  WorkflowScopeGuardPolicy,
   ScopeChromeVisibilityState,
   SearchOptions,
   TextStyleFilter,
@@ -588,6 +589,13 @@ export interface DocumentRuntime {
   setScopeVisibility(scopeId: string, visibility: ScopeVisibility): void;
   /** §C8 — Get a scope's current visibility (absent = "visible"). */
   getScopeVisibility(scopeId: string): ScopeVisibility;
+  /** Scope edit-enforcement posture (collab-replicated). */
+  setScopeGuardPolicy(
+    scopeId: string,
+    guardPolicy: WorkflowScopeGuardPolicy,
+  ): void;
+  /** Effective scope edit-enforcement posture (unknown = "none"). */
+  getScopeGuardPolicy(scopeId: string): WorkflowScopeGuardPolicy;
   /** §C7 — Set local chrome visibility state (never collab-replicated). */
   setScopeChromeVisibility(state: ScopeChromeVisibilityState): void;
   /** §C7 — Get local chrome visibility state (default: { mode: "all" }). */
@@ -3095,6 +3103,7 @@ export function createDocumentRuntime(
               {
                 selection: createSelectionFromPublicAnchor(anchor),
                 blockedCommandName: "applyScopeReplacement",
+                skipWorkflowGuard: true,
               },
             );
           } catch (error) {
@@ -3129,6 +3138,7 @@ export function createDocumentRuntime(
               {
                 selection: createSelectionFromPublicAnchor(anchor),
                 blockedCommandName: "applyScopeReplacement",
+                skipWorkflowGuard: true,
               },
             );
           } catch (error) {
@@ -3168,6 +3178,7 @@ export function createDocumentRuntime(
                 selection: createSelectionFromPublicAnchor(anchor),
                 blockedCommandName: "applyScopeReplacement",
                 documentModeOverride: "suggesting",
+                skipWorkflowGuard: true,
               },
             );
           } catch (error) {
@@ -3200,6 +3211,7 @@ export function createDocumentRuntime(
                 selection: createSelectionFromPublicAnchor(anchor),
                 blockedCommandName: "applyScopeReplacement",
                 documentModeOverride: "suggesting",
+                skipWorkflowGuard: true,
               },
             );
           } catch (error) {
@@ -3580,6 +3592,12 @@ export function createDocumentRuntime(
     getScopeVisibility(scopeId) {
       return workflowCoordinator.getScopeVisibility(scopeId);
     },
+    setScopeGuardPolicy(scopeId, guardPolicy) {
+      workflowCoordinator.setScopeGuardPolicy(scopeId, guardPolicy);
+    },
+    getScopeGuardPolicy(scopeId) {
+      return workflowCoordinator.getScopeGuardPolicy(scopeId);
+    },
     setScopeChromeVisibility(chromeVisibility) {
       workflowCoordinator.setScopeChromeVisibility(chromeVisibility);
     },
@@ -4939,6 +4957,13 @@ export function createDocumentRuntime(
        * override to the context that `executeEditorCommand` reads.
        */
       documentModeOverride?: DocumentMode;
+      /**
+       * Scope replacements are validated against their target scope by the
+       * Layer-08 compiler before reaching this mechanical dispatch step.
+       * Re-running the selection-scoped workflow guard here would make the
+       * live cursor, not the target scope, decide whether the edit lands.
+       */
+      skipWorkflowGuard?: boolean;
     } = {},
   ): TextCommandAck {
     emitStageToken(telemetryBus, "command", "command.dispatch.start", {
@@ -4980,20 +5005,22 @@ export function createDocumentRuntime(
         blockedReasons: [{ code: "suggesting_unsupported", message }],
       });
     }
-    const blockedReasons = workflowCoordinator.evaluateBlockedReasons(selection, command.type);
-    if (blockedReasons.length > 0) {
-      emit({
-        type: "command_blocked",
-        documentId: state.documentId,
-        command: textOptions.blockedCommandName ?? command.type,
-        reasons: blockedReasons,
-      });
-      return completeDispatch({
-        kind: "rejected",
-        opId,
-        newRevisionToken: "",
-        blockedReasons: blockedReasons.map((r) => ({ code: r.code, message: r.message })),
-      });
+    if (!textOptions.skipWorkflowGuard) {
+      const blockedReasons = workflowCoordinator.evaluateBlockedReasons(selection, command.type);
+      if (blockedReasons.length > 0) {
+        emit({
+          type: "command_blocked",
+          documentId: state.documentId,
+          command: textOptions.blockedCommandName ?? command.type,
+          reasons: blockedReasons,
+        });
+        return completeDispatch({
+          kind: "rejected",
+          opId,
+          newRevisionToken: "",
+          blockedReasons: blockedReasons.map((r) => ({ code: r.code, message: r.message })),
+        });
+      }
     }
 
     const timestamp = normalizeCommandTimestamp(command.origin?.timestamp) ?? clock();

package/src/runtime/scopes/_scope-dependencies.ts

@@ -37,6 +37,7 @@ export type {
   WorkflowMetadataSnapshot,
   WorkflowOverlay,
   WorkflowScope,
+  WorkflowScopeGuardPolicy,
   WorkflowScopeMetadataField,
 } from "../../api/public-types.ts";
 

package/src/runtime/scopes/action-validation.ts

@@ -204,55 +204,64 @@ function collectGuardVerdict(
   }
 
   const guard = runtime.getInteractionGuardSnapshot();
-  if (
-    guard.effectiveMode === "view" &&
-    !blockedReasons.includes("guard:view-mode-active")
-  ) {
-    blockedReasons.push("guard:view-mode-active");
+  // Scope-targeted writes target `scope.handle.scopeId`, not the current
+  // editor selection. The target scope's own overlay posture was handled
+  // above through `scope.workflow.effectiveMode`; this second guard read is
+  // only allowed to contribute global/session-wide blockers.
+  const isSelectionScopeMembershipReason = (reason: { readonly code: string; readonly scopeId?: string }): boolean => {
+    if (reason.code === "outside_workflow_scope") return true;
+    if (
+      (reason.code === "workflow_view_only" ||
+        reason.code === "workflow_comment_only") &&
+      typeof reason.scopeId === "string" &&
+      reason.scopeId.length > 0
+    ) {
+      return true;
+    }
+    return false;
+  };
+  const rawReasons = guard.blockedReasons ?? [];
+  const nonSelectionScoped = rawReasons.filter(
+    (r) => !isSelectionScopeMembershipReason(r),
+  );
+  const pushTypedGuardBlocker = (code: string | undefined): void => {
+    const suffix = typeof code === "string" && code.length > 0
+      ? code
+      : "unspecified";
+    const typedBlocker = `guard:block-${suffix}`;
+    if (!blockedReasons.some((existing) => existing === typedBlocker)) {
+      blockedReasons.push(typedBlocker);
+    }
+  };
+  if (guard.effectiveMode === "view") {
+    const globalViewReason = nonSelectionScoped.find(
+      (reason) => reason.code === "workflow_view_only",
+    );
+    if (globalViewReason) {
+      pushTypedGuardBlocker(globalViewReason.code);
+    } else if (
+      rawReasons.length === 0 &&
+      !blockedReasons.includes("guard:view-mode-active")
+    ) {
+      blockedReasons.push("guard:view-mode-active");
+    }
+  }
+  if (guard.effectiveMode === "comment") {
+    const globalCommentReason = nonSelectionScoped.find(
+      (reason) => reason.code === "workflow_comment_only",
+    );
+    if (globalCommentReason) {
+      pushTypedGuardBlocker(globalCommentReason.code);
+    }
   }
   if (guard.effectiveMode === "blocked") {
     // Coord-06 §13e — promote the bare `guard:blocked` blocker to a typed
-    // `guard:block-<reason>` suffix so agents can route intelligently on
-    // boundary-paragraph / system-paragraph / read-only / protected-range
-    // situations. The specific sub-reason is the first NON-selection-
-    // scope-membership reason.
-    //
-    // Scope-targeted-write carve-out (coord-09, TemplateViewer repro
-    // 2026-04-24): `applyReplacementScope`, `attachExplanation`, and
-    // `createIssue` target a scopeId, not the current editor selection.
-    // The scope's own `workflow.effectiveMode` already drove the
-    // scope-level arm of `collectGuardVerdict` above (lines 159–197).
-    // The selection-scoped coordinator guard, in contrast, evaluates
-    // against the live `state.selection` — which, for scope-targeted
-    // writes, may sit anywhere in the document. Reasons that depend on
-    // selection-scope membership (`outside_workflow_scope`,
-    // `workflow_view_only`, `workflow_comment_only`) are therefore
-    // double-counting and must not block. Globally-scoped reasons
-    // (`document_read_only`, `document_viewing_mode`) still apply — a
-    // read-only doc rejects every write, scope-targeted or not.
-    const SELECTION_SCOPE_MEMBERSHIP_CODES = new Set([
-      "outside_workflow_scope",
-      "workflow_view_only",
-      "workflow_comment_only",
-    ]);
-    const rawReasons = guard.blockedReasons ?? [];
-    const nonSelectionScoped = rawReasons.filter(
-      (r) => !SELECTION_SCOPE_MEMBERSHIP_CODES.has(r.code),
-    );
-    // If every reason was selection-scope-membership for a scope-
-    // targeted write, emit no blocker — the scope-level arm above is
-    // authoritative. The defensive empty-array fallback
-    // (guard:block-unspecified) still fires when the coordinator
-    // produced effectiveMode:"blocked" without any reasons at all.
+    // `guard:block-<reason>` suffix. Selection-membership reasons are
+    // intentionally ignored here; global/session reasons such as read-only,
+    // protected ranges, shared workflow locks, and unsupported suggesting
+    // commands remain blockers.
     if (nonSelectionScoped.length > 0 || rawReasons.length === 0) {
-      const primaryCode = nonSelectionScoped[0]?.code;
-      const suffix = typeof primaryCode === "string" && primaryCode.length > 0
-        ? primaryCode
-        : "unspecified";
-      const typedBlocker = `guard:block-${suffix}`;
-      if (!blockedReasons.some((existing) => existing === typedBlocker)) {
-        blockedReasons.push(typedBlocker);
-      }
+      pushTypedGuardBlocker(nonSelectionScoped[0]?.code);
     }
   }
   for (const reason of guard.blockedReasons ?? []) {

package/src/runtime/scopes/workflow-overlap.ts

@@ -3,11 +3,13 @@
  *
  * Given a scope's canonical range and the workflow overlay, returns the
  * `SemanticScopeWorkflow` projection: the ids of overlay scopes overlapping
- * the range + the most-restrictive `effectiveMode` across them +
- * `blockedReasons` when a `view`-mode overlap blocks the scope.
+ * the range + the most-restrictive enforced `effectiveMode` across scopes
+ * whose `guardPolicy` participates in editing + `blockedReasons` when a
+ * read-only overlap blocks the scope.
  *
  * The most-restrictive rule matches layer 06's `InteractionGuardSnapshot`
- * composition (see `docs/architecture/06-workflow-review.md` §W3):
+ * composition for guard-participating scopes (see
+ * `docs/architecture/06-workflow-review.md` §W3):
  *   view > comment > suggest > edit
  *
  * When no overlay is threaded, or no overlap exists, the returned shape
@@ -19,7 +21,11 @@
  * overlap on top.
  */
 
-import type { WorkflowOverlay, WorkflowScope } from "./_scope-dependencies.ts";
+import type {
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeGuardPolicy,
+} from "./_scope-dependencies.ts";
 
 import type { ScopePositionMap, ScopePositionRange } from "./position-map.ts";
 import { rangesOverlap } from "./scope-range.ts";
@@ -27,6 +33,14 @@ import type { SemanticScopeWorkflow } from "./semantic-scope-types.ts";
 
 type WorkflowMode = "edit" | "suggest" | "comment" | "view";
 
+function getScopeGuardPolicy(scope: WorkflowScope): WorkflowScopeGuardPolicy {
+  return scope.guardPolicy ?? (scope.mode === "view" ? "read-only" : "none");
+}
+
+function getScopeGuardMode(scope: WorkflowScope): WorkflowMode {
+  return getScopeGuardPolicy(scope) === "read-only" ? "view" : scope.mode;
+}
+
 function modeRank(mode: WorkflowMode): number {
   // Higher = more restrictive (wins the merge).
   switch (mode) {
@@ -45,6 +59,21 @@ function mergeModes(a: WorkflowMode, b: WorkflowMode): WorkflowMode {
   return modeRank(a) >= modeRank(b) ? a : b;
 }
 
+function rangeForWorkflowScope(
+  scope: WorkflowScope,
+  positionMap: ScopePositionMap,
+): ScopePositionRange | null {
+  const markerRange = positionMap.markerScopes.get(scope.scopeId);
+  if (markerRange) return markerRange;
+  if (scope.anchor.kind === "range") {
+    return { from: scope.anchor.from, to: scope.anchor.to };
+  }
+  if (scope.anchor.kind === "node") {
+    return { from: scope.anchor.at, to: scope.anchor.at };
+  }
+  return null;
+}
+
 export interface WorkflowOverlapInputs {
   readonly overlay: WorkflowOverlay | null | undefined;
   readonly positionMap: ScopePositionMap;
@@ -73,12 +102,15 @@ export function resolveWorkflowOverlap(
   let mode: WorkflowMode = "edit";
   for (const scope of overlay.scopes as readonly WorkflowScope[]) {
     if (selfScopeIds && selfScopeIds.has(scope.scopeId)) continue;
-    const markerRange = positionMap.markerScopes.get(scope.scopeId);
-    if (!markerRange) continue;
-    if (!rangesOverlap(range, markerRange)) continue;
+    const scopeRange = rangeForWorkflowScope(scope, positionMap);
+    if (!scopeRange) continue;
+    if (!rangesOverlap(range, scopeRange)) continue;
     overlappingIds.push(scope.scopeId);
-    mode = mergeModes(mode, scope.mode);
-    if (scope.mode === "view") {
+    const guardPolicy = getScopeGuardPolicy(scope);
+    if (guardPolicy === "none") continue;
+    const guardMode = getScopeGuardMode(scope);
+    mode = mergeModes(mode, guardMode);
+    if (guardMode === "view") {
       blockedReasons.push(`workflow-scope-view:${scope.scopeId}`);
     }
   }

package/src/runtime/workflow/coordinator.ts

@@ -64,6 +64,7 @@ import type {
   WorkflowMetadataSnapshot,
   WorkflowOverlay,
   WorkflowScope,
+  WorkflowScopeGuardPolicy,
   WorkflowScopeMode,
   WorkflowScopeSnapshot,
 } from "../../api/public-types.ts";
@@ -227,6 +228,11 @@ export interface WorkflowCoordinator {
   addInvisibleScope(params: AddScopeParams): AddScopeResult;
   setScopeVisibility(scopeId: string, visibility: ScopeVisibility): void;
   getScopeVisibility(scopeId: string): ScopeVisibility;
+  setScopeGuardPolicy(
+    scopeId: string,
+    guardPolicy: WorkflowScopeGuardPolicy,
+  ): void;
+  getScopeGuardPolicy(scopeId: string): WorkflowScopeGuardPolicy;
   getScope(scopeId: string): WorkflowScope | null;
   getMarkerBackedScopeIds(): ReadonlySet<string>;
   /* --- scope chrome visibility (local view state) --- */
@@ -316,6 +322,18 @@ const MODE_RESTRICTIVENESS: Record<WorkflowScopeMode, number> = {
   view: 3,
 };
 
+function resolveScopeGuardPolicy(scope: WorkflowScope): WorkflowScopeGuardPolicy {
+  return scope.guardPolicy ?? (scope.mode === "view" ? "read-only" : "none");
+}
+
+function getScopeGuardMode(scope: WorkflowScope): WorkflowScopeMode {
+  return resolveScopeGuardPolicy(scope) === "read-only" ? "view" : scope.mode;
+}
+
+function participatesInInteractionGuard(scope: WorkflowScope): boolean {
+  return resolveScopeGuardPolicy(scope) !== "none";
+}
+
 export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordinator {
   const { overlayStore, clock } = deps;
 
@@ -413,8 +431,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     };
     const activeScopes = getEffectiveWorkflowScopes(overlay);
     const matching = activeScopes.filter((scope) => {
-      // §C8: invisible non-view scopes are transparent to the guard.
-      if (scope.visibility === "invisible" && scope.mode !== "view") return false;
+      if (!participatesInInteractionGuard(scope)) return false;
       if (scope.anchor.kind === "detached") return false;
       const scopeFrom =
         scope.anchor.kind === "range" ? scope.anchor.from : scope.anchor.at;
@@ -450,8 +467,8 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     if (stack.length === 0) return null;
     // §C6 — most-restrictive-wins across overlapping scopes.
     return stack.reduce((best, scope) =>
-      (MODE_RESTRICTIVENESS[scope.mode] ?? 0) >
-      (MODE_RESTRICTIVENESS[best.mode] ?? 0)
+      (MODE_RESTRICTIVENESS[getScopeGuardMode(scope)] ?? 0) >
+      (MODE_RESTRICTIVENESS[getScopeGuardMode(best)] ?? 0)
         ? scope
         : best,
     );
@@ -463,7 +480,9 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     const mode = deps.getDocumentMode();
     if (mode === "viewing" || mode === "commenting") return mode;
     const matchingScope = getMatchingWorkflowScope(selection);
-    if (matchingScope?.mode === "suggest") return "suggesting";
+    if (matchingScope && getScopeGuardMode(matchingScope) === "suggest") {
+      return "suggesting";
+    }
     return mode;
   }
 
@@ -536,17 +555,18 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     if (normalized) {
       const matchingScope = getMatchingWorkflowScope(selection);
       const activeScopes = getEffectiveWorkflowScopes(normalized);
-      const guardingScopes = activeScopes.filter(
-        (s) => !(s.visibility === "invisible" && s.mode !== "view"),
+      const insertOnlyScopes = activeScopes.filter(
+        (s) => resolveScopeGuardPolicy(s) === "insert-only",
       );
 
-      if (!matchingScope && guardingScopes.length > 0) {
+      if (!matchingScope && insertOnlyScopes.length > 0) {
         reasons.push({
           code: "outside_workflow_scope",
-          message: "Selection is outside any active workflow scope.",
+          message: "Selection is outside any active insert-only workflow scope.",
         });
       } else if (matchingScope) {
-        if (matchingScope.mode === "comment") {
+        const guardMode = getScopeGuardMode(matchingScope);
+        if (guardMode === "comment") {
           const isCommentCommand = commandType?.startsWith("comment.") ?? false;
           if (!isCommentCommand) {
             reasons.push({
@@ -556,7 +576,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
               workItemId: matchingScope.workItemId,
             });
           }
-        } else if (matchingScope.mode === "view") {
+        } else if (guardMode === "view") {
           reasons.push({
             code: "workflow_view_only",
             message: `Scope "${matchingScope.label ?? matchingScope.scopeId}" is view-only.`,
@@ -618,6 +638,9 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     const matchingScope = getMatchingWorkflowScope(state.selection);
     const scopeStack = buildMatchingScopeStack(state.selection);
     const primaryBlockedReason = blockedReasons[0];
+    const matchingGuardMode = matchingScope
+      ? getScopeGuardMode(matchingScope)
+      : undefined;
     const effectiveMode = primaryBlockedReason
       ? primaryBlockedReason.code === "workflow_comment_only"
         ? "comment"
@@ -626,19 +649,19 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           : "blocked"
       : getEffectiveDocumentMode(state.selection) === "suggesting"
         ? "suggest"
-        : matchingScope?.mode ?? "edit";
+        : matchingGuardMode ?? "edit";
     const matchedScopeStack: InteractionGuardSnapshot["matchedScopeStack"] =
       scopeStack.length > 0
         ? scopeStack.map((s) => ({
             scopeId: s.scopeId,
-            mode: s.mode,
+            mode: getScopeGuardMode(s),
             visibility: s.visibility ?? "visible",
           }))
         : undefined;
     const snapshot: InteractionGuardSnapshot = {
       effectiveMode,
       ...(matchingScope?.scopeId ? { matchedScopeId: matchingScope.scopeId } : {}),
-      ...(matchingScope?.mode ? { matchedScopeMode: matchingScope.mode } : {}),
+      ...(matchingGuardMode ? { matchedScopeMode: matchingGuardMode } : {}),
       ...(matchedScopeStack ? { matchedScopeStack } : {}),
       targetAccess:
         effectiveMode === "edit"
@@ -888,6 +911,8 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
       anchor: publicAnchor,
       ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
       ...(params.label ? { label: params.label } : {}),
+      ...(params.visibility ? { visibility: params.visibility } : {}),
+      ...(params.guardPolicy ? { guardPolicy: params.guardPolicy } : {}),
       ...(params.scopeMetadataFields && params.scopeMetadataFields.length > 0
         ? { metadata: [...params.scopeMetadataFields] }
         : {}),
@@ -1004,6 +1029,31 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     return scope?.visibility ?? "visible";
   }
 
+  function setScopeGuardPolicy(
+    scopeId: string,
+    guardPolicy: WorkflowScopeGuardPolicy,
+  ): void {
+    const overlay = overlayStore.getOverlay();
+    if (!overlay) return;
+    const idx = overlay.scopes.findIndex((s) => s.scopeId === scopeId);
+    if (idx === -1) return;
+    const nextScopes = overlay.scopes.map((s) =>
+      s.scopeId === scopeId ? { ...s, guardPolicy } : s,
+    );
+    deps.dispatch({
+      type: "workflow.set-overlay",
+      overlay: { ...overlay, scopes: nextScopes },
+      origin: { source: "api", at: clock() },
+    });
+  }
+
+  function getScopeGuardPolicy(scopeId: string): WorkflowScopeGuardPolicy {
+    const overlay = overlayStore.getOverlay();
+    if (!overlay) return "none";
+    const scope = overlay.scopes.find((s) => s.scopeId === scopeId);
+    return scope ? resolveScopeGuardPolicy(scope) : "none";
+  }
+
   function getScope(scopeId: string): WorkflowScope | null {
     const normalized = getNormalizedOverlay();
     const fromOverlay = normalized?.scopes.find((s) => s.scopeId === scopeId);
@@ -1360,6 +1410,8 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     addInvisibleScope,
     setScopeVisibility,
     getScopeVisibility,
+    setScopeGuardPolicy,
+    getScopeGuardPolicy,
     getScope,
     getMarkerBackedScopeIds: () => overlayStore.getMarkerBackedScopeIds(),
     setScopeChromeVisibility,

package/src/runtime/workflow/scope-writer.ts

@@ -37,6 +37,8 @@ import type {
   EditorAnchorProjection,
   EditorStoryTarget,
   RuntimeRenderSnapshot,
+  ScopeVisibility,
+  WorkflowScopeGuardPolicy,
   WorkflowMetadataEntry,
   WorkflowMetadataPersistence,
   WorkflowScopeMetadataField,
@@ -62,6 +64,8 @@ export interface CreateScopeFromBlockIdInput {
   readonly persistence?: WorkflowMetadataPersistence;
   readonly metadata?: Partial<WorkflowMetadataEntry>;
   readonly storyTarget?: EditorStoryTarget;
+  readonly visibility?: ScopeVisibility;
+  readonly guardPolicy?: WorkflowScopeGuardPolicy;
   /**
    * Coord-06 §13d — per-scope edge stickiness for the range anchor.
    * Defaults to `{ start: 1, end: -1 }` (greedy — absorbs boundary
@@ -98,7 +102,23 @@ export interface CreateScopeFromBlockIdInput {
 
 export type CreateScopeFromBlockIdResult =
   | { readonly status: "created"; readonly scopeId: string; readonly anchor: EditorAnchorProjection }
-  | { readonly status: "block-not-found"; readonly blockId: string };
+  | { readonly status: "block-not-found"; readonly blockId: string }
+  | {
+      readonly status: "range-invalid";
+      readonly scopeId: "";
+      readonly reason:
+        | "range-exceeds-story-length"
+        | "non-paragraph-target"
+        | "empty-document";
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+      /** Non-paragraph target only — the offending block's index and kind. */
+      readonly blockIndex?: number;
+      readonly blockKind?: string;
+      readonly message: string;
+      readonly nextStep: string;
+    };
 
 function inlineLength(node: InlineNode): number {
   switch (node.type) {
@@ -190,8 +210,9 @@ export function createScopeFromBlockId(
   runtime: ScopeWriterRuntime,
   input: CreateScopeFromBlockIdInput,
 ): CreateScopeFromBlockIdResult {
+  const document = runtime.getCanonicalDocument();
   const anchor = resolveBlockAnchorFromCanonical(
-    runtime.getCanonicalDocument(),
+    document,
     input.blockId,
     input.assoc,
   );
@@ -216,10 +237,63 @@ export function createScopeFromBlockId(
     metadata: input.metadata,
     storyTarget: input.storyTarget,
     label: input.label,
+    ...(input.visibility ? { visibility: input.visibility } : {}),
+    ...(input.guardPolicy ? { guardPolicy: input.guardPolicy } : {}),
     ...(scopeMetadataFields.length > 0
       ? { scopeMetadataFields }
       : {}),
   });
+  if (result.plantStatus && result.plantStatus.planted === false) {
+    const ps = result.plantStatus;
+    const from = anchor.kind === "range" ? anchor.from : 0;
+    const to = anchor.kind === "range" ? anchor.to : from;
+    const storyLength = ps.storyLength ?? computeMainStoryLength(document);
+    if (ps.reason === "non-paragraph-target") {
+      return {
+        status: "range-invalid",
+        scopeId: "",
+        reason: "non-paragraph-target",
+        from,
+        to,
+        storyLength,
+        blockIndex: ps.blockIndex ?? -1,
+        blockKind: ps.blockKind ?? "unknown",
+        message:
+          `createScope refused blockId "${input.blockId}": it resolves to a ` +
+          `${ps.blockKind ?? "non-paragraph"} block (index ${ps.blockIndex}). ` +
+          `Marker-backed scopes only plant inside paragraphs today; choose a ` +
+          `paragraph block or create an overlay-only scope for table/SDT metadata.`,
+        nextStep: "pick-a-paragraph-block-or-use-overlay-only-scope",
+      };
+    }
+    if (ps.reason === "range-out-of-bounds") {
+      return {
+        status: "range-invalid",
+        scopeId: "",
+        reason: "range-exceeds-story-length",
+        from,
+        to,
+        storyLength,
+        message:
+          `createScope refused blockId "${input.blockId}": resolved range ` +
+          `[${from}, ${to}] exceeds the current story length (${storyLength}). ` +
+          `Re-query block ids from the current render snapshot before retrying.`,
+        nextStep: "re-query-current-block-id",
+      };
+    }
+    return {
+      status: "range-invalid",
+      scopeId: "",
+      reason: "empty-document",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScope refused blockId "${input.blockId}": the target document ` +
+        `has no blocks, so scope markers cannot be planted.`,
+      nextStep: "initialize-document-before-creating-scopes",
+    };
+  }
   return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
 }
 
@@ -251,6 +325,8 @@ export interface CreateScopeFromAnchorInput {
   readonly scopeId?: string;
   readonly persistence?: WorkflowMetadataPersistence;
   readonly metadata?: Partial<WorkflowMetadataEntry>;
+  readonly visibility?: ScopeVisibility;
+  readonly guardPolicy?: WorkflowScopeGuardPolicy;
   /**
    * Per-scope edge stickiness for the range anchor. Defaults to
    * `{ start: 1, end: -1 }` (greedy — absorbs boundary inserts). See
@@ -423,6 +499,8 @@ export function createScopeFromAnchor(
     metadata: input.metadata,
     storyTarget,
     label: input.label,
+    ...(input.visibility ? { visibility: input.visibility } : {}),
+    ...(input.guardPolicy ? { guardPolicy: input.guardPolicy } : {}),
     ...(scopeMetadataFields.length > 0 ? { scopeMetadataFields } : {}),
   });
 
@@ -448,9 +526,9 @@ export function createScopeFromAnchor(
         message:
           `createScopeFromAnchor refused: range [${from}, ${to}] targets a ` +
           `${ps.blockKind ?? "non-paragraph"} block (index ${ps.blockIndex}). ` +
-          `Marker scopes only plant inside paragraphs today. Pick a paragraph ` +
-          `target, or use runtime.workflow.createScope({blockId}) for ` +
-          `whole-block scopes on the containing structure.`,
+          `Marker-backed scopes only plant inside paragraphs today. Pick a ` +
+          `paragraph target, or create an overlay-only scope for table/SDT ` +
+          `metadata until structural marker support lands.`,
         nextStep: "pick-a-paragraph-target",
       };
     }

package/src/shell/session-bootstrap.ts

@@ -1289,6 +1289,8 @@ function createLoadingRuntimeBridge(input: {
     addInvisibleScope: () => ({ scopeId: "", anchor: { kind: "range", from: 0, to: 0, assoc: { start: -1, end: 1 } } }),
     setScopeVisibility: () => undefined,
     getScopeVisibility: () => "visible" as const,
+    setScopeGuardPolicy: () => undefined,
+    getScopeGuardPolicy: () => "none" as const,
     setScopeChromeVisibility: () => undefined,
     getScopeChromeVisibility: () => ({ mode: "all" as const }),
     subscribeToScopeQuery: (_filter, _callback) => () => undefined,

package/src/ui/WordReviewEditor.tsx

@@ -393,6 +393,8 @@ export function __createWordReviewEditorRefBridge(
     addInvisibleScope: (params) => runtime.addInvisibleScope(params),
     setScopeVisibility: (scopeId, visibility) => runtime.setScopeVisibility(scopeId, visibility),
     getScopeVisibility: (scopeId) => runtime.getScopeVisibility(scopeId),
+    setScopeGuardPolicy: (scopeId, guardPolicy) => runtime.setScopeGuardPolicy(scopeId, guardPolicy),
+    getScopeGuardPolicy: (scopeId) => runtime.getScopeGuardPolicy(scopeId),
     setScopeChromeVisibility: (state) => runtime.setScopeChromeVisibility(state),
     getScopeChromeVisibility: () => runtime.getScopeChromeVisibility(),
     subscribeToScopeQuery: (filter, callback) => runtime.subscribeToScopeQuery(filter, callback),
@@ -1654,6 +1656,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         addInvisibleScope: (params) => activeRuntime.addInvisibleScope(params),
         setScopeVisibility: (scopeId, visibility) => activeRuntime.setScopeVisibility(scopeId, visibility),
         getScopeVisibility: (scopeId) => activeRuntime.getScopeVisibility(scopeId),
+        setScopeGuardPolicy: (scopeId, guardPolicy) => activeRuntime.setScopeGuardPolicy(scopeId, guardPolicy),
+        getScopeGuardPolicy: (scopeId) => activeRuntime.getScopeGuardPolicy(scopeId),
         setScopeChromeVisibility: (state) => activeRuntime.setScopeChromeVisibility(state),
         getScopeChromeVisibility: () => activeRuntime.getScopeChromeVisibility(),
         subscribeToScopeQuery: (filter, callback) => activeRuntime.subscribeToScopeQuery(filter, callback),