@beyondwork/docx-react-component 1.0.75 → 1.0.77

package/src/runtime/scopes/resolve-reference.ts

@@ -1,16 +1,35 @@
 /**
- * Slice 3 — reference resolution.
+ * Reference resolution + position queries.
  *
- * Takes an agent-supplied `ScopeReference` hint + a live document and
- * returns either a resolved `ScopeHandle`, a list of candidate handles
- * (ambiguous), a detached placeholder (scopeId was once valid), or a
- * `not-found`.
+ * Two distinct surfaces live in this module now, matching the two
+ * distinct semantics (KI-P9 fix):
  *
- * Deterministic hint kinds — `scope-id`, `semantic-path`, `offset`,
- * `range` — all resolve live today. Natural-language hints return a
- * `partial` result with `confidence: "low"`; a richer NL matcher lives
- * in a later slice (the AI API will keep the function at status
- * `partial` until then).
+ * 1. `resolveReference(ref)` — **identity lookup**. Takes a durable
+ *    `ScopeReference` (`scope-id`, `semantic-path`, or
+ *    `natural-language` hint) and returns the scope it names. Safe
+ *    across mutations: `scope-id` survives text replaces; missing
+ *    references return typed `not-found` / `detached`. Callers that
+ *    hold a `ScopeReference` across a mutation window should only ever
+ *    be holding one of these durable kinds.
+ *
+ * 2. `queryScopeAtPosition(at)` / `queryScopeInRange(from, to)` —
+ *    **one-shot positional queries**. Return a `ScopeHandle | null`
+ *    against the *current* document state. The caller's next use of
+ *    the returned handle MUST be through its `scopeId` — the position
+ *    is consumed by the query and never round-trips as a reference.
+ *    This is the click-to-scope / hit-test / selection-to-scope
+ *    surface. Positions that lived at time T1 are meaningless at time
+ *    T2 after any intervening mutation, so these functions refuse to
+ *    be part of the stored-reference vocabulary.
+ *
+ * Before 2026-04-24, `ScopeReference` had `offset` and `range` variants
+ * that flowed through `resolveReference` with the same
+ * `{status:"resolved", handle, confidence}` shape as identity lookups.
+ * That conflation is the KI-P9 trap — documented in
+ * `docs/testing/scopes.md §6c` and `KNOWN-ISSUES.md` KI-P9. Removed.
+ *
+ * Natural-language hints continue to resolve through `resolveReference`
+ * with `confidence: "low"`; richer NL matching is a later slice.
  */
 
 import type { CanonicalDocument } from "../../model/canonical-document.ts";
@@ -23,11 +42,28 @@ import { buildScopePositionMap, type ScopePositionRange } from "./position-map.t
 import { resolveScopeRange, scopeSpecificity } from "./scope-range.ts";
 import type { ScopeHandle } from "./semantic-scope-types.ts";
 
+/**
+ * Durable references to a scope. Each kind is safe to cache / store /
+ * round-trip through a tool-call boundary and re-resolve after
+ * arbitrary mutations:
+ *
+ *   - `scope-id` — identity primitive. Preserved through text edits;
+ *     returns `not-found` / `detached` cleanly on delete.
+ *   - `semantic-path` — structural path (`body/paragraph/5`). Stable
+ *     when block structure doesn't change; returns `not-found` when
+ *     the path no longer resolves. Fragile on KI-001-class fixtures
+ *     where a neighbour block drop shifts all later indices by 1.
+ *   - `natural-language` — substring heuristic. Always
+ *     `confidence: "low"`; callers must surface that to humans.
+ *
+ * Positional references (`offset`, `range`) are **not** part of this
+ * union — see `queryScopeAtPosition` / `queryScopeInRange` for those.
+ * They are one-shot queries that return a `ScopeHandle | null`; the
+ * position never becomes a stored reference. Cf. KI-P9.
+ */
 export type ScopeReference =
   | { readonly kind: "scope-id"; readonly value: string }
   | { readonly kind: "semantic-path"; readonly path: readonly string[] }
-  | { readonly kind: "offset"; readonly at: number }
-  | { readonly kind: "range"; readonly from: number; readonly to: number }
   | { readonly kind: "natural-language"; readonly hint: string };
 
 export type ResolveReferenceResult =
@@ -161,50 +197,74 @@ function innermostContaining(
   return best?.entry ?? null;
 }
 
-function resolveByOffset(
+/**
+ * Inputs for the one-shot positional query functions. Narrower than
+ * `ResolveReferenceInputs` because the query functions never need NL
+ * overlay labels — they're pure structural lookups.
+ */
+export interface QueryScopePositionInputs {
+  readonly document:
+    | Pick<CanonicalDocument, "content" | "docId" | "review">
+    | CanonicalDocumentEnvelope;
+  readonly overlay?: WorkflowOverlay | null;
+  readonly scopes?: readonly EnumeratedScope[];
+}
+
+/**
+ * Return the innermost scope whose range contains `at` in the current
+ * document state, or `null` if no scope contains the position.
+ *
+ * **One-shot query, not a stored reference.** The returned handle is
+ * the durable object — its `scopeId` may be stored and re-resolved via
+ * `resolveReference({kind:"scope-id", value: handle.scopeId})`. The
+ * input position must NOT be stored; it is meaningful only against the
+ * document state it was queried against. See KI-P9 for the trap this
+ * separation closes.
+ *
+ * Precision: marker-backed handles (workflow / comment / revision
+ * scopes anchored by inline `scope_marker_*` nodes) are returned with
+ * full confidence; derived handles (paragraph / heading / list-item /
+ * field / table etc. enumerated from the canonical tree) are just as
+ * authoritative — the confidence distinction that previously lived on
+ * the `{status:"resolved", confidence}` return went away with
+ * `resolveReference`'s offset/range cases. Callers that need to know
+ * whether the hit is marker-backed can read `handle.provenance`.
+ */
+export function queryScopeAtPosition(
   at: number,
-  scopes: readonly EnumeratedScope[],
-  positionMap: ReturnType<typeof buildScopePositionMap>,
-): ResolveReferenceResult {
+  inputs: QueryScopePositionInputs,
+): ScopeHandle | null {
+  const scopes = scopesFor({ ...inputs, overlay: inputs.overlay ?? null });
+  const positionMap = buildScopePositionMap(inputs.document);
   const hit = innermostContaining(
     scopes,
     positionMap,
     (range) => range.from <= at && at <= range.to,
   );
-  if (!hit) {
-    return { status: "not-found", reason: `no scope contains offset ${at}` };
-  }
-  return {
-    status: "resolved",
-    handle: hit.handle,
-    confidence: hit.handle.provenance === "marker-backed" ? "high" : "medium",
-  };
+  return hit?.handle ?? null;
 }
 
-function resolveByRange(
+/**
+ * Return the innermost scope that fully contains the range `[from, to]`
+ * in the current document state, or `null` if no single scope contains
+ * the whole range. Same one-shot-query semantics as
+ * `queryScopeAtPosition`.
+ */
+export function queryScopeInRange(
   from: number,
   to: number,
-  scopes: readonly EnumeratedScope[],
-  positionMap: ReturnType<typeof buildScopePositionMap>,
-): ResolveReferenceResult {
+  inputs: QueryScopePositionInputs,
+): ScopeHandle | null {
   const low = Math.min(from, to);
   const high = Math.max(from, to);
+  const scopes = scopesFor({ ...inputs, overlay: inputs.overlay ?? null });
+  const positionMap = buildScopePositionMap(inputs.document);
   const hit = innermostContaining(
     scopes,
     positionMap,
     (range) => range.from <= low && high <= range.to,
   );
-  if (!hit) {
-    return {
-      status: "not-found",
-      reason: `no scope fully contains range [${low}, ${high}]`,
-    };
-  }
-  return {
-    status: "resolved",
-    handle: hit.handle,
-    confidence: hit.handle.provenance === "marker-backed" ? "high" : "medium",
-  };
+  return hit?.handle ?? null;
 }
 
 /**
@@ -329,10 +389,6 @@ export function resolveReference(
       return resolveByScopeId(reference.value, scopes, inputs.overlay, positionMap);
     case "semantic-path":
       return resolveBySemanticPath(reference.path, scopes);
-    case "offset":
-      return resolveByOffset(reference.at, scopes, positionMap);
-    case "range":
-      return resolveByRange(reference.from, reference.to, scopes, positionMap);
     case "natural-language":
       return resolveByNaturalLanguage(
         reference.hint,

package/src/session/import/loader-types.ts

@@ -137,6 +137,32 @@ export interface LoadDocxEditorSessionOptions {
    * inspect every marker.
    */
   stripCosmeticMarkers?: boolean;
+  /**
+   * Phase 2 bookmark-strip allowlist. When `stripCosmeticMarkers` is
+   * `true` (the default), the parser's reference scan retains
+   * bookmarks whose name is referenced by a `<w:hyperlink w:anchor>`
+   * or `<w:instrText>` (REF / PAGEREF / NOTEREF / TOC) AND any name
+   * listed here. Use this when the host depends on a stable
+   * host-authored bookmark name (e.g. `placeholder_party_name`,
+   * `signature_block_2`) that the parser's automatic scan cannot
+   * infer is load-bearing.
+   *
+   * Default: `[]` (only the automatic scan retains names).
+   *
+   * Always-retained, regardless of this list:
+   *   - `_Toc*` (when any TOC field exists in the document)
+   *   - `_Ref*` and any other name explicitly cited by a hyperlink
+   *     anchor or REF/PAGEREF/NOTEREF instruction
+   *   - `bw:scope:*` (workflow scope markers — converted to
+   *     first-class scope markers by the parser before strip runs)
+   *   - everything (defensive blanket-retain) when the document
+   *     contains a `<w:dataBinding>` whose xpath could reference
+   *     bookmarks via paths the scanner cannot statically analyze
+   *
+   * See `services/debug/docs/phase-2-bookmark-strip-audit-2026-04-24.md`
+   * for the corpus categorization that informed this contract.
+   */
+  retainedBookmarkNames?: ReadonlyArray<string>;
 }
 
 /**

package/src/session/import/loader.ts

@@ -540,7 +540,12 @@ export async function loadDocxSessionAsync(
         mediaParts,
         mainDocumentPath,
         chartPartLookup,
-        { stripCosmeticMarkers: options.stripCosmeticMarkers !== false },
+        {
+          stripCosmeticMarkers: options.stripCosmeticMarkers !== false,
+          ...(options.retainedBookmarkNames !== undefined
+            ? { retainedBookmarkNames: options.retainedBookmarkNames }
+            : {}),
+        },
       );
     } finally {
       if (options.telemetryBus) setActiveParseTelemetryBus(undefined);
@@ -1313,7 +1318,12 @@ export function loadDocxSessionSync(
         mediaParts,
         mainDocumentPath,
         chartPartLookup,
-        { stripCosmeticMarkers: options.stripCosmeticMarkers !== false },
+        {
+          stripCosmeticMarkers: options.stripCosmeticMarkers !== false,
+          ...(options.retainedBookmarkNames !== undefined
+            ? { retainedBookmarkNames: options.retainedBookmarkNames }
+            : {}),
+        },
       );
     } finally {
       if (options.telemetryBus) setActiveParseTelemetryBus(undefined);

package/src/ui-tailwind/editor-surface/fast-text-edit-lane.ts

@@ -123,7 +123,7 @@ export function createFastTextEditLane(
     const fromRuntime = positionMap.pmToRuntime(fromPm);
     const toRuntime = positionMap.pmToRuntime(toPm);
 
-    pushLaneDebug({
+    const debugEntry = pushLaneDebug({
       opId,
       intent: intent.kind,
       pmFrom: fromPm,
@@ -137,6 +137,7 @@ export function createFastTextEditLane(
     if (options.shouldBailBeforePredict?.(intent, fromRuntime, toRuntime)) {
       const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
       incrementInvalidationCounter(PREDICTED_LANE_COUNTERS.bailBeforePredict);
+      markLaneDebugReconciled(debugEntry, ack.kind, true);
       options.probe?.markReconciled(opId, ack.kind);
       switch (ack.kind) {
         case "equivalent":
@@ -183,6 +184,7 @@ export function createFastTextEditLane(
       op.predictedSelectionHead = view.state.selection.head;
 
       const ack = options.dispatchRuntimeCommand(toRuntimeCommand(intent, opId));
+      markLaneDebugReconciled(debugEntry, ack.kind, false);
       options.probe?.markReconciled(opId, ack.kind);
 
       switch (ack.kind) {
@@ -280,6 +282,14 @@ interface LaneDebugEntry {
   runtimeStorySize: number;
   fromRuntime: number;
   toRuntime: number;
+  /** Dispatch → reconcile observation. Filled by `markLaneDebugReconciled`. */
+  ackKind?: TextCommandAck["kind"];
+  /** Wall-clock ms between `pushLaneDebug` and `markLaneDebugReconciled`. */
+  reconcileMs?: number;
+  /** Whether the lane short-circuited to dispatch-only (no predicted TX). */
+  bailed?: boolean;
+  /** Wall-clock timestamp at push time — used to compute reconcileMs. */
+  startedAtMs: number;
 }
 
 declare global {
@@ -294,19 +304,48 @@ declare global {
  * buffer is capped at 200 entries; consumers can read it from the browser
  * console to diagnose cursor position mismatches between PM and the runtime.
  *
+ * Returns the pushed entry (or `null` when the buffer isn't enabled) so
+ * the caller can mutate it in place with ack-kind + reconcile timing
+ * via `markLaneDebugReconciled` once the runtime dispatch returns.
+ *
  * To enable in the browser console:
  *   window.__DOCX_LANE_DEBUG__ = [];
  * Then type, then:
  *   JSON.stringify(window.__DOCX_LANE_DEBUG__, null, 2)
  */
-function pushLaneDebug(entry: LaneDebugEntry): void {
-  if (typeof window === "undefined") return;
+function pushLaneDebug(
+  entry: Omit<LaneDebugEntry, "startedAtMs">,
+): LaneDebugEntry | null {
+  if (typeof window === "undefined") return null;
   const buffer = window.__DOCX_LANE_DEBUG__;
-  if (!Array.isArray(buffer)) return;
-  buffer.push(entry);
+  if (!Array.isArray(buffer)) return null;
+  const full: LaneDebugEntry = {
+    ...entry,
+    startedAtMs:
+      typeof performance !== "undefined" && typeof performance.now === "function"
+        ? performance.now()
+        : Date.now(),
+  };
+  buffer.push(full);
   if (buffer.length > 200) {
     buffer.splice(0, buffer.length - 200);
   }
+  return full;
+}
+
+function markLaneDebugReconciled(
+  entry: LaneDebugEntry | null,
+  ackKind: TextCommandAck["kind"],
+  bailed: boolean,
+): void {
+  if (!entry) return;
+  entry.ackKind = ackKind;
+  entry.bailed = bailed;
+  const now =
+    typeof performance !== "undefined" && typeof performance.now === "function"
+      ? performance.now()
+      : Date.now();
+  entry.reconcileMs = now - entry.startedAtMs;
 }
 
 function buildTxCompat(

package/src/ui-tailwind/editor-surface/perf-probe.ts

@@ -12,6 +12,9 @@ export type PerfProbeKind =
   | "snapshot.navigation"
   | "pm.rebuild"
   | "pm.decorations"
+  | "pm.decorations.comments"
+  | "pm.decorations.revisions"
+  | "pm.decorations.workflow"
   | "pm.mount"
   | "shell.render"
   | "workspace.chrome"

package/src/ui-tailwind/editor-surface/pm-decorations.ts

@@ -20,9 +20,26 @@ import type {
   WorkflowScope,
 } from "../../api/public-types";
 import { MAIN_STORY_TARGET, storyTargetsEqual } from "../../api/public-types.ts";
+import {
+  incrementInvalidationCounter,
+  recordPerfSample,
+} from "./perf-probe";
 import type { PositionMap } from "./pm-position-map";
 import type { Node as PMNode } from "prosemirror-model";
 
+/**
+ * Cheap wall-clock delta helper for sub-section probes. `performance.now`
+ * is always defined in the browser surface where this runs; the guard
+ * keeps headless Node contexts (tests) from throwing when the global
+ * isn't polyfilled.
+ */
+function nowMs(): number {
+  return typeof performance !== "undefined" &&
+    typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}
+
 type RailDecorationSpec = {
   railKind: "scope" | "candidate" | "blocked";
   className: string;
@@ -394,6 +411,8 @@ export function buildDecorations(
   const lockedPmRanges = collectLockedPmRanges(workflowLockedZones, activeStory, positionMap);
 
   // Walk comment threads and create inline decorations
+  const commentsStartMs = nowMs();
+  let commentCount = 0;
   if (commentModel) {
     for (const thread of commentModel.threads) {
       const cls = getCommentHighlightClass(
@@ -413,11 +432,18 @@ export function buildDecorations(
             "data-comment-id": thread.commentId,
           }),
         );
+        commentCount += 1;
       }
     }
   }
+  recordPerfSample("pm.decorations.comments", nowMs() - commentsStartMs);
+  if (commentCount > 0) {
+    incrementInvalidationCounter("pm.decorations.comments.count", commentCount);
+  }
 
   // Walk revision entries and create inline decorations.
+  const revisionsStartMs = nowMs();
+  let revisionCount = 0;
   // Deletion hiding in clean mode ALWAYS applies, even when showTrackedChanges is off.
   // Visual styling (underlines, colors) only applies when showTrackedChanges is on.
   if (revisionModel) {
@@ -442,6 +468,7 @@ export function buildDecorations(
               "data-revision-id": rev.revisionId,
             }),
           );
+          revisionCount += 1;
         }
         continue;
       }
@@ -477,6 +504,7 @@ export function buildDecorations(
               return el;
             }, { side: 1, key: `${rev.revisionId}-close` }),
           );
+          revisionCount += 1;
         } else if (rev.kind === "deletion") {
           decorations.push(
             Decoration.inline(pmFrom, pmTo, {
@@ -484,6 +512,7 @@ export function buildDecorations(
               "data-revision-id": rev.revisionId,
             }),
           );
+          revisionCount += 1;
         }
         continue;
       }
@@ -511,9 +540,16 @@ export function buildDecorations(
           "data-revision-id": rev.revisionId,
         }),
       );
+      revisionCount += 1;
     }
   }
+  recordPerfSample("pm.decorations.revisions", nowMs() - revisionsStartMs);
+  if (revisionCount > 0) {
+    incrementInvalidationCounter("pm.decorations.revisions.count", revisionCount);
+  }
 
+  const workflowStartMs = nowMs();
+  const workflowDecorationsBefore = decorations.length;
   if (effectiveWorkflowScopes.length > 0) {
     for (const scope of effectiveWorkflowScopes) {
       const scopeStoryTarget = scope.storyTarget ?? MAIN_STORY_TARGET;
@@ -655,6 +691,14 @@ export function buildDecorations(
       }, railRangeCache);
     }
   }
+  recordPerfSample("pm.decorations.workflow", nowMs() - workflowStartMs);
+  const workflowDecorationCount = decorations.length - workflowDecorationsBefore;
+  if (workflowDecorationCount > 0) {
+    incrementInvalidationCounter(
+      "pm.decorations.workflow.count",
+      workflowDecorationCount,
+    );
+  }
 
   return DecorationSet.create(doc, decorations);
 }