@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/api/v3/_mocks.ts

@@ -0,0 +1,84 @@
+/**
+ * @endStateApi v3 — deterministic mock factories.
+ *
+ * Every mock payload carries `__mock: true`. Mocks are seeded from stable
+ * inputs (documentId, sha256, or a fixed counter) so BW consumer tests
+ * snapshot against deterministic shapes. Nothing here uses randomness.
+ */
+
+import type { MockPayload } from "./_layer-metadata.ts";
+
+/**
+ * @endStateApi
+ * Tag a payload as a mock. Called by every mock-returning v3 function.
+ *
+ * Body is spread FIRST, then the markers — this guarantees that even if a
+ * caller accidentally passes a body with an `__mock`/`reason`/`shape` key,
+ * the markers win and the mock flag is never lost.
+ */
+export function mockPayload<T extends object>(
+  reason: string,
+  shape: string,
+  body: T,
+): T & MockPayload {
+  return {
+    ...body,
+    __mock: true,
+    reason,
+    shape,
+  };
+}
+
+/**
+ * @endStateApi
+ * Tag an ARRAY payload as a mock. `mockPayload` uses object spread which
+ * collapses arrays to plain objects (loses Array-ness). Use this for
+ * functions whose return type is `ReadonlyArray<T>` — it attaches the
+ * markers as non-indexed properties so `Array.isArray` still returns true
+ * AND `isMock` narrows correctly.
+ */
+export function mockArray<T>(
+  reason: string,
+  shape: string,
+  items: readonly T[],
+): readonly T[] & MockPayload {
+  const arr = items.slice() as T[];
+  return Object.assign(arr, {
+    __mock: true as const,
+    reason,
+    shape,
+  }) as readonly T[] & MockPayload;
+}
+
+/**
+ * @endStateApi
+ * Derive a stable string from a seed + name. Used where a mock needs an
+ * ID-shaped value (e.g. scopeId for a mock createScope call).
+ */
+export function mockId(seed: string, name: string): string {
+  // Simple deterministic mix — not cryptographic; just stable across runs.
+  let h = 0;
+  const input = `${seed}::${name}`;
+  for (let i = 0; i < input.length; i += 1) {
+    h = (h * 31 + input.charCodeAt(i)) | 0;
+  }
+  // `h >>> 0` coerces the 32-bit signed int to unsigned so base36 never
+  // produces a negative-prefixed string (edge case: h === -2^31 where
+  // Math.abs would still return negative).
+  const hex = (h >>> 0).toString(36).padStart(8, "0");
+  return `mock-${name}-${hex}`;
+}
+
+/**
+ * @endStateApi
+ * Return `true` iff the argument carries the mock flag. Consumer tests
+ * can narrow via this guard: `if (isMock(result)) { ... }`.
+ */
+export function isMock(value: unknown): value is MockPayload {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __mock?: unknown }).__mock === true
+  );
+}
+

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

@@ -0,0 +1,162 @@
+/**
+ * @endStateApi v3 — `RuntimeApiHandle`.
+ *
+ * The narrow interface v3 family modules type against. It enumerates the
+ * exact runtime surface v3 reads — nothing more. Family modules accept a
+ * `RuntimeApiHandle` instead of a full `DocumentRuntime`, which:
+ *
+ *   1. Removes the `(runtime as unknown as { ... })` casts that previously
+ *      asserted facet shape from inside each family module.
+ *   2. Enables headless callers (tests, debug harness, stateless services)
+ *      to satisfy the v3 API with a minimal stub — no full runtime needed.
+ *   3. Makes the v3 dependency surface auditable: any v3 code that reaches
+ *      a method not on this interface is a compile error.
+ *
+ * The interface is defined as `Pick<DocumentRuntime, ...>` so the member
+ * types stay in lockstep with the authoritative runtime interface. If a
+ * runtime method signature changes, v3 breaks at the consumption site
+ * rather than silently drifting.
+ *
+ * Geometry note: `handle.geometry` is the `GeometryFacet` constructed by
+ * `document-runtime.ts` against the shared render kernel. v3's
+ * `runtime.geometry` family reads through `handle.geometry` — the prior
+ * "reach geometry through `handle.layout`" shim was removed in the
+ * refactor/05 adversarial-closure pass once the runtime exposed the facet
+ * directly.
+ */
+
+import type { DocumentRuntime } from "../../runtime/document-runtime.ts";
+import type { CollabSession } from "../../runtime/collab-session.ts";
+
+/**
+ * @endStateApi
+ * Narrow runtime surface consumed by v3 family modules. Structurally a
+ * subset of `DocumentRuntime`; any `DocumentRuntime` satisfies it.
+ *
+ * Optional members (declared via intersection after the Pick) expose
+ * surfaces the runtime does not own directly but hosts can wire in —
+ * `collabSession` is the first such member, letting v3's
+ * `runtime.collab.*` family graduate its live path when hosts supply it
+ * and fall back to deterministic mocks when they don't.
+ */
+export type RuntimeApiHandle = Pick<
+  DocumentRuntime,
+  // Session + export (runtime.document family)
+  | "getSessionState"
+  | "exportDocx"
+  | "getCompatibilityReport"
+  | "getWarnings"
+  | "getRenderSnapshot"
+  // Canonical document read (ai.inspect + ai.bundle + ai.resolve families,
+  // added in refactor/08 Slice 2/3 graduations)
+  | "getCanonicalDocument"
+  // Content search + selection (runtime.content + ai.bundle families)
+  | "findAllText"
+  // Review (runtime.review family)
+  | "getReviewWorkSnapshot"
+  | "acceptChange"
+  | "resolveComment"
+  // Workflow (runtime.workflow + ai.inspect families)
+  | "queryScopes"
+  | "getWorkflowMarkupSnapshot"
+  | "getInteractionGuardSnapshot"
+  | "getWorkflowOverlay"
+  // Workflow writers (runtime.workflow.createScope + attachMetadata
+  // graduations, Layer-06 Slice 3). The handle must expose the
+  // pipeline each adapter dispatches through, or v3 cannot be a real
+  // live seam. `getWorkflowMetadataSnapshot` is the read side the
+  // metadata writer inspects before merging its entry.
+  | "addScope"
+  | "setWorkflowMetadataEntries"
+  | "getWorkflowMetadataSnapshot"
+  // W10 overlay-visibility policy (state-classes X1). Class-A canonical
+  // state; L06 owns read + write, L10 composes with local preference.
+  | "getVisibilityPolicy"
+  | "getVisibilityPolicies"
+  | "setVisibilityPolicy"
+  | "clearVisibilityPolicy"
+  | "subscribeVisibilityPolicy"
+  // X5 class-A markup-mode policy (state-classes X5).
+  | "getMarkupModePolicy"
+  | "setMarkupModePolicy"
+  | "subscribeMarkupModePolicy"
+  // Scope lookup (runtime.content.getLocation — replaced the debug-facet
+  // escape-hatch path with a typed scope + anchor read)
+  | "getScope"
+  | "getLocationForAnchor"
+  // Layer-10 `ui.scope.*` enabler (coord-07 §2.7 / coord-10 §α). L10's
+  // layer-purity guard blocks `src/runtime/scopes/**` + `src/api/v3/ai/**`,
+  // so L10 cannot construct its own scope compiler or call ai.getScopeBundle.
+  // Exposing this scopeId-keyed compile primitive on the handle lets
+  // `ui/scope.ts` deliver `SemanticScope` / `ScopeBundle` reads directly.
+  | "compileScopeBundleById"
+  // Layer-08 Slice-5 — scope-scoped replacement dispatch. `ai.apply
+  // ReplacementScope` + `runtime.content.replaceText(scopeId, …)`
+  // route compiled plans through this seam.
+  | "applyScopeReplacement"
+  // Nested facets (runtime.layout + runtime.geometry families,
+  // plus debug telemetry bus for UxResponse emission)
+  | "debug"
+  | "layout"
+  | "geometry"
+> & {
+  /**
+   * Optional collab session — hosts that wire Yjs/Awareness pass the
+   * session here so `api.runtime.collab.getPresence` / `.getPosture`
+   * can delegate live. When absent, those functions return
+   * deterministic mock snapshots (peers: [], posture: unattached).
+   */
+  readonly collabSession?: CollabSession;
+};
+
+/**
+ * @endStateApi
+ * Compile-time drift guard. This object's type is
+ * `Record<keyof RuntimeApiHandle, true>`, so adding a member to the
+ * interface without adding a key here — or removing a member without
+ * dropping the key — fails `pnpm run lint:tsgo` before it can land.
+ *
+ * `test/api/v3/runtime-handle-shape.test.ts` imports this constant and
+ * asserts at runtime that its key set equals the explicit audit roster
+ * maintained there. The two checks together catch both interface drift
+ * (this file, via tsgo) and audit-list drift (the test, via node:test).
+ */
+export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true> = {
+  getSessionState: true,
+  exportDocx: true,
+  getCompatibilityReport: true,
+  getWarnings: true,
+  getRenderSnapshot: true,
+  getCanonicalDocument: true,
+  findAllText: true,
+  getReviewWorkSnapshot: true,
+  acceptChange: true,
+  resolveComment: true,
+  queryScopes: true,
+  getWorkflowMarkupSnapshot: true,
+  getInteractionGuardSnapshot: true,
+  getWorkflowOverlay: true,
+  addScope: true,
+  setWorkflowMetadataEntries: true,
+  getWorkflowMetadataSnapshot: true,
+  getVisibilityPolicy: true,
+  getVisibilityPolicies: true,
+  setVisibilityPolicy: true,
+  clearVisibilityPolicy: true,
+  subscribeVisibilityPolicy: true,
+  getMarkupModePolicy: true,
+  setMarkupModePolicy: true,
+  subscribeMarkupModePolicy: true,
+  getScope: true,
+  getLocationForAnchor: true,
+  compileScopeBundleById: true,
+  applyScopeReplacement: true,
+  debug: true,
+  layout: true,
+  geometry: true,
+  // Optional members participate in the drift guard too — they're keys
+  // of the full RuntimeApiHandle type, so omitting them here would not
+  // fail `Record<keyof ...>`. Included explicitly so additions are
+  // visible in this single audit roster.
+  collabSession: true,
+};

package/src/api/v3/_ux-response.ts

@@ -0,0 +1,73 @@
+/**
+ * @endStateApi v3 — UX-response event contract.
+ *
+ * Every v3 function whose metadata declares `uxIntent.uiVisible === true`
+ * MUST call `emitUxResponse(runtime, res)` exactly once per invocation.
+ * The response is published on the existing `api` telemetry channel with
+ * `type: "ux.response.<apiFn>"`. Phase Q's debug UX subscribes to these to
+ * render mock-or-live visual traces identically.
+ *
+ * Unit tests assert the one-emit-per-call invariant. The
+ * `ci-check-api-v3-metadata` guard cross-checks that every function with
+ * `uiVisible: true` in its metadata has a corresponding `emitUxResponse`
+ * call in its implementation body.
+ */
+
+import type { RuntimeApiHandle } from "./_runtime-handle.ts";
+import type { ApiStatus, UxIntent } from "./_layer-metadata.ts";
+
+/**
+ * @endStateApi
+ * UX event envelope. `intent`/`expectedDelta` come from the function's
+ * metadata and describe what the UI should render if the operation is
+ * live. `actualDelta` is populated only on the live path.
+ */
+export interface UxResponse {
+  readonly apiFn: string;
+  readonly intent: string;
+  readonly mockOrLive: ApiStatus;
+  readonly uiVisible: boolean;
+  readonly expectedDelta?: string;
+  readonly actualDelta?: {
+    readonly kind: NonNullable<UxIntent["expectsUxResponse"]>;
+    readonly payload: unknown;
+  };
+  readonly auditHints?: readonly string[];
+  readonly ts: number;
+}
+
+/**
+ * @endStateApi
+ * Publish a UxResponse on the runtime's `api` telemetry channel. Safe to
+ * call when the channel is off — the bus bitmap gate short-circuits
+ * before any allocation. Returns nothing; fire-and-forget.
+ *
+ * Defensive posture: when the handle does not carry a telemetry bus
+ * (headless stubs, test doubles that exercise UI dispatch logic without
+ * wiring telemetry), this function silently no-ops instead of throwing.
+ * Production `DocumentRuntime` always supplies `runtime.debug.bus`;
+ * test handles may choose not to. A missing bus is NOT a contract
+ * violation — it's an opt-out of telemetry observation, not of the
+ * dispatch/subscribe behaviour itself.
+ */
+export function emitUxResponse(
+  runtime: RuntimeApiHandle,
+  res: Omit<UxResponse, "ts">,
+): void {
+  const bus = runtime.debug?.bus;
+  if (!bus || typeof bus.emit !== "function") return;
+  const stamped: UxResponse = { ...res, ts: performanceNow() };
+  bus.emit({
+    channel: "api",
+    type: `ux.response.${res.apiFn}`,
+    t: 0,
+    payload: stamped as unknown as Record<string, unknown>,
+  });
+}
+
+function performanceNow(): number {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}

package/src/api/v3/ai/_metadata-audit.ts

@@ -0,0 +1,225 @@
+/**
+ * @endStateApi v3 — metadata-write audit emitter.
+ *
+ * Architecture 09 §A4: every mutating function emits exactly one
+ * `ScopeActionAudit` record. `applyReplacementScope` emits via the
+ * /08 scope-compiler's `emitScopeActionAudit` on the replacement path.
+ * `attachExplanation` and `createIssue` are mutating (scope-metadata
+ * writes) but do not route through the replacement lifecycle — they
+ * need their own audit emission that reuses the `ScopeActionAudit`
+ * shape with `operation: "annotate"`.
+ *
+ * This module is the single place that constructs those audit records
+ * for /09's metadata writes, so the shape + emission site stay honest
+ * and discoverable from one file.
+ *
+ * Design notes:
+ *
+ *   1. We reuse the `ScopeActionAudit` shape exactly — no new type.
+ *      The `ReplacementScope.operation: "annotate"` variant already
+ *      exists in the taxonomy for this case; metadata writes fill it
+ *      with a synthesized `ReplacementScope` carrying structured
+ *      payload describing the attached explanation / created issue.
+ *
+ *   2. The helper compiles the target scope fresh before emission —
+ *      the snapshot captures the scope state AFTER the primitive
+ *      returned, which is the post-mutation canonical truth.
+ *
+ *   3. `validation` is synthesized as a `safe: true, blockedReasons:[],
+ *      warnings: []` record. Metadata writes currently bypass the
+ *      unified action-validation contract (Layer 08 Slice 4 shape);
+ *      when /06 ships the workflow-metadata policy-gating pass, this
+ *      emitter upgrades to route through composeScopeValidation too.
+ *
+ *   4. `documentHash` is a local copy of the same block-count + text-
+ *      length structural hash used by the replacement path so
+ *      before/after signatures stay comparable across audit types.
+ *      When /08 promotes `documentHash` to a public export the two
+ *      copies collapse to one.
+ *
+ *   5. Errors in the emitter MUST NOT propagate. The primitive's
+ *      write has already committed; the audit is a telemetry side-
+ *      effect. Failure here is logged on the `commit` channel (per
+ *      CLAUDE.md's "never break the edit path" discipline) and
+ *      swallowed.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { CanonicalDocumentEnvelope } from "../../../core/state/editor-state.ts";
+import {
+  buildParagraphIndexMap,
+  compileScope,
+  enumerateScopes,
+  type ReplacementOperationKind,
+  type ReplacementScope,
+  type ScopeActionAudit,
+  type SemanticScope,
+  type ValidationResult,
+} from "../../../runtime/scopes/index.ts";
+
+export interface EmitMetadataAuditInputs {
+  readonly runtime: RuntimeApiHandle;
+  /**
+   * API function name in dotted form (e.g. `"ai.attachExplanation"`).
+   * Used as the audit's `actionId`.
+   */
+  readonly actionId: string;
+  /** `"ui" | "agent" | "host"` — default `"agent"` when omitted. */
+  readonly origin?: "ui" | "agent" | "host";
+  /** Actor id — default `"v3-ai-api"` when omitted. */
+  readonly actorId?: string;
+  /** ScopeId of the write target. */
+  readonly scopeId: string;
+  /**
+   * Pre-mutation scope snapshot. The caller captures this BEFORE running
+   * the primitive — post-mutation the scope's text / formatting may have
+   * shifted (common when a same-session replacement just ran against the
+   * same target) and a fresh compile can miss. When the caller cannot
+   * produce a snapshot (e.g. the scope did not enumerate before the
+   * write), the audit is skipped silently.
+   */
+  readonly targetScopeSnapshot: SemanticScope;
+  /**
+   * Structured payload describing what was attached. Surfaced in the
+   * audit's `proposed.proposedContent.structured` field.
+   */
+  readonly proposedContent: {
+    readonly kind: "explanation" | "issue";
+    readonly payload: Record<string, unknown>;
+  };
+  /**
+   * Single-step `compiledOperations` entry kind. Distinct from the
+   * replacement-path kinds (`text-replace`, etc.) so audit consumers
+   * can narrow by `step.kind`.
+   */
+  readonly compiledOperationKind: "metadata-attach-explanation" | "metadata-attach-issue";
+  /** Short description of the write — surfaced on `compiledOperations[0].summary`. */
+  readonly compiledOperationSummary: string;
+  /** Pin for determinism — callers pass a fixed value in tests. */
+  readonly emittedAtUtc: string;
+  /** Document hash snapshot BEFORE the primitive ran. Captured by the caller. */
+  readonly documentHashBefore: string;
+}
+
+function structuralDocumentHash(doc: CanonicalDocumentEnvelope): string {
+  // Same shape as /08's `documentHash` in replacement/apply.ts — local
+  // copy until /08 promotes that helper to a public export.
+  const root = doc.content;
+  let textLength = 0;
+  for (const block of root.children) {
+    if (block.type === "paragraph") {
+      for (const child of block.children) {
+        if (child.type === "text") textLength += child.text.length;
+      }
+    }
+  }
+  return `blocks:${root.children.length}|text:${textLength}`;
+}
+
+function compileScopeSnapshot(
+  runtime: RuntimeApiHandle,
+  scopeId: string,
+): SemanticScope | null {
+  const doc = runtime.getCanonicalDocument();
+  const overlay = runtime.getWorkflowOverlay();
+  const paragraphIndexByBlockIndex = buildParagraphIndexMap(doc);
+  for (const entry of enumerateScopes(doc, overlay ? { overlay } : {})) {
+    if (entry.handle.scopeId !== scopeId) continue;
+    const compiled = compileScope(entry, {
+      document: doc,
+      ...(overlay ? { overlay } : {}),
+      paragraphIndexByBlockIndex,
+    });
+    if (compiled) return compiled;
+  }
+  return null;
+}
+
+export function snapshotDocumentHash(runtime: RuntimeApiHandle): string {
+  return structuralDocumentHash(
+    runtime.getCanonicalDocument() as CanonicalDocumentEnvelope,
+  );
+}
+
+/**
+ * Build + emit one `ScopeActionAudit` on the `scope` telemetry channel
+ * for a metadata-write (attachExplanation / createIssue). Returns the
+ * emitted audit so callers can surface it on their result.
+ *
+ * Never throws — telemetry failures are swallowed.
+ */
+/**
+ * Pre-mutation snapshot helper. Caller composes `captureScopeSnapshot`
+ * + primitive-write + `emitScopeMetadataAudit({targetScopeSnapshot})`
+ * so the snapshot reflects the state the write targeted, not the
+ * possibly-shifted post-mutation state.
+ */
+export function captureScopeSnapshot(
+  runtime: RuntimeApiHandle,
+  scopeId: string,
+): SemanticScope | null {
+  return compileScopeSnapshot(runtime, scopeId);
+}
+
+export function emitScopeMetadataAudit(
+  inputs: EmitMetadataAuditInputs,
+): ScopeActionAudit | null {
+  try {
+    const snapshot = inputs.targetScopeSnapshot;
+    const operation: ReplacementOperationKind = "annotate";
+    const proposed: ReplacementScope = {
+      targetHandle: snapshot.handle,
+      operation,
+      proposedContent: {
+        kind: "structured",
+        structured: {
+          metadataKind: inputs.proposedContent.kind,
+          ...inputs.proposedContent.payload,
+        },
+      },
+      proposedAtUtc: inputs.emittedAtUtc,
+    };
+
+    const validation: ValidationResult = {
+      safe: true,
+      blockedReasons: [],
+      warnings: [],
+    };
+
+    // We build + emit the audit inline rather than going through
+    // `/08`'s `emitScopeActionAudit(plan)` helper because the helper
+    // reads `plan.steps[].kind` as a narrow `RuntimeOperationStepKind`
+    // union (`text-replace | … | fragment-replace`). Metadata writes
+    // need distinct op kinds (`metadata-attach-explanation`, etc.) that
+    // aren't in the replacement-path taxonomy and shouldn't be — they
+    // are not runtime operations in the replacement sense. The audit's
+    // downstream `compiledOperations[].kind` field is typed `string`,
+    // so emitting a metadata-specific value here is shape-compatible.
+    const audit: ScopeActionAudit = {
+      actionId: inputs.actionId,
+      actorId: inputs.actorId ?? "v3-ai-api",
+      origin: inputs.origin ?? "agent",
+      documentHashBefore: inputs.documentHashBefore,
+      documentHashAfter: snapshotDocumentHash(inputs.runtime),
+      targetScopeSnapshot: snapshot,
+      proposed,
+      compiledOperations: Object.freeze([
+        {
+          kind: inputs.compiledOperationKind,
+          summary: inputs.compiledOperationSummary,
+        },
+      ]),
+      validation,
+      emittedAtUtc: inputs.emittedAtUtc,
+    };
+
+    inputs.runtime.debug?.bus.emitLazy("scope", () => ({
+      type: "scope.action_audit",
+      payload: audit,
+    }));
+    return audit;
+  } catch {
+    // Audit is a side-effect; never break the edit path.
+    return null;
+  }
+}