@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/scopes/projector.ts

@@ -0,0 +1,49 @@
+/**
+ * Scope-compiler debug projector — Slice 1.
+ *
+ * Given a compiled `SemanticScope`, produce a `ScopeCompilerDebugEntry` that
+ * summarises which projection fields carry data. Intended for consumption
+ * from `DebugInspectorSnapshot.scopes.compilerView` (the snapshot-side
+ * wiring lands in a cross-surface follow-up commit; Slice 1 ships the
+ * producer in isolation so runtime code can consume it without a circular
+ * edit against `src/runtime/debug/types.ts`).
+ */
+
+import type {
+  ScopeCompilerDebugEntry,
+  SemanticScope,
+} from "./semantic-scope-types.ts";
+
+export interface ProjectScopeOptions {
+  readonly nowUtc: string;
+}
+
+function hasValue(obj: object): boolean {
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      const v = (obj as Record<string, unknown>)[key];
+      if (v !== undefined) return true;
+    }
+  }
+  return false;
+}
+
+export function projectScopeDebugEntry(
+  scope: SemanticScope,
+  options: ProjectScopeOptions,
+): ScopeCompilerDebugEntry {
+  return {
+    scopeId: scope.handle.scopeId,
+    kind: scope.kind,
+    provenance: scope.handle.provenance,
+    partial: scope.partial === true,
+    projectionFields: {
+      content: scope.content.text.length > 0,
+      formatting: hasValue(scope.formatting),
+      layout: hasValue(scope.layout),
+      geometry: hasValue(scope.geometry),
+      workflow: scope.workflow.scopeIds.length > 0,
+    },
+    compiledAtUtc: options.nowUtc,
+  };
+}

package/src/runtime/scopes/replaceability.ts

@@ -0,0 +1,87 @@
+/**
+ * Replaceability — structural + provenance driven.
+ *
+ * Returns a `{ level, reason }` pair purely from the scope's kind +
+ * provenance — no vertical vocabulary. Domain-specific replacement
+ * constraints (e.g. "a legal clause must preserve its defined terms
+ * section") are host policy concerns surfaced via the workflow overlay,
+ * NOT hardcoded into the compiler.
+ *
+ * The key structural rule: **marker-backed scopes default to `text-only`**
+ * because replacing beyond the marker boundaries would destroy the
+ * markers themselves. That applies uniformly whether the marker is a
+ * CLM clause, a compliance annotation, or any other host-defined
+ * semantic region.
+ *
+ * Slice 4's `composeScopeValidation` composes this baseline with
+ * workflow guard + preservation + compatibility + AI policy at
+ * validate-time; the replaceability field here is the static baseline
+ * consumers read from the compiled scope.
+ */
+
+import type {
+  Replaceability,
+  SemanticScopeKind,
+  ScopeProvenance,
+} from "./semantic-scope-types.ts";
+
+export function deriveReplaceability(
+  kind: SemanticScopeKind,
+  provenance: ScopeProvenance,
+): Replaceability {
+  if (provenance === "detached") {
+    return {
+      level: "blocked",
+      reason: "scope-detached-requires-rebind",
+    };
+  }
+  // Marker-backed paragraph-like scopes — the marker pair brackets the
+  // scope's identity; a full replace would destroy the markers.
+  // Text-only replacement preserves them.
+  if (
+    provenance === "marker-backed" &&
+    (kind === "paragraph" || kind === "heading" || kind === "list-item")
+  ) {
+    return {
+      level: "text-only",
+      reason: "marker-backed-preserves-anchor",
+    };
+  }
+  switch (kind) {
+    case "paragraph":
+      return { level: "full", reason: "derived-default" };
+    case "heading":
+      return { level: "text-only", reason: "heading-preserves-outline" };
+    case "list-item":
+      return { level: "text-only", reason: "list-item-preserves-numbering" };
+    case "table-cell":
+      return { level: "text-only", reason: "table-cell-preserves-structure" };
+    case "table":
+      return {
+        level: "blocked",
+        reason: "table-replacement-not-yet-implemented",
+      };
+    case "table-row":
+      return {
+        level: "blocked",
+        reason: "table-row-replacement-not-yet-implemented",
+      };
+    case "field":
+      return {
+        level: "preserve-only",
+        reason: "field-result-is-computed-preserve-only",
+      };
+    case "comment-thread":
+      return {
+        level: "preserve-only",
+        reason: "comment-thread-is-review-artifact",
+      };
+    case "revision":
+      return {
+        level: "preserve-only",
+        reason: "revision-open-preserve-only",
+      };
+    default:
+      return { level: "blocked", reason: "kind-not-yet-implemented" };
+  }
+}

package/src/runtime/scopes/replacement/apply.ts

@@ -0,0 +1,228 @@
+/**
+ * Slice 5 — replacement apply pipeline.
+ *
+ * Composition (honouring §7 of the Slice-5 handover):
+ *   1. Re-resolve + re-compile the target scope against live state.
+ *   2. Re-run `composeScopeValidation` — never trust a propose-time
+ *      verdict; Yjs remote or local edits may have moved since propose.
+ *   3. When `validation.safe === false`, refuse with a typed result and
+ *      do NOT dispatch anything.
+ *   4. Compile the per-kind `RuntimeOperationPlan` (no-op kinds land as
+ *      `compile-refused:<kind>` blockers).
+ *   5. Dispatch through `runtimeSink.applyScopeReplacement(plan)`.
+ *   6. Emit exactly one `ScopeActionAudit` on the `scope` telemetry
+ *      channel (S5).
+ *
+ * The "runtimeSink" parameter is a narrow interface rather than
+ * `DocumentRuntime` so the apply pipeline stays testable and doesn't
+ * drag the full runtime surface into the compiler.
+ */
+
+import type { TelemetryBus } from "../../debug/telemetry-bus.ts";
+import type { AIAction } from "../../workflow/ai-action-policy.ts";
+import type {
+  CompatibilityReport,
+  InteractionGuardSnapshot,
+  WorkflowOverlay,
+} from "../_scope-dependencies.ts";
+import type { CanonicalDocumentEnvelope } from "../../../core/state/editor-state.ts";
+
+import { composeScopeValidation } from "../action-validation.ts";
+import { buildParagraphIndexMap, compileScope } from "../compile-scope.ts";
+import { enumerateScopes } from "../enumerate-scopes.ts";
+import type { EnumeratedScope } from "../enumerate-scopes.ts";
+import { emitScopeActionAudit } from "../audit-bundle.ts";
+import { compileReplacement } from "./compile.ts";
+import type {
+  ReplacementScope,
+  RuntimeOperationPlan,
+  ScopeActionAudit,
+  SemanticScope,
+  ValidationResult,
+} from "../semantic-scope-types.ts";
+
+export interface ApplyScopeReplacementSink {
+  readonly getCanonicalDocument: () => CanonicalDocumentEnvelope;
+  readonly getWorkflowOverlay: () => WorkflowOverlay | null;
+  readonly getInteractionGuardSnapshot: () => InteractionGuardSnapshot;
+  readonly getCompatibilityReport: () => CompatibilityReport;
+  readonly applyScopeReplacement: (plan: RuntimeOperationPlan) => void;
+}
+
+export interface ApplyScopeReplacementInputs {
+  readonly sink: ApplyScopeReplacementSink;
+  readonly proposed: ReplacementScope;
+  readonly actionId?: AIAction;
+  readonly actorId: string;
+  readonly origin: "ui" | "agent" | "host";
+  readonly emittedAtUtc: string;
+  readonly bus?: TelemetryBus;
+}
+
+export interface ApplyScopeReplacementResult {
+  readonly applied: boolean;
+  readonly reason?: string;
+  readonly validation: ValidationResult;
+  readonly audit?: ScopeActionAudit;
+  readonly plan?: RuntimeOperationPlan;
+  readonly scope?: SemanticScope;
+}
+
+function documentHash(doc: CanonicalDocumentEnvelope): string {
+  // Cheap structural hash — block-count + total text length. Good enough
+  // for the audit's "something changed" signal; later slices can swap in
+  // a canonical serializer-backed content hash.
+  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}`;
+}
+
+export function applyScopeReplacement(
+  inputs: ApplyScopeReplacementInputs,
+): ApplyScopeReplacementResult {
+  const proposed = inputs.proposed;
+  const docBefore = inputs.sink.getCanonicalDocument();
+  const overlay = inputs.sink.getWorkflowOverlay() ?? undefined;
+
+  const paragraphIndexByBlockIndex = buildParagraphIndexMap(docBefore);
+  let resolvedScope: SemanticScope | null = null;
+  let resolvedEnumerated: EnumeratedScope | null = null;
+  const enumerateInputs = overlay ? { overlay } : {};
+  for (const entry of enumerateScopes(docBefore, enumerateInputs)) {
+    if (entry.handle.scopeId !== proposed.targetHandle.scopeId) continue;
+    const compiled = compileScope(entry, {
+      document: docBefore,
+      ...(overlay ? { overlay } : {}),
+      paragraphIndexByBlockIndex,
+    });
+    if (compiled) {
+      resolvedScope = compiled;
+      resolvedEnumerated = entry;
+      break;
+    }
+  }
+
+  if (!resolvedScope || !resolvedEnumerated) {
+    const validation: ValidationResult = {
+      safe: false,
+      blockedReasons: Object.freeze([
+        `scope-not-resolvable:${proposed.targetHandle.scopeId}`,
+      ]),
+      warnings: Object.freeze([]),
+    };
+    return { applied: false, reason: "scope-not-resolvable", validation };
+  }
+
+  const verdict = composeScopeValidation({
+    scope: resolvedScope,
+    operation: proposed.operation,
+    proposedContent: proposed.proposedContent,
+    runtime: {
+      getInteractionGuardSnapshot: () => inputs.sink.getInteractionGuardSnapshot(),
+      getCompatibilityReport: () => inputs.sink.getCompatibilityReport(),
+    },
+    document: docBefore,
+    enumeratedScope: resolvedEnumerated,
+    ...(inputs.actionId ? { actionId: inputs.actionId } : {}),
+  });
+
+  if (!verdict.safe) {
+    return {
+      applied: false,
+      reason: "validation-blocked",
+      validation: verdict,
+      scope: resolvedScope,
+    };
+  }
+
+  // Suggest-mode guard: the composer tags suggest-mode sessions with a
+  // `guard:suggest-mode` warning; the apply pipeline branches the plan's
+  // posture on that signal.
+  const posture: "direct-edit" | "suggest-mode" =
+    verdict.warnings.some((w) => w.code === "guard:suggest-mode")
+      ? "suggest-mode"
+      : "direct-edit";
+
+  const plan = compileReplacement({
+    scope: resolvedScope,
+    enumeratedScope: resolvedEnumerated,
+    proposed,
+    document: docBefore,
+    posture,
+  });
+  if (!plan) {
+    // Coord-08 §10 — disambiguate the refusal taxonomy. A `null` plan
+    // has two distinct causes that callers (especially CLM agents)
+    // treat differently:
+    //
+    //   (A) The scope kind dispatches nothing at all (e.g. table-cell
+    //       has no flat-range text-replace lowering). Bare suffix:
+    //       `compile-refused:<kind>`. Caller must fall back to
+    //       `attach_explanation`.
+    //   (B) The scope kind IS dispatched but the requested operation
+    //       variant is not implemented on that kind (e.g. paragraph +
+    //       "insert-before" — only "replace" is wired). Suffix:
+    //       `compile-refused:<kind>:operation-not-implemented:<op>`.
+    //       Caller can potentially retry with `operation: "replace"`.
+    //
+    // We can disambiguate on paragraph-like kinds without introspecting
+    // the compiler because we know the operation is the only
+    // non-"replace" refusal arm there. Other kinds (table-cell, field,
+    // …) may reintroduce this disambiguation when they gain per-op
+    // branching.
+    const paragraphLike =
+      resolvedScope.kind === "paragraph" ||
+      resolvedScope.kind === "heading" ||
+      resolvedScope.kind === "list-item";
+    const blocker =
+      paragraphLike && proposed.operation !== "replace"
+        ? `compile-refused:${resolvedScope.kind}:operation-not-implemented:${proposed.operation}`
+        : `compile-refused:${resolvedScope.kind}`;
+    const refused: ValidationResult = {
+      safe: false,
+      blockedReasons: Object.freeze([blocker]),
+      warnings: verdict.warnings,
+    };
+    return {
+      applied: false,
+      reason: "compile-refused",
+      validation: refused,
+      scope: resolvedScope,
+    };
+  }
+
+  const documentHashBefore = documentHash(docBefore);
+
+  inputs.sink.applyScopeReplacement(plan);
+
+  const documentHashAfter = documentHash(inputs.sink.getCanonicalDocument());
+
+  const audit = emitScopeActionAudit({
+    actionId: inputs.actionId ?? "replacement",
+    actorId: inputs.actorId,
+    origin: inputs.origin,
+    documentHashBefore,
+    documentHashAfter,
+    targetScopeSnapshot: resolvedScope,
+    proposed,
+    plan,
+    validation: verdict,
+    emittedAtUtc: inputs.emittedAtUtc,
+    ...(inputs.bus ? { bus: inputs.bus } : {}),
+  });
+
+  return {
+    applied: true,
+    validation: verdict,
+    audit,
+    plan,
+    scope: resolvedScope,
+  };
+}

package/src/runtime/scopes/replacement/compile.ts

@@ -0,0 +1,59 @@
+/**
+ * Slice 5 — replacement compilation dispatcher.
+ *
+ * Lowers a `ReplacementScope` proposal against a compiled
+ * `SemanticScope` into a `RuntimeOperationPlan` that the runtime's
+ * `applyScopeReplacement(plan)` can dispatch. Each scope-kind owns its
+ * own lowering (`compile<Kind>Replacement`); this dispatcher routes on
+ * `scope.kind`. Unknown or unsupported kinds return `null` — the apply
+ * pipeline surfaces that as a `compile-refused:<kind>` blocker.
+ *
+ * S3 determinism: pure function of (enumerated scope, proposed, document,
+ * posture). No clock, no random.
+ */
+
+import type { CanonicalDocumentEnvelope } from "../../../core/state/editor-state.ts";
+import type { EnumeratedScope } from "../enumerate-scopes.ts";
+import type {
+  ReplacementScope,
+  RuntimeOperationPlan,
+  SemanticScope,
+} from "../semantic-scope-types.ts";
+import { compileParagraphReplacement } from "../scope-kinds/paragraph.ts";
+
+export interface CompileReplacementInputs {
+  readonly scope: SemanticScope;
+  readonly enumeratedScope: EnumeratedScope;
+  readonly proposed: ReplacementScope;
+  readonly document: CanonicalDocumentEnvelope;
+  readonly posture: "direct-edit" | "suggest-mode";
+}
+
+export function compileReplacement(
+  inputs: CompileReplacementInputs,
+): RuntimeOperationPlan | null {
+  switch (inputs.scope.kind) {
+    case "paragraph":
+    case "heading":
+    case "list-item": {
+      // Paragraph-like kinds all delegate to the paragraph replacement
+      // compiler — the canonical block range projection is the same.
+      if (
+        inputs.enumeratedScope.kind === "paragraph" ||
+        inputs.enumeratedScope.kind === "heading" ||
+        inputs.enumeratedScope.kind === "list-item"
+      ) {
+        return compileParagraphReplacement(inputs.enumeratedScope, inputs.proposed, {
+          document: inputs.document,
+          posture: inputs.posture,
+        });
+      }
+      return null;
+    }
+    default:
+      // Other kinds land in follow-up steps of Slice 5 (structured,
+      // table-cell, field inline, …). Returning null lets `apply` surface
+      // a typed `compile-refused:<kind>` blocker.
+      return null;
+  }
+}

package/src/runtime/scopes/replacement/propose.ts

@@ -0,0 +1,42 @@
+/**
+ * Slice 5 — replacement proposal.
+ *
+ * Projects a caller-shaped proposal (targetScopeId + operation +
+ * proposed content) into the compiler's `ReplacementScope` plain value.
+ * Pure: no runtime lookup, no document read — the proposed `ScopeHandle`
+ * is supplied by the caller (who has already resolved it).
+ *
+ * Slice-5 note: the `proposedAtUtc` field is caller-supplied rather than
+ * generated here so the compiler stays deterministic (S3). Callers with
+ * a clock should pass their clock reading; callers without one pass the
+ * reference instant they want audited.
+ */
+
+import type {
+  ReplacementOperationKind,
+  ReplacementPreservePolicy,
+  ReplacementScope,
+  ScopeHandle,
+} from "../semantic-scope-types.ts";
+
+export interface ReplacementProposalInput {
+  readonly targetHandle: ScopeHandle;
+  readonly operation: ReplacementOperationKind;
+  readonly proposedContent: ReplacementScope["proposedContent"];
+  readonly preserve?: ReplacementPreservePolicy;
+  readonly reason?: string;
+  readonly proposedAtUtc: string;
+}
+
+export function proposeReplacement(
+  input: ReplacementProposalInput,
+): ReplacementScope {
+  return {
+    targetHandle: input.targetHandle,
+    operation: input.operation,
+    proposedContent: input.proposedContent,
+    ...(input.preserve ? { preserve: input.preserve } : {}),
+    ...(input.reason ? { reason: input.reason } : {}),
+    proposedAtUtc: input.proposedAtUtc,
+  };
+}