@beyondwork/docx-react-component 1.0.71 → 1.0.73

package/package.json

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

package/src/api/public-types.ts

@@ -103,6 +103,27 @@ export type {
 export type { CollabSession } from "../runtime/collab-session.ts";
 export type { MetadataIntegrity } from "../runtime/workflow/tamper-gate.ts";
 export type { ScopeTagRegistry } from "../runtime/workflow/scope-tag-registry.ts";
+/**
+ * Zero-arg factory for the default-seeded `ScopeTagRegistry`. Two
+ * equivalent call sites ship today; pick whichever matches your scope:
+ *
+ *   - `createScopeTagRegistry()` (this re-export) — handle-free path for
+ *     L11 consumers that already import from `public-types`. §4.17
+ *     "simple pass-through of a runtime helper" precedent. Safe when
+ *     there's no `api` in scope (tests, pre-mount, PM-surface
+ *     component-internal memo).
+ *
+ *   - `api.runtime.workflow.createScopeTagRegistry()` — L06 proper API
+ *     home shipped 2026-04-23 per coord-10 §L11-4 (L11 delegation).
+ *     Preferred when a handle is already threaded: the registry is then
+ *     reachable through the same family as `queryScopes`, `getMarkup`,
+ *     etc., and the call appears in agent-audit telemetry.
+ *
+ * Both paths delegate to the same implementation in
+ * `src/runtime/workflow/scope-tag-registry.ts` and return an identical
+ * `ScopeTagRegistry` shape. No behavior difference.
+ */
+export { createScopeTagRegistry } from "../runtime/workflow/scope-tag-registry.ts";
 // Semantic-scope shapes — re-exported so L10 (ui.scope.*) + L09
 // (ai.getScopeBundle) + L11 (scope-card consumers) can import the
 // canonical types from the public-types choke point instead of
@@ -119,6 +140,23 @@ export type {
 } from "../runtime/scopes/semantic-scope-types.ts";
 export type { GeometryFacet } from "../runtime/geometry/index.ts";
 export type { RuntimePageGraph } from "../runtime/layout/page-graph.ts";
+export type { RuntimePageNode } from "../runtime/layout/page-graph.ts";
+
+/**
+ * `resolvePageFieldDisplayText` pure helper — resolves `PAGE` /
+ * `NUMPAGES` field text for a specific page + graph. Used by the PM
+ * page-break decoration renderer to substitute the cached preserve-
+ * only text with a live per-page number. Pure function over the
+ * already-public `RuntimePageGraph` / `RuntimePageNode` +
+ * `SupportedFieldFamily` types; no runtime handle in scope at the
+ * presentation-layer call site. Matches the §4.8 / §4.17 re-export
+ * precedent. Canonical impl lives on
+ * `src/runtime/layout/resolve-page-fields.ts`.
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 L04 layout
+ * long-tail row after `RuntimePageGraph` graduated to public-types.
+ */
+export type { PageFieldContext } from "../runtime/layout/resolve-page-fields.ts";
+export { resolvePageFieldDisplayText } from "../runtime/layout/resolve-page-fields.ts";
 
 export type {
   WordReviewEditorLayoutFacet,
@@ -182,6 +220,63 @@ export type { ScopeRailPosture } from "../runtime/workflow/rail/compose.ts";
 // reaching into `src/runtime/**` directly (P3).
 export type { SessionCapabilities } from "../runtime/session-capabilities.ts";
 
+/**
+ * `deriveCapabilities` value re-export — pure function over the
+ * already-public `RuntimeRenderSnapshot` + `WorkflowScopeSnapshot`
+ * inputs. Matches the `storyTargetsEqual` / unit-constant precedent
+ * for pure-helper re-exports where no runtime handle is in scope at
+ * the consumer. Called by `src/ui-tailwind/index.ts`'s public
+ * facade so hosts can derive capabilities without reaching into
+ * `src/runtime/**` directly. Re-exported 2026-04-24 per refactor/11
+ * handoff §4.17 self-closable row (L01 session-capabilities value).
+ */
+export { deriveCapabilities } from "../runtime/session-capabilities.ts";
+
+/**
+ * Editor capability table — frozen map + accompanying pure types.
+ * Re-exported 2026-04-24 per coord-10 §L11-1 (delegated from
+ * refactor/11 handoff register). Retires the direct reach-through
+ * from `src/ui/runtime-shortcut-dispatch.ts` into
+ * `src/runtime/editor-surface/capabilities.ts`. Matches the §4.8
+ * precedent class: frozen value + pure types, no runtime handle at
+ * the consumer. L07 may later formalize this as
+ * `api.runtime.capabilities.getById(id)` / `.list()`; the re-export
+ * here is the minimum-viable unblock.
+ */
+export type {
+  CapabilityKind,
+  CapabilityCategory,
+  CapabilityShortcut,
+  CapabilityBlockReason,
+  EditorCapability,
+} from "../runtime/editor-surface/capabilities.ts";
+export { CAPABILITY_BY_ID } from "../runtime/editor-surface/capabilities.ts";
+
+/**
+ * Per-page header/footer short-text preview maps — used by the in-flow
+ * page-chrome bands to show live content ("Page 3 of 5") instead of
+ * generic "Header" / "Footer" labels. Re-exported 2026-04-24 per coord-10
+ * §L11-2 (delegated from refactor/11 handoff register). `buildPagePreviewMaps`
+ * reads only `pages[].pageId / stories / isBlankFiller` on its graph input,
+ * and consumers already pass a structural adapter (see
+ * `tw-prosemirror-surface.tsx`); the minimum-viable unblock re-exports the
+ * function + result type without hoisting `RuntimePageGraph` itself. L04
+ * may later formalize as `api.runtime.layout.getPagePreviews(nav, subParts)`.
+ */
+export type { PagePreviewMaps } from "../runtime/layout/resolve-page-previews.ts";
+export { buildPagePreviewMaps } from "../runtime/layout/resolve-page-previews.ts";
+
+/**
+ * Canvas measurement backend factory — browser-only `LayoutMeasurementProvider`
+ * that uses Canvas2D `measureText()` for font-metric-aware width computation.
+ * Re-exported 2026-04-24 per coord-10 §L11-5 (delegated from refactor/11
+ * handoff register). Consumers pass the result to
+ * `WordReviewEditorLayoutFacet.swapMeasurementProvider(...)`; the provider
+ * type is already threaded through the facet's public surface. L04 may
+ * later formalize as `api.runtime.layout.createCanvasBackend()`.
+ */
+export { createCanvasBackend } from "../runtime/layout/measurement-backend-canvas.ts";
+
 export type FieldFamily = import("../model/canonical-document.ts").FieldFamily;
 export type FieldRefreshStatus = import("../model/canonical-document.ts").FieldRefreshStatus;
 export type SupportedFieldFamily = import("../model/canonical-document.ts").SupportedFieldFamily;
@@ -260,6 +355,89 @@ export type { EditorStoryTarget } from "../model/layout/page-layout-snapshot.ts"
  */
 export { storyTargetsEqual, MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
 
+/**
+ * `storyTargetKey` pure function — stable string key derivation for
+ * `EditorStoryTarget` (`main` / `header` / `footer` / `footnote` /
+ * `endnote`). Used by presentation-layer caches keyed by story
+ * target (e.g. floating-image overlay model). Matches the
+ * `storyTargetsEqual` precedent — pure function over a public type,
+ * no runtime handle in scope at the consumer. Canonical impl lives
+ * on `src/runtime/story-targeting.ts`.
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 self-closable row.
+ */
+export { storyTargetKey } from "../runtime/story-targeting.ts";
+
+/**
+ * Public-shape anchor constructors — pure helpers producing the
+ * `EditorAnchorProjection` discriminated union used in
+ * `SelectionSnapshot.activeRange`. `createPublicRangeAnchor`
+ * normalizes `from <= to` internally; `createPublicNodeAnchor`
+ * tags a node anchor at `at` with boundary associativity. Canonical
+ * impl lives on `src/core/selection/anchor-conversion.ts` — the
+ * single authority enforced by
+ * `test/api/anchor-boundary-invariants.test.ts`.
+ *
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 — the L03/L06
+ * selection-primitives row names `anchor-conversion` as a candidate
+ * for the public-types re-export pattern (chart family precedent)
+ * when the consumer is a leaf helper with no runtime handle in scope,
+ * which `src/ui/headless/selection-helpers.ts` is.
+ */
+export {
+  createPublicRangeAnchor,
+  createPublicNodeAnchor,
+} from "../core/selection/anchor-conversion.ts";
+
+/**
+ * L04 pagination pure helpers — leaf functions over already-public
+ * `DocumentPageSnapshot` / `PageLayoutSnapshot` / `SurfaceBlockSnapshot`
+ * shapes, used by presentation-layer page-chrome surfaces
+ * (`src/ui-tailwind/page-chrome-model.ts`). No runtime handle in scope
+ * at call sites — exactly the §4.8 precedent class.
+ *
+ * - `findPageForOffset(pages, offset)` — index resolver.
+ * - `estimateBlockHeight`, `estimateParagraphLineHeight`,
+ *   `estimateParagraphLineCount`, `getUsableColumnWidth` — pure
+ *   layout estimators used before real layout is available (cold
+ *   open + placeholder chrome).
+ *
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 L04 layout
+ * family long-tail. Canonical impls live on
+ * `src/runtime/document-navigation.ts` +
+ * `src/runtime/page-layout-estimation.ts`.
+ */
+export { findPageForOffset } from "../runtime/document-navigation.ts";
+export {
+  estimateBlockHeight,
+  estimateParagraphLineHeight,
+  estimateParagraphLineCount,
+  getUsableColumnWidth,
+} from "../runtime/page-layout-estimation.ts";
+
+/**
+ * L03/L06 search-text pure helpers + type aliases — pure functions
+ * over `SurfaceBlockSnapshot` + `SearchOptions` (public types) used
+ * by the PM search plugin at `src/ui-tailwind/editor-surface/search-plugin.ts`.
+ * No runtime handle in scope. Matches the handoff §4.17 "L03/L06
+ * selection/search primitives — promote to public-types.ts as pure
+ * re-exports (chart family precedent)" alternative.
+ *
+ * Canonical impl lives on `src/core/search/search-text.ts`.
+ *
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17. The larger
+ * `runtime.content.search` family seam on L07 is still the preferred
+ * long-term home; until it ships, this pragmatic re-export unblocks
+ * the L11 boundary register.
+ */
+export {
+  buildSearchPattern,
+  createSearchExcerpt,
+  findSearchMatches,
+  searchSecondaryStories,
+  type SecondaryStorySearchResult,
+  type SearchTextOptions,
+} from "../core/search/search-text.ts";
+
 /**
  * OOXML unit-conversion constants shared with presentation-layer
  * renderers. EMU (English Metric Units) is the OOXML measurement
@@ -280,6 +458,39 @@ export {
   SRCRECT_UNITS_PER_PERCENT,
 } from "../runtime/units.ts";
 
+/**
+ * Geometry-kernel + page-estimation unit constants used by presentation-
+ * layer chrome (table grip, page chrome). Both fold into public-types
+ * alongside the OOXML unit constants above so chrome overlays can
+ * convert between twips and CSS px without reaching into
+ * `src/runtime/**`.
+ *
+ * - `DEFAULT_PX_PER_TWIP = 96 / 1440` — kernel render-frame conversion
+ *   used by `tw-table-grip-layer` for grip positioning.
+ * - `DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP = 1 / 15` — page-chrome
+ *   estimation scale used for placeholder chrome before real layout.
+ *
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 self-closable
+ * rows. Canonical values live on `src/runtime/render/render-frame-types.ts`
+ * and `src/runtime/page-layout-estimation.ts`.
+ */
+export { DEFAULT_PX_PER_TWIP } from "../runtime/render/render-frame-types.ts";
+export { DEFAULT_PAGE_ESTIMATE_PX_PER_TWIP } from "../runtime/page-layout-estimation.ts";
+
+/**
+ * Markdown sanitizer re-exported at the public-types boundary so the
+ * Layer-11 comment-markdown renderer can consume it without reaching
+ * into `src/runtime/**`. Pure function over a string; no runtime handle
+ * in scope at the leaf renderer. Canonical implementation lives on
+ * `src/runtime/markdown-sanitizer.ts` and is shared with
+ * `runtime/comment-presentation.ts`.
+ * Re-exported 2026-04-24 per refactor/11 handoff §4.17 self-closable row.
+ */
+export {
+  sanitizeMarkdown,
+  type SanitizeResult,
+} from "../runtime/markdown-sanitizer.ts";
+
 export interface SelectionSnapshot {
   anchor: number;
   head: number;
@@ -904,7 +1115,16 @@ export type SurfaceTextMark =
   | "imprint"
   | "shadow"
   | "smallCaps"
-  | "allCaps";
+  | "allCaps"
+  /**
+   * Present iff the run carried `w:highlight`. The concrete highlight color
+   * is on `markAttrs.backgroundColor`. Consumers that only care about the
+   * presence signal (e.g. "is this run highlighted?") read `marks`; those
+   * that need the color read `markAttrs.backgroundColor`. Note that
+   * `backgroundColor` can also originate from `w:shd` (run shading) — only
+   * the `"highlight"` mark disambiguates the source.
+   */
+  | "highlight";
 
 /**
  * V2c.4 / V2c.5 — DrawingFrame anchor geometry projected onto image + shape
@@ -1225,6 +1445,34 @@ export type SurfaceBlockSnapshot =
       outlineLevel?: number;
       bidi?: boolean;
       suppressLineNumbers?: boolean;
+      /**
+       * `<w:framePr>` text-frame properties (ECMA-376 §17.3.1.11). Populated
+       * by L03 surface projection from `CanonicalParagraphFormatting.frameProperties`
+       * when present. L04 consumers use the positioning fields to decide
+       * paginated-layout placement (out-of-flow framed paragraph vs. in-flow
+       * block); L11 consumers use them to render `<div>` with absolute or
+       * margin-anchored positioning + wrap behavior. Absent field = normal
+       * in-flow paragraph.
+       *
+       * All sub-fields optional; absence carries the OOXML default.
+       */
+      frameProperties?: {
+        widthTwips?: number;
+        heightTwips?: number;
+        hRule?: "auto" | "atLeast" | "exact";
+        xTwips?: number;
+        yTwips?: number;
+        xAlign?: "left" | "center" | "right" | "inside" | "outside";
+        yAlign?: "top" | "center" | "bottom" | "inside" | "outside" | "inline";
+        hAnchor?: "text" | "margin" | "page";
+        vAnchor?: "text" | "margin" | "page";
+        wrap?: "around" | "auto" | "none" | "notBeside" | "tight" | "through";
+        hSpaceTwips?: number;
+        vSpaceTwips?: number;
+        dropCap?: "none" | "drop" | "margin";
+        lines?: number;
+        anchorLock?: boolean;
+      };
       segments: SurfaceInlineSegment[];
     }
   | {
@@ -1657,6 +1905,15 @@ export interface TableStructureContextSnapshot {
   columnCount: number;
   selectedCellCount: number;
   isSimpleTable: boolean;
+  /**
+   * Table-level alignment declared on the canonical `TableNode.alignment`.
+   * `null` when the table has no explicit alignment (renders against the
+   * parent's default — typically left). Mirrors `PublicTableSummary.alignment`
+   * (refactor/11 §4.13) so the active-state of the whole-table alignment
+   * toolbar button can read from the context snapshot directly without
+   * a separate `getTable(tableBlockIndex).alignment` hop.
+   */
+  alignment: "left" | "center" | "right" | null;
   currentCell: {
     rowIndex: number;
     columnIndex: number;
@@ -2205,6 +2462,19 @@ export interface AddScopeParams {
    * held runtime-only, split across doc + workblock, or fully embedded.
    */
   metadata?: Partial<WorkflowMetadataEntry>;
+  /**
+   * Optional fields stamped onto the overlay scope's `metadata` array
+   * at creation time. Distinct from `metadata?: Partial<WorkflowMetadataEntry>`
+   * above (which writes a typed metadata *entry* keyed by `metadataId`);
+   * `scopeMetadataFields` lands as plain `WorkflowScopeMetadataField[]`
+   * on the `WorkflowScope.metadata` slot and survives serialization /
+   * collab replication with the overlay.
+   *
+   * Used by coord-08 §9 — L06's `createScopeFromBlockId({stableRefHint})`
+   * encodes the hint as `{key: "stableRefHint", value: <kind>}` here so
+   * the L08 compiler can read it back during enumeration.
+   */
+  scopeMetadataFields?: readonly WorkflowScopeMetadataField[];
   /** Non-main-body stories (footnote / header / endnote). */
   storyTarget?: EditorStoryTarget;
   /** Optional display label for the scope card / rail. */
@@ -5337,6 +5607,15 @@ export interface WordReviewEditorChromeVisibility {
   pageChrome: boolean;
   statusBar: boolean;
   reviewRail: boolean;
+  /**
+   * TwShellHeader (Edit / Review / Workflow / More mode tabs) at the top
+   * of the workspace. Defaults to `true` on every preset EXCEPT
+   * `selection`, which is intended for minimal embeds and should not paint
+   * a workspace chrome header. coord-11 §21 — regressing this default has
+   * history, particularly for visual-fidelity captures that expect a
+   * truly chrome-less `chrome=none` embed.
+   */
+  shellHeader: boolean;
 }
 
 // ---------------------------------------------------------------------------

package/src/api/v3/_create.ts

@@ -27,6 +27,7 @@ import { createClipboardFamily } from "./runtime/clipboard.ts";
 import { createChartFamily } from "./runtime/chart.ts";
 import { createSearchFamily } from "./runtime/search.ts";
 import { createTableFamily } from "./runtime/table.ts";
+import { createViewportFamily } from "./runtime/viewport.ts";
 
 import { createInspectFamily } from "./ai/inspect.ts";
 import { createResolveFamily } from "./ai/resolve.ts";
@@ -36,6 +37,10 @@ import { createAttachFamily } from "./ai/attach.ts";
 import { createExportFamily } from "./ai/export.ts";
 import { createExplainFamily } from "./ai/explain.ts";
 import { createPolicyFamily } from "./ai/policy.ts";
+import { createReviewFamily as createAiReviewFamily } from "./ai/review.ts";
+import { createEvaluateFamily } from "./ai/evaluate.ts";
+import { createStatsFamily } from "./ai/stats.ts";
+import { createOutlineFamily } from "./ai/outline.ts";
 
 import { createUiApi } from "./ui/_create.ts";
 import type { ApiV3Ui, UiControllerFactory } from "./ui/_types.ts";
@@ -62,6 +67,7 @@ export type ApiV3Runtime = {
   readonly chart: ReturnType<typeof createChartFamily>;
   readonly search: ReturnType<typeof createSearchFamily>;
   readonly table: ReturnType<typeof createTableFamily>;
+  readonly viewport: ReturnType<typeof createViewportFamily>;
 };
 
 export type ApiV3Ai = ReturnType<typeof createInspectFamily>
@@ -71,7 +77,11 @@ export type ApiV3Ai = ReturnType<typeof createInspectFamily>
   & ReturnType<typeof createAttachFamily>
   & ReturnType<typeof createExportFamily>
   & ReturnType<typeof createExplainFamily>
-  & ReturnType<typeof createPolicyFamily>;
+  & ReturnType<typeof createPolicyFamily>
+  & ReturnType<typeof createAiReviewFamily>
+  & ReturnType<typeof createEvaluateFamily>
+  & ReturnType<typeof createStatsFamily>
+  & ReturnType<typeof createOutlineFamily>;
 
 export interface ApiV3 {
   readonly runtime: ApiV3Runtime;
@@ -117,6 +127,10 @@ export function createApiV3(handle: RuntimeApiHandle, opts?: CreateApiV3Opts): A
     ...createExportFamily(handle),
     ...createExplainFamily(handle),
     ...createPolicyFamily(handle),
+    ...createAiReviewFamily(handle),
+    ...createEvaluateFamily(handle),
+    ...createStatsFamily(handle),
+    ...createOutlineFamily(handle),
   };
   const runtime: ApiV3Runtime = {
     document: createDocumentFamily(handle),
@@ -131,6 +145,7 @@ export function createApiV3(handle: RuntimeApiHandle, opts?: CreateApiV3Opts): A
     chart: createChartFamily(handle),
     search: createSearchFamily(handle),
     table: createTableFamily(handle),
+    viewport: createViewportFamily(handle),
   };
   // Construct the UI namespace only when a factory is supplied.
   // `ui` remains `undefined` otherwise — the shape in ApiV3 is optional

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

@@ -55,6 +55,7 @@ export type RuntimeApiHandle = Pick<
   // Review (runtime.review family)
   | "getReviewWorkSnapshot"
   | "acceptChange"
+  | "rejectChange"
   | "resolveComment"
   // Workflow (runtime.workflow + ai.inspect families)
   | "queryScopes"
@@ -131,6 +132,7 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   findAllText: true,
   getReviewWorkSnapshot: true,
   acceptChange: true,
+  rejectChange: true,
   resolveComment: true,
   queryScopes: true,
   getWorkflowMarkupSnapshot: true,

package/src/api/v3/ai/evaluate.ts

@@ -0,0 +1,113 @@
+/**
+ * @endStateApi v3 — `ai.evaluate` family.
+ *
+ * evaluateAction — pre-flight verdict combining /06's static policy
+ * matrix with live runtime state. Returns whether an action can
+ * currently proceed, what blockers (if any) apply, and whether human
+ * approval is required per the policy tier.
+ *
+ * Composition rules:
+ *
+ *   1. If `policy.support` is `'blocked'` or `'unsupported'`, emit a
+ *      `policy-refused:<support>` blocker. `allowed: false` regardless
+ *      of live state — the policy override wins.
+ *
+ *   2. When `input.scopeId` is supplied, resolve it via the scope
+ *      compiler. If it does not resolve, emit
+ *      `scope-not-resolvable:<scopeId>` and flip `allowed: false`. This
+ *      mirrors the refusal taxonomy that `ai.validateReplacementScope`
+ *      surfaces.
+ *
+ *   3. `approvalRequired` is the policy tier's confirmation flag —
+ *      `support === 'confirmation-required' ||
+ *      requirements.userConfirmation`. Agents should surface this to a
+ *      human before calling the mutating path, even when `allowed:
+ *      true`.
+ *
+ * Read-family function — A4 audit emission does not apply.
+ * `validateReplacementScope` remains the authoritative pre-flight for
+ * replacement-class mutations (it runs the full `composeScopeValidation`
+ * pipeline); `evaluateAction` is a lighter, scope-optional probe an
+ * agent can call against any `AIAction`, including non-replacement
+ * operations (resolve_comment_thread, auto_accept_changes, etc.) that
+ * have no scope target.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  getAIActionPolicy,
+  type AIAction,
+  type AIActionPolicy,
+} from "../../../runtime/workflow/ai-action-policy.ts";
+import { createScopeCompilerService } from "../../../runtime/scopes/index.ts";
+
+export interface EvaluateActionInput {
+  readonly action: AIAction;
+  readonly scopeId?: string;
+}
+
+export interface EvaluateActionResult {
+  readonly action: AIAction;
+  readonly allowed: boolean;
+  readonly policy: AIActionPolicy;
+  readonly blockers: readonly string[];
+  readonly approvalRequired: boolean;
+}
+
+export const evaluateActionMetadata: ApiV3FnMetadata = {
+  name: "ai.evaluateAction",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/ai-evaluate-action.test.ts",
+    commit: "refactor-09-post-closure-evaluate-action",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "policy-evaluate",
+    contextPromptShape:
+      "Pre-flight verdict: can this action proceed against (optionally) this scope? Returns {allowed, policy, blockers, approvalRequired}. Composes getPolicy() with live scope resolvability.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§AI API § ai.evaluateAction. Composes /06's static policy matrix with live scope resolvability. Returns a single-verdict carrier agents branch on before calling the mutating path. Read-only; no audit emission.",
+};
+
+export function createEvaluateFamily(runtime: RuntimeApiHandle) {
+  const compiler = createScopeCompilerService(runtime);
+  return {
+    evaluateAction(input: EvaluateActionInput): EvaluateActionResult {
+      // @endStateApi — live-with-adapter. Composes /06's static policy
+      // matrix with live scope resolvability from the /08 compiler.
+      const policy = getAIActionPolicy(input.action);
+      const blockers: string[] = [];
+
+      if (policy.support === "blocked" || policy.support === "unsupported") {
+        blockers.push(`policy-refused:${policy.support}`);
+      }
+
+      if (input.scopeId !== undefined) {
+        const compiled = compiler.compileScopeById(input.scopeId);
+        if (!compiled) {
+          blockers.push(`scope-not-resolvable:${input.scopeId}`);
+        }
+      }
+
+      const approvalRequired =
+        policy.support === "confirmation-required" ||
+        policy.requirements.userConfirmation === true;
+
+      return {
+        action: input.action,
+        allowed: blockers.length === 0,
+        policy,
+        blockers: Object.freeze([...blockers]),
+        approvalRequired,
+      };
+    },
+  };
+}