@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/scopes/attach-explanation.ts

@@ -0,0 +1,102 @@
+/**
+ * Slice 6 — `ai.attachExplanation` live-with-adapter primitive.
+ *
+ * Attaches an agent-authored explanation to a semantic scope by routing
+ * through Layer-06's `attachScopeMetadata` writer — the same pipeline
+ * `runtime.workflow.attachMetadata` graduated against. The explanation
+ * persists as a `WorkflowMetadataEntry` with a stable `metadataId`
+ * prefix (`ai.explanation`) and the caller-supplied text +
+ * explanationId in `value`.
+ *
+ * Determinism (S3): given identical (scopeId, explanationText,
+ * explanationId) inputs, the emitted entry is identical. The
+ * explanationId + createdAtUtc are caller-supplied so consumers that
+ * want deterministic output (tests, replay) can pin them.
+ *
+ * Scope coverage (coord-06 §13c shipped 2026-04-23): both overlay
+ * (workflow) scopes AND derived paragraph / heading / list-item
+ * scopes are valid targets. Derived scopeIds (e.g. `para:<paraId>`,
+ * `heading:<paraId>`, `li:<paraId>`) resolve against the canonical
+ * document via `resolveDerivedScopeAnchorFromCanonical`; the stored
+ * entry's anchor is the resolver's range output, and the result
+ * carries `resolvedFrom: "derived"`. Non-paragraph-like scopeIds
+ * (fields, comment threads, revisions, table-kind) still return
+ * `attached: false`.
+ */
+
+import type {
+  AttachScopeMetadataResult,
+  MetadataWriterRuntime,
+} from "../workflow/metadata-writer.ts";
+import { attachScopeMetadata } from "../workflow/metadata-writer.ts";
+
+/** Stable metadataId prefix for AI-attached explanations. */
+export const AI_EXPLANATION_METADATA_ID = "ai.explanation" as const;
+
+export interface AttachExplanationInput {
+  readonly scopeId: string;
+  readonly explanation: string;
+  /** Optional stable id — defaults to `explanation-<scopeId>` when omitted. */
+  readonly explanationId?: string;
+  /** Optional ISO UTC stamp — defaults to `new Date(0).toISOString()` for determinism. */
+  readonly createdAtUtc?: string;
+}
+
+export type AttachExplanationResult =
+  | {
+      readonly attached: true;
+      readonly explanationId: string;
+      readonly entryId: string;
+      /**
+       * Coord-06 §13c — `"overlay"` when the scope was on the workflow
+       * overlay, `"derived"` when it was a paragraph / heading /
+       * list-item scopeId resolved from the canonical document.
+       */
+      readonly resolvedFrom: "overlay" | "derived";
+    }
+  | {
+      readonly attached: false;
+      readonly explanationId: string;
+      /**
+       * `scope-not-resolvable:<scopeId>` — the scopeId is neither on
+       * the workflow overlay nor a paragraph-like derived id the
+       * canonical walk can resolve. Pre-§13c this was always
+       * `scope-not-in-overlay`; the broader prefix reflects the
+       * post-§13c two-stage resolution.
+       */
+      readonly reason: string;
+    };
+
+export function attachExplanation(
+  runtime: MetadataWriterRuntime,
+  input: AttachExplanationInput,
+): AttachExplanationResult {
+  const explanationId = input.explanationId ?? `explanation-${input.scopeId}`;
+  const createdAtUtc = input.createdAtUtc ?? new Date(0).toISOString();
+  const writerResult: AttachScopeMetadataResult = attachScopeMetadata(runtime, {
+    scopeId: input.scopeId,
+    metadataId: AI_EXPLANATION_METADATA_ID,
+    value: {
+      explanationId,
+      text: input.explanation,
+      createdAtUtc,
+    },
+    // `inherit` persistence is the right default: explanations that
+    // need to export through to docx do so via the standard
+    // workflow-metadata export path; callers wanting `external`
+    // (side-channel only) pass through `attachScopeMetadata` directly.
+  });
+  if (writerResult.status === "attached") {
+    return {
+      attached: true,
+      explanationId,
+      entryId: writerResult.entryId,
+      resolvedFrom: writerResult.resolvedFrom,
+    };
+  }
+  return {
+    attached: false,
+    explanationId,
+    reason: `scope-not-resolvable:${writerResult.scopeId}`,
+  };
+}

package/src/runtime/scopes/audit-bundle.ts

@@ -0,0 +1,71 @@
+/**
+ * Slice 5 — `ScopeActionAudit` producer + telemetry emission.
+ *
+ * Every mutating replacement-scope action emits exactly one audit on the
+ * `scope` channel (S5 of layer-08 architecture). This module is the
+ * single producer — callers must not compose audit bundles locally and
+ * emit directly; they compose here so the shape + emission site stay
+ * honest.
+ */
+
+import type { TelemetryBus } from "../debug/telemetry-bus.ts";
+import type {
+  ReplacementScope,
+  RuntimeOperationPlan,
+  ScopeActionAudit,
+  SemanticScope,
+  ValidationResult,
+} from "./semantic-scope-types.ts";
+
+export interface EmitScopeActionAuditInputs {
+  readonly actionId: string;
+  readonly actorId: string;
+  readonly origin: "ui" | "agent" | "host";
+  readonly documentHashBefore: string;
+  readonly documentHashAfter?: string;
+  readonly targetScopeSnapshot: SemanticScope;
+  readonly proposed: ReplacementScope;
+  readonly plan: RuntimeOperationPlan;
+  readonly validation: ValidationResult;
+  readonly emittedAtUtc: string;
+  readonly bus?: TelemetryBus;
+}
+
+export function buildScopeActionAudit(
+  inputs: EmitScopeActionAuditInputs,
+): ScopeActionAudit {
+  return {
+    actionId: inputs.actionId,
+    actorId: inputs.actorId,
+    origin: inputs.origin,
+    documentHashBefore: inputs.documentHashBefore,
+    ...(inputs.documentHashAfter
+      ? { documentHashAfter: inputs.documentHashAfter }
+      : {}),
+    targetScopeSnapshot: inputs.targetScopeSnapshot,
+    proposed: inputs.proposed,
+    compiledOperations: Object.freeze(
+      inputs.plan.steps.map((step) => ({
+        kind: step.kind,
+        summary: step.summary,
+      })),
+    ),
+    validation: inputs.validation,
+    emittedAtUtc: inputs.emittedAtUtc,
+  };
+}
+
+/**
+ * Build + emit one audit event on the `scope` telemetry channel. Returns
+ * the bundle so callers can surface it in their apply-result response.
+ */
+export function emitScopeActionAudit(
+  inputs: EmitScopeActionAuditInputs,
+): ScopeActionAudit {
+  const audit = buildScopeActionAudit(inputs);
+  inputs.bus?.emitLazy("scope", () => ({
+    type: "scope.action_audit",
+    payload: audit,
+  }));
+  return audit;
+}

package/src/runtime/scopes/compile-scope-bundle.ts

@@ -0,0 +1,163 @@
+/**
+ * Slice 3 — scope-bundle compiler.
+ *
+ * Wraps a compiled `SemanticScope` with its neighborhood (prev / next /
+ * parent / siblings) + evidence (review overlap, workflow overlap,
+ * formatting summary) into a single `ScopeBundle` sized for an agent turn
+ * budget (S7). The bundle is the primary unit an AI-API consumer reads.
+ *
+ * Cost: `neighborhoodFor` is O(n) per call. When composing many bundles
+ * over the same scope enumeration, pass `scopes` through explicitly so the
+ * enumeration runs once. A scope-id → index cache is a Slice 4+ follow-up.
+ */
+
+import type { CanonicalDocument, StylesCatalog } from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  WorkflowMetadataEntry,
+  WorkflowOverlay,
+} from "./_scope-dependencies.ts";
+
+import { buildParagraphIndexMap, compileScope } from "./compile-scope.ts";
+import type { EnumeratedScope } from "./enumerate-scopes.ts";
+import { enumerateScopes } from "./enumerate-scopes.ts";
+import { composeEvidence } from "./evidence.ts";
+import type {
+  ScopeBundle,
+  ScopeBundleNeighborhood,
+  SemanticScope,
+} from "./semantic-scope-types.ts";
+
+export interface ScopeBundleInputs {
+  readonly document: Pick<CanonicalDocument, "content" | "docId" | "styles" | "review"> | CanonicalDocumentEnvelope;
+  readonly overlay?: WorkflowOverlay | null;
+  readonly nowUtc: string;
+  /** Pre-enumerated scopes; computed when absent. */
+  readonly scopes?: readonly EnumeratedScope[];
+  /**
+   * Workflow-metadata entries to project into the bundle's evidence as
+   * `aiExplanations` + `aiIssues`. When absent, those fields are
+   * omitted. Closes the adversarial-close read-side join: explanations
+   * + issues written via `ai.attachExplanation` / `ai.createIssue`
+   * become readable through `getScopeBundle` without the caller having
+   * to walk the metadata snapshot.
+   */
+  readonly workflowMetadataEntries?: readonly WorkflowMetadataEntry[];
+}
+
+/**
+ * S7 cap — the bundle is sized for an agent turn, so we clamp the
+ * `siblingScopeIds` list to avoid O(n) bloat on top-level paragraphs in a
+ * 500-scope document. Prev/next always carry the immediate neighbors; the
+ * sibling list is truncated lexicographically after the self-position.
+ */
+const SIBLING_CAP = 20;
+
+function neighborhoodFor(
+  handle: SemanticScope["handle"],
+  scopes: readonly EnumeratedScope[],
+): ScopeBundleNeighborhood {
+  const siblings: string[] = [];
+  let previousScopeId: string | undefined;
+  let nextScopeId: string | undefined;
+
+  const parentScopeId = handle.parentScopeId;
+  const parentKey = parentScopeId ?? null;
+
+  for (let i = 0; i < scopes.length; i += 1) {
+    const entry = scopes[i]!;
+    if (entry.handle.scopeId === handle.scopeId) {
+      for (let p = i - 1; p >= 0; p -= 1) {
+        const cand = scopes[p]!;
+        if ((cand.handle.parentScopeId ?? null) === parentKey) {
+          previousScopeId = cand.handle.scopeId;
+          break;
+        }
+      }
+      for (let n = i + 1; n < scopes.length; n += 1) {
+        const cand = scopes[n]!;
+        if ((cand.handle.parentScopeId ?? null) === parentKey) {
+          nextScopeId = cand.handle.scopeId;
+          break;
+        }
+      }
+      continue;
+    }
+    if (
+      (entry.handle.parentScopeId ?? null) === parentKey &&
+      entry.handle.scopeId !== handle.scopeId
+    ) {
+      if (siblings.length < SIBLING_CAP) {
+        siblings.push(entry.handle.scopeId);
+      }
+    }
+  }
+
+  return {
+    ...(previousScopeId ? { previousScopeId } : {}),
+    ...(nextScopeId ? { nextScopeId } : {}),
+    ...(parentScopeId ? { parentScopeId } : {}),
+    ...(siblings.length > 0 ? { siblingScopeIds: siblings } : {}),
+  };
+}
+
+/**
+ * Compile a scope bundle for one `SemanticScope`. Callers typically
+ * produce `scope` via `compileScope(entry, catalog)` and thread the same
+ * `document` + `overlay` through here.
+ */
+export function compileScopeBundle(
+  scope: SemanticScope,
+  inputs: ScopeBundleInputs,
+): ScopeBundle {
+  const scopes =
+    inputs.scopes ??
+    enumerateScopes(inputs.document, { overlay: inputs.overlay ?? null });
+  const neighborhood = neighborhoodFor(scope.handle, scopes);
+  const evidence = composeEvidence({
+    scope,
+    document: inputs.document,
+    overlay: inputs.overlay,
+    scopes,
+    ...(inputs.workflowMetadataEntries
+      ? { workflowMetadataEntries: inputs.workflowMetadataEntries }
+      : {}),
+  });
+  return {
+    scope,
+    neighborhood,
+    evidence,
+    generatedAtUtc: inputs.nowUtc,
+  };
+}
+
+/**
+ * Convenience wrapper — resolves a scope by id, compiles it, and returns
+ * its bundle. Returns null when the scope id does not enumerate.
+ *
+ * The `document` on `inputs` is the primary Layer 03 cascade input — when
+ * present, the compiler delegates formatting resolution to Layer 03 (see
+ * `compileScope` + `_formatting-seam.ts`). A bare `catalog` remains
+ * accepted for back-compat but is ignored by the seam.
+ */
+export function compileScopeBundleById(
+  scopeId: string,
+  inputs: ScopeBundleInputs & { readonly catalog?: StylesCatalog },
+): ScopeBundle | null {
+  const scopes =
+    inputs.scopes ??
+    enumerateScopes(inputs.document, { overlay: inputs.overlay ?? null });
+  const entry = scopes.find((e) => e.handle.scopeId === scopeId);
+  if (!entry) return null;
+  const fullDoc =
+    "styles" in inputs.document && "content" in inputs.document
+      ? (inputs.document as CanonicalDocument)
+      : undefined;
+  const compiled = compileScope(entry, {
+    ...(fullDoc ? { document: fullDoc } : {}),
+    ...(inputs.overlay !== undefined ? { overlay: inputs.overlay } : {}),
+    paragraphIndexByBlockIndex: buildParagraphIndexMap(inputs.document),
+  });
+  if (!compiled) return null;
+  return compileScopeBundle(compiled, { ...inputs, scopes });
+}

package/src/runtime/scopes/compile-scope.ts

@@ -0,0 +1,262 @@
+/**
+ * Scope compile dispatcher.
+ *
+ * Takes an `EnumeratedScope` and dispatches to the matching kind compiler.
+ * Callers may thread a `CompileScopeOptions` bundle carrying:
+ *
+ *   - `document`  — full canonical document; enables Layer 03
+ *                   `resolveEffectiveFormatting` delegation for
+ *                   paragraph-like kinds (paragraphStyleId / outlineLevel
+ *                   / numbering.label honour the style cascade).
+ *   - `overlay`   — workflow overlay; the dispatcher computes overlay-
+ *                   scope overlap and threads `SemanticScopeWorkflow`
+ *                   into every paragraph-like and table-like compile.
+ *                   Identity-posture kinds (field, comment-thread,
+ *                   revision) override this in their kind file because
+ *                   the kind's identity implies its own mode.
+ *   - `paragraphIndexByBlockIndex` — map from the all-children
+ *                   `blockIndex` used by the scope walker to the
+ *                   paragraph-type index Layer 03's synthesis uses
+ *                   (`paragraph-${N}`). Built once per document by
+ *                   `buildParagraphIndexMap`.
+ *   - `positionMap` — precomputed `ScopePositionMap`. Reused across
+ *                   all compiles in a single pass so we only walk the
+ *                   document once for offset arithmetic.
+ *
+ * Kinds not yet implemented (note, image, scope, composite — 4 of 13)
+ * return `null`; the caller decides how to handle. `enumerate-scopes`
+ * already skips emitting these, so the null branch is a belt-and-braces
+ * guard for forward compatibility.
+ *
+ * Back-compat: the legacy `(entry, catalog)` signature still compiles —
+ * a bare `StylesCatalog` is accepted and ignored (it carried no cascade
+ * information the seam consumes directly). Callers are encouraged to
+ * migrate to `(entry, options)` to get Layer 03 cascade-accurate output.
+ */
+
+import type {
+  CanonicalDocument,
+  StylesCatalog,
+} from "../../model/canonical-document.ts";
+import type { WorkflowOverlay } from "./_scope-dependencies.ts";
+import type {
+  CanonicalDocumentEnvelope,
+} from "../../core/state/editor-state.ts";
+
+import type { EnumeratedScope } from "./enumerate-scopes.ts";
+import {
+  buildScopePositionMap,
+  type ScopePositionMap,
+} from "./position-map.ts";
+import { resolveScopeRange } from "./scope-range.ts";
+import type {
+  SemanticScope,
+  SemanticScopeWorkflow,
+} from "./semantic-scope-types.ts";
+import { resolveWorkflowOverlap } from "./workflow-overlap.ts";
+
+import { compileCommentThreadScope } from "./scope-kinds/comment-thread.ts";
+import { compileFieldScope } from "./scope-kinds/field.ts";
+import { compileHeadingScope } from "./scope-kinds/heading.ts";
+import { compileListItemScope } from "./scope-kinds/list-item.ts";
+import { compileParagraphScope } from "./scope-kinds/paragraph.ts";
+import { compileRevisionScope } from "./scope-kinds/revision.ts";
+import { compileTableScope } from "./scope-kinds/table.ts";
+import { compileTableCellScope } from "./scope-kinds/table-cell.ts";
+import { compileTableRowScope } from "./scope-kinds/table-row.ts";
+
+export interface CompileScopeOptions {
+  readonly document?: CanonicalDocument;
+  readonly overlay?: WorkflowOverlay | null;
+  readonly paragraphIndexByBlockIndex?: ReadonlyMap<number, number>;
+  /**
+   * `blockIndex → sectionIndex` precomputed via
+   * `buildSectionIndexByBlockIndex`. When present, paragraph-like kinds
+   * project `layout.sectionIndex` (coord-08 §12). When absent, the
+   * dispatcher computes it lazily from `options.document`. Callers that
+   * compile many scopes against the same document should hoist.
+   */
+  readonly sectionIndexByBlockIndex?: ReadonlyMap<number, number>;
+  readonly positionMap?: ScopePositionMap;
+}
+
+function isCompileScopeOptions(
+  v: unknown,
+): v is CompileScopeOptions {
+  if (v === null || v === undefined) return true;
+  if (typeof v !== "object") return false;
+  return (
+    "document" in v ||
+    "overlay" in v ||
+    "paragraphIndexByBlockIndex" in v ||
+    "sectionIndexByBlockIndex" in v ||
+    "positionMap" in v
+  );
+}
+
+/**
+ * Walk the document once to build a `blockIndex → sectionIndex` map.
+ * Section index is derived by counting `section_break` blocks that
+ * appear BEFORE the current block — every `section_break` advances the
+ * counter for the next block, matching OOXML's "blocks belong to the
+ * section whose properties live at the *next* section_break (or
+ * `finalSectionProperties` for the trailing section)" convention.
+ *
+ * Blocks before the first `section_break` report `sectionIndex = 0`.
+ * Callers use this for `SemanticScopeLayout.sectionIndex` projection
+ * (coord-08 §12). L04's `page-graph` carries its own per-page section
+ * indexing; this helper stays on L08's side because the per-block
+ * answer is a pure canonical-tree walk that doesn't require the
+ * layout facet.
+ */
+export function buildSectionIndexByBlockIndex(
+  document:
+    | Pick<CanonicalDocument, "content">
+    | CanonicalDocumentEnvelope,
+): Map<number, number> {
+  const envelope = document as CanonicalDocumentEnvelope;
+  const root =
+    "content" in envelope
+      ? envelope.content
+      : (document as unknown as { children: readonly { type: string }[] });
+  const out = new Map<number, number>();
+  let sectionIndex = 0;
+  for (let i = 0; i < root.children.length; i += 1) {
+    out.set(i, sectionIndex);
+    const child = root.children[i];
+    if (child && child.type === "section_break") {
+      sectionIndex += 1;
+    }
+  }
+  return out;
+}
+
+/**
+ * Walk the document once to build a `blockIndex → paragraphIndex` map.
+ * Paragraph-type indexing matches Layer 03's `paragraph-${N}` blockId
+ * synthesis (see `src/runtime/formatting/document-lookup.ts`). Callers
+ * that compile many scopes over the same document should build this
+ * once and reuse.
+ */
+export function buildParagraphIndexMap(
+  document:
+    | Pick<CanonicalDocument, "content">
+    | CanonicalDocumentEnvelope,
+): Map<number, number> {
+  const envelope = document as CanonicalDocumentEnvelope;
+  const root =
+    "content" in envelope
+      ? envelope.content
+      : (document as unknown as { children: readonly { type: string }[] });
+  const out = new Map<number, number>();
+  let paragraphIndex = 0;
+  for (let i = 0; i < root.children.length; i += 1) {
+    const child = root.children[i];
+    if (child && child.type === "paragraph") {
+      out.set(i, paragraphIndex);
+      paragraphIndex += 1;
+    }
+  }
+  return out;
+}
+
+function workflowFor(
+  entry: EnumeratedScope,
+  overlay: WorkflowOverlay | null | undefined,
+  positionMap: ScopePositionMap | undefined,
+): SemanticScopeWorkflow | undefined {
+  if (!overlay || !positionMap) return undefined;
+  // Review-store kinds carry identity-derived posture in their kind
+  // file (comment-thread = "comment", revision = "suggest"), so we
+  // skip the overlap path for them. All structural kinds — including
+  // marker-backed paragraphs that hosts classify as "clause" — get
+  // the proper overlap merge, which means outer `view` / `comment`
+  // scopes correctly override inner `edit` scopes.
+  const isIdentityKind =
+    entry.kind === "comment-thread" || entry.kind === "revision";
+  if (isIdentityKind) return undefined;
+  const range = resolveScopeRange(entry, entry.handle, positionMap);
+  return resolveWorkflowOverlap({
+    overlay,
+    positionMap,
+    range,
+    // Intentionally do NOT pass selfScopeIds — a marker-backed scope's
+    // own overlay entry carries the authoritative mode for its own
+    // range, and outer overlap scopes merge on top via the most-
+    // restrictive rule. Filtering self would drop the scope's own
+    // mode signal and misrepresent its posture.
+  });
+}
+
+export function compileScope(
+  entry: EnumeratedScope,
+  optionsOrCatalog?: CompileScopeOptions | StylesCatalog,
+): SemanticScope | null {
+  const options: CompileScopeOptions = isCompileScopeOptions(optionsOrCatalog)
+    ? (optionsOrCatalog ?? {})
+    : {};
+  const blockIndex = "blockIndex" in entry ? entry.blockIndex : -1;
+  const paragraphIndex =
+    options.paragraphIndexByBlockIndex?.get(blockIndex);
+  // Lazy section-index map: build once per dispatcher call when the
+  // caller didn't hoist + we have a document to walk. Derived scopes
+  // without a blockIndex (e.g. comment-thread/revision identity kinds)
+  // skip the projection via the `blockIndex >= 0` check below.
+  let sectionIndexMap = options.sectionIndexByBlockIndex;
+  if (!sectionIndexMap && options.document && blockIndex >= 0) {
+    sectionIndexMap = buildSectionIndexByBlockIndex(options.document);
+  }
+  const sectionIndex =
+    blockIndex >= 0 ? sectionIndexMap?.get(blockIndex) : undefined;
+  const paragraphLikeOpts: {
+    document?: CanonicalDocument;
+    paragraphIndex?: number;
+    sectionIndex?: number;
+  } = {};
+  if (options.document) paragraphLikeOpts.document = options.document;
+  if (typeof paragraphIndex === "number") {
+    paragraphLikeOpts.paragraphIndex = paragraphIndex;
+  }
+  if (typeof sectionIndex === "number") {
+    paragraphLikeOpts.sectionIndex = sectionIndex;
+  }
+  // Compute positionMap + workflow only when overlay is threaded. This
+  // keeps hot-path unit tests (without overlay) allocation-free.
+  let positionMap = options.positionMap;
+  if (!positionMap && options.overlay && options.document) {
+    positionMap = buildScopePositionMap(options.document);
+  }
+  const workflow = workflowFor(entry, options.overlay, positionMap);
+
+  switch (entry.kind) {
+    case "paragraph":
+      return compileParagraphScope(entry, {
+        ...paragraphLikeOpts,
+        ...(workflow ? { workflow } : {}),
+      });
+    case "heading":
+      return compileHeadingScope(entry, {
+        ...paragraphLikeOpts,
+        ...(workflow ? { workflow } : {}),
+      });
+    case "list-item":
+      return compileListItemScope(entry, {
+        ...paragraphLikeOpts,
+        ...(workflow ? { workflow } : {}),
+      });
+    case "table":
+      return compileTableScope(entry, workflow ? { workflow } : {});
+    case "table-row":
+      return compileTableRowScope(entry, workflow ? { workflow } : {});
+    case "table-cell":
+      return compileTableCellScope(entry, workflow ? { workflow } : {});
+    case "field":
+      return compileFieldScope(entry);
+    case "comment-thread":
+      return compileCommentThreadScope(entry);
+    case "revision":
+      return compileRevisionScope(entry);
+    default:
+      return null;
+  }
+}