@beyondwork/docx-react-component 1.0.66 → 1.0.69

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

@@ -0,0 +1,188 @@
+/**
+ * Layer-06 Slice 3 — `createScopeFromBlockId` adapter.
+ *
+ * Resolves a `blockId` (paragraph/table/sdt-index identifier minted by
+ * `src/runtime/surface-projection.ts`) into the `EditorAnchorProjection`
+ * that `runtime.addScope` expects, then delegates to the existing
+ * marker-backed scope creator.
+ *
+ * Resolution walks the canonical document directly, not the surface
+ * snapshot. Going through `runtime.getRenderSnapshot().surface.blocks`
+ * would miss blocks the surface replaces with `placeholder-culled-*`
+ * entries under viewport culling — a real reproducibility failure on
+ * CCEP-size documents.
+ *
+ * This adapter unblocks `v3 runtime.workflow.createScope` graduation
+ * from `mock` → `live-with-adapter`. Consumers that already carry a
+ * full `EditorAnchorProjection` should continue calling
+ * `runtime.addScope` directly.
+ */
+
+import type {
+  BlockNode,
+  CanonicalDocument,
+  DocumentRootNode,
+  InlineNode,
+  ParagraphNode,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  AddScopeParams,
+  AddScopeResult,
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  RuntimeRenderSnapshot,
+  WorkflowMetadataEntry,
+  WorkflowMetadataPersistence,
+  WorkflowScopeMode,
+} from "../../api/public-types.ts";
+
+/**
+ * Minimal runtime surface the scope writer needs. Narrowed so layer-06
+ * does not import the full `DocumentRuntime` (which would reach up into
+ * layer-07/orchestration and violate contract W9).
+ */
+export interface ScopeWriterRuntime {
+  getCanonicalDocument(): CanonicalDocumentEnvelope;
+  getRenderSnapshot(): RuntimeRenderSnapshot;
+  addScope(params: AddScopeParams): AddScopeResult;
+}
+
+export interface CreateScopeFromBlockIdInput {
+  readonly blockId: string;
+  readonly mode?: WorkflowScopeMode;
+  readonly label?: string;
+  readonly scopeId?: string;
+  readonly persistence?: WorkflowMetadataPersistence;
+  readonly metadata?: Partial<WorkflowMetadataEntry>;
+  readonly storyTarget?: EditorStoryTarget;
+  /**
+   * Coord-06 §13d — per-scope edge stickiness for the range anchor.
+   * Defaults to `{ start: 1, end: -1 }` (greedy — absorbs boundary
+   * inserts, the pre-§13d shipped shape). Use `{ start: -1, end: 1 }`
+   * for a fixed-position anchor (signature-block / template-slot /
+   * system-paragraph semantics — rejects boundary inserts; cursor work
+   * doesn't leak in). The two diagonal variants `{ 1, 1 }` and
+   * `{ -1, -1 }` produce asymmetric edge behaviour (one sticky side,
+   * one fixed side) — uncommon in practice but accepted for
+   * completeness since `BoundaryAssoc` typing allows them.
+   */
+  readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
+}
+
+export type CreateScopeFromBlockIdResult =
+  | { readonly status: "created"; readonly scopeId: string; readonly anchor: EditorAnchorProjection }
+  | { readonly status: "block-not-found"; readonly blockId: string };
+
+function inlineLength(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "hyperlink":
+    case "field":
+      return node.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return 0;
+    default:
+      return 1;
+  }
+}
+
+function paragraphLength(paragraph: ParagraphNode): number {
+  return paragraph.children.reduce(
+    (total, child) => total + inlineLength(child as InlineNode),
+    0,
+  );
+}
+
+/**
+ * Resolve a surface-level `blockId` (e.g. `paragraph-3`, `table-0`,
+ * `sdt-1`) into an `EditorAnchorProjection` by walking the canonical
+ * document in surface-projection order. Returns `null` when no block
+ * matches — viewport culling cannot produce false negatives here
+ * because the walk is independent of the render snapshot.
+ */
+function resolveBlockAnchorFromCanonical(
+  document: CanonicalDocumentEnvelope,
+  blockId: string,
+  assoc: { readonly start: -1 | 1; readonly end: -1 | 1 } = { start: 1, end: -1 },
+): EditorAnchorProjection | null {
+  const root = document.content as DocumentRootNode;
+  let paragraphIndex = 0;
+  let tableIndex = 0;
+  let sdtIndex = 0;
+  let cursor = 0;
+  const blocks = root.children;
+  for (let i = 0; i < blocks.length; i += 1) {
+    const block: BlockNode = blocks[i]!;
+    let thisBlockLength: number;
+    let thisBlockId: string | null = null;
+    if (block.type === "paragraph") {
+      thisBlockLength = paragraphLength(block);
+      thisBlockId = `paragraph-${paragraphIndex}`;
+      paragraphIndex += 1;
+    } else if (block.type === "table") {
+      thisBlockLength = 1;
+      thisBlockId = `table-${tableIndex}`;
+      tableIndex += 1;
+    } else if (block.type === "sdt") {
+      thisBlockLength = 1;
+      thisBlockId = `sdt-${sdtIndex}`;
+      sdtIndex += 1;
+    } else {
+      thisBlockLength = 1;
+    }
+    if (thisBlockId === blockId) {
+      return {
+        kind: "range",
+        from: cursor,
+        to: cursor + thisBlockLength,
+        assoc,
+      };
+    }
+    cursor += thisBlockLength;
+    // Surface-projection order inserts a 1-unit gap between sibling
+    // blocks except after the last one. Mirror that so paragraph
+    // offsets match `surface.blocks[i].{from,to}` for visible rows.
+    if (i < blocks.length - 1) cursor += 1;
+  }
+  return null;
+}
+
+/**
+ * Create a workflow scope covering the block identified by `blockId`.
+ * Uses the runtime's own `addScope` pipeline so markers, overlay state,
+ * audit records, and collab sync all follow the canonical path.
+ */
+export function createScopeFromBlockId(
+  runtime: ScopeWriterRuntime,
+  input: CreateScopeFromBlockIdInput,
+): CreateScopeFromBlockIdResult {
+  const anchor = resolveBlockAnchorFromCanonical(
+    runtime.getCanonicalDocument(),
+    input.blockId,
+    input.assoc,
+  );
+  if (!anchor) {
+    return { status: "block-not-found", blockId: input.blockId };
+  }
+  const result: AddScopeResult = runtime.addScope({
+    anchor,
+    mode: input.mode,
+    scopeId: input.scopeId,
+    persistence: input.persistence,
+    metadata: input.metadata,
+    storyTarget: input.storyTarget,
+    label: input.label,
+  });
+  return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
+}
+
+// Exported for tests that need to verify the resolver independently.
+export { resolveBlockAnchorFromCanonical };

package/src/runtime/{tamper-gate.ts → workflow/tamper-gate.ts}

@@ -2,7 +2,7 @@ import {
   verifyWorkflowPayloadXml,
   type PayloadSignature,
   type PayloadVerifier,
-} from "../io/ooxml/payload-signature.ts";
+} from "../../io/ooxml/payload-signature.ts";
 
 /**
  * Runtime metadata-integrity states.

package/src/runtime/workflow/visibility-policy.ts

@@ -0,0 +1,129 @@
+/**
+ * W10 · Overlay-visibility policy (class-A state) — runtime helpers.
+ *
+ * Document-authored visibility policy for every overlay kind (scope rail,
+ * tracked-changes markup, comment threads, suggestion halos, debug panel,
+ * presence halos). The policy is the class-A input to the class-C local
+ * preference composition that lives in Layer 10 (`ui.overlays.getVisibility`);
+ * this module does NOT compose the two — that is strictly L10's job.
+ *
+ * Spec: `docs/architecture/06-workflow-review.md` §W10 and
+ * `docs/plans/refactor/state-classes-cross-cutting.md` §X1. The public
+ * types live in `src/api/public-types.ts` (shared vocabulary); the
+ * runtime-internal helpers live here.
+ *
+ * Invariants:
+ * - Policies are keyed by `OverlayKind`; at most one policy per kind.
+ * - `enforcement: "always"` / `"never"` overrides any local preference.
+ * - `enforcement: "authored-default"` cedes to the local preference; the
+ *   `defaultOn` field is only consulted when the user has not expressed one.
+ * - Mutations flow through the coordinator so they persist via
+ *   `customXml/item1.xml` (see `workflow-payload.ts` `bw:overlayVisibility`
+ *   block) and broadcast via the Yjs CRDT (shared-workflow state carries them).
+ */
+
+import type {
+  OverlayKind,
+  OverlayVisibilityAuthorship,
+  OverlayVisibilityEnforcement,
+  OverlayVisibilityPolicy,
+} from "../../api/public-types.ts";
+
+export type {
+  OverlayKind,
+  OverlayVisibilityAuthorship,
+  OverlayVisibilityEnforcement,
+  OverlayVisibilityPolicy,
+};
+
+/** The closed set — used by the CI guard + the serializer. */
+export const OVERLAY_KINDS: readonly OverlayKind[] = [
+  "scope-rail",
+  "comments",
+  "tracked-changes",
+  "suggestions",
+  "debug-panel",
+  "presence",
+];
+
+const OVERLAY_KIND_SET: ReadonlySet<OverlayKind> = new Set(OVERLAY_KINDS);
+const ENFORCEMENT_SET: ReadonlySet<OverlayVisibilityEnforcement> = new Set([
+  "authored-default",
+  "always",
+  "never",
+]);
+
+export function isOverlayKind(value: unknown): value is OverlayKind {
+  return typeof value === "string" && OVERLAY_KIND_SET.has(value as OverlayKind);
+}
+
+export function isOverlayVisibilityEnforcement(
+  value: unknown,
+): value is OverlayVisibilityEnforcement {
+  return (
+    typeof value === "string" &&
+    ENFORCEMENT_SET.has(value as OverlayVisibilityEnforcement)
+  );
+}
+
+/** Type-guard — shallow validation. Authorship is optional and not checked. */
+export function isOverlayVisibilityPolicy(
+  value: unknown,
+): value is OverlayVisibilityPolicy {
+  if (value === null || typeof value !== "object") return false;
+  const candidate = value as { kind?: unknown; enforcement?: unknown; defaultOn?: unknown };
+  return (
+    isOverlayKind(candidate.kind) &&
+    isOverlayVisibilityEnforcement(candidate.enforcement) &&
+    typeof candidate.defaultOn === "boolean"
+  );
+}
+
+/**
+ * Factory. Applies structural clone so callers cannot mutate the record
+ * after registration.
+ */
+export function createOverlayVisibilityPolicy(input: {
+  kind: OverlayKind;
+  enforcement: OverlayVisibilityEnforcement;
+  defaultOn: boolean;
+  authoredBy?: OverlayVisibilityAuthorship;
+}): OverlayVisibilityPolicy {
+  return {
+    kind: input.kind,
+    enforcement: input.enforcement,
+    defaultOn: input.defaultOn,
+    ...(input.authoredBy ? { authoredBy: { ...input.authoredBy } } : {}),
+  };
+}
+
+/**
+ * Structural equality — used by the store to short-circuit no-op
+ * `setVisibilityPolicy` calls (no spurious subscriber wakeups).
+ */
+export function overlayVisibilityPoliciesEqual(
+  left: OverlayVisibilityPolicy | null | undefined,
+  right: OverlayVisibilityPolicy | null | undefined,
+): boolean {
+  if (left === right) return true;
+  if (!left || !right) return false;
+  if (left.kind !== right.kind) return false;
+  if (left.enforcement !== right.enforcement) return false;
+  if (left.defaultOn !== right.defaultOn) return false;
+  const la = left.authoredBy;
+  const ra = right.authoredBy;
+  if (!la && !ra) return true;
+  if (!la || !ra) return false;
+  return la.actorId === ra.actorId && la.at === ra.at;
+}
+
+/**
+ * Deterministic ordering for serialization — by the fixed `OVERLAY_KINDS`
+ * order, so re-export of an unchanged policy set is byte-identical.
+ */
+export function sortOverlayVisibilityPolicies(
+  policies: readonly OverlayVisibilityPolicy[],
+): readonly OverlayVisibilityPolicy[] {
+  const indexOf = (kind: OverlayKind): number => OVERLAY_KINDS.indexOf(kind);
+  return [...policies].sort((a, b) => indexOf(a.kind) - indexOf(b.kind));
+}

package/src/session/_sync-legacy.ts

@@ -0,0 +1,66 @@
+/**
+ * Transitional sync entry — wraps `loadDocxEditorSession` from the
+ * legacy `src/io/docx-session.ts` for the two sync call sites inside
+ * `src/ui/editor-runtime-boundary.ts` that cannot (yet) await.
+ *
+ * Why this module exists.
+ * =======================
+ * `DocxSession.open()` is async per the architecture (the loader
+ * yields between parse stages so the browser can paint). Two
+ * `editor-runtime-boundary` paths need a sync load:
+ *
+ *   1. `createRuntime`'s SSR / Node fallback — runs when no
+ *      `preloadedDocxSession` was produced by the async warm path but
+ *      `initialDocx` bytes are present. `createRuntime` is sync, so a
+ *      sync loader is the only entry that keeps the mount simple.
+ *      Slice 5e-9 is expected to eliminate this fallback altogether
+ *      by requiring the async warm path to run, OR by making
+ *      `createRuntime` async-capable.
+ *
+ *   2. `resolvePackageBackedExportSession` — resolves an embedded
+ *      source-package blob to decide the export barrier for
+ *      snapshot-only mounts. The result drives the compatibility
+ *      report that shows on first paint; deferring to first export
+ *      would regress the blocked-export UX. Slice 5e-9 may thread a
+ *      preloaded barrier session through the async warm path
+ *      instead.
+ *
+ * Isolation.
+ * ==========
+ * By routing both sync call sites through this one module, the
+ * `src/ui/editor-runtime-boundary.ts` file no longer imports directly
+ * from `src/io/docx-session.ts`. The transit is pinned as a
+ * WARNING-level debt exception in
+ * `scripts/ci-check-session-layer-purity.mjs`, so the legacy-import
+ * surface shrinks to one narrow file that Slice 5e-9 deletes whole.
+ *
+ * Not exported from the session barrel.
+ * =====================================
+ * `src/session/index.ts` intentionally does NOT re-export this
+ * module; it is an in-tree implementation seam. External consumers
+ * never see it. Agents: do not widen its surface.
+ */
+
+// Slice 5e-8.a: reach the sync loader body directly (in-layer),
+// retiring the `src/io/docx-session.ts` transit for this shim.
+import { loadDocxSessionSync } from "./import/loader.ts";
+
+/**
+ * Sync docx load — returns the legacy-shaped handle the two
+ * `editor-runtime-boundary` sync call sites currently consume.
+ *
+ * Options + result are typed via `Parameters<>` / `ReturnType<>` so
+ * this module does not force its loader-types dependency to widen
+ * publicly.
+ *
+ * Removed in Slice 5e-9 when the sync call sites either flip to
+ * `await DocxSession.open(...)` or rely on a preloaded session
+ * produced by the async warm path.
+ */
+export type SyncLegacyOpenOptions = Parameters<typeof loadDocxSessionSync>[0];
+
+export function openDocxSync(
+  opts: SyncLegacyOpenOptions,
+): ReturnType<typeof loadDocxSessionSync> {
+  return loadDocxSessionSync(opts);
+}

package/src/session/export/embedded-reconstitute.ts

@@ -0,0 +1,104 @@
+/**
+ * P8 Step 7 — export-time reconstitution of offloaded embedded
+ * documents back into the OPC package.
+ *
+ * Mirrors `src/session/import/embedded-offload.ts`. For every
+ * `EmbeddingOffloadEntry` the session captured at open time:
+ *   1. Call `hostAdapter.loadEmbeddedDocument(entry.storageReference)`
+ *      → on `Uint8Array` success, use those bytes;
+ *      → on `null` / rejection / thrown exception, decode the entry's
+ *        `inlineBytes` base64 fallback and use that.
+ *   2. Write the bytes back to the OPC package at `entry.sourcePartPath`
+ *      via `exportSession.replaceOwnedPart`.
+ *
+ * The source part path was added to the export session's owned-paths
+ * list at construction, so `replaceOwnedPart` is valid for it. The
+ * preservation path does NOT carry these parts — `buildImportPreservation`
+ * excluded them based on the `ownedPartPaths` the offload module
+ * returned at load time.
+ *
+ * Export never fails on storage unavailability: every entry carries
+ * the inline-bytes fallback inline (the whole point of P3). A
+ * ubiquitous host-storage outage simply results in the exported
+ * package looking identical to the source — bytes just round-trip
+ * via customXml instead of via preservation.
+ */
+
+import type {
+  EditorHostAdapter,
+  StorageReference,
+} from "../../api/public-types.ts";
+import { sha256Hex } from "../../io/source-package-provenance.ts";
+import {
+  decodeInlineBytes,
+  type EmbeddingOffloadEntry,
+} from "../import/embedded-offload.ts";
+import type { createExportSession } from "../../io/export/export-session.ts";
+
+/**
+ * Call-shape of the `exportSession` argument. Typed via `ReturnType`
+ * so this module does not drag internal export-session implementation
+ * into the public surface.
+ */
+type ExportSession = ReturnType<typeof createExportSession>;
+
+export interface ReconstituteEmbeddedParams {
+  readonly exportSession: ExportSession;
+  readonly entries: readonly EmbeddingOffloadEntry[];
+  readonly hostAdapter: EditorHostAdapter | undefined;
+}
+
+/**
+ * Rebuild the OPC parts for every offload entry. No-op when `entries`
+ * is empty (no offload was performed on this session, OR the package
+ * had no offloadable embeddings).
+ */
+export async function reconstituteEmbeddedDocuments(
+  params: ReconstituteEmbeddedParams,
+): Promise<void> {
+  const { exportSession, entries, hostAdapter } = params;
+  if (entries.length === 0) return;
+  for (const entry of entries) {
+    const bytes = await resolveEntryBytes(hostAdapter, entry);
+    exportSession.replaceOwnedPart({
+      path: entry.sourcePartPath,
+      bytes,
+      contentType: entry.contentType,
+    });
+  }
+}
+
+async function resolveEntryBytes(
+  hostAdapter: EditorHostAdapter | undefined,
+  entry: EmbeddingOffloadEntry,
+): Promise<Uint8Array> {
+  if (hostAdapter?.loadEmbeddedDocument) {
+    try {
+      const fetched = await hostAdapter.loadEmbeddedDocument(entry.storageReference);
+      if (fetched && fetched.byteLength > 0) {
+        // Tamper check: the `StorageReference.sha256` contract in
+        // `public-types.ts` promises the session computes the sha
+        // so hosts can detect tampering on rehydrate. Verify the
+        // loaded payload matches the sha we captured at offload
+        // time. On mismatch, treat it identically to a null /
+        // failed load and fall through to the inline-bytes
+        // fallback — export still ships honest bytes.
+        if (sha256Hex(fetched) === entry.sha256) {
+          return fetched;
+        }
+      }
+    } catch {
+      // Treat identically to `null` — fall through to the inline-
+      // bytes fallback. The architecture guarantees export never
+      // fails on storage unavailability.
+    }
+  }
+  return decodeInlineBytes(entry.inlineBytes);
+}
+
+/**
+ * Re-export for convenience so consumers of the reconstitute module
+ * that need to chain additional logic can reach the `StorageReference`
+ * shape without a separate import.
+ */
+export type { StorageReference };

package/src/session/export/export-diagnostics.ts

@@ -0,0 +1,85 @@
+/**
+ * Typed export diagnostic producers.
+ *
+ * Slice 4a of refactor/01 package-session. The legacy export path in
+ * `src/io/docx-session.ts` currently throws plain `Error` objects when
+ * the canonical document cannot be serialized — callers get a string
+ * message but no stable code to react against.
+ *
+ * This module defines a single `ExportBlockedError` class carrying a
+ * stable `code` + `featureKey` + `details`, so:
+ *   - the runtime can surface targeted UX (block dialog, rail badge)
+ *   - CI / truth-baseline can assert on the code, not the message
+ *   - export-validation.ts's `assert*` predicates throw these directly
+ *
+ * Contract P6 clean. Depends on no runtime / ui / core / review code.
+ */
+
+/**
+ * Stable classification codes used across the export path.
+ * Consumers snapshot on `code` rather than `message`; the message
+ * format may change for i18n without breaking callers.
+ */
+export type ExportBlockedCode =
+  /** Export is blocked by the active compatibility report. */
+  | "compatibility-blocked"
+  /** Preserve-only comment anchors cannot be remapped safely. */
+  | "preserve-only-comments"
+  /** Active revisions overlap unsupported serialization boundaries. */
+  | "revision-boundary"
+  /** One or more comments no longer map to a serializable range. */
+  | "comment-range-lost";
+
+export interface ExportBlockedDetails {
+  /** Count of items that contributed to the block (when applicable). */
+  readonly count?: number;
+  /**
+   * Arbitrary identifiers (revision ids, comment ids, feature keys)
+   * the runtime can cite in its block-dialog UX. Empty when the
+   * block reason is a single global flag (compatibility-blocked).
+   */
+  readonly ids?: readonly string[];
+}
+
+/**
+ * Thrown from the export path to signal a structural block. The
+ * runtime catches this, reads `code`, and drives UX / telemetry
+ * accordingly. Message is human-facing; the machine-readable
+ * projection is the `code` + `details` pair.
+ */
+export class ExportBlockedError extends Error {
+  readonly code: ExportBlockedCode;
+  readonly details: ExportBlockedDetails;
+
+  constructor(
+    code: ExportBlockedCode,
+    message: string,
+    details: ExportBlockedDetails = {},
+  ) {
+    super(message);
+    this.name = "ExportBlockedError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/**
+ * Produce a human-facing message with a count prefix. Kept in a
+ * shared helper so both the assertion functions in export-validation
+ * and downstream diagnostic-panel UX format the string identically.
+ */
+export function formatBlockedExportMessage(
+  code: ExportBlockedCode,
+  count?: number,
+): string {
+  switch (code) {
+    case "compatibility-blocked":
+      return "DOCX export is blocked by the current compatibility report.";
+    case "preserve-only-comments":
+      return `DOCX export is blocked because ${count ?? 0} preserve-only comment anchors cannot be safely remapped after runtime edits.`;
+    case "revision-boundary":
+      return `DOCX export is blocked because ${count ?? 0} active revisions overlap unsupported serialization boundaries.`;
+    case "comment-range-lost":
+      return `DOCX export is blocked because ${count ?? 0} comments no longer map to serializable ranges.`;
+  }
+}

package/src/session/export/export-validation.ts

@@ -0,0 +1,110 @@
+/**
+ * Export-validation helpers for the session-layer export path.
+ *
+ * Slice 4a of refactor/01 package-session. Extracted from the four
+ * inline `throw new Error(...)` points in
+ * `exportDocxEditorSession` (`src/io/docx-session.ts:2021`, `:2066`,
+ * `:2109`, `:2148`). Each inline throw becomes a single `assert*`
+ * call that routes through the typed `ExportBlockedError` from
+ * `export-diagnostics.ts`.
+ *
+ * Pure functions over primitives + typed value objects; no IO, no
+ * runtime imports, no review-store reads. Contract P6 clean.
+ */
+
+import type { CompatibilityReport } from "../../api/public-types.ts";
+import {
+  ExportBlockedError,
+  formatBlockedExportMessage,
+} from "./export-diagnostics.ts";
+
+/**
+ * Block export when the compatibility report flags the document as
+ * unsafe to re-serialize. This is the earliest structural gate — if
+ * compatibility blocks, nothing else matters.
+ */
+export function assertExportNotBlockedByCompatibility(
+  compatibility: Pick<CompatibilityReport, "blockExport">,
+): void {
+  if (compatibility.blockExport) {
+    throw new ExportBlockedError(
+      "compatibility-blocked",
+      formatBlockedExportMessage("compatibility-blocked"),
+    );
+  }
+}
+
+/**
+ * Block export when the loader captured preserve-only comment anchors
+ * that no longer map to serializable ranges after runtime edits.
+ *
+ * `count` is the greater of:
+ *   - `state.blockingCommentDiagnostics.length`
+ *   - `state.preservedCommentDefinitions.length` (deduped)
+ *
+ * Kept as a scalar count input so callers can decide the combination
+ * policy before calling in. Callers that need to cite specific
+ * comment ids pass them via `ids` for inclusion in the error's
+ * machine-readable payload.
+ */
+export function assertNoBlockingPreservedComments(
+  count: number,
+  ids?: readonly string[],
+): void {
+  if (count > 0) {
+    throw new ExportBlockedError(
+      "preserve-only-comments",
+      formatBlockedExportMessage("preserve-only-comments", count),
+      {
+        count,
+        ...(ids !== undefined ? { ids } : {}),
+      },
+    );
+  }
+}
+
+/**
+ * Block export when runtime revisions overlap unsupported
+ * serialization boundaries. `skippedRevisionIds` comes from
+ * `serializeRuntimeRevisionsIntoDocumentXml` — the serializer
+ * returns the list of ids it could not safely rewrite, and any
+ * non-empty list blocks export.
+ */
+export function assertNoSkippedRevisions(
+  skippedRevisionIds: readonly string[],
+): void {
+  if (skippedRevisionIds.length > 0) {
+    throw new ExportBlockedError(
+      "revision-boundary",
+      formatBlockedExportMessage("revision-boundary", skippedRevisionIds.length),
+      {
+        count: skippedRevisionIds.length,
+        ids: skippedRevisionIds,
+      },
+    );
+  }
+}
+
+/**
+ * Block export when comment-anchor serialization dropped comments
+ * whose anchor is not merely "detached" (detached comments are
+ * acceptable; others signal a serializer bug / unexpected runtime
+ * state).
+ */
+export function assertNoBlockingSkippedComments(
+  blockingSkippedCommentIds: readonly string[],
+): void {
+  if (blockingSkippedCommentIds.length > 0) {
+    throw new ExportBlockedError(
+      "comment-range-lost",
+      formatBlockedExportMessage(
+        "comment-range-lost",
+        blockingSkippedCommentIds.length,
+      ),
+      {
+        count: blockingSkippedCommentIds.length,
+        ids: blockingSkippedCommentIds,
+      },
+    );
+  }
+}