@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/workflow/derived-scope-resolver.ts

@@ -0,0 +1,125 @@
+/**
+ * Coord-06 §13c — resolve a *derived* paragraph-like scopeId to an
+ * `EditorAnchorProjection` (range anchor).
+ *
+ * Derived scopeIds are the paragraph / heading / list-item identifiers
+ * minted by `src/runtime/scopes/enumerate-scopes.ts` for blocks that
+ * aren't backed by an overlay marker. They don't live on the workflow
+ * overlay, so `overlayStore.scopes.find(...)` misses them — but the
+ * block itself exists in the canonical document and has a well-defined
+ * range. This resolver walks the canonical document, classifies each
+ * paragraph the same way the enumerator does, mints the candidate
+ * scopeId, and emits the range anchor on match.
+ *
+ * Shape rules:
+ * - `para:<paraId>` / `para:<blockIndex>`
+ * - `heading:<paraId>` / `heading:<level>:<blockIndex>`
+ * - `li:<paraId>` / `li:<instance>:<level>:<blockIndex>`
+ *
+ * Default `assoc` is `{ start: 1, end: -1 }` (greedy — same shipped
+ * shape as the pre-§13d scope-writer). Derived scopes don't carry a
+ * caller-authored `assoc` today; if a future slice exposes one on
+ * `attachExplanation` / `createIssue` inputs, this resolver accepts
+ * the override via the second argument.
+ *
+ * Non-paragraph kinds (table / table-row / table-cell / field /
+ * comment-thread / revision) are not in scope for §13c — CLM hot-path
+ * dominates paragraph / heading / list-item. Table-kind resolution is
+ * straightforward to add later (the scopeId grammar is `table:<index>`)
+ * but no consumer asks for it yet.
+ */
+
+import type {
+  BlockNode,
+  DocumentRootNode,
+  InlineNode,
+  ParagraphNode,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { EditorAnchorProjection } from "../../api/public-types.ts";
+import {
+  buildParagraphScopeId,
+  detectParagraphKind,
+} from "../../model/paragraph-scope-ids.ts";
+
+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,
+  );
+}
+
+/**
+ * Walk the canonical document and resolve a derived paragraph-like
+ * scopeId to its range anchor. Returns `null` when no paragraph /
+ * heading / list-item mints this scopeId.
+ */
+export function resolveDerivedScopeAnchorFromCanonical(
+  document: CanonicalDocumentEnvelope,
+  scopeId: string,
+  assoc: { readonly start: -1 | 1; readonly end: -1 | 1 } = { start: 1, end: -1 },
+): EditorAnchorProjection | null {
+  // Fast-reject: derived paragraph-like scopeIds are always
+  // `para:…` / `heading:…` / `li:…`. Anything else (`table:…`,
+  // `field:…`, comment / revision ids, arbitrary host strings) can't
+  // match in this pass.
+  if (
+    !scopeId.startsWith("para:") &&
+    !scopeId.startsWith("heading:") &&
+    !scopeId.startsWith("li:")
+  ) {
+    return null;
+  }
+
+  const root = document.content as DocumentRootNode;
+  let cursor = 0;
+  const blocks = root.children;
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block: BlockNode = blocks[index]!;
+    let thisBlockLength: number;
+    let matchedScopeId: string | null = null;
+
+    if (block.type === "paragraph") {
+      thisBlockLength = paragraphLength(block);
+      const kind = detectParagraphKind(block);
+      matchedScopeId = buildParagraphScopeId(kind, index, block);
+    } else if (block.type === "table" || block.type === "sdt") {
+      thisBlockLength = 1;
+    } else {
+      thisBlockLength = 1;
+    }
+
+    if (matchedScopeId !== null && matchedScopeId === scopeId) {
+      return {
+        kind: "range",
+        from: cursor,
+        to: cursor + thisBlockLength,
+        assoc,
+      };
+    }
+
+    cursor += thisBlockLength;
+    if (index < blocks.length - 1) cursor += 1;
+  }
+  return null;
+}

package/src/runtime/workflow/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Workflow layer barrel.
+ *
+ * Layer 06 (workflow/review) — consolidated home for workflow scopes,
+ * scope markers, workflow markup, AI action policy, tamper gate, and the
+ * scope-rail composer. See `docs/architecture/06-workflow-review.md` for
+ * the canonical target and contracts W1–W9.
+ */
+
+export * from "./query-scopes.ts";
+export * from "./scope-resolver.ts";
+export * from "./scope-tag-registry.ts";
+export * from "./markup.ts";
+export * from "./ai-action-policy.ts";
+export * from "./tamper-gate.ts";
+export * from "./rail/types.ts";
+export * from "./rail/compose.ts";
+export * from "./scope-writer.ts";
+export * from "./metadata-writer.ts";
+export * from "./projector.ts";
+export * from "./overlay-store.ts";
+export * from "./coordinator.ts";
+export * from "./visibility-policy.ts";
+export * from "./markup-mode-policy.ts";
+export * from "./scope-rail-composer.ts";

package/src/runtime/workflow/markup-mode-policy.ts

@@ -0,0 +1,98 @@
+/**
+ * X5 · Workflow markup-mode policy (class-A state) — runtime helpers.
+ *
+ * Mirrors the `visibility-policy.ts` shape for a single-value policy.
+ * Per `docs/plans/refactor/state-classes-cross-cutting.md` §X5:
+ *
+ *   - L06 publishes `workflow.getMarkupModePolicy()` — class A.
+ *   - L10 composes with class-C local preference in
+ *     `ui.viewport.getEffectiveMarkupMode()`.
+ *   - L03's `applyRevisionDisplay(run, revision, markupMode)` is
+ *     unchanged — the composed value flows through.
+ *
+ * Invariants:
+ *   - One policy record per document (not per-kind). Exposed via the
+ *     `getMarkupModePolicy()` / `setMarkupModePolicy(policy)` pair.
+ *   - `enforcement: "always"` hard-locks the mode; `"authored-default"`
+ *     cedes to the local preference.
+ *   - Mutations flow through the coordinator so they persist via
+ *     `customXml/item1.xml` and broadcast via the Yjs document share.
+ */
+
+import type {
+  OverlayVisibilityAuthorship,
+  WorkflowMarkupMode,
+  WorkflowMarkupModeEnforcement,
+  WorkflowMarkupModePolicy,
+} from "../../api/public-types.ts";
+
+export type {
+  WorkflowMarkupMode,
+  WorkflowMarkupModeEnforcement,
+  WorkflowMarkupModePolicy,
+};
+
+const MARKUP_MODE_SET: ReadonlySet<WorkflowMarkupMode> = new Set([
+  "clean",
+  "simple",
+  "all",
+]);
+const ENFORCEMENT_SET: ReadonlySet<WorkflowMarkupModeEnforcement> = new Set([
+  "authored-default",
+  "always",
+]);
+
+export function isWorkflowMarkupMode(value: unknown): value is WorkflowMarkupMode {
+  return (
+    typeof value === "string" &&
+    MARKUP_MODE_SET.has(value as WorkflowMarkupMode)
+  );
+}
+
+export function isWorkflowMarkupModeEnforcement(
+  value: unknown,
+): value is WorkflowMarkupModeEnforcement {
+  return (
+    typeof value === "string" &&
+    ENFORCEMENT_SET.has(value as WorkflowMarkupModeEnforcement)
+  );
+}
+
+export function isWorkflowMarkupModePolicy(
+  value: unknown,
+): value is WorkflowMarkupModePolicy {
+  if (value === null || typeof value !== "object") return false;
+  const c = value as { mode?: unknown; enforcement?: unknown };
+  return isWorkflowMarkupMode(c.mode) && isWorkflowMarkupModeEnforcement(c.enforcement);
+}
+
+export function createWorkflowMarkupModePolicy(input: {
+  mode: WorkflowMarkupMode;
+  enforcement: WorkflowMarkupModeEnforcement;
+  authoredBy?: OverlayVisibilityAuthorship;
+}): WorkflowMarkupModePolicy {
+  return {
+    mode: input.mode,
+    enforcement: input.enforcement,
+    ...(input.authoredBy ? { authoredBy: { ...input.authoredBy } } : {}),
+  };
+}
+
+/**
+ * Structural equality — used by the store to short-circuit no-op sets
+ * (no spurious subscriber wakeups).
+ */
+export function workflowMarkupModePoliciesEqual(
+  left: WorkflowMarkupModePolicy | null | undefined,
+  right: WorkflowMarkupModePolicy | null | undefined,
+): boolean {
+  if (left === right) return true;
+  if (!left || !right) return false;
+  if (left.mode !== right.mode) return false;
+  if (left.enforcement !== right.enforcement) 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;
+}

package/src/runtime/{workflow-markup.ts → workflow/markup.ts}

@@ -20,15 +20,15 @@ import type {
   WorkflowProtectedRangeMarkup,
   WorkflowRevisionMarkup,
   WorkflowCommentMarkup,
-} from "../api/public-types";
-import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
-import { createPublicRangeAnchor } from "../core/selection/anchor-conversion.ts";
+} from "../../api/public-types";
+import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
+import { createPublicRangeAnchor } from "../../core/selection/anchor-conversion.ts";
 import {
   projectSurfaceText,
   searchProjectedSurfaceText,
-} from "../core/search/search-text.ts";
-import { describeOpaqueFragment, isBlockedImportFeatureKey } from "../preservation/store.ts";
-import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+} from "../../core/search/search-text.ts";
+import { describeOpaqueFragment, isBlockedImportFeatureKey } from "../../preservation/store.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
 
 /**
  * Surface-derived markup (highlights + block-level opaque fragments).

package/src/runtime/workflow/metadata-persistence.ts

@@ -0,0 +1,306 @@
+/**
+ * Layer 06 — Workflow metadata persistence + conflict resolution.
+ *
+ * Owns the semantics of converting scope metadata between the three
+ * persistence modes (overlay default / scope-level / entry-level
+ * cascading to "internal" | "external"), the version-mismatch
+ * detection that emits `metadata_conflict_detected`, and the
+ * internal ↔ external conversion routines that talk to a host-
+ * supplied `ScopeMetadataResolver`.
+ *
+ * Slice 4 rehousing (2026-04-22): this logic lived directly in
+ * `src/ui/WordReviewEditor.tsx` (lines 280-477) before the
+ * adversarial closure pass. It had no UI dependencies — it
+ * operated on the runtime's workflow metadata snapshot and the
+ * resolver — so it was a strong layering violation. Moving it
+ * behind a Layer-06 seam means:
+ *
+ * - The semantics are now inspectable + testable without booting
+ *   the React tree.
+ * - A pending `WorkflowHostHandle` type can consume this module
+ *   directly; v3 callers get the same conflict-resolution policy
+ *   as the UI layer without the UI having to hand it to them.
+ * - The "conflict emission + deduplication by conflict key" rule
+ *   is versioned in one place.
+ *
+ * W9 purity: this module imports only from `src/api/public-types`
+ * and the scope-metadata-resolver type file. Both are type-only
+ * module references allowed by
+ * `scripts/ci-check-workflow-layer-purity.mjs`.
+ */
+
+import type {
+  MetadataPersistenceMode,
+  ScopeMetadataPersistence,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+  WorkflowOverlay,
+  WordReviewEditorEvent,
+} from "../../api/public-types.ts";
+import {
+  MetadataResolverMissingError,
+} from "../../api/public-types.ts";
+import type { ScopeMetadataResolver } from "../../api/scope-metadata-resolver-types.ts";
+
+/* -------------------------------------------------------------------- *\
+ * Conflict keying — stable string identity per (scope, entry, field).
+ *
+ * The deduplication rule on `registerAndEmitConflict` depends on this
+ * key being stable, so the function is exported for host callers
+ * that want to find a previously-emitted conflict in their queue.
+\* -------------------------------------------------------------------- */
+
+export function conflictKey(input: {
+  scopeId?: string;
+  entryId?: string;
+  fieldKey?: string;
+}): string {
+  return `${input.scopeId ?? ""}|${input.entryId ?? ""}|${input.fieldKey ?? ""}`;
+}
+
+/**
+ * §W5 — cascade for effective persistence mode. Field-level wins over
+ * scope-level wins over overlay-default; unset falls back to "internal".
+ * Pure function of the three inputs.
+ */
+export function resolveEffectivePersistence(input: {
+  overlay?: MetadataPersistenceMode;
+  scope?: ScopeMetadataPersistence;
+  field?: ScopeMetadataPersistence;
+}): "internal" | "external" {
+  if (input.field === "internal" || input.field === "external") return input.field;
+  if (input.scope === "internal" || input.scope === "external") return input.scope;
+  return input.overlay ?? "internal";
+}
+
+/**
+ * A pending conflict record held by the host while it decides how to
+ * resolve. Keyed by `conflictKey(...)`.
+ */
+export interface PendingConflict {
+  scopeId?: string;
+  entryId?: string;
+  fieldKey?: string;
+  embedded: { value?: Record<string, unknown>; version?: number } | null;
+  external: { value?: Record<string, unknown>; version?: number } | null;
+  defaultPolicy: "prefer-latest";
+}
+
+/**
+ * Emit a single `metadata_conflict_detected` event and register the
+ * pending conflict, unless a conflict with the same key is already
+ * registered (deduplication). Pure side effect on the `pendingConflicts`
+ * map + the `onEvent` callback.
+ */
+export function registerAndEmitConflict(args: {
+  onEvent: ((event: WordReviewEditorEvent) => void) | undefined;
+  documentId: string;
+  conflict: PendingConflict;
+  pendingConflicts: Map<string, PendingConflict>;
+}): void {
+  const key = conflictKey(args.conflict);
+  // Guard: do not emit duplicate events for the same key in a single pass.
+  if (args.pendingConflicts.has(key)) return;
+  args.pendingConflicts.set(key, args.conflict);
+  args.onEvent?.({
+    type: "metadata_conflict_detected",
+    documentId: args.documentId,
+    scopeId: args.conflict.scopeId,
+    entryId: args.conflict.entryId,
+    fieldKey: args.conflict.fieldKey,
+    embedded: args.conflict.embedded,
+    external: args.conflict.external,
+    defaultPolicy: args.conflict.defaultPolicy,
+  });
+}
+
+/* -------------------------------------------------------------------- *\
+ * Narrow runtime interface — everything the conversion routines need
+ * from the runtime, specified as a structural type so callers can
+ * pass `DocumentRuntime` (or `WorkflowCoordinator`) verbatim without
+ * Layer-06 reaching up into `src/runtime/document-runtime.ts` or
+ * `src/api/v3/**`.
+\* -------------------------------------------------------------------- */
+
+export interface MetadataPersistenceRuntime {
+  getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  getWorkflowOverlay(): WorkflowOverlay | null;
+  setWorkflowMetadataEntries(entries: readonly WorkflowMetadataEntry[]): void;
+}
+
+/* -------------------------------------------------------------------- *\
+ * Conversion: scopes → internal (pull external payloads in-doc)
+\* -------------------------------------------------------------------- */
+
+export interface ConvertScopesToInternalInput {
+  runtime: MetadataPersistenceRuntime;
+  scopeIds: string[];
+  resolver: ScopeMetadataResolver | null;
+  /** When provided, version mismatches emit `metadata_conflict_detected`. */
+  documentId?: string;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  pendingConflicts?: Map<string, PendingConflict>;
+}
+
+/**
+ * Convert the given scopes' metadata entries to internal persistence
+ * (inline value in the customXml payload). For each entry currently
+ * in external mode, resolves the value via the host-supplied
+ * resolver, detects version mismatches (optional), and rewrites the
+ * entry with `metadataPersistence: "internal"` and the resolved
+ * value. Throws `MetadataResolverMissingError` when no resolver is
+ * supplied but conversion is attempted.
+ */
+export async function convertScopesToInternal(
+  args: ConvertScopesToInternalInput,
+): Promise<void> {
+  if (!args.resolver) throw new MetadataResolverMissingError();
+  const snapshot = args.runtime.getWorkflowMetadataSnapshot();
+  const overlay = args.runtime.getWorkflowOverlay();
+
+  const nextEntries = await Promise.all(
+    snapshot.entries.map(async (entry) => {
+      if (!entry.scopeId || !args.scopeIds.includes(entry.scopeId)) return entry;
+      const scope = overlay?.scopes.find((s) => s.scopeId === entry.scopeId);
+      const effective = resolveEffectivePersistence({
+        overlay: overlay?.metadataPersistence,
+        scope: scope?.metadataPersistence,
+        field: entry.metadataPersistence,
+      });
+      if (effective !== "external" || !entry.storageRef) return entry;
+      const resolved = await args.resolver!.resolve(entry.storageRef);
+      if (!resolved) return entry;
+
+      // Conflict detection: compare embedded metadataVersion vs resolver version.
+      if (
+        args.pendingConflicts &&
+        args.documentId !== undefined &&
+        entry.metadataVersion !== undefined &&
+        resolved.version !== undefined &&
+        entry.metadataVersion !== resolved.version
+      ) {
+        registerAndEmitConflict({
+          onEvent: args.onEvent,
+          documentId: args.documentId,
+          pendingConflicts: args.pendingConflicts,
+          conflict: {
+            scopeId: entry.scopeId,
+            entryId: entry.entryId,
+            // External entries have no inline value; embedded side carries version only.
+            embedded: { version: entry.metadataVersion },
+            external: { value: resolved.value, version: resolved.version },
+            defaultPolicy: "prefer-latest",
+          },
+        });
+      }
+
+      // Default behavior: always apply the resolved value (host can override via resolveMetadataConflict).
+      return {
+        ...entry,
+        value: resolved.value,
+        metadataPersistence: "internal" as const,
+        storageRef: undefined,
+        metadataVersion: resolved.version ?? entry.metadataVersion,
+      };
+    }),
+  );
+
+  args.runtime.setWorkflowMetadataEntries(nextEntries);
+}
+
+/* -------------------------------------------------------------------- *\
+ * Conversion: scopes → external (publish payloads out of the doc)
+\* -------------------------------------------------------------------- */
+
+export interface ConvertScopesToExternalInput {
+  runtime: MetadataPersistenceRuntime;
+  scopeIds: string[];
+  resolver: ScopeMetadataResolver | null;
+  /** When provided, version-conflict publish errors emit `metadata_conflict_detected`. */
+  documentId?: string;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  pendingConflicts?: Map<string, PendingConflict>;
+}
+
+/**
+ * Convert the given scopes' metadata entries to external persistence
+ * (value lives in the host store; customXml carries only a ref +
+ * version). For each entry currently in internal mode, publishes
+ * the value via the host-supplied resolver, duck-types version-
+ * conflict errors into `metadata_conflict_detected`, and rewrites
+ * the entry with `metadataPersistence: "external"` and the new
+ * storage ref. Throws `MetadataResolverMissingError` when no
+ * resolver is supplied.
+ */
+export async function convertScopesToExternal(
+  args: ConvertScopesToExternalInput,
+): Promise<void> {
+  if (!args.resolver) throw new MetadataResolverMissingError();
+  const snapshot = args.runtime.getWorkflowMetadataSnapshot();
+  const overlay = args.runtime.getWorkflowOverlay();
+
+  const nextEntries = await Promise.all(
+    snapshot.entries.map(async (entry) => {
+      if (!entry.scopeId || !args.scopeIds.includes(entry.scopeId)) return entry;
+      const scope = overlay?.scopes.find((s) => s.scopeId === entry.scopeId);
+      const effective = resolveEffectivePersistence({
+        overlay: overlay?.metadataPersistence,
+        scope: scope?.metadataPersistence,
+        field: entry.metadataPersistence,
+      });
+      if (effective === "external") return entry;
+
+      try {
+        const { ref, version } = await args.resolver!.publish({
+          scopeId: entry.scopeId,
+          metadataId: entry.metadataId,
+          entryId: entry.entryId,
+          value: entry.value ?? {},
+          expectedVersion: entry.metadataVersion,
+        });
+        return {
+          ...entry,
+          value: undefined,
+          metadataPersistence: "external" as const,
+          storageRef: ref,
+          metadataVersion: version,
+        };
+      } catch (err: unknown) {
+        // Duck-type version-conflict errors (HarnessVersionConflictError or compatible shapes).
+        if (
+          args.pendingConflicts &&
+          args.documentId !== undefined &&
+          err instanceof Error &&
+          (err.name === "HarnessVersionConflictError" ||
+            ("ref" in err && "expected" in err && "actual" in err))
+        ) {
+          const conflictErr = err as Error & {
+            ref?: string;
+            expected?: number;
+            actual?: number;
+          };
+          registerAndEmitConflict({
+            onEvent: args.onEvent,
+            documentId: args.documentId,
+            pendingConflicts: args.pendingConflicts,
+            conflict: {
+              scopeId: entry.scopeId,
+              entryId: entry.entryId,
+              // Embedded side: the entry's current inline value and metadataVersion.
+              embedded: { value: entry.value, version: entry.metadataVersion },
+              // External side: only the rowstore's actual version (no value available from error).
+              external: { version: conflictErr.actual },
+              defaultPolicy: "prefer-latest",
+            },
+          });
+          // Skip this entry — do not publish; leave it unchanged.
+          return entry;
+        }
+        // Non-conflict errors propagate normally.
+        throw err;
+      }
+    }),
+  );
+
+  args.runtime.setWorkflowMetadataEntries(nextEntries);
+}