@beyondwork/docx-react-component 1.0.83 → 1.0.85

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/core/commands/index.ts

@@ -58,7 +58,9 @@ import {
 } from "./text-commands.ts";
 import type {
   BlockNode,
+  InlineNode,
   MutableCanonicalDocument,
+  ParagraphNode,
   RevisionRecord as CanonicalRevisionRecord,
 } from "../../model/canonical-document.ts";
 import { remapCommentThreads } from "../../review/store/comment-remapping.ts";
@@ -2314,39 +2316,93 @@ function isSingleParagraphSuggestingRange(
   to: number,
 ): boolean {
   const ranges: Array<{ start: number; end: number }> = [];
-  let cursor = 0;
-  let previousWasParagraph = false;
+  collectSuggestingParagraphRanges(
+    document.content.children,
+    0,
+    ranges,
+    true,
+  );
+
+  return ranges.some((range) => from >= range.start && to <= range.end);
+}
+
+function collectSuggestingParagraphRanges(
+  blocks: readonly BlockNode[],
+  startCursor: number,
+  output: Array<{ start: number; end: number }>,
+  addRootParagraphBoundaries: boolean,
+): number {
+  let cursor = startCursor;
+
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block = blocks[index];
+    if (!block) {
+      continue;
+    }
 
-  for (const block of document.content.children) {
     if (block.type === "paragraph") {
-      if (previousWasParagraph) {
-        cursor += 1;
-      }
       const start = cursor;
-      cursor += block.children.reduce<number>((size, child) => {
-        if (child.type === "text") {
-          return size + child.text.length;
-        }
-        if (child.type === "hyperlink") {
-          return size + child.children.reduce<number>((childSize, entry) => {
-            if (entry.type === "text") {
-              return childSize + entry.text.length;
-            }
-            return childSize + 1;
-          }, 0);
+      cursor += paragraphLogicalLength(block);
+      output.push({ start, end: cursor });
+    } else if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          cursor = collectSuggestingParagraphRanges(
+            cell.children,
+            cursor,
+            output,
+            false,
+          );
         }
-        return size + 1;
-      }, 0);
-      ranges.push({ start, end: cursor });
-      previousWasParagraph = true;
-      continue;
+      }
+    } else if (block.type === "sdt") {
+      cursor = collectSuggestingParagraphRanges(
+        block.children,
+        cursor,
+        output,
+        false,
+      );
+    } else {
+      cursor += 1;
     }
 
-    cursor += 1;
-    previousWasParagraph = false;
+    if (
+      addRootParagraphBoundaries &&
+      index < blocks.length - 1 &&
+      blocks[index + 1]?.type === "paragraph"
+    ) {
+      cursor += 1;
+    }
   }
 
-  return ranges.some((range) => from >= range.start && to <= range.end);
+  return cursor;
+}
+
+function paragraphLogicalLength(paragraph: ParagraphNode): number {
+  return paragraph.children.reduce<number>(
+    (size, child) => size + inlineLogicalLength(child),
+    0,
+  );
+}
+
+function inlineLogicalLength(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return node.text.length;
+    case "hyperlink":
+    case "field":
+      return node.children.reduce<number>(
+        (size, child) => size + inlineLogicalLength(child as InlineNode),
+        0,
+      );
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return 0;
+    default:
+      return 1;
+  }
 }
 
 function applySuggestingInsert(

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

@@ -839,6 +839,21 @@ export function normalizeCommentThreadRecord(value: unknown): CommentThreadRecor
             typeof record.metadata.rootParaId === "string"
               ? record.metadata.rootParaId
               : undefined,
+          linkedRevisionId:
+            typeof record.metadata.linkedRevisionId === "string"
+              ? record.metadata.linkedRevisionId
+              : undefined,
+          detachedReason:
+            record.metadata.detachedReason === "incomplete-markers" ||
+            record.metadata.detachedReason === "multi-paragraph" ||
+            record.metadata.detachedReason === "opaque-region" ||
+            record.metadata.detachedReason === "revision-overlap"
+              ? record.metadata.detachedReason
+              : undefined,
+          actionabilityNote:
+            typeof record.metadata.actionabilityNote === "string"
+              ? record.metadata.actionabilityNote
+              : undefined,
         }
       : undefined,
   };

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/header-footer-reference.ts

@@ -0,0 +1,38 @@
+import type { HeaderFooterVariant } from "../../model/canonical-document.ts";
+
+interface HeaderFooterReferenceElement {
+  attributes: Record<string, string>;
+}
+
+export interface ParsedHeaderFooterReferenceAttributes {
+  variant: HeaderFooterVariant;
+  relationshipId: string;
+}
+
+export function readHeaderFooterReferenceAttributes(
+  element: HeaderFooterReferenceElement,
+): ParsedHeaderFooterReferenceAttributes | undefined {
+  const relationshipId =
+    element.attributes["r:id"] ??
+    element.attributes["r:Id"] ??
+    element.attributes.id ??
+    element.attributes.Id;
+  if (!relationshipId) {
+    return undefined;
+  }
+
+  return {
+    variant: toHeaderFooterVariant(element.attributes["w:type"] ?? element.attributes.type),
+    relationshipId,
+  };
+}
+
+export function toHeaderFooterVariant(raw: string | undefined): HeaderFooterVariant {
+  if (raw === "first") {
+    return "first";
+  }
+  if (raw === "even") {
+    return "even";
+  }
+  return "default";
+}

package/src/io/ooxml/parse-headers-footers.ts

@@ -20,6 +20,7 @@ import { classifyFieldInstruction } from "./parse-fields.ts";
 import { isSafeTableFieldInstruction } from "./table-opaque-preservation.ts";
 import { parseXmlWithOffsets as parseXml } from "./xml-parser.ts";
 import { localName, readStringAttr } from "./xml-attr-helpers.ts";
+import { readHeaderFooterReferenceAttributes } from "./header-footer-reference.ts";
 import {
   readCellBorders,
   readCellCnfStyle,
@@ -200,40 +201,27 @@ function extractSectPrRefs(
     const name = localName(child.name);
     if (name === "headerReference" || name === "footerReference") {
       const kind: "header" | "footer" = name === "headerReference" ? "header" : "footer";
-      const rawType =
-        readStringAttr(child, "w:type") ?? "default";
-      const variant = toHeaderFooterVariant(rawType);
-      const relationshipId =
-        child.attributes["r:id"] ??
-        child.attributes["r:Id"] ??
-        child.attributes.id ??
-        child.attributes.Id ??
-        "";
-
-      if (relationshipId) {
+      const ref = readHeaderFooterReferenceAttributes(child);
+
+      if (ref) {
         // Avoid duplicates (multiple sectPr may reference same header)
-        const dedupeKey = `${kind}:${variant}:${relationshipId}`;
+        const dedupeKey = `${kind}:${ref.variant}:${ref.relationshipId}`;
         const alreadyAdded = refs.some(
           (ref) => `${ref.kind}:${ref.variant}:${ref.relationshipId}` === dedupeKey,
         );
         if (!alreadyAdded) {
-          refs.push({ variant, relationshipId, kind, sectionIndex });
+          refs.push({
+            variant: ref.variant,
+            relationshipId: ref.relationshipId,
+            kind,
+            sectionIndex,
+          });
         }
       }
     }
   }
 }
 
-function toHeaderFooterVariant(raw: string): HeaderFooterVariant {
-  if (raw === "first") {
-    return "first";
-  }
-  if (raw === "even") {
-    return "even";
-  }
-  return "default";
-}
-
 function parseHdrFtrXml(
   xml: string,
   rootLocalName: "hdr" | "ftr",

package/src/io/ooxml/parse-main-document.ts

@@ -21,8 +21,6 @@ import type {
   PageMargins,
   ColumnProperties,
   PageNumbering,
-  HeaderFooterReference,
-  HeaderFooterVariant,
   SectionDocumentGrid,
   SectionLineNumbering,
   SectionPageBorders,
@@ -45,6 +43,7 @@ import { parseComplexContentXml, type ChartPartLookup } from "./parse-complex-co
 import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
 import { parseObject } from "./parse-object.ts";
 import { parseDrawingFrame } from "./parse-drawing.ts";
+import { readHeaderFooterReferenceAttributes } from "./header-footer-reference.ts";
 import { readFrameProperties } from "./parse-paragraph-formatting.ts";
 import { tableRequiresOpaquePreservation } from "./table-opaque-preservation.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
@@ -3756,20 +3755,18 @@ export function parseSectionPropertiesFromElement(
         break;
       }
       case "headerReference": {
-        const variant = child.attributes["w:type"] as HeaderFooterVariant | undefined;
-        const rId = child.attributes["r:id"];
-        if (variant && rId) {
+        const ref = readHeaderFooterReferenceAttributes(child);
+        if (ref) {
           if (!props.headerReferences) props.headerReferences = [];
-          props.headerReferences.push({ variant, relationshipId: rId });
+          props.headerReferences.push(ref);
         }
         break;
       }
       case "footerReference": {
-        const variant = child.attributes["w:type"] as HeaderFooterVariant | undefined;
-        const rId = child.attributes["r:id"];
-        if (variant && rId) {
+        const ref = readHeaderFooterReferenceAttributes(child);
+        if (ref) {
           if (!props.footerReferences) props.footerReferences = [];
-          props.footerReferences.push({ variant, relationshipId: rId });
+          props.footerReferences.push(ref);
         }
         break;
       }

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 (