@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/scopes/_formatting-seam.ts

@@ -0,0 +1,262 @@
+/**
+ * Scope-local formatting seam — **bounded semantic-summary projection**,
+ * NOT formatting semantics.
+ *
+ * ## Contract (tightened 2026-04-22)
+ *
+ * Layer 08 does NOT own formatting. Layer 03 owns formatting semantics
+ * (style cascade, theme colour resolution, run-level accurate mark
+ * computation, numbering-instance evaluation, etc.). This seam's job
+ * is narrow:
+ *
+ *   1. **Delegate the cascade-sensitive fields** — `paragraphStyleId`,
+ *      `outlineLevel`, resolved `numbering.label` — to Layer 03's
+ *      `resolveEffectiveFormatting` (`src/runtime/formatting/`).
+ *      When `doc` is threaded, the seam is a pure pass-through for
+ *      these fields. If Layer 03 disagrees with this seam on any of
+ *      them, Layer 03 wins.
+ *
+ *   2. **Compute a scope-level summary** the compiler adds on top — and
+ *      ONLY on top. Specifically:
+ *        - `emphasis` — majority-emphasis aggregation across the
+ *          paragraph's runs (scope-level; Layer 03 only emits per-run
+ *          accurate marks).
+ *        - `tableRole` (via `deriveTableCellRole`) — structural role
+ *          derived from the row's `isHeader` + position.
+ *      These summaries do NOT re-derive the cascade; they compose
+ *      scope-level signal from canonical structure Layer 03 already
+ *      resolves.
+ *
+ * Anything else — font resolution, character-pair widths, theme
+ * colours, list-item run marks, numbering instance advancement — is
+ * out of scope. Callers needing those go through Layer 03 directly.
+ *
+ * ## Fallback posture
+ *
+ * When the caller only has a bare `ParagraphNode` (no `doc` / no
+ * `paragraphIndex`), the seam returns a honest degraded projection
+ * built from paragraph fields only. The `formatting` fields the scope
+ * then carries are narrower but never wrong. Callers that require the
+ * full cascade-accurate projection must thread `doc` + `paragraphIndex`.
+ *
+ * ## Contracts it honors:
+ *   F1 — single Layer 03 entry. We call `resolveEffectiveFormatting`
+ *        for `{kind: "paragraph", blockId}` when `doc` is available.
+ *   F2 — no state stored here. Every call is pure over its inputs.
+ *   S9 — returns plain immutable values. No runtime-instance leakage.
+ */
+
+import type {
+  CanonicalDocument,
+  ParagraphNode,
+  TableCellNode,
+  TableNode,
+  TableRowNode,
+} from "../../model/canonical-document.ts";
+import { resolveEffectiveFormatting } from "../formatting/resolve-effective.ts";
+
+export interface EffectiveNumbering {
+  readonly numberingInstanceId: string;
+  readonly level: number;
+  readonly label?: string;
+}
+
+export interface EffectiveFormatting {
+  readonly paragraphStyleId?: string;
+  readonly emphasis: readonly string[];
+  readonly numbering?: EffectiveNumbering;
+  readonly outlineLevel?: number;
+}
+
+export interface ScopeFormattingInputs {
+  readonly paragraph: ParagraphNode;
+  /**
+   * Full canonical document. When present, the seam delegates cascade-
+   * sensitive fields (`paragraphStyleId`, `outlineLevel`, resolved
+   * `numbering.label`) to Layer 03's production entry. When absent, the
+   * seam returns the degraded projection built from bare paragraph
+   * fields only — still honest, just narrower.
+   */
+  readonly document?: CanonicalDocument;
+  /**
+   * Paragraph-type index matching Layer 03's `blockId` synthesis
+   * convention (`paragraph-${N}` counts paragraphs in `doc.content.children`
+   * order, not all blocks). Required alongside `document` — the seam
+   * calls `resolveEffectiveFormatting(doc, { kind: "paragraph", blockId })`.
+   */
+  readonly paragraphIndex?: number;
+}
+
+/**
+ * Majority-emphasis summary across the paragraph's text runs. This is a
+ * scope-level aggregation the AI context prompt reads ("is this paragraph
+ * mostly bold?"); Layer 03 owns the per-run cascade and does NOT express
+ * paragraph-wide emphasis as a derived field. Keeping this local is
+ * architecturally correct — it does not duplicate cascade logic.
+ */
+function deriveEmphasisSummary(paragraph: ParagraphNode): string[] {
+  const counts = new Map<string, number>();
+  let runCount = 0;
+  for (const child of paragraph.children) {
+    if (child.type !== "text") continue;
+    runCount += 1;
+    if (!child.marks) continue;
+    for (const mark of child.marks) {
+      if (
+        mark.type === "bold" ||
+        mark.type === "italic" ||
+        mark.type === "underline" ||
+        mark.type === "strikethrough"
+      ) {
+        counts.set(mark.type, (counts.get(mark.type) ?? 0) + 1);
+      }
+    }
+  }
+  if (runCount === 0) return [];
+  const majority: string[] = [];
+  for (const [mark, count] of counts) {
+    if (count * 2 >= runCount) majority.push(mark);
+  }
+  return majority.sort();
+}
+
+/**
+ * Degraded-path outline level. Used ONLY when no canonical document is
+ * threaded — in that case the cascade-resolved outline level is not
+ * reachable; we expose the paragraph's own `outlineLevel` or a bounded
+ * `Heading\d` fallback parsed from the styleId. This is narrower than
+ * the Layer-03 cascade result (which follows style inheritance chains),
+ * and documented as such so downstream consumers can reason about the
+ * loss when `document` is omitted.
+ */
+function degradedOutlineLevel(paragraph: ParagraphNode): number | undefined {
+  if (typeof paragraph.outlineLevel === "number") return paragraph.outlineLevel;
+  const match = /^heading(\d)$/i.exec(paragraph.styleId ?? "");
+  if (match) return Math.max(0, Number(match[1]) - 1);
+  return undefined;
+}
+
+function resolveViaLayer03(
+  doc: CanonicalDocument,
+  paragraph: ParagraphNode,
+  paragraphIndex: number,
+): Pick<EffectiveFormatting, "paragraphStyleId" | "outlineLevel" | "numbering"> {
+  const eff = resolveEffectiveFormatting(doc, {
+    kind: "paragraph",
+    blockId: `paragraph-${paragraphIndex}`,
+  });
+  if (eff.kind !== "paragraph") {
+    // Defensive: the façade always returns a paragraph branch for a
+    // paragraph nodeRef. If the shape drifts, degrade rather than crash.
+    return {
+      ...(paragraph.styleId ? { paragraphStyleId: paragraph.styleId } : {}),
+      ...(typeof paragraph.outlineLevel === "number"
+        ? { outlineLevel: paragraph.outlineLevel }
+        : {}),
+      ...(paragraph.numbering
+        ? {
+            numbering: {
+              numberingInstanceId: paragraph.numbering.numberingInstanceId,
+              level: paragraph.numbering.level,
+            },
+          }
+        : {}),
+    };
+  }
+  // `EffectiveParagraphFormatting` extends `CanonicalParagraphFormatting`
+  // (pPr body) — it does NOT expose `styleId` directly because a paragraph's
+  // styleId is a tree field on `ParagraphNode`, not a pPr property. The
+  // canonical source of the paragraph style id is `paragraph.styleId`; the
+  // cascade uses that id as an input, not an output. We surface the
+  // canonical field directly here.
+  const paragraphStyleId = paragraph.styleId;
+  const outlineLevel =
+    typeof eff.paragraph.outlineLevel === "number"
+      ? eff.paragraph.outlineLevel
+      : degradedOutlineLevel(paragraph);
+  // Numbering identity (instanceId + level) comes from the canonical
+  // paragraph field — Layer 03's `EffectiveNumbering` carries the resolved
+  // marker glyph + indentation, not the instance id. We combine the two
+  // here: identity from canonical, label from Layer 03's cascade.
+  let numbering: EffectiveNumbering | undefined;
+  const canonicalNum = paragraph.numbering;
+  if (canonicalNum) {
+    const label = eff.paragraph.numbering?.marker;
+    numbering = {
+      numberingInstanceId: canonicalNum.numberingInstanceId,
+      level: canonicalNum.level,
+      ...(label ? { label } : {}),
+    };
+  }
+  return {
+    ...(paragraphStyleId ? { paragraphStyleId } : {}),
+    ...(typeof outlineLevel === "number" ? { outlineLevel } : {}),
+    ...(numbering ? { numbering } : {}),
+  };
+}
+
+/**
+ * Narrow paragraph-level projection used by paragraph / heading / list-item
+ * / clause scope kinds. Delegates cascade-sensitive fields to Layer 03
+ * when `inputs.document` is present; falls back to bare paragraph fields
+ * otherwise. Either way, `emphasis` is computed as a scope-level
+ * majority-summary — not a cascade result.
+ *
+ * Callers that pass `document` + `paragraphIndex` receive the cascade-
+ * accurate `paragraphStyleId` / `outlineLevel` / `numbering.label`.
+ * Callers that omit them receive a projection marked implicitly narrower
+ * (the caller is expected to set `partial: true` on the resulting
+ * `SemanticScope`).
+ */
+export function resolveEffectiveFormattingForScope(
+  paragraphOrInputs: ParagraphNode | ScopeFormattingInputs,
+): EffectiveFormatting {
+  const inputs: ScopeFormattingInputs =
+    "paragraph" in paragraphOrInputs
+      ? paragraphOrInputs
+      : { paragraph: paragraphOrInputs };
+  const { paragraph, document, paragraphIndex } = inputs;
+  const emphasis = deriveEmphasisSummary(paragraph);
+  if (document && typeof paragraphIndex === "number") {
+    const base = resolveViaLayer03(document, paragraph, paragraphIndex);
+    return { emphasis, ...base };
+  }
+  const outlineLevel = degradedOutlineLevel(paragraph);
+  return {
+    emphasis,
+    ...(paragraph.styleId ? { paragraphStyleId: paragraph.styleId } : {}),
+    ...(paragraph.numbering
+      ? {
+          numbering: {
+            numberingInstanceId: paragraph.numbering.numberingInstanceId,
+            level: paragraph.numbering.level,
+          },
+        }
+      : {}),
+    ...(outlineLevel !== undefined ? { outlineLevel } : {}),
+  };
+}
+
+export interface TableCellRoleInput {
+  readonly row: TableRowNode;
+  readonly rowIndex: number;
+  readonly table: TableNode;
+}
+
+/**
+ * Structural role for a table cell. This is NOT a formatting cascade
+ * question — role derives from the row's `isHeader` flag + positional
+ * convention (first row → header, last row → footer, middle rows →
+ * body). Keeping the derivation local is architecturally correct;
+ * Layer 03's `resolveEffectiveFormatting` for `kind: "table-cell"`
+ * exposes cascade-resolved paragraph + run formatting, not row role.
+ */
+export function deriveTableCellRole(
+  input: TableCellRoleInput,
+  _cell: TableCellNode,
+): "header" | "body" | "footer" {
+  if (input.row.isHeader === true) return "header";
+  if (input.rowIndex === 0) return "header";
+  if (input.rowIndex === input.table.rows.length - 1) return "footer";
+  return "body";
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Layer 08 · dependency bridge — upstream types from the shared
+ * vocabulary.
+ *
+ * The adversarial-close pass (2026-04-22) flagged that the compiler was
+ * reaching directly into `src/api/public-types.ts` from many files.
+ * Honest fix: **every upstream type Layer 08 depends on crosses through
+ * this single bridge**. All other files under `src/runtime/scopes/**`
+ * import from this module. The compiler-purity guard now enforces the
+ * choke point — only this file is allowed to import from
+ * `src/api/public-types.ts`.
+ *
+ * This does NOT eliminate the upward dependency (a full move of these
+ * shared-vocabulary types into a runtime-internal home would ripple
+ * through ~30 runtime files outside Layer 08's scope; see `docs/plans/
+ * cross-layer-coord-08.md` item 5 for the deferred refactor path). It
+ * DOES:
+ *
+ *   1. Reduce the leak from ~11 import sites to 1.
+ *   2. Document explicitly which shared-vocabulary types Layer 08 depends on.
+ *   3. Make a future type-migration a one-file change.
+ *
+ * If a new type is needed from `src/api/public-types.ts`, add the
+ * re-export here and nowhere else. If a new type CAN be defined in
+ * runtime-internal code, prefer that.
+ */
+
+export type {
+  CompatibilityFeatureEntry,
+  CompatibilityReport,
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  EffectiveSelectionMode,
+  InteractionGuardSnapshot,
+  WorkflowBlockedCommandReason,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeMetadataField,
+} from "../../api/public-types.ts";
+
+/**
+ * The session-state shape the compiler-service reads. Declared as a
+ * Pick rather than re-exporting `EditorSessionState` whole so the
+ * dependency surface stays narrow to exactly the one field used.
+ */
+import type { EditorSessionState } from "../../api/public-types.ts";
+export type ScopeSessionState = Pick<EditorSessionState, "documentId">;

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

@@ -0,0 +1,356 @@
+/**
+ * Layer 08 · Slice 4 — unified action-validation composer.
+ *
+ * Composes four independent policy surfaces into one `ValidationResult`
+ * verdict that callers read before applying a replacement:
+ *
+ *   1. workflow guard    — `runtime.getInteractionGuardSnapshot()` plus
+ *                          the scope's overlay-overlap projection
+ *                          (`scope.workflow.effectiveMode` +
+ *                          `scope.workflow.blockedReasons`). Scope-level
+ *                          posture is authoritative because guard-snapshot
+ *                          is selection-scoped; the scope may live in a
+ *                          view-mode overlay even when the cursor does not.
+ *   2. preservation      — `computePreservationVerdict` reads the document
+ *                          preservation store + scope markers inside the
+ *                          range. Any overlap is a blocker.
+ *   3. compatibility     — `runtime.getCompatibilityReport()` — current
+ *                          `unsupported-fatal` feature entries surface as
+ *                          warnings (`source: "compat"`); `blockExport`
+ *                          surfaces as a blocker so apply never produces
+ *                          an undeliverable document.
+ *   4. AI-action policy  — `getAIActionPolicy(actionId)` — `blocked` /
+ *                          `unsupported` support is a blocker; `high` /
+ *                          `critical` risk or `userConfirmation`
+ *                          requirements surface as `approval.required`.
+ *
+ * Contract highlights (see architecture 08 §"Contracts" + Slice 4
+ * handover):
+ *   - `safe === true`  iff  `blockedReasons.length === 0`. Warnings do
+ *                          NOT degrade safety — they surface as advisory.
+ *   - `approval.required` is orthogonal to `safe`. A low-risk action can
+ *                          still need approval; a blocked action can still
+ *                          report `approval: undefined` (the block is the
+ *                          primary signal).
+ *   - `blockedReasons` strings use a stable prefix grammar:
+ *     `guard:…` / `preserve:…` / `compat:…` / `policy:…`. UIs and BW
+ *     workblocks routing keys match on the prefix; grammar is a
+ *     compatibility event.
+ *   - Every `ValidationIssue` carries a `source` tag so consumers can
+ *     route warnings by origin.
+ *   - Deterministic (S3): no wall-clock reads, no PRNG, no state mutation.
+ *
+ * Slice 4 ships the composer + v3 adapter graduation for
+ * `ai.validateReplacementScope`. Slice 5 will consume `composeScopeValidation`
+ * from `replacement/apply.ts` before dispatching any runtime plan.
+ */
+
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import type {
+  CompatibilityReport,
+  InteractionGuardSnapshot,
+} from "./_scope-dependencies.ts";
+import { getAIActionPolicy, type AIAction } from "../workflow/ai-action-policy.ts";
+
+import type { EnumeratedScope } from "./enumerate-scopes.ts";
+import {
+  buildScopePositionMap,
+  type ScopePositionMap,
+} from "./position-map.ts";
+import {
+  computePreservationVerdict,
+} from "./preservation-boundary.ts";
+import { resolveScopeRange } from "./scope-range.ts";
+import type {
+  ReplacementOperationKind,
+  ReplacementScope,
+  SemanticScope,
+  ValidationApproval,
+  ValidationIssue,
+  ValidationResult,
+} from "./semantic-scope-types.ts";
+
+/**
+ * Minimal runtime surface the composer reads. Declared inline rather
+ * than `Pick<RuntimeApiHandle, …>` because the scope compiler must not
+ * import from `src/api/v3/**` (purity guard). The v3 `RuntimeApiHandle`
+ * naturally satisfies this interface because its members carry the
+ * same `InteractionGuardSnapshot` / `CompatibilityReport` shapes from
+ * `src/api/public-types.ts`.
+ */
+export interface ScopeValidationRuntime {
+  getInteractionGuardSnapshot(): InteractionGuardSnapshot;
+  getCompatibilityReport(): CompatibilityReport;
+}
+
+export interface ComposeScopeValidationInputs {
+  readonly scope: SemanticScope;
+  readonly operation: ReplacementOperationKind;
+  readonly proposedContent: ReplacementScope["proposedContent"];
+  readonly runtime: ScopeValidationRuntime;
+  /**
+   * Canonical document — enables preservation-boundary check. Omitting
+   * this field skips the preservation step (no blockers contributed).
+   */
+  readonly document?: CanonicalDocument;
+  /**
+   * Optional precomputed position map — if omitted, built from
+   * `document` (allocation cost) or skipped when document is absent.
+   */
+  readonly positionMap?: ScopePositionMap;
+  /**
+   * Optional enumerated-scope entry, used to resolve the scope's
+   * canonical range when the scope was compiled with a position map the
+   * caller no longer has. Omit to use `scope.handle` + position-map
+   * marker lookup only.
+   */
+  readonly enumeratedScope?: EnumeratedScope;
+  /**
+   * AI-action-policy id. Overrides the operation-derived default. When
+   * the id is unknown to `getAIActionPolicy`, the policy step contributes
+   * no blockers / warnings / approval.
+   */
+  readonly actionId?: AIAction;
+}
+
+/**
+ * Default action-id derivation when the caller did not provide one.
+ * Maps replacement-operation + proposed-content shape to the closest
+ * entry in the 37-op policy matrix.
+ */
+function inferActionId(
+  operation: ReplacementOperationKind,
+  content: ReplacementScope["proposedContent"],
+): AIAction {
+  switch (operation) {
+    case "replace":
+      return content.kind === "text" ? "rewrite_paragraph" : "generate_text";
+    case "insert-before":
+    case "insert-after":
+      return "generate_text";
+    case "split":
+      return "rewrite_paragraph";
+    case "annotate":
+      return "suggest_comment_response";
+  }
+}
+
+/**
+ * Scope-level guard step — consults both the scope's own overlay-overlap
+ * projection (deepest, most specific signal) and the runtime's
+ * selection-scoped `InteractionGuardSnapshot` (catches global posture
+ * overrides like read-only + document-mode). The most restrictive signal
+ * produces the blocker.
+ */
+function collectGuardVerdict(
+  scope: SemanticScope,
+  runtime: ComposeScopeValidationInputs["runtime"],
+  blockedReasons: string[],
+  warnings: ValidationIssue[],
+): void {
+  const scopeMode = scope.workflow.effectiveMode;
+  if (scopeMode === "view") {
+    blockedReasons.push("guard:view-mode-active");
+    warnings.push({
+      code: "guard:view-mode-active",
+      message: "scope is inside a view-mode workflow overlay",
+      source: "guard",
+    });
+  } else if (scopeMode === "blocked") {
+    // Coord-06 §13e — `guard:blocked` becomes typed `guard:block-<reason>`
+    // so agents can route intelligently. This path is a defensive catchall
+    // (scope.workflow.effectiveMode is normally edit/suggest/comment/view;
+    // the overlay-compiler doesn't emit "blocked"). Mark with the
+    // specific sub-reason so the grammar is consistent across both
+    // emission sites.
+    blockedReasons.push("guard:block-scope-overlay");
+    warnings.push({
+      code: "guard:block-scope-overlay",
+      message: "scope is inside a blocked workflow overlay",
+      source: "guard",
+    });
+  } else if (scopeMode === "comment") {
+    blockedReasons.push("guard:comment-only");
+    warnings.push({
+      code: "guard:comment-only",
+      message: "scope is inside a comment-only workflow overlay",
+      source: "guard",
+    });
+  } else if (scopeMode === "suggest") {
+    // Suggest is not a blocker — the call site converts the replacement
+    // into a tracked-change in Slice 5. Still emit a warning so the
+    // caller can switch to a suggest-shaped apply without surprise.
+    warnings.push({
+      code: "guard:suggest-mode",
+      message:
+        "scope is in suggest mode; replacement must be issued as a tracked change",
+      source: "guard",
+    });
+  }
+  for (const reason of scope.workflow.blockedReasons ?? []) {
+    warnings.push({
+      code: `guard:${reason}`,
+      message: `workflow overlay signal: ${reason}`,
+      source: "guard",
+    });
+  }
+
+  const guard = runtime.getInteractionGuardSnapshot();
+  if (
+    guard.effectiveMode === "view" &&
+    !blockedReasons.includes("guard:view-mode-active")
+  ) {
+    blockedReasons.push("guard:view-mode-active");
+  }
+  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 code on
+    // `guard.blockedReasons` (coordinator's `evaluateBlockedReasons`
+    // output). When the array is empty (defensive — shouldn't happen;
+    // coordinator sets `effectiveMode: "blocked"` only when at least
+    // one blockedReason fires) fall back to `guard:block-unspecified`.
+    const primaryCode = guard.blockedReasons?.[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);
+    }
+  }
+  for (const reason of guard.blockedReasons ?? []) {
+    // `reason` is a `WorkflowBlockedCommandReason` object — the legacy
+    // template emitted the bare object here, producing `guard:selection-
+    // [object Object]` in serialized warnings. Use `.code` so downstream
+    // receivers see a stable string identifier (§13e / coord-09 routing).
+    const code = typeof reason === "object" && reason !== null && "code" in reason
+      ? (reason as { code: unknown }).code
+      : reason;
+    const codeStr = typeof code === "string" ? code : JSON.stringify(code);
+    warnings.push({
+      code: `guard:selection-${codeStr}`,
+      message: `selection guard signal: ${codeStr}`,
+      source: "guard",
+    });
+  }
+}
+
+function collectPreservationVerdict(
+  inputs: ComposeScopeValidationInputs,
+  blockedReasons: string[],
+): void {
+  const { document, scope, positionMap } = inputs;
+  if (!document) return;
+  const pm = positionMap ?? buildScopePositionMap(document);
+  const range = inputs.enumeratedScope
+    ? resolveScopeRange(inputs.enumeratedScope, scope.handle, pm)
+    : scope.handle.stableRef.kind === "scope-id"
+      ? (pm.markerScopes.get(scope.handle.stableRef.value) ?? null)
+      : null;
+  const verdict = computePreservationVerdict(document, range, pm);
+  if (!verdict.replaceable) {
+    for (const reason of verdict.reasons) {
+      blockedReasons.push(`preserve:${reason}`);
+    }
+  }
+}
+
+function collectCompatibilityVerdict(
+  runtime: ComposeScopeValidationInputs["runtime"],
+  blockedReasons: string[],
+  warnings: ValidationIssue[],
+): void {
+  const report = runtime.getCompatibilityReport();
+  if (report.blockExport) {
+    blockedReasons.push("compat:block-export");
+  }
+  for (const entry of report.featureEntries) {
+    if (entry.featureClass === "unsupported-fatal") {
+      warnings.push({
+        code: `compat:unsupported-fatal-${entry.featureKey}`,
+        message: entry.message,
+        source: "compat",
+      });
+    }
+  }
+}
+
+function collectPolicyVerdict(
+  actionId: AIAction,
+  blockedReasons: string[],
+  warnings: ValidationIssue[],
+): ValidationApproval | undefined {
+  // `getAIActionPolicy` throws on unknown actions. The composer absorbs
+  // that as "no policy signal" rather than propagating — the caller's
+  // actionId choice is a best-effort mapping, not a contract.
+  let policy;
+  try {
+    policy = getAIActionPolicy(actionId);
+  } catch {
+    return undefined;
+  }
+
+  if (policy.support === "blocked") {
+    blockedReasons.push(`policy:blocked-${policy.action}`);
+    warnings.push({
+      code: `policy:blocked-${policy.action}`,
+      message: policy.rationale,
+      source: "policy",
+    });
+  } else if (policy.support === "unsupported") {
+    blockedReasons.push(`policy:unsupported-${policy.action}`);
+    warnings.push({
+      code: `policy:unsupported-${policy.action}`,
+      message: policy.rationale,
+      source: "policy",
+    });
+  }
+
+  // Note: `policy.constraints.preservedContentRespect` and
+  // `compatibilityValidation` are *enforcement requirements* — the
+  // composer already enforces both (preservation step + compatibility
+  // step emit the actual blockers/warnings when they fire). Surfacing
+  // them as always-on policy advisories would double-report, so we
+  // consult them implicitly through the other steps rather than
+  // emitting a `policy:*` warning here.
+
+  const needsApproval =
+    policy.risk === "high" ||
+    policy.risk === "critical" ||
+    policy.requirements.userConfirmation;
+  if (needsApproval) {
+    return { required: true, reason: policy.rationale };
+  }
+  return undefined;
+}
+
+/**
+ * Compose a single validation verdict for a proposed scope replacement.
+ * Synchronous, deterministic, free of side effects. Safe to call in hot
+ * paths; the composer reuses a single position-map when the caller
+ * provides one.
+ */
+export function composeScopeValidation(
+  inputs: ComposeScopeValidationInputs,
+): ValidationResult {
+  const blockedReasons: string[] = [];
+  const warnings: ValidationIssue[] = [];
+
+  collectGuardVerdict(inputs.scope, inputs.runtime, blockedReasons, warnings);
+  collectPreservationVerdict(inputs, blockedReasons);
+  collectCompatibilityVerdict(inputs.runtime, blockedReasons, warnings);
+
+  const actionId =
+    inputs.actionId ?? inferActionId(inputs.operation, inputs.proposedContent);
+  const approval = collectPolicyVerdict(actionId, blockedReasons, warnings);
+
+  const safe = blockedReasons.length === 0;
+  return {
+    safe,
+    blockedReasons: Object.freeze([...blockedReasons]),
+    warnings: Object.freeze([...warnings]),
+    ...(approval ? { approval } : {}),
+  };
+}