@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/api/session-state.ts

@@ -39,6 +39,8 @@ export function editorSessionStateFromPersistedSnapshot(
     sourcePackage: snapshot.sourcePackage,
     workflowOverlay: snapshot.workflowOverlay,
     workflowMetadata: snapshot.workflowMetadata,
+    visibilityPolicies: snapshot.visibilityPolicies,
+    markupModePolicy: snapshot.markupModePolicy,
   });
 }
 
@@ -64,6 +66,8 @@ export function persistedSnapshotFromEditorSessionState(
     sourcePackage: sessionState.sourcePackage,
     workflowOverlay: sessionState.workflowOverlay,
     workflowMetadata: sessionState.workflowMetadata,
+    visibilityPolicies: sessionState.visibilityPolicies,
+    markupModePolicy: sessionState.markupModePolicy,
   });
 }
 

package/src/api/v3/README.md

@@ -0,0 +1,91 @@
+# `src/api/v3/` — End-state public API surface
+
+> **@endStateApi v3** — the canonical Beyond Work build-team contract.
+> Do NOT treat this as a rename of `WordReviewEditorRef`. It is a
+> separate, additive API that mirrors the target architecture in
+> [`docs/architecture/00-overview.md`](../../../docs/architecture/00-overview.md)
+> (Runtime API + AI API split per §9 + §10).
+
+## What this directory is
+
+- The shape every new Beyond Work consumer builds against, today.
+- Each function carries `ApiV3FnMetadata` declaring
+  `status: "mock" | "partial" | "live-with-adapter" | "live"`, its
+  target layer, UX intent, and agent metadata.
+- Every UX-visible function emits one `UxResponse` event on the
+  `api` telemetry channel per invocation so the future debug UX
+  (Phase Q) and agent-facing audit can observe it identically in
+  mock and live modes.
+
+### Four-status taxonomy (Phase P')
+
+| Status | Meaning |
+|---|---|
+| `mock` | No live path attempted; returns a `mockPayload(...)` / `mockArray(...)` carrying `__mock: true`. |
+| `partial` | Live path attempted; falls back to a mock-shaped payload when the runtime cannot satisfy it. `mockShape` is required. |
+| `live-with-adapter` | Delegates to a real runtime/facet method through a nontrivial adapter or composition layer. `mockShape` optional. |
+| `live` | Direct delegation to a single runtime/facet method. `mockShape` is forbidden. |
+
+The current distribution (as reported by the authoritative
+`test/runtime/debug/api-contract.test.ts` runner) is `9 live / 18
+live-with-adapter / 1 partial / 7 mock / 35 total`. See the Changelog
+in [`docs/reference/public-api.md`](../../../docs/reference/public-api.md)
+for the latest entry.
+
+## What this directory is NOT
+
+- NOT a re-export of the existing `WordReviewEditorRef`. The two CI
+  guards `scripts/ci-check-api-v3-no-ref-reexport.mjs` and
+  `scripts/ci-check-api-v3-metadata.mjs` enforce this. Adding a
+  convenience re-export of a ref method trips the guard.
+- NOT the place for internal runtime refactoring (`src/session/`,
+  `src/runtime/formatting/`, etc.). That work lands behind this
+  surface — v3 stays stable while internals move.
+- NOT a sandbox. `status: "live"` functions MUST parity-match the
+  underlying runtime behavior (asserted in per-family tests).
+
+## Consumers
+
+- **Beyond Work build team** (canonical). Import via
+  `import { createApiV3 } from "@beyondwork/docx-react-component/api/v3"`.
+- **Debug UX (Phase Q)**. Uses `UxResponse` events to render mock-or-live
+  visualizations.
+- **Phase D runners** (Layer-level validators). Use `createApiV3` as the
+  single entry point so runners don't depend on internal runtime shape.
+
+## Graduating a function's status
+
+The intended progression is `mock → partial → live-with-adapter → live`.
+Skipping a stage is allowed when justified, but each flip requires
+evidence:
+
+1. Implement the live path (delegate to the appropriate runtime
+   facet or layer extractor). For `live-with-adapter`, write the
+   adapter/composition in the family file; for `live`, the body
+   must be a single delegation call.
+2. Add a validator log entry under `services/debug/docs/` with the
+   new evidence.
+3. Update the function's `<fnName>Metadata.liveEvidence` field to
+   point at the log + the commit SHA; update `mockShape` per the
+   taxonomy rules above (required for `mock` and `partial`, optional
+   for `live-with-adapter`, forbidden for `live`).
+4. Update the per-family test's parity assertion and the matching
+   inline `// @endStateApi — <status>.` comment on the function
+   body so the status-drift canary stays green.
+
+Silent flips — changing `status` without updating `liveEvidence` or
+the inline annotation — are a review-time reject.
+
+## Canonical reference doc
+
+[`docs/reference/public-api.md`](../../../docs/reference/public-api.md).
+That's the URL the BW team bookmarks. This README is the in-repo
+maintainer-facing companion.
+
+## Phase Q (debug UX refactor) dependency
+
+Phase Q ships a runtime-embedded debug UX (`src/ui-tailwind/debug/**`)
+that subscribes to the `UxResponse` event stream emitted from this
+directory. Phase Q does NOT re-import the existing harness debug
+panel — it renders against `UxResponse` + `runtime.debug.getSnapshot`
+directly. See the Phase P plan for the full Phase Q spec.

package/src/api/v3/_create.ts

@@ -0,0 +1,146 @@
+/**
+ * @endStateApi v3 — `createApiV3(runtime)` entry point.
+ *
+ * Single binding point. Every v3 family is a record of functions bound to
+ * the runtime supplied here. Consumers get one value with typed sub-namespaces:
+ *
+ *   const api = createApiV3(runtime);
+ *   await api.runtime.review.getComments();
+ *   await api.ai.inspectDocument();
+ *
+ * No other import path is supported. The family modules under `runtime/**`
+ * and `ai/**` export `createXxxFamily(runtime)` factories; this file wires
+ * them. The resulting object is frozen to prevent monkey-patching.
+ */
+
+import type { RuntimeApiHandle } from "./_runtime-handle.ts";
+
+import { createDocumentFamily } from "./runtime/document.ts";
+import { createContentFamily } from "./runtime/content.ts";
+import { createReviewFamily } from "./runtime/review.ts";
+import { createWorkflowFamily } from "./runtime/workflow.ts";
+import { createLayoutFamily } from "./runtime/layout.ts";
+import { createGeometryFamily } from "./runtime/geometry.ts";
+import { createCollabFamily } from "./runtime/collab.ts";
+import { createFormattingFamily } from "./runtime/formatting.ts";
+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 { createInspectFamily } from "./ai/inspect.ts";
+import { createResolveFamily } from "./ai/resolve.ts";
+import { createBundleFamily } from "./ai/bundle.ts";
+import { createReplacementFamily } from "./ai/replacement.ts";
+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 { createUiApi } from "./ui/_create.ts";
+import type { ApiV3Ui, UiControllerFactory } from "./ui/_types.ts";
+
+/**
+ * @endStateApi
+ * End-state v3 API surface. See `docs/reference/public-api.md`.
+ *
+ * Shape mirrors `docs/architecture/00-overview.md §Runtime API vs AI API`:
+ * runtime.* is sub-grouped (document/content/review/workflow/layout/geometry);
+ * ai.* is intentionally flat (inspectDocument / resolveReference / etc.) so
+ * agents call them as single-level tools without sub-namespace stitching.
+ */
+export type ApiV3Runtime = {
+  readonly document: ReturnType<typeof createDocumentFamily>;
+  readonly content: ReturnType<typeof createContentFamily>;
+  readonly review: ReturnType<typeof createReviewFamily>;
+  readonly workflow: ReturnType<typeof createWorkflowFamily>;
+  readonly layout: ReturnType<typeof createLayoutFamily>;
+  readonly geometry: ReturnType<typeof createGeometryFamily>;
+  readonly collab: ReturnType<typeof createCollabFamily>;
+  readonly formatting: ReturnType<typeof createFormattingFamily>;
+  readonly clipboard: ReturnType<typeof createClipboardFamily>;
+  readonly chart: ReturnType<typeof createChartFamily>;
+  readonly search: ReturnType<typeof createSearchFamily>;
+  readonly table: ReturnType<typeof createTableFamily>;
+};
+
+export type ApiV3Ai = ReturnType<typeof createInspectFamily>
+  & ReturnType<typeof createResolveFamily>
+  & ReturnType<typeof createBundleFamily>
+  & ReturnType<typeof createReplacementFamily>
+  & ReturnType<typeof createAttachFamily>
+  & ReturnType<typeof createExportFamily>
+  & ReturnType<typeof createExplainFamily>
+  & ReturnType<typeof createPolicyFamily>;
+
+export interface ApiV3 {
+  readonly runtime: ApiV3Runtime;
+  readonly ai: ApiV3Ai;
+  /**
+   * UI API namespace. Present iff the caller passed
+   * `createApiV3(handle, { ui: factory })`. Hosts that do not mount a
+   * React surface (services/debug, headless tests, stateless agents)
+   * omit the factory and get `{ runtime, ai }` only.
+   */
+  readonly ui?: ApiV3Ui;
+}
+
+/**
+ * @endStateApi
+ * Optional construction options. Currently only `ui` — a
+ * `UiControllerFactory` that the UI API consumes to wire mounted-surface
+ * dispatch + subscription hooks. Additive; hosts that only need runtime
+ * + AI drop the options argument entirely.
+ *
+ * Per the staircase in `docs/plans/refactor-master-plan.md §2`:
+ *   /07 Slice 1 (RuntimeApiHandle) → /10 Slice 1 (src/api/v3/ui/**) →
+ *   /07 Slice 2 (this extension).
+ */
+export interface CreateApiV3Opts {
+  readonly ui?: UiControllerFactory;
+}
+
+/**
+ * @endStateApi
+ * Single entry point. Returns a frozen `ApiV3` bound to the handle. Back-
+ * compat: `createApiV3(handle)` still returns `{ runtime, ai }` without a
+ * `ui` property so existing callers (services/debug, headless drivers)
+ * stay green.
+ */
+export function createApiV3(handle: RuntimeApiHandle, opts?: CreateApiV3Opts): ApiV3 {
+  const ai: ApiV3Ai = {
+    ...createInspectFamily(handle),
+    ...createResolveFamily(handle),
+    ...createBundleFamily(handle),
+    ...createReplacementFamily(handle),
+    ...createAttachFamily(handle),
+    ...createExportFamily(handle),
+    ...createExplainFamily(handle),
+    ...createPolicyFamily(handle),
+  };
+  const runtime: ApiV3Runtime = {
+    document: createDocumentFamily(handle),
+    content: createContentFamily(handle),
+    review: createReviewFamily(handle),
+    workflow: createWorkflowFamily(handle),
+    layout: createLayoutFamily(handle),
+    geometry: createGeometryFamily(handle),
+    collab: createCollabFamily(handle),
+    formatting: createFormattingFamily(handle),
+    clipboard: createClipboardFamily(handle),
+    chart: createChartFamily(handle),
+    search: createSearchFamily(handle),
+    table: createTableFamily(handle),
+  };
+  // Construct the UI namespace only when a factory is supplied.
+  // `ui` remains `undefined` otherwise — the shape in ApiV3 is optional
+  // so consumer snapshot tests that already assert `{ runtime, ai }`
+  // continue to match.
+  const ui: ApiV3Ui | undefined = opts?.ui ? createUiApi(handle, opts.ui) : undefined;
+
+  const api: ApiV3 = ui ? { runtime, ai, ui } : { runtime, ai };
+  Object.freeze(api.runtime);
+  Object.freeze(api.ai);
+  // api.ui is already frozen by createUiApi.
+  return Object.freeze(api);
+}

package/src/api/v3/_layer-metadata.ts

@@ -0,0 +1,362 @@
+/**
+ * @endStateApi v3 — metadata primitives. See docs/reference/public-api.md.
+ *
+ * Every exported v3 function has a sibling `<fnName>Metadata: ApiV3FnMetadata`
+ * export. The two CI guards under `scripts/ci-check-api-v3-*.mjs` enforce this.
+ * Replacing a mock with a live implementation requires updating `liveEvidence`
+ * with a validator log + commit SHA.
+ */
+
+/**
+ * @endStateApi
+ * 4-status discriminator (Phase P' taxonomy).
+ *
+ * - `mock` — no valid runtime-backed path yet; deterministic mock only.
+ * - `partial` — some behavior is real and some is still mocked (e.g. read
+ *   path live, write path mocked; or only a subset of the contract
+ *   satisfied).
+ * - `live-with-adapter` — a valid shipped runtime/facet/debug candidate
+ *   exists and the contract is semantically supportable now, but only
+ *   through a nontrivial adapter / rebinding / composition layer rather
+ *   than direct 1:1 delegation. Stays visible in metadata until the
+ *   adapter is promoted to a first-class surface or replaced by a
+ *   cleaner underlying contract.
+ * - `live` — direct delegation to a shipped runtime contract (no
+ *   meaningful adapter debt).
+ */
+export type ApiStatus = "mock" | "partial" | "live-with-adapter" | "live";
+
+/**
+ * @endStateApi
+ * 11-layer taxonomy from `docs/architecture/00-overview.md § Target End-State
+ * Stack`. Each v3 function declares which layer it belongs to so future
+ * layer-extraction refactors can move the implementation behind the surface
+ * without breaking consumers.
+ */
+export type SourceLayer =
+  | "beyond-work-substrate"
+  | "package-session"
+  | "canonical"
+  | "formatting-semantics"
+  | "layout-semantics"
+  | "geometry-projection"
+  | "workflow-review"
+  | "runtime-core"
+  | "semantic-scope-compiler"
+  | "ai"
+  | "presentation";
+
+/**
+ * @endStateApi
+ * Pointers to the evidence that backs a `live` or `partial` claim. At least
+ * one of these fields is required for a non-mock function; mock functions
+ * leave this undefined.
+ */
+export interface LiveEvidence {
+  readonly validatorLog?: string;
+  readonly runnerTest?: string;
+  readonly probeScript?: string;
+  readonly commit?: string;
+}
+
+/**
+ * @endStateApi
+ * Shape declaration for mock-returning functions. Every mock payload carries
+ * `__mock: true` so consumer tests can snapshot against it without
+ * accidentally depending on mock-specific fields in production code.
+ */
+export interface MockShape {
+  readonly deterministic: boolean;
+  readonly seededFrom?: "documentId" | "hash" | "fixed" | "counter";
+  readonly shapeDescription: string;
+  readonly carriesMockFlag: true;
+}
+
+/**
+ * @endStateApi
+ * UX expectation. Functions with `uiVisible: true` MUST emit exactly one
+ * UxResponse event on the `api` channel per invocation. Asserted in tests.
+ */
+export interface UxIntent {
+  readonly uiVisible: boolean;
+  readonly expectsUxResponse?:
+    | "toast"
+    | "overlay"
+    | "inline-change"
+    | "surface-refresh"
+    | "selection-change"
+    | "warning-added"
+    | "scope-created"
+    | "none";
+  readonly expectedDelta?: string;
+}
+
+/**
+ * @endStateApi
+ * Agent-facing metadata. Drives prompt-context inclusion, audit categorization,
+ * and policy hinting in the future Beyond Work agent surface.
+ */
+export interface AgentMetadata {
+  readonly readOrMutate: "read" | "mutate" | "compound";
+  readonly boundedScope?: "document" | "scope" | "selection" | "session";
+  readonly auditCategory?: string;
+  readonly policyHints?: readonly string[];
+  readonly contextPromptShape?: string;
+}
+
+/**
+ * @endStateApi
+ * Shape contract for UI-API subscription-style channels. When a
+ * `bidirectional: true` function produces an ongoing stream rather
+ * than a single request/response (e.g. `ui.viewport.subscribe`), its
+ * metadata carries this record so consumers can reason about the
+ * payload and coalescing discipline without reading the implementation.
+ *
+ * - `eventType` — the `ux.response.<fn>.subscribed` event emitted once
+ *   per subscribe call (the seam acknowledgement) AND the ongoing
+ *   event type the bind-side pushes per coalesced tick.
+ * - `payloadType` — a human-readable name for the payload shape
+ *   (matches an exported TS type name like `"ViewportState"`).
+ * - `coalescing` — how the bind-side batches upstream events before
+ *   firing the listener. `"raf"` is the default for viewport /
+ *   overlay channels; `"microtask"` for state-store-backed posture;
+ *   `"immediate"` only when the upstream already throttles.
+ */
+export interface SubscriptionShape {
+  readonly eventType: string;
+  readonly payloadType: string;
+  readonly coalescing: "raf" | "microtask" | "immediate";
+}
+
+/**
+ * @endStateApi
+ * Complete metadata record. `liveEvidence` is required when `status !==
+ * "mock"`; `mockShape` is required when `status !== "live"`. A function can
+ * be both (partial: both live and mock in different paths).
+ *
+ * `bidirectional` + `subscriptionShape` are UI-API specific fields added
+ * by refactor/07 Slice 2. A function is `bidirectional: true` when it
+ * carries data across the runtime ↔ UI seam in both directions — either
+ * as a dispatch/echo pair (`ui.surface.setSelection` requests, runtime
+ * emits `selection.changed`) or as a subscribe/stream pair (the
+ * subscribe call establishes the channel, the runtime pushes events).
+ * The invariant asserted by `validateApiV3Metadata` is:
+ *   bidirectional: true  ⇒  uxIntent.uiVisible: true
+ *                            ∧ (dispatch form:    expectsUxResponse != "none")
+ *                               ∨ (stream  form:    subscriptionShape present)
+ * Dispatch-form functions (no `subscriptionShape`) must emit exactly one
+ * `ux.response.<fn>` event per invocation; stream-form functions
+ * (`subscriptionShape` present) emit exactly one
+ * `ux.response.<fn>.subscribed` event on the establishing call, then
+ * deliver events through the subscription.
+ */
+/**
+ * @endStateApi
+ * Three-way state model classifier (per `docs/architecture/00-overview.md §9.1`
+ * + `07-runtime-api.md §R9`).
+ *
+ * - `A-canonical` — document-authored state. Lives in the canonical
+ *   document or its overlay; persists across sessions; broadcasts via
+ *   CRDT (Yjs). Examples: scope metadata, comments, tracked changes.
+ * - `B-session` — session-shared transient state. Present for the
+ *   duration of a session, shared across tabs/peers in the same session
+ *   via Awareness; does not persist beyond the session. Examples:
+ *   presence, posture, cursor position.
+ * - `C-local` — local view preference. Never leaves the user's tab.
+ *   Does not persist in the document or the session. Examples: UI
+ *   overlay visibility, chrome posture, viewport scroll.
+ */
+export type StateClass = "A-canonical" | "B-session" | "C-local";
+
+/**
+ * @endStateApi
+ * Persistence target for a function's effect.
+ *
+ * - `canonical` — write lands in the canonical document structure
+ *   (class-A mutation that rides a scope-scoped command).
+ * - `customXml` — write lands in the `bw:*` customXml overlay parts
+ *   (class-A workflow mutation — scopes, metadata, visibility policy).
+ * - `none` — function does not persist (reads, local-view toggles,
+ *   transient session-shared broadcasts).
+ */
+export type PersistsTo = "canonical" | "customXml" | "none";
+
+/**
+ * @endStateApi
+ * Transport for class-A or class-B broadcasts.
+ *
+ * - `crdt` — Yjs document broadcast. Eventually-consistent with
+ *   deterministic merge. Used by class-A mutations.
+ * - `awareness` — Y.Awareness ephemeral broadcast. Last-writer-wins,
+ *   bounded per-peer. Used by class-B session-shared state.
+ *
+ * Omit for class-C (local-only) functions.
+ */
+export type BroadcastsVia = "crdt" | "awareness";
+
+export interface ApiV3FnMetadata {
+  readonly name: string;
+  readonly status: ApiStatus;
+  readonly sourceLayer: SourceLayer;
+  readonly liveEvidence?: LiveEvidence;
+  readonly mockShape?: MockShape;
+  readonly uxIntent: UxIntent;
+  readonly agentMetadata: AgentMetadata;
+  readonly rwdReference?: string;
+  readonly bidirectional?: boolean;
+  readonly subscriptionShape?: SubscriptionShape;
+  /**
+   * @endStateApi
+   * Three-way state class (§R9 / §9.1). Required on every metadata
+   * record. CI-guard-enforced with namespace-class coherence rules:
+   *
+   * - `ui.*` → `C-local`
+   * - `runtime.collab.*` → `B-session`
+   * - `runtime.workflow.*` → `A-canonical`
+   * - Other `runtime.*` → `A-canonical` (per namespace rules below)
+   * - `ai.*` → follows the runtime function it delegates to
+   */
+  readonly stateClass: StateClass;
+  /**
+   * @endStateApi
+   * Where a mutation's effect lands. Required on every metadata
+   * record. Rules:
+   *
+   * - `C-local` ⇒ `"none"`
+   * - `B-session` ⇒ `"none"`
+   * - `A-canonical` + read ⇒ `"none"`
+   * - `A-canonical` + runtime.workflow mutate ⇒ `"customXml"`
+   * - `A-canonical` + other runtime mutate ⇒ `"canonical"`
+   */
+  readonly persistsTo: PersistsTo;
+  /**
+   * @endStateApi
+   * Broadcast transport. Required for class-B and for class-A
+   * mutations; forbidden for class-C.
+   *
+   * - `B-session` ⇒ `"awareness"`
+   * - `A-canonical` + runtime.workflow mutate ⇒ `"crdt"`
+   * - `A-canonical` + other ⇒ optional (`"crdt"` when the write
+   *   broadcasts to peers; omit when it's purely local/read)
+   * - `C-local` ⇒ omit
+   */
+  readonly broadcastsVia?: BroadcastsVia;
+}
+
+/**
+ * @endStateApi
+ * Marker type every mock payload uses. Consumer code can narrow on
+ * `__mock: true` to explicitly branch test doubles vs. real responses.
+ */
+export interface MockPayload {
+  readonly __mock: true;
+  readonly reason: string;
+  readonly shape: string;
+}
+
+/**
+ * @endStateApi
+ * Validate a metadata record. Used by CI guards + runtime tests. Returns
+ * null if valid; returns a human-readable error string otherwise.
+ *
+ * Contract (intentional asymmetry — do not "tighten"):
+ * - `liveEvidence` is required whenever status ≠ `mock` (live,
+ *   live-with-adapter, partial all need evidence).
+ * - `mockShape` is required only for `mock` or `partial` — adapter-
+ *   backed functions with a fallback branch SHOULD declare `mockShape`
+ *   for the fallback, but bare `live-with-adapter` functions that
+ *   return null instead of a mock-flagged payload are valid without it.
+ *   `live` functions never carry `mockShape`.
+ */
+export function validateApiV3Metadata(m: ApiV3FnMetadata): string | null {
+  if (!m.name || typeof m.name !== "string") return "missing name";
+  if (!m.status) return "missing status";
+  if (!m.sourceLayer) return "missing sourceLayer";
+  if (!m.uxIntent) return "missing uxIntent";
+  if (typeof m.uxIntent.uiVisible !== "boolean") return "uxIntent.uiVisible must be boolean";
+  if (!m.agentMetadata) return "missing agentMetadata";
+  if (!m.agentMetadata.readOrMutate) return "missing agentMetadata.readOrMutate";
+  if (m.status !== "mock" && !m.liveEvidence) {
+    return `status "${m.status}" requires liveEvidence`;
+  }
+  const mockShapeRequired = m.status === "mock" || m.status === "partial";
+  if (mockShapeRequired && !m.mockShape) {
+    return `status "${m.status}" requires mockShape`;
+  }
+  if (m.mockShape && m.mockShape.carriesMockFlag !== true) {
+    return "mockShape.carriesMockFlag must be true";
+  }
+  if (m.bidirectional === true) {
+    if (m.uxIntent.uiVisible !== true) {
+      return "bidirectional: true requires uxIntent.uiVisible: true";
+    }
+    const hasStream = !!m.subscriptionShape;
+    const hasDispatch =
+      typeof m.uxIntent.expectsUxResponse === "string" &&
+      m.uxIntent.expectsUxResponse !== "none";
+    if (!hasStream && !hasDispatch) {
+      return (
+        "bidirectional: true requires either subscriptionShape (stream form) " +
+        "or uxIntent.expectsUxResponse != 'none' (dispatch form)"
+      );
+    }
+  }
+  if (m.subscriptionShape) {
+    const s = m.subscriptionShape;
+    if (!s.eventType || typeof s.eventType !== "string") {
+      return "subscriptionShape.eventType must be a non-empty string";
+    }
+    if (!s.payloadType || typeof s.payloadType !== "string") {
+      return "subscriptionShape.payloadType must be a non-empty string";
+    }
+    if (s.coalescing !== "raf" && s.coalescing !== "microtask" && s.coalescing !== "immediate") {
+      return "subscriptionShape.coalescing must be 'raf' | 'microtask' | 'immediate'";
+    }
+  }
+  // Three-way state model checks (§R9). `stateClass` describes where the
+  // function's state LIVES; `persistsTo` and `broadcastsVia` describe the
+  // persistence home + broadcast transport of that state class (not the
+  // per-call effect). Reads and mutations of the same class share the same
+  // values. CI guard `scripts/ci-check-api-v3-metadata.mjs` runs the
+  // namespace-coherence rules (which names must declare which classes)
+  // over the file AST; this validator enforces the shape invariants that
+  // are independent of the function's name.
+  if (m.stateClass !== "A-canonical" && m.stateClass !== "B-session" && m.stateClass !== "C-local") {
+    return `stateClass must be "A-canonical" | "B-session" | "C-local"; got ${JSON.stringify(m.stateClass)}`;
+  }
+  if (m.persistsTo !== "canonical" && m.persistsTo !== "customXml" && m.persistsTo !== "none") {
+    return `persistsTo must be "canonical" | "customXml" | "none"; got ${JSON.stringify(m.persistsTo)}`;
+  }
+  if (m.broadcastsVia !== undefined && m.broadcastsVia !== "crdt" && m.broadcastsVia !== "awareness") {
+    return `broadcastsVia must be "crdt" | "awareness" (or omitted); got ${JSON.stringify(m.broadcastsVia)}`;
+  }
+  // Class-C: local-only. Never persists, never broadcasts.
+  if (m.stateClass === "C-local") {
+    if (m.persistsTo !== "none") {
+      return `stateClass "C-local" requires persistsTo "none"; got ${m.persistsTo}`;
+    }
+    if (m.broadcastsVia !== undefined) {
+      return `stateClass "C-local" must omit broadcastsVia; got ${m.broadcastsVia}`;
+    }
+  }
+  // Class-B: session-shared via awareness. Does not persist.
+  if (m.stateClass === "B-session") {
+    if (m.persistsTo !== "none") {
+      return `stateClass "B-session" requires persistsTo "none"; got ${m.persistsTo}`;
+    }
+    if (m.broadcastsVia !== "awareness") {
+      return `stateClass "B-session" requires broadcastsVia "awareness"; got ${m.broadcastsVia}`;
+    }
+  }
+  // Class-A: document-authored. Persists canonical or customXml; may
+  // broadcast crdt (required for workflow overlay writes).
+  if (m.stateClass === "A-canonical") {
+    if (m.persistsTo === "none") {
+      return `stateClass "A-canonical" ${m.name} must persist (canonical or customXml); got "none"`;
+    }
+    if (m.broadcastsVia === "awareness") {
+      return `stateClass "A-canonical" cannot broadcast via "awareness" (class-B transport); ${m.name}`;
+    }
+  }
+  return null;
+}