@beyondwork/docx-react-component 1.0.66 → 1.0.69

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

@@ -0,0 +1,235 @@
+/**
+ * @endStateApi v3 — `ai.attach` family.
+ *
+ * attachExplanation (live-with-adapter) / createIssue (live-with-adapter).
+ *
+ * Both route through the Layer-08 compiler-service facade
+ * (`createScopeCompilerService`), which wraps Layer-06's
+ * `attachScopeMetadata` writer. Metadata persists as
+ * `WorkflowMetadataEntry` records with stable `metadataId` prefixes
+ * (`ai.explanation`, `ai.issue`).
+ *
+ * Coverage: /06's derived-scope resolver (2026-04-23, `1a3d127e`) lets
+ * both paths succeed on paragraph-like derived scopeIds (`para:*`,
+ * `heading:*`, `li:*`) in addition to overlay scopes — no overlay
+ * promotion step required. Non-paragraph-like derived scopeIds (`table:*`,
+ * `field:*`, comment-thread, revision) return `{attached: false,
+ * reason: "scope-not-resolvable:<id>"}` / `{created: false, reason}`
+ * — the broader prefix reflects §13c's two-stage resolution (overlay
+ * miss then derived-resolver miss); pre-§13c was `scope-not-in-overlay:`.
+ *
+ * Architecture A4 — every mutating function emits exactly one
+ * `ScopeActionAudit` on the `scope` telemetry channel. The facade does
+ * not own audit emission for metadata writes; this module does, via
+ * `_metadata-audit.ts`. `applyReplacementScope`'s audit emission stays
+ * inside /08's replacement pipeline. Together the three mutating
+ * functions (`applyReplacementScope`, `attachExplanation`, `createIssue`)
+ * carry exactly-one-audit-per-mutation coverage.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import { mockId } from "../_mocks.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+import { createScopeCompilerService } from "../../../runtime/scopes/index.ts";
+import {
+  captureScopeSnapshot,
+  emitScopeMetadataAudit,
+  snapshotDocumentHash,
+} from "./_metadata-audit.ts";
+
+export interface AttachExplanationInput {
+  readonly scopeId: string;
+  readonly explanation: string;
+}
+
+export interface AttachExplanationResult {
+  readonly explanationId: string;
+  readonly attached: boolean;
+  /**
+   * Present when `attached: false`. Mirrors the primitive's refusal
+   * reason (`scope-not-resolvable:<scopeId>` post-coord-06 §13c;
+   * pre-§13c: `scope-not-in-overlay:<scopeId>`). Restored in
+   * `cross-layer-coord-09.md §1.17` — symmetry with
+   * `CreateIssueResult.reason`.
+   */
+  readonly reason?: string;
+}
+
+export const attachExplanationMetadata: ApiV3FnMetadata = {
+  name: "ai.attachExplanation",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest: "test/runtime/scopes/attach-explanation.test.ts",
+    commit: "refactor-08-slice-6",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "scope card gains explanation chip",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "scope",
+    auditCategory: "explanation-attach",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§AI API § ai.attachExplanation. Adapter: routes through the Layer-08 compiler-service facade with metadataId=ai.explanation. /06's derived-scope resolver (§13c) now handles paragraph/heading/list-item derived scopeIds in addition to overlay scopes. Returns `attached:false` with a typed `reason` on non-paragraph-like derived scopeIds (table/field/comment-thread/revision) and on unresolvable ids. Emits one ScopeActionAudit per successful attachment on the `scope` telemetry channel (A4).",
+};
+
+export interface CreateIssueInput {
+  readonly scopeId: string;
+  readonly summary: string;
+  readonly severity?: "info" | "warning" | "error";
+}
+
+export interface CreateIssueResult {
+  readonly issueId: string;
+  readonly created: boolean;
+  readonly reason?: string;
+}
+
+export const createIssueMetadata: ApiV3FnMetadata = {
+  name: "ai.createIssue",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest: "test/runtime/scopes/create-issue.test.ts",
+    commit: "refactor-08-slice-6",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "warning-added",
+    expectedDelta: "issue rail shows new issue card",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "scope",
+    auditCategory: "issue-create",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§AI API § ai.createIssue. Adapter: routes through the Layer-08 compiler-service facade with metadataId=ai.issue; issues are metadata entries keyed by issueId carrying {summary, severity, status, createdAtUtc}. /06's derived-scope resolver (§13c) now handles paragraph/heading/list-item derived scopeIds in addition to overlay scopes. Returns `created:false` with a typed `reason` on non-paragraph-like derived scopeIds and on unresolvable ids. Emits one ScopeActionAudit per successful issue creation on the `scope` telemetry channel (A4).",
+};
+
+export function createAttachFamily(runtime: RuntimeApiHandle) {
+  const compiler = createScopeCompilerService(runtime);
+  return {
+    attachExplanation(input: AttachExplanationInput): AttachExplanationResult {
+      // @endStateApi — live-with-adapter (Slice 6). Routes through the
+      // Layer-08 compiler-service facade.
+      //
+      // A4 wiring: capture scope snapshot + document hash BEFORE the
+      // primitive runs (the scope can shift post-mutation if a same-
+      // session replacement just ran); on `attached: true` emit one
+      // `ScopeActionAudit` with `operation: "annotate"`. `attached:
+      // false` (scope-not-on-overlay) → no mutation → no audit.
+      const explanationId = mockId(
+        runtime.getSessionState().documentId,
+        `explanation-${input.scopeId}`,
+      );
+      const preScope = captureScopeSnapshot(runtime, input.scopeId);
+      const documentHashBefore = snapshotDocumentHash(runtime);
+      const primitiveResult = compiler.attachExplanation({
+        scopeId: input.scopeId,
+        explanation: input.explanation,
+        explanationId,
+      });
+      if (primitiveResult.attached && preScope) {
+        emitScopeMetadataAudit({
+          runtime,
+          actionId: attachExplanationMetadata.name,
+          scopeId: input.scopeId,
+          targetScopeSnapshot: preScope,
+          proposedContent: {
+            kind: "explanation",
+            payload: {
+              explanationId: primitiveResult.explanationId,
+              explanation: input.explanation,
+            },
+          },
+          compiledOperationKind: "metadata-attach-explanation",
+          compiledOperationSummary: `attach explanation ${primitiveResult.explanationId} to scope ${input.scopeId}`,
+          emittedAtUtc: new Date(0).toISOString(),
+          documentHashBefore,
+        });
+      }
+      emitUxResponse(runtime, {
+        apiFn: attachExplanationMetadata.name,
+        intent: attachExplanationMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: attachExplanationMetadata.uxIntent.expectedDelta,
+      });
+      return {
+        explanationId: primitiveResult.explanationId,
+        attached: primitiveResult.attached,
+        // §1.17 — surface primitive's reason on refusal for symmetry
+        // with CreateIssueResult. The primitive returns `reason` only
+        // when `attached: false`; passthrough preserves that contract.
+        ...(primitiveResult.attached
+          ? {}
+          : { reason: (primitiveResult as { reason?: string }).reason }),
+      };
+    },
+
+    createIssue(input: CreateIssueInput): CreateIssueResult {
+      // @endStateApi — live-with-adapter (Slice 6). Routes through the
+      // Layer-08 compiler-service facade.
+      //
+      // A4 wiring: same pattern as attachExplanation — pre-snapshot +
+      // primitive + audit on the happy path only.
+      const issueId = mockId(
+        runtime.getSessionState().documentId,
+        `issue-${input.scopeId}`,
+      );
+      const preScope = captureScopeSnapshot(runtime, input.scopeId);
+      const documentHashBefore = snapshotDocumentHash(runtime);
+      const primitiveResult = compiler.createIssue({
+        scopeId: input.scopeId,
+        summary: input.summary,
+        ...(input.severity ? { severity: input.severity } : {}),
+        issueId,
+      });
+      if (primitiveResult.created && preScope) {
+        emitScopeMetadataAudit({
+          runtime,
+          actionId: createIssueMetadata.name,
+          scopeId: input.scopeId,
+          targetScopeSnapshot: preScope,
+          proposedContent: {
+            kind: "issue",
+            payload: {
+              issueId: primitiveResult.issueId,
+              summary: input.summary,
+              ...(input.severity ? { severity: input.severity } : {}),
+            },
+          },
+          compiledOperationKind: "metadata-attach-issue",
+          compiledOperationSummary: `create issue ${primitiveResult.issueId} on scope ${input.scopeId}`,
+          emittedAtUtc: new Date(0).toISOString(),
+          documentHashBefore,
+        });
+      }
+      emitUxResponse(runtime, {
+        apiFn: createIssueMetadata.name,
+        intent: createIssueMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: createIssueMetadata.uxIntent.expectedDelta,
+      });
+      const out: CreateIssueResult = {
+        issueId: primitiveResult.issueId,
+        created: primitiveResult.created,
+        ...(primitiveResult.created ? {} : { reason: primitiveResult.reason }),
+      };
+      return out;
+    },
+  };
+}

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

@@ -0,0 +1,132 @@
+/**
+ * @endStateApi v3 — `ai.bundle` family.
+ *
+ * Slice 3 of refactor/08 graduated `getScopeBundle` from `mock` to
+ * `live-with-adapter`. Delegates to `compileScopeBundleById` from
+ * `src/runtime/scopes/`.
+ *
+ * Slice 1 of refactor/09 adds `getScope({handle}): SemanticScope | null` —
+ * the handle-shaped reader that surfaces the full compiled scope without
+ * its neighborhood + evidence. Architecture contract A3
+ * (scope-handle-first) + A9 (plain immutable values).
+ *
+ * The caller MUST pin `nowUtc` — we do not fall back to `new Date()` here,
+ * because a wall-clock `generatedAtUtc` makes `ScopeBundle` non-deterministic
+ * and violates S3 (identical runtime inputs → identical compiler output).
+ * Host wrappers supply a clock; tests supply a fixed string.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import {
+  createScopeCompilerService,
+  type ScopeHandle,
+  type ScopeBundle as RuntimeScopeBundle,
+  type SemanticScope,
+} from "../../../runtime/scopes/index.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+
+/**
+ * Handle-shaped input (architecture A3 — scope-handle-first targeting).
+ *
+ * Slice 1 of refactor/09 accepted a transitional `{scopeId} | {handle}`
+ * union; Slice 2 tightens to `{handle}` only. `resolveReference` is the
+ * canonical way to obtain a handle when a caller only has a bookmark
+ * name, offset, or scope id.
+ */
+export interface GetScopeBundleInput {
+  readonly handle: ScopeHandle;
+  /**
+   * ISO-8601 UTC timestamp to stamp into `ScopeBundle.generatedAtUtc`.
+   * Required — see the module docstring for the determinism rationale.
+   */
+  readonly nowUtc: string;
+}
+
+/** Re-export the runtime-side `ScopeBundle` so v3 consumers get the rich shape. */
+export type { RuntimeScopeBundle as ScopeBundle };
+
+export interface ScopeBundleNotFound {
+  readonly notFound: true;
+  readonly scopeId: string;
+  readonly reason: string;
+}
+
+export interface GetScopeInput {
+  readonly handle: ScopeHandle;
+}
+
+export const getScopeMetadata: ApiV3FnMetadata = {
+  name: "ai.getScope",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ai/ai-get-scope.test.ts",
+    commit: "refactor-09-slice-1",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "scope-read",
+    contextPromptShape:
+      "Full SemanticScope for a handle — handle + kind + content + formatting + layout + geometry + workflow + replaceability + audit.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§AI API § ai.getScope",
+};
+
+export const getScopeBundleMetadata: ApiV3FnMetadata = {
+  name: "ai.getScopeBundle",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest:
+      "test/runtime/scopes/bundle-paragraph.test.ts,test/runtime/scopes/bundle-clause-with-review.test.ts",
+    commit: "refactor-08-slice-3",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "scope-bundle",
+    contextPromptShape:
+      "Bundle content + formatting + layout + geometry + workflow + replaceability for prompt context.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§AI API § ai.getScopeBundle",
+};
+
+export function createBundleFamily(runtime: RuntimeApiHandle) {
+  const compiler = createScopeCompilerService(runtime);
+  return {
+    getScope(input: GetScopeInput): SemanticScope | null {
+      // @endStateApi — live-with-adapter. Routes through the compiler-
+      // service facade. Returns null when the scopeId does not enumerate
+      // (handle drift, caller error, marker-backed scope on a different
+      // story target, etc.).
+      const compiled = compiler.compileScopeById(input.handle.scopeId);
+      return compiled?.scope ?? null;
+    },
+
+    getScopeBundle(input: GetScopeBundleInput): RuntimeScopeBundle | ScopeBundleNotFound {
+      // @endStateApi — live-with-adapter. Routes through the compiler-
+      // service facade.
+      //
+      // Slice 2 tightened input to `{handle}` only — A3 scope-handle-first.
+      // Callers with only a scope id / bookmark / offset resolve through
+      // `ai.resolveReference` first.
+      const { scopeId } = input.handle;
+      const bundle = compiler.compileBundleById(scopeId, input.nowUtc);
+      if (!bundle) {
+        return {
+          notFound: true,
+          scopeId,
+          reason: "no scope with this id in canonical document or review store",
+        };
+      }
+      return bundle;
+    },
+  };
+}

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

@@ -0,0 +1,144 @@
+/**
+ * @endStateApi v3 — `ai.explain` family.
+ *
+ * explainFormatting — agent-facing formatting-provenance view for a run.
+ *
+ * Returns `{ effective, provenance, explanation }` where `effective` is the
+ * fully-cascaded formatting, `provenance` is the per-property source map
+ * (`direct` / `characterStyle` / `style` / `docDefaults` + `sourceId` for
+ * the style tiers), and `explanation` is a plain-text human-readable
+ * summary an agent can surface directly.
+ *
+ * Thin adapter over Layer-03's `FormattingContext.resolveRunWithProvenance`
+ * (shipped substrate, live on `runtime.formatting.resolveRunWithProvenance`).
+ * No new derivation — this function re-shapes the existing provenance
+ * record into an agent-prompt-friendly carrier.
+ *
+ * Cross-layer-coord history: filed by /03 §3 "L09 consume
+ * resolveRunWithProvenance" (2026-04-22). Closes that ask.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import {
+  createFormattingContext,
+  type EffectiveRunFormatting,
+  type RunProvenance,
+  type RunResolvedProperty,
+} from "../../../runtime/formatting/index.ts";
+import {
+  findParagraphByBlockId,
+  resolveDirectRunFormattingAtSegment,
+} from "../../../runtime/formatting/document-lookup.ts";
+
+export interface ExplainFormattingInput {
+  readonly blockId: string;
+  readonly runId: string;
+}
+
+export interface ExplainFormattingResult {
+  /** Fully-cascaded effective formatting for the run (direct → charStyle → paraStyle → docDefaults). */
+  readonly effective: EffectiveRunFormatting;
+  /** Per-property provenance map — which cascade tier contributed each value, and its sourceId where relevant. */
+  readonly provenance: {
+    readonly [K in keyof RunProvenance["properties"]]?: RunResolvedProperty;
+  };
+  /** Plain-text human-readable summary agents surface directly to users. */
+  readonly explanation: string;
+}
+
+/**
+ * Not-found record — distinct from a run with no populated formatting
+ * (which returns a valid result with empty `effective`).
+ */
+export interface ExplainFormattingNotFound {
+  readonly notFound: true;
+  readonly blockId: string;
+  readonly runId: string;
+  readonly reason: string;
+}
+
+export const explainFormattingMetadata: ApiV3FnMetadata = {
+  name: "ai.explainFormatting",
+  status: "live-with-adapter",
+  sourceLayer: "formatting-semantics",
+  liveEvidence: {
+    runnerTest:
+      "test/api/v3/ai/ai-explain-formatting.test.ts,test/runtime/formatting/provenance.test.ts",
+    commit: "refactor-09-slice-5",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "formatting-explain",
+    contextPromptShape:
+      "Explain why a run looks the way it does — effective formatting + per-property cascade source (direct / characterStyle / paragraphStyle / docDefaults) + plain-text summary.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§AI API § ai.explainFormatting. Adapter: re-shapes FormattingContext.resolveRunWithProvenance into an agent-friendly carrier. Closes cross-layer-coord-03.md §3 (L09 consume resolveRunWithProvenance).",
+};
+
+/**
+ * Build a plain-text summary from a provenance map. Keeps the output
+ * short (one line) and deterministic — property order fixed.
+ */
+function formatExplanation(provenance: RunProvenance["properties"]): string {
+  const lines: string[] = [];
+  const entries = [
+    ["bold", (provenance as { bold?: RunResolvedProperty }).bold],
+    ["italic", (provenance as { italic?: RunResolvedProperty }).italic],
+    ["fontFamily", (provenance as { fontFamily?: RunResolvedProperty }).fontFamily],
+    ["fontSize", (provenance as { fontSize?: RunResolvedProperty }).fontSize],
+    ["color", (provenance as { color?: RunResolvedProperty }).color],
+  ] as const;
+  for (const [name, record] of entries) {
+    if (!record) continue;
+    const value = String(record.value);
+    const sourceId = record.sourceId ? ` (${record.sourceId})` : "";
+    lines.push(`${name}=${value} from ${record.source}${sourceId}`);
+  }
+  return lines.length === 0
+    ? "no formatting properties resolved"
+    : lines.join("; ");
+}
+
+export function createExplainFamily(runtime: RuntimeApiHandle) {
+  return {
+    explainFormatting(
+      input: ExplainFormattingInput,
+    ): ExplainFormattingResult | ExplainFormattingNotFound {
+      // @endStateApi — live-with-adapter. Delegates to Layer-03's
+      // FormattingContext.resolveRunWithProvenance (same substrate as
+      // runtime.formatting.resolveRunWithProvenance); re-shapes the
+      // provenance record with an agent-facing `explanation` string.
+      const doc = runtime.getCanonicalDocument();
+      const foundPara = findParagraphByBlockId(doc, input.blockId);
+      if (!foundPara) {
+        return {
+          notFound: true,
+          blockId: input.blockId,
+          runId: input.runId,
+          reason: "no paragraph with this blockId in canonical document",
+        };
+      }
+      const direct = resolveDirectRunFormattingAtSegment(
+        foundPara.paragraph,
+        input.runId,
+      );
+      const ctx = createFormattingContext(doc);
+      const provenance = ctx.resolveRunWithProvenance({
+        paragraphStyleId: foundPara.paragraph.styleId,
+        characterStyleId: direct?.characterStyleId,
+        direct,
+      });
+      return {
+        effective: provenance.run,
+        provenance: provenance.properties,
+        explanation: formatExplanation(provenance.properties),
+      };
+    },
+  };
+}

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

@@ -0,0 +1,54 @@
+/**
+ * @endStateApi v3 — `ai.export` family.
+ *
+ * exportReviewedDocument — live (delegates to runtime.document.export).
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ExportDocxOptions, ExportResult } from "../../public-types.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+
+export const exportReviewedDocumentMetadata: ApiV3FnMetadata = {
+  name: "ai.exportReviewedDocument",
+  status: "live",
+  sourceLayer: "ai",
+  liveEvidence: {
+    runnerTest: "services/debug/lib/session-manager.test.ts",
+    probeScript: "services/debug/scripts/probe-channel-emissions.ts",
+    commit: "6aca0666",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "toast",
+    expectedDelta: "toast shows export bytes size + completion; filename reflects review posture",
+  },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "document-export-reviewed",
+    contextPromptShape: "Export the document with review artefacts applied; same bytes as runtime.document.export today.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§AI API § ai.exportReviewedDocument",
+};
+
+export function createExportFamily(runtime: RuntimeApiHandle) {
+  return {
+    async exportReviewedDocument(options?: ExportDocxOptions): Promise<ExportResult> {
+      // @endStateApi — live. Delegates to the live export path. Future review-
+      // posture filtering happens in Phase 5 (Apply replacement-scope lifecycle).
+      const result = await runtime.exportDocx(options);
+      emitUxResponse(runtime, {
+        apiFn: exportReviewedDocumentMetadata.name,
+        intent: exportReviewedDocumentMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: exportReviewedDocumentMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "toast", payload: { bytes: result.bytes?.byteLength ?? 0 } },
+      });
+      return result;
+    },
+  };
+}

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

@@ -0,0 +1,118 @@
+/**
+ * @endStateApi v3 — `ai.inspect` family.
+ *
+ * Slice 2 of refactor/08 graduated both functions from `partial` →
+ * `live-with-adapter`. Live path delegates to `src/runtime/scopes/` via
+ * an adapter that reads canonical + overlay from the runtime.
+ *
+ * The v3 surface stays a thin shim — semantic-scope compilation lives
+ * under `src/runtime/scopes/**` (layer 08), not here.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import {
+  createScopeCompilerService,
+  type SemanticScope,
+  type SemanticScopeKind,
+} from "../../../runtime/scopes/index.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+
+export interface InspectDocumentResult {
+  readonly documentId: string;
+  readonly scopeCount: number;
+  readonly pageCount?: number;
+  readonly semanticSummary: string;
+  readonly kindDistribution: Readonly<Partial<Record<SemanticScopeKind, number>>>;
+}
+
+export const inspectDocumentMetadata: ApiV3FnMetadata = {
+  name: "ai.inspectDocument",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest:
+      "test/runtime/scopes/compile-paragraph.test.ts,test/runtime/scopes/compile-table.test.ts,test/runtime/scopes/compile-clause.test.ts",
+    commit: "refactor-08-slice-2",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "document-inspect",
+    contextPromptShape:
+      "Summarize document by scope count + page count + semantic kind distribution.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§AI API § ai.inspectDocument",
+};
+
+export const listScopesMetadata: ApiV3FnMetadata = {
+  name: "ai.listScopes",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest:
+      "test/runtime/scopes/compile-paragraph.test.ts,test/runtime/scopes/compile-table.test.ts,test/runtime/scopes/compile-clause.test.ts",
+    commit: "refactor-08-slice-2",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "scope-list",
+    contextPromptShape:
+      "List scopes with scopeId + kind + semanticPath for agent selection.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference: "§AI API § ai.listScopes",
+};
+
+function buildKindDistribution(
+  scopes: readonly SemanticScope[],
+): Partial<Record<SemanticScopeKind, number>> {
+  const out: Partial<Record<SemanticScopeKind, number>> = {};
+  for (const scope of scopes) {
+    out[scope.kind] = (out[scope.kind] ?? 0) + 1;
+  }
+  return out;
+}
+
+export function createInspectFamily(runtime: RuntimeApiHandle) {
+  const compiler = createScopeCompilerService(runtime);
+  return {
+    inspectDocument(): InspectDocumentResult {
+      // @endStateApi — live-with-adapter. Routes through the Layer-08
+      // compiler-service facade (src/runtime/scopes/compiler-service.ts).
+      const state = runtime.getSessionState();
+      const scopes = compiler.compileAllScopes();
+      const kindDistribution = buildKindDistribution(scopes);
+      const summary =
+        scopes.length === 0
+          ? "empty document or no enumerable scopes"
+          : `${scopes.length} semantic scope(s) compiled across ${Object.keys(kindDistribution).length} kind(s)`;
+      return {
+        documentId: state.documentId,
+        scopeCount: scopes.length,
+        semanticSummary: summary,
+        kindDistribution,
+      };
+    },
+
+    listScopes(filter?: { readonly limit?: number; readonly kind?: SemanticScopeKind }) {
+      // @endStateApi — live-with-adapter. Routes through the compiler-
+      // service facade and applies filter/limit over the compiled scope
+      // list. Always return a fresh array so agent code that sorts /
+      // splices the result never leaks into the internal scope list.
+      const scopes = compiler.compileAllScopes();
+      const byKind = filter?.kind
+        ? scopes.filter((scope) => scope.kind === filter.kind)
+        : scopes.slice();
+      if (typeof filter?.limit === "number") {
+        return byKind.slice(0, filter.limit);
+      }
+      return byKind;
+    },
+  };
+}