@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/scopes/compiler-service.ts

@@ -0,0 +1,431 @@
+/**
+ * Slice 7 adversarial-closure pass — Layer 8 compiler-service facade.
+ *
+ * A single runtime-side entry point for compiler orchestration. Before
+ * this module, v3 adapters each reconstructed the enumerate + compile
+ * + position-map dance in isolation:
+ *
+ *   const doc = runtime.getCanonicalDocument();
+ *   const overlay = runtime.getWorkflowOverlay();
+ *   const paragraphIndexByBlockIndex = buildParagraphIndexMap(doc);
+ *   for (const entry of enumerateScopes(doc, { overlay })) {
+ *     const scope = compileScope(entry, {...});
+ *     ...
+ *   }
+ *
+ * The duplication drifted easily — different files rebuilt the setup
+ * with subtly different option threading, and "boundary" was a
+ * maintenance claim more than a shape.
+ *
+ * The compiler-service consolidates that orchestration. v3 adapters
+ * call `createScopeCompilerService(runtime).{compileAllScopes, compileScopeById,
+ * compileBundleById, applyReplacement, attachExplanation, createIssue}`.
+ * Each call is a fresh compile — no caching across calls (S3
+ * determinism). Within a single call, the paragraph-index-map is
+ * built once and threaded to every `compileScope` invocation.
+ *
+ * The runtime interface is declared narrowly (`CompilerServiceRuntime`)
+ * rather than depending on the full `RuntimeApiHandle`, so the facade
+ * is unit-testable with a plain object and the compiler layer stays
+ * free of upward imports it does not need.
+ */
+
+import type {
+  CompatibilityReport,
+  InteractionGuardSnapshot,
+  ScopeSessionState,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+  WorkflowOverlay,
+} from "./_scope-dependencies.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { TelemetryBus } from "../debug/telemetry-bus.ts";
+import type { AIAction } from "../workflow/ai-action-policy.ts";
+
+import {
+  buildParagraphIndexMap,
+  buildSectionIndexByBlockIndex,
+  compileScope,
+} from "./compile-scope.ts";
+import { compileScopeBundleById } from "./compile-scope-bundle.ts";
+import { enumerateScopes, type EnumeratedScope } from "./enumerate-scopes.ts";
+import {
+  attachExplanation,
+  type AttachExplanationResult,
+} from "./attach-explanation.ts";
+import {
+  createIssue,
+  type CreateIssueResult,
+  type IssueSeverity,
+  type IssueStatus,
+} from "./create-issue.ts";
+import {
+  applyScopeReplacement,
+  type ApplyScopeReplacementResult,
+} from "./replacement/apply.ts";
+import { proposeReplacement } from "./replacement/propose.ts";
+import type {
+  ReplacementOperationKind,
+  ReplacementPreservePolicy,
+  ReplacementScope,
+  RuntimeOperationPlan,
+  ScopeBundle,
+  ScopeHandle,
+  SemanticScope,
+} from "./semantic-scope-types.ts";
+
+/**
+ * Narrow runtime-side interface the compiler-service reads + dispatches
+ * through. Declared inline rather than importing the v3 `RuntimeApiHandle`
+ * because:
+ *
+ *   1. `src/runtime/scopes/` must not import from `src/api/v3/**` (purity
+ *      guard); declaring the shape here keeps the dependency downward.
+ *   2. Unit tests can satisfy this with a plain object — no full runtime
+ *      needed.
+ *   3. Any real `DocumentRuntime` structurally satisfies it because its
+ *      methods carry the same public-types shapes.
+ */
+export interface CompilerServiceRuntime {
+  getCanonicalDocument(): CanonicalDocumentEnvelope;
+  getWorkflowOverlay(): WorkflowOverlay | null;
+  getInteractionGuardSnapshot(): InteractionGuardSnapshot;
+  getCompatibilityReport(): CompatibilityReport;
+  getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  setWorkflowMetadataEntries(entries: readonly WorkflowMetadataEntry[]): void;
+  getSessionState(): ScopeSessionState;
+  applyScopeReplacement(plan: RuntimeOperationPlan): void;
+  debug?: { bus: TelemetryBus };
+}
+
+export interface CompileScopeByIdResult {
+  readonly scope: SemanticScope;
+  readonly document: CanonicalDocumentEnvelope;
+  readonly enumerated: EnumeratedScope;
+}
+
+export interface ApplyReplacementRequest {
+  readonly targetScopeId: string;
+  readonly operation: ReplacementOperationKind;
+  /**
+   * Flat text payload. Shorthand for
+   * `proposedContent: {kind: "text", text}`. Ignored when
+   * `proposedContent` is supplied.
+   */
+  readonly proposedText?: string;
+  /**
+   * Full proposed-content shape. Use this for structured-fragment
+   * replacement (`kind: "structured"` with a
+   * `CanonicalDocumentFragment`-shaped payload). Unblocks /09
+   * `cross-layer-coord-09.md §1.5`: v3 consumers that need to pass a
+   * structured fragment through `ai.applyReplacementScope` supply it
+   * here. Widened 2026-04-22 after L08's structured-fragment runtime
+   * dispatch shipped (see `cross-layer-coord-08.md §8`).
+   */
+  readonly proposedContent?: ReplacementScope["proposedContent"];
+  readonly preserve?: ReplacementPreservePolicy;
+  readonly reason?: string;
+  readonly actionId?: AIAction;
+  readonly actorId: string;
+  readonly origin: "ui" | "agent" | "host";
+  readonly emittedAtUtc: string;
+}
+
+export interface AttachExplanationRequest {
+  readonly scopeId: string;
+  readonly explanation: string;
+  readonly explanationId?: string;
+  readonly createdAtUtc?: string;
+}
+
+export interface CreateIssueRequest {
+  readonly scopeId: string;
+  readonly summary: string;
+  readonly severity?: IssueSeverity;
+  readonly issueId?: string;
+  readonly createdAtUtc?: string;
+  readonly status?: IssueStatus;
+}
+
+export interface ScopeCompilerService {
+  /**
+   * Enumerate + compile every live scope in the document. Per-call the
+   * paragraph-index-map is built once and shared across every compile.
+   * Callers filter / limit on the returned array.
+   */
+  compileAllScopes(): SemanticScope[];
+
+  /**
+   * Resolve a scopeId against the live enumeration + compile it. Returns
+   * null when the id does not enumerate. Also surfaces the raw
+   * `EnumeratedScope` + `document` so callers that need to compose a
+   * downstream operation (e.g. per-kind replacement compile) do not have
+   * to re-enumerate.
+   */
+  compileScopeById(scopeId: string): CompileScopeByIdResult | null;
+
+  /**
+   * Compile a `ScopeBundle` keyed by id. Delegates to
+   * `compileScopeBundleById`; `nowUtc` is caller-supplied per S3
+   * (determinism) — no `new Date()` fallback.
+   */
+  compileBundleById(scopeId: string, nowUtc: string): ScopeBundle | null;
+
+  /**
+   * Build a `ReplacementScope` from a plain request + the resolved
+   * handle. The `proposedAtUtc` stamp is caller-supplied; pass a fixed
+   * reference instant in tests.
+   */
+  buildReplacementScope(
+    targetHandle: ScopeHandle,
+    input: {
+      readonly operation: ReplacementOperationKind;
+      readonly proposedText?: string;
+      readonly preserve?: ReplacementPreservePolicy;
+      readonly reason?: string;
+      readonly proposedAtUtc: string;
+    },
+  ): ReplacementScope;
+
+  /**
+   * Run the full propose → re-validate → compile → apply pipeline and
+   * emit exactly one `ScopeActionAudit` on the `scope` telemetry
+   * channel. Refuses with a typed `ApplyScopeReplacementResult` when
+   * validation is unsafe or compile refuses the kind; no dispatch
+   * happens in those cases.
+   */
+  applyReplacement(request: ApplyReplacementRequest): ApplyScopeReplacementResult;
+
+  /**
+   * Attach an agent-authored explanation via the Layer-06
+   * `attachScopeMetadata` writer. Resolves against the workflow
+   * overlay first, then falls back to a paragraph/heading/list-item
+   * derived-scope resolver (coord-06 §13c). Returns
+   * `{attached: false, reason: "scope-not-resolvable:…"}` for
+   * scopeIds neither path can resolve (e.g. `table:*`, `field:*`,
+   * arbitrary host strings).
+   */
+  attachExplanation(request: AttachExplanationRequest): AttachExplanationResult;
+
+  /**
+   * Create an agent-authored issue on an overlay scope. Same
+   * overlay-only constraint as `attachExplanation`.
+   */
+  createIssue(request: CreateIssueRequest): CreateIssueResult;
+}
+
+/**
+ * Factory for the Layer-08 compiler-service facade.
+ *
+ * Stateless — every call enumerates + compiles fresh. Callers pay the
+ * cost per call; callers that compile the same document repeatedly
+ * within a tight loop should hoist the `compileAllScopes()` result
+ * themselves (the compiler does not internally cache).
+ */
+export function createScopeCompilerService(
+  runtime: CompilerServiceRuntime,
+): ScopeCompilerService {
+  function allEnumerated(): {
+    readonly document: CanonicalDocumentEnvelope;
+    readonly overlay: WorkflowOverlay | null;
+    readonly paragraphIndexByBlockIndex: ReturnType<typeof buildParagraphIndexMap>;
+    readonly sectionIndexByBlockIndex: ReturnType<typeof buildSectionIndexByBlockIndex>;
+    readonly entries: readonly EnumeratedScope[];
+  } {
+    const document = runtime.getCanonicalDocument();
+    const overlay = runtime.getWorkflowOverlay();
+    const paragraphIndexByBlockIndex = buildParagraphIndexMap(document);
+    const sectionIndexByBlockIndex = buildSectionIndexByBlockIndex(document);
+    const enumerateInputs = overlay ? { overlay } : {};
+    const entries = [...enumerateScopes(document, enumerateInputs)];
+    return {
+      document,
+      overlay,
+      paragraphIndexByBlockIndex,
+      sectionIndexByBlockIndex,
+      entries,
+    };
+  }
+
+  return {
+    compileAllScopes(): SemanticScope[] {
+      const {
+        document,
+        overlay,
+        paragraphIndexByBlockIndex,
+        sectionIndexByBlockIndex,
+        entries,
+      } = allEnumerated();
+      const out: SemanticScope[] = [];
+      for (const entry of entries) {
+        const compiled = compileScope(entry, {
+          document,
+          ...(overlay ? { overlay } : {}),
+          paragraphIndexByBlockIndex,
+          sectionIndexByBlockIndex,
+        });
+        if (compiled) out.push(compiled);
+      }
+      return out;
+    },
+
+    compileScopeById(scopeId: string): CompileScopeByIdResult | null {
+      const {
+        document,
+        overlay,
+        paragraphIndexByBlockIndex,
+        sectionIndexByBlockIndex,
+        entries,
+      } = allEnumerated();
+      for (const entry of entries) {
+        if (entry.handle.scopeId !== scopeId) continue;
+        const scope = compileScope(entry, {
+          document,
+          ...(overlay ? { overlay } : {}),
+          paragraphIndexByBlockIndex,
+          sectionIndexByBlockIndex,
+        });
+        if (scope) return { scope, document, enumerated: entry };
+      }
+      return null;
+    },
+
+    compileBundleById(scopeId: string, nowUtc: string): ScopeBundle | null {
+      const document = runtime.getCanonicalDocument();
+      const overlay = runtime.getWorkflowOverlay();
+      // Read-side join — thread metadata entries through so the bundle's
+      // evidence surfaces ai.explanation / ai.issue entries. Write
+      // operations go through `attachScopeMetadata` via this same
+      // runtime surface, so the snapshot is always fresh here.
+      const workflowMetadataEntries = runtime.getWorkflowMetadataSnapshot().entries;
+      return compileScopeBundleById(scopeId, {
+        document,
+        ...(overlay ? { overlay } : {}),
+        nowUtc,
+        catalog: document.styles,
+        workflowMetadataEntries,
+      });
+    },
+
+    buildReplacementScope(targetHandle, input) {
+      return proposeReplacement({
+        targetHandle,
+        operation: input.operation,
+        proposedContent:
+          typeof input.proposedText === "string"
+            ? { kind: "text", text: input.proposedText }
+            : { kind: "text", text: "" },
+        ...(input.preserve ? { preserve: input.preserve } : {}),
+        ...(input.reason ? { reason: input.reason } : {}),
+        proposedAtUtc: input.proposedAtUtc,
+      });
+    },
+
+    applyReplacement(
+      request: ApplyReplacementRequest,
+    ): ApplyScopeReplacementResult {
+      // Resolve + build the ReplacementScope fresh. `applyScopeReplacement`
+      // re-enumerates + re-compiles + re-validates on live state (§7 trap
+      // 2 — never trust a propose-time verdict).
+      const compiled = this.compileScopeById(request.targetScopeId);
+      if (!compiled) {
+        return {
+          applied: false,
+          reason: "scope-not-resolvable",
+          validation: {
+            safe: false,
+            blockedReasons: Object.freeze([
+              `scope-not-resolvable:${request.targetScopeId}`,
+            ]),
+            warnings: Object.freeze([]),
+          },
+        };
+      }
+      // Caller-supplied proposedContent takes precedence (structured-
+      // fragment path); otherwise we fall back to the flat-text
+      // shorthand via proposedText.
+      const proposed = request.proposedContent
+        ? proposeReplacement({
+            targetHandle: compiled.scope.handle,
+            operation: request.operation,
+            proposedContent: request.proposedContent,
+            ...(request.preserve ? { preserve: request.preserve } : {}),
+            ...(request.reason ? { reason: request.reason } : {}),
+            proposedAtUtc: request.emittedAtUtc,
+          })
+        : this.buildReplacementScope(compiled.scope.handle, {
+            operation: request.operation,
+            ...(request.proposedText !== undefined
+              ? { proposedText: request.proposedText }
+              : {}),
+            ...(request.preserve ? { preserve: request.preserve } : {}),
+            ...(request.reason ? { reason: request.reason } : {}),
+            proposedAtUtc: request.emittedAtUtc,
+          });
+      return applyScopeReplacement({
+        sink: {
+          getCanonicalDocument: () => runtime.getCanonicalDocument(),
+          getWorkflowOverlay: () => runtime.getWorkflowOverlay(),
+          getInteractionGuardSnapshot: () =>
+            runtime.getInteractionGuardSnapshot(),
+          getCompatibilityReport: () => runtime.getCompatibilityReport(),
+          applyScopeReplacement: (plan) => runtime.applyScopeReplacement(plan),
+        },
+        proposed,
+        ...(request.actionId ? { actionId: request.actionId } : {}),
+        actorId: request.actorId,
+        origin: request.origin,
+        emittedAtUtc: request.emittedAtUtc,
+        ...(runtime.debug?.bus ? { bus: runtime.debug.bus } : {}),
+      });
+    },
+
+    attachExplanation(
+      request: AttachExplanationRequest,
+    ): AttachExplanationResult {
+      return attachExplanation(
+        {
+          getWorkflowOverlay: () => runtime.getWorkflowOverlay(),
+          getWorkflowMetadataSnapshot: () =>
+            runtime.getWorkflowMetadataSnapshot(),
+          setWorkflowMetadataEntries: (entries) =>
+            runtime.setWorkflowMetadataEntries([...entries]),
+          getCanonicalDocument: () => runtime.getCanonicalDocument(),
+        },
+        {
+          scopeId: request.scopeId,
+          explanation: request.explanation,
+          ...(request.explanationId
+            ? { explanationId: request.explanationId }
+            : {}),
+          ...(request.createdAtUtc
+            ? { createdAtUtc: request.createdAtUtc }
+            : {}),
+        },
+      );
+    },
+
+    createIssue(request: CreateIssueRequest): CreateIssueResult {
+      return createIssue(
+        {
+          getWorkflowOverlay: () => runtime.getWorkflowOverlay(),
+          getWorkflowMetadataSnapshot: () =>
+            runtime.getWorkflowMetadataSnapshot(),
+          setWorkflowMetadataEntries: (entries) =>
+            runtime.setWorkflowMetadataEntries([...entries]),
+          getCanonicalDocument: () => runtime.getCanonicalDocument(),
+        },
+        {
+          scopeId: request.scopeId,
+          summary: request.summary,
+          ...(request.severity ? { severity: request.severity } : {}),
+          ...(request.issueId ? { issueId: request.issueId } : {}),
+          ...(request.createdAtUtc
+            ? { createdAtUtc: request.createdAtUtc }
+            : {}),
+          ...(request.status ? { status: request.status } : {}),
+        },
+      );
+    },
+  };
+}

package/src/runtime/scopes/create-issue.ts

@@ -0,0 +1,107 @@
+/**
+ * Slice 6 — `ai.createIssue` live-with-adapter primitive.
+ *
+ * Creates an agent-authored issue record scoped to a handle by routing
+ * through Layer-06's `attachScopeMetadata` writer. The issue persists
+ * as a `WorkflowMetadataEntry` with `metadataId: "ai.issue"` and
+ * `value: {issueId, summary, severity, status, createdAtUtc}`.
+ *
+ * Issues are metadata records rather than a dedicated overlay section
+ * in this slice — matches the Slice-6 plan's "issue store is a new
+ * section on the workflow overlay" intent without requiring an
+ * overlay-schema minor bump. When CLM workblocks need richer lifecycle
+ * (resolve/reopen transitions, assigned owners), a follow-up sub-slice
+ * promotes issues to a first-class overlay kind and the storage
+ * migrates — the metadataId stays stable so callers don't break.
+ *
+ * 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 resolve against the
+ * canonical document and produce an `ai.issue` entry whose anchor is
+ * the resolver's range output; the result carries
+ * `resolvedFrom: "derived"`. Non-paragraph-like scopeIds still
+ * return `created: false`.
+ */
+
+import type {
+  AttachScopeMetadataResult,
+  MetadataWriterRuntime,
+} from "../workflow/metadata-writer.ts";
+import { attachScopeMetadata } from "../workflow/metadata-writer.ts";
+
+/** Stable metadataId for AI-authored issues. */
+export const AI_ISSUE_METADATA_ID = "ai.issue" as const;
+
+export type IssueSeverity = "info" | "warning" | "error";
+export type IssueStatus = "open" | "resolved";
+
+export interface CreateIssueInput {
+  readonly scopeId: string;
+  readonly summary: string;
+  readonly severity?: IssueSeverity;
+  readonly issueId?: string;
+  readonly createdAtUtc?: string;
+  readonly status?: IssueStatus;
+}
+
+export type CreateIssueResult =
+  | {
+      readonly created: true;
+      readonly issueId: 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 created: false;
+      readonly issueId: 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`.
+       */
+      readonly reason: string;
+    };
+
+export function createIssue(
+  runtime: MetadataWriterRuntime,
+  input: CreateIssueInput,
+): CreateIssueResult {
+  const issueId = input.issueId ?? `issue-${input.scopeId}`;
+  const createdAtUtc = input.createdAtUtc ?? new Date(0).toISOString();
+  const severity: IssueSeverity = input.severity ?? "info";
+  const status: IssueStatus = input.status ?? "open";
+  const writerResult: AttachScopeMetadataResult = attachScopeMetadata(runtime, {
+    scopeId: input.scopeId,
+    metadataId: AI_ISSUE_METADATA_ID,
+    // Entry id is issueId-scoped so multiple issues can co-exist on
+    // one scope (the default attachScopeMetadata entryId would
+    // collide on `${scopeId}::ai.issue`).
+    entryId: `${input.scopeId}::${AI_ISSUE_METADATA_ID}::${issueId}`,
+    value: {
+      issueId,
+      summary: input.summary,
+      severity,
+      status,
+      createdAtUtc,
+    },
+  });
+  if (writerResult.status === "attached") {
+    return {
+      created: true,
+      issueId,
+      entryId: writerResult.entryId,
+      resolvedFrom: writerResult.resolvedFrom,
+    };
+  }
+  return {
+    created: false,
+    issueId,
+    reason: `scope-not-resolvable:${writerResult.scopeId}`,
+  };
+}