@beyondwork/docx-react-component 1.0.66 → 1.0.69

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

@@ -0,0 +1,208 @@
+/**
+ * Slice 3 — single source of truth for "what canonical range does this
+ * scope cover?" + "how specific is this kind for tie-breaking?".
+ *
+ * Used by three sites:
+ *   - `resolve-reference.ts` — offset / range hints need each scope's
+ *     live range to pick the innermost containing match.
+ *   - `evidence.ts` — scope-bundle evidence composer needs the self-range
+ *     to compute review + workflow overlap.
+ *   - `review-bundle.ts` — per-scope review summary needs the same range.
+ *
+ * Keeping these three sites on one helper prevents the behavioural drift
+ * the independent code-review flagged at Slice 3 close. Adversarial-
+ * closure pass 2026-04-22: widened to precise inline ranges for fields +
+ * proportional sub-ranges for table rows/cells, plus a kind-specificity
+ * ordering so `innermostContaining` picks the deepest scope when ranges
+ * tie or nest.
+ */
+
+import type {
+  CanonicalAnchor,
+  CanonicalDocument,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+
+import type { EnumeratedScope } from "./enumerate-scopes.ts";
+import {
+  buildScopePositionMap,
+  computeTableCellRange,
+  computeTableRowRange,
+  type ScopePositionMap,
+  type ScopePositionRange,
+} from "./position-map.ts";
+import type {
+  ScopeHandle,
+  SemanticScopeKind,
+} from "./semantic-scope-types.ts";
+
+function anchorToRange(anchor: CanonicalAnchor): ScopePositionRange | null {
+  switch (anchor.kind) {
+    case "range":
+      return { from: anchor.range.from, to: anchor.range.to };
+    case "node":
+      return { from: anchor.at, to: anchor.at };
+    case "detached":
+      return anchor.lastKnownRange;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Kind-level specificity ranking. Higher = more specific (deeper / more
+ * narrowly-scoped). Used as a tie-breaker when multiple scopes contain the
+ * same offset or share identical canonical ranges (fields inside a
+ * paragraph, cells inside a row inside a table). Marker-backed scopes
+ * still win regardless of rank — the rank only matters among derived
+ * scopes whose canonical range is a coarser block-level projection of the
+ * structural truth.
+ *
+ * Values chosen so that:
+ *   - paragraph-like kinds (paragraph / heading / list-item / clause)
+ *     outrank the documentwide / composite scopes
+ *   - table < table-row < table-cell (nested containment)
+ *   - field outranks the enclosing paragraph (an inline hit should snap
+ *     to the field, not the paragraph that contains it)
+ *   - comment-thread / revision carry an anchor-based range and win over
+ *     the enclosing paragraph when the caller asked for a review-scoped
+ *     resolution
+ */
+export function scopeSpecificity(kind: SemanticScopeKind): number {
+  switch (kind) {
+    case "composite":
+      return 0;
+    case "scope":
+      return 1;
+    case "paragraph":
+    case "heading":
+    case "list-item":
+      return 2;
+    case "table":
+      return 3;
+    case "table-row":
+      return 4;
+    case "table-cell":
+      return 5;
+    case "image":
+    case "note":
+      return 6;
+    case "field":
+      return 7;
+    case "comment-thread":
+    case "revision":
+      return 8;
+    default: {
+      const _never: never = kind;
+      void _never;
+      return 0;
+    }
+  }
+}
+
+/**
+ * Resolve the canonical `{from,to}` range for any `EnumeratedScope` variant.
+ *
+ * Precision tiers:
+ *   - paragraph / heading / list-item / clause : block range
+ *   - table                                    : block range (1-slot)
+ *   - table-row                                : proportional sub-range
+ *                                                of the table's 1-slot
+ *                                                canonical range
+ *   - table-cell                               : proportional sub-range
+ *                                                of the row's sub-range
+ *   - field                                    : inline slot range
+ *                                                `inlines[${blockIndex}:${inlineIndex}]`
+ *   - comment-thread / revision                : review-store anchor range
+ *
+ * Marker-backed scope handles always take precedence — the marker pair's
+ * precise range wins over the derived block/inline range so offset /
+ * overlap math stays tight on the shipped marker contract.
+ */
+export function resolveScopeRange(
+  entry: EnumeratedScope,
+  handle: ScopeHandle,
+  positionMap: ScopePositionMap,
+): ScopePositionRange | null {
+  // Marker-backed scopes get their precise range from `scope-resolver`.
+  if (handle.stableRef.kind === "scope-id") {
+    const marker = positionMap.markerScopes.get(handle.stableRef.value);
+    if (marker) return marker;
+  }
+  switch (entry.kind) {
+    case "paragraph":
+    case "heading":
+    case "list-item":
+      return positionMap.blocks.get(entry.blockIndex) ?? null;
+    case "table":
+      return positionMap.blocks.get(entry.blockIndex) ?? null;
+    case "table-row": {
+      const tableRange = positionMap.blocks.get(entry.blockIndex);
+      if (!tableRange) return null;
+      return computeTableRowRange(entry.table, entry.rowIndex, tableRange);
+    }
+    case "table-cell": {
+      const tableRange = positionMap.blocks.get(entry.blockIndex);
+      if (!tableRange) return null;
+      const rowRange = computeTableRowRange(
+        entry.table,
+        entry.rowIndex,
+        tableRange,
+      );
+      return computeTableCellRange(entry.row, entry.cellIndex, rowRange);
+    }
+    case "field": {
+      const key = `${entry.blockIndex}:${entry.inlineIndex}`;
+      const inlineRange = positionMap.inlines.get(key);
+      if (inlineRange) return inlineRange;
+      // Fallback: the paragraph's block range. A field without a
+      // corresponding inline entry is a position-map bug, but returning
+      // null would drop the field from overlap/resolve entirely. Fall
+      // back rather than regress.
+      return positionMap.blocks.get(entry.blockIndex) ?? null;
+    }
+    case "comment-thread":
+      return anchorToRange(entry.thread.anchor);
+    case "revision":
+      return anchorToRange(entry.revision.anchor);
+    default: {
+      const never: never = entry;
+      void never;
+      return null;
+    }
+  }
+}
+
+/**
+ * Inclusive-inclusive range overlap. Canonical positions treat marker pairs
+ * as closed intervals, so `[aFrom, aTo]` and `[bFrom, bTo]` overlap when
+ * `aHigh >= bLow && aLow <= bHigh`. The position-map computes block ranges
+ * with a `+1` gap between blocks (per `scope-resolver`), so adjacent
+ * block-range overlap is not an off-by-one hazard.
+ *
+ * Fractional ranges (table-row / table-cell synthesized subranges) are
+ * safe to compare with the same rule — the partition contract of
+ * `computeTableRowRange` / `computeTableCellRange` guarantees no two
+ * subranges share any interior point.
+ */
+export function rangesOverlap(
+  a: ScopePositionRange,
+  b: ScopePositionRange,
+): boolean {
+  const aLow = Math.min(a.from, a.to);
+  const aHigh = Math.max(a.from, a.to);
+  const bLow = Math.min(b.from, b.to);
+  const bHigh = Math.max(b.from, b.to);
+  return aHigh >= bLow && aLow <= bHigh;
+}
+
+/**
+ * Convenience — build a position map once and resolve the scope's range.
+ */
+export function resolveScopeRangeFromDoc(
+  entry: EnumeratedScope,
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+): ScopePositionRange | null {
+  const positionMap = buildScopePositionMap(document);
+  return resolveScopeRange(entry, entry.handle, positionMap);
+}

package/src/runtime/scopes/semantic-scope-types.ts

@@ -0,0 +1,454 @@
+/**
+ * Layer 08 — Semantic Scope Compiler · public types.
+ *
+ * Target: `docs/architecture/08-semantic-scope-compiler.md` §"Core types".
+ *
+ * All shapes here are plain, structurally-cloneable, immutable values (S9).
+ * No runtime proxy references, no DOM nodes, no live session handles leak
+ * across this boundary.
+ *
+ * ## Taxonomy (13 kinds, all structural / OOXML-native)
+ *
+ * The compiler is a **generic substrate** — it does not encode any
+ * vertical / domain vocabulary (CLM, legal, compliance, etc.). Domain
+ * concepts like "clause", "issue", or "suggestion" flow through the
+ * generic `classifications: readonly string[]` field on every scope,
+ * populated from host metadata on the workflow overlay. Layer 08 reads
+ * those tags and surfaces them verbatim; it does not mint new kinds
+ * for them.
+ *
+ * See `docs/wiki/use-case-domains/clm/semantic-scope-usage.md` for the
+ * CLM example of how hosts tag scopes for domain workflows.
+ *
+ * Taxonomy is FROZEN. Renaming, splitting, or adding kinds is a
+ * compatibility event.
+ */
+
+import type { EditorStoryTarget } from "./_scope-dependencies.ts";
+
+/**
+ * 13-value kind taxonomy — purely structural.
+ */
+export type SemanticScopeKind =
+  | "heading"
+  | "paragraph"
+  | "list-item"
+  | "table"
+  | "table-row"
+  | "table-cell"
+  | "note"
+  | "field"
+  | "image"
+  | "comment-thread"
+  | "revision"
+  | "scope"
+  | "composite";
+
+/**
+ * Provenance of a scope (three-way classification from workflow scopes,
+ * extended with `derived` for scopes the compiler synthesizes from canonical
+ * structure without any marker / overlay backing).
+ */
+export type ScopeProvenance =
+  | "marker-backed"
+  | "overlay-only"
+  | "detached"
+  | "derived";
+
+/**
+ * Stable reference strategy encoded into a handle. Consumers pick the
+ * strongest available; the compiler picks the single authoritative strategy
+ * per scope (marker-backed scopes carry `scope-id`, bookmarked regions carry
+ * `bookmark`, purely structural scopes carry `semantic-path`).
+ */
+export type ScopeStableRef =
+  | { readonly kind: "scope-id"; readonly value: string }
+  | { readonly kind: "bookmark"; readonly value: string }
+  | { readonly kind: "semantic-path"; readonly value: string }
+  | { readonly kind: "runtime-handle"; readonly value: string };
+
+/**
+ * Discriminator on how precise the scope's canonical range is:
+ *
+ *   - `"marker-backed"` — range derived from the scope's own marker pair;
+ *     canonical offsets are exact. Safe for offset arithmetic + apply.
+ *   - `"canonical"` — range taken from the canonical document structure
+ *     (paragraph / heading / list-item / table / field inline slot).
+ *     Canonical offsets are exact.
+ *   - `"synthetic"` — range is a proportional subdivision of a containing
+ *     canonical slot (table-row / table-cell today). Suitable for overlap
+ *     ordering inside the containing slot but NOT for cross-document
+ *     offset arithmetic. Consumers needing a precise replacement envelope
+ *     must resolve via the layer-05 geometry facet instead of trusting
+ *     this range.
+ */
+export type ScopeRangePrecision = "marker-backed" | "canonical" | "synthetic";
+
+/**
+ * Opaque reference handle that identifies one scope across sessions (S2).
+ * Plain value — serialize, transport over Yjs / gRPC, feed back into
+ * `resolveReference` later.
+ */
+export interface ScopeHandle {
+  readonly scopeId: string;
+  readonly documentId: string;
+  readonly storyTarget: EditorStoryTarget;
+  readonly semanticPath: readonly string[];
+  readonly parentScopeId?: string;
+  readonly stableRef: ScopeStableRef;
+  readonly provenance: ScopeProvenance;
+  /**
+   * How precise the scope's canonical range is. Consumers reading range
+   * offsets (resolve-reference, apply pipelines, overlay positioning)
+   * must check this before trusting the range for anything beyond
+   * overlap ordering inside the containing slot.
+   *
+   * Optional for backwards compatibility with scopes constructed before
+   * the discriminator shipped; when absent, treat as `"canonical"`.
+   */
+  readonly rangePrecision?: ScopeRangePrecision;
+}
+
+export interface SemanticScopeContent {
+  readonly text: string;
+  readonly normalizedText?: string;
+  readonly excerpt?: string;
+  readonly childScopeIds?: readonly string[];
+}
+
+export interface SemanticScopeNumbering {
+  readonly numberingInstanceId: string;
+  readonly level: number;
+  readonly label?: string;
+}
+
+export interface SemanticScopeFormatting {
+  readonly paragraphStyleId?: string;
+  readonly numbering?: SemanticScopeNumbering;
+  readonly emphasis?: readonly string[];
+  readonly tableRole?: "header" | "body" | "footer";
+  readonly outlineLevel?: number;
+}
+
+export interface SemanticScopeLineSpan {
+  readonly start: number;
+  readonly end: number;
+}
+
+export interface SemanticScopeLayout {
+  readonly sectionIndex?: number;
+  readonly pageSpan?: { readonly start: number; readonly end: number };
+  readonly regionKind?: string;
+  readonly lineSpan?: SemanticScopeLineSpan;
+  readonly flowKind?: string;
+}
+
+export interface GeometryRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface SemanticScopeGeometry {
+  readonly anchorRect?: GeometryRect;
+  readonly scopeRects?: readonly GeometryRect[];
+  readonly attachPoint?: {
+    readonly x: number;
+    readonly y: number;
+    readonly side: "before" | "after" | "inside";
+  };
+}
+
+export interface SemanticScopeWorkflow {
+  readonly scopeIds: readonly string[];
+  readonly effectiveMode: "edit" | "suggest" | "comment" | "view" | "blocked";
+  readonly blockedReasons?: readonly string[];
+  readonly issueIds?: readonly string[];
+  readonly suggestionIds?: readonly string[];
+}
+
+export type ReplaceabilityLevel =
+  | "full"
+  | "text-only"
+  | "formatting-only"
+  | "preserve-only"
+  | "blocked";
+
+export interface Replaceability {
+  readonly level: ReplaceabilityLevel;
+  readonly reason?: string;
+}
+
+export interface SemanticScopeAudit {
+  readonly source: "runtime" | "import" | "host" | "agent";
+  readonly derivedFrom?: readonly string[];
+  readonly confidence?: "high" | "medium" | "low";
+}
+
+/**
+ * A fully compiled semantic scope. All projection fields are derived from
+ * the runtime at compile time (S1 — scopes reference truth; they are not
+ * truth).
+ *
+ * `partial: true` indicates at least one projection field degraded because
+ * its upstream input (formatting seam, geometry envelope, layout graph) was
+ * unavailable at compile time. Consumers treat this as a read-useful /
+ * write-unsafe signal.
+ *
+ * `classifications` carries host-supplied domain tags for the scope (for
+ * example: CLM hosts supply `"clause"`, `"domain:legal"`, `"label:Liability"`
+ * as classifications on a paragraph marker-backed by a clause overlay
+ * scope). The compiler does not interpret classification strings — it
+ * only surfaces them. Consumers route / filter / render on them.
+ */
+export interface SemanticScope {
+  readonly handle: ScopeHandle;
+  readonly kind: SemanticScopeKind;
+  readonly classifications: readonly string[];
+  readonly content: SemanticScopeContent;
+  readonly formatting: SemanticScopeFormatting;
+  readonly layout: SemanticScopeLayout;
+  readonly geometry: SemanticScopeGeometry;
+  readonly workflow: SemanticScopeWorkflow;
+  readonly replaceability: Replaceability;
+  readonly audit: SemanticScopeAudit;
+  readonly partial?: boolean;
+}
+
+/* -------------------------------------------------------------------------
+ * Bundle / replacement / validation / audit shapes
+ *
+ * Declared in Slice 1 so downstream layers (AI API, review-bundle) can
+ * reference the types without creating a churn point when later slices
+ * implement them. Implementation lands in Slice 3 (bundle), Slice 4
+ * (ValidationResult), Slice 5 (replacement + audit).
+ * ---------------------------------------------------------------------- */
+
+export interface ScopeBundleNeighborhood {
+  readonly previousScopeId?: string;
+  readonly nextScopeId?: string;
+  readonly parentScopeId?: string;
+  readonly siblingScopeIds?: readonly string[];
+}
+
+/**
+ * Agent-authored explanation attached to a scope via
+ * `ai.attachExplanation`. Read back through `ScopeBundleEvidence` so the
+ * write-side + read-side stay symmetric (adversarial-close item 1).
+ */
+export interface AIExplanationSummary {
+  readonly explanationId: string;
+  readonly text: string;
+  readonly createdAtUtc?: string;
+}
+
+/**
+ * Agent-authored issue attached to a scope via `ai.createIssue`. Same
+ * read-side-symmetry rationale as `AIExplanationSummary`.
+ */
+export interface AIIssueSummary {
+  readonly issueId: string;
+  readonly summary: string;
+  readonly severity: "info" | "warning" | "error";
+  readonly status: "open" | "resolved";
+  readonly createdAtUtc?: string;
+}
+
+export interface ScopeBundleEvidence {
+  readonly formattingSummary?: string;
+  readonly reviewItemIds?: readonly string[];
+  readonly overlappingWorkflowScopeIds?: readonly string[];
+  readonly compatibilityFlags?: readonly string[];
+  /**
+   * Agent-authored explanations on this scope, read back from Layer-06
+   * metadata entries keyed by `metadataId: "ai.explanation"`. Adversarial-
+   * close 2026-04-22 read-side join: the compiler previously wrote
+   * explanations but did not surface them back through `getScopeBundle`.
+   */
+  readonly aiExplanations?: readonly AIExplanationSummary[];
+  /**
+   * Agent-authored issues on this scope, read back from Layer-06
+   * metadata entries keyed by `metadataId: "ai.issue"`. Same adversarial-
+   * close read-side-symmetry rationale.
+   */
+  readonly aiIssues?: readonly AIIssueSummary[];
+}
+
+export interface ScopeBundle {
+  readonly scope: SemanticScope;
+  readonly neighborhood: ScopeBundleNeighborhood;
+  readonly evidence: ScopeBundleEvidence;
+  readonly generatedAtUtc: string;
+}
+
+export type ReplacementOperationKind =
+  | "replace"
+  | "insert-before"
+  | "insert-after"
+  | "split"
+  | "annotate";
+
+export interface ReplacementPreservePolicy {
+  readonly numbering?: boolean;
+  readonly paragraphStyle?: boolean;
+  readonly runFormatting?: boolean;
+  readonly comments?: boolean;
+  readonly revisions?: boolean;
+  readonly bookmarks?: boolean;
+}
+
+export interface ReplacementScope {
+  readonly targetHandle: ScopeHandle;
+  readonly operation: ReplacementOperationKind;
+  readonly proposedContent: {
+    readonly kind: "text" | "structured";
+    /** Present when `kind === "text"` — flat text replacement. */
+    readonly text?: string;
+    /**
+     * Present when `kind === "structured"`. Typed as `unknown` at the
+     * plain-value boundary because consumers that serialise a
+     * `ReplacementScope` across transports (Yjs / MCP / storage) don't
+     * need the full L02 `BlockNode` type graph at the use site. It also
+     * lets adjacent payloads (metadata-audit annotations, etc.) reuse
+     * the field. Runtime consumers (paragraph.compileReplacement,
+     * DocumentRuntime.applyScopeReplacement) narrow via
+     * `isStructuredReplacementContent` before trusting the shape as a
+     * `CanonicalDocumentFragment`.
+     */
+    readonly structured?: unknown;
+  };
+  readonly preserve?: ReplacementPreservePolicy;
+  readonly reason?: string;
+  readonly proposedAtUtc: string;
+}
+
+/**
+ * Structural guard for `proposedContent.structured` when it carries a
+ * fragment payload (L02's `CanonicalDocumentFragment`). Callers that
+ * need to dispatch the fragment through the runtime narrow via this
+ * predicate before trusting the shape.
+ */
+export interface StructuredReplacementContent {
+  readonly blocks: ReadonlyArray<unknown>;
+}
+
+export function isStructuredReplacementContent(
+  value: unknown,
+): value is StructuredReplacementContent {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Array.isArray((value as { blocks?: unknown }).blocks)
+  );
+}
+
+export interface ValidationIssue {
+  readonly code: string;
+  readonly message: string;
+  readonly source: "guard" | "preserve" | "compat" | "policy";
+}
+
+export interface ValidationApproval {
+  readonly required: boolean;
+  readonly reason?: string;
+}
+
+/**
+ * Composed verdict from workflow guard + preservation boundaries +
+ * compatibility posture + AI policy. Slice 4 implements the composer;
+ * Slice 5 consumes it before any apply.
+ */
+export interface ValidationResult {
+  readonly safe: boolean;
+  readonly blockedReasons: readonly string[];
+  readonly warnings: readonly ValidationIssue[];
+  readonly approval?: ValidationApproval;
+}
+
+/**
+ * Plain-value description of the runtime operations a replacement
+ * lowers to. Produced by Slice 5's per-kind `compileReplacement(scope,
+ * proposed)` and consumed by `DocumentRuntime.applyScopeReplacement`.
+ * Kept narrow — one step per mutation — so the audit bundle's
+ * `compiledOperations` is a faithful ledger of what the runtime did.
+ */
+export type RuntimeOperationStepKind =
+  | "text-replace"
+  | "text-insert-tracked"
+  | "text-delete-tracked"
+  | "fragment-replace";
+
+export interface RuntimeOperationStep {
+  readonly kind: RuntimeOperationStepKind;
+  /** Human-readable one-line description; used in audit `compiledOperations`. */
+  readonly summary: string;
+  /**
+   * Document-coordinate range the step operates on. Absent for steps
+   * that target the scope as a whole.
+   */
+  readonly range?: {
+    readonly from: number;
+    readonly to: number;
+  };
+  /** New text for text-replace / text-insert-tracked. */
+  readonly text?: string;
+  /**
+   * `CanonicalDocumentFragment`-shaped payload for `fragment-replace`.
+   * Plain-value boundary (S9) — no live references; safe to serialise.
+   * Consumers narrow to `CanonicalDocumentFragment` at the runtime
+   * boundary (`DocumentRuntime.applyScopeReplacement`).
+   */
+  readonly fragment?: StructuredReplacementContent;
+}
+
+export interface RuntimeOperationPlan {
+  readonly scopeId: string;
+  readonly targetKind: SemanticScopeKind;
+  readonly operation: ReplacementOperationKind;
+  readonly steps: readonly RuntimeOperationStep[];
+  readonly preserve?: ReplacementPreservePolicy;
+  /** Posture the apply pipeline should dispatch under. */
+  readonly posture: "direct-edit" | "suggest-mode";
+}
+
+export interface ScopeActionAudit {
+  readonly actionId: string;
+  readonly actorId: string;
+  readonly origin: "ui" | "agent" | "host";
+  readonly documentHashBefore: string;
+  readonly documentHashAfter?: string;
+  readonly targetScopeSnapshot: SemanticScope;
+  readonly proposed: ReplacementScope;
+  readonly compiledOperations: readonly {
+    readonly kind: string;
+    readonly summary: string;
+  }[];
+  readonly validation: ValidationResult;
+  readonly emittedAtUtc: string;
+}
+
+/* -------------------------------------------------------------------------
+ * Debug projector
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Debug-channel projector entry produced per compiled scope. Consumed by
+ * the runtime `DebugInspectorSnapshot.scopes.compilerView` (wired in a
+ * follow-up slice — Slice 1 emits the entries; snapshot-side wiring is a
+ * cross-surface edit deferred to the next layer-local commit).
+ */
+export interface ScopeCompilerDebugEntry {
+  readonly scopeId: string;
+  readonly kind: SemanticScopeKind;
+  readonly provenance: ScopeProvenance;
+  readonly partial: boolean;
+  readonly projectionFields: {
+    readonly content: boolean;
+    readonly formatting: boolean;
+    readonly layout: boolean;
+    readonly geometry: boolean;
+    readonly workflow: boolean;
+  };
+  readonly compiledAtUtc: string;
+}