@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/workflow/projector.ts

@@ -0,0 +1,127 @@
+/**
+ * Layer-06 Slice 3 — `WorkflowDebugEntry` projector.
+ *
+ * Produces a richer debug snapshot over the workflow overlay, metadata
+ * entries, interaction guard, tamper gate, and AI-action policy. The
+ * runtime's `buildDebugInspectorSnapshot` plugs this projector in when
+ * the `scope` or `warning` telemetry channels are on.
+ *
+ * Contract W-projector (plan §Slice 3): fields are counts and compact
+ * summaries, not full payloads. The projector walks the overlay once;
+ * cost scales linearly with scope + entry count and is acceptable only
+ * on-demand (not every commit).
+ */
+
+import type {
+  InteractionGuardSnapshot,
+  WorkflowMetadataDefinition,
+  WorkflowMetadataEntry,
+  WorkflowOverlay,
+} from "../../api/public-types.ts";
+import {
+  AI_ACTION_POLICIES,
+  type AIActionCategory,
+} from "./ai-action-policy.ts";
+
+export interface WorkflowDebugEntry {
+  readonly overlay: {
+    readonly present: boolean;
+    readonly scopeCount: number;
+    readonly candidateCount: number;
+    /**
+     * Count of `WorkflowMarkupSnapshot.protectedRanges` — the stored,
+     * marker-backed analog of the UI-derived `WorkflowLockedZone`.
+     * Not the runtime derivation from `deriveVisibleWorkflowLockedZones`
+     * (that needs a surface + lives in the UI layer).
+     */
+    readonly protectedRangeCount: number;
+    readonly workItemCount: number;
+    readonly activeWorkItemId: string | null;
+    readonly metadataPersistenceMode: string | null;
+  };
+  readonly metadata: {
+    readonly definitionCount: number;
+    readonly entryCount: number;
+    readonly inlineEntryCount: number;
+    readonly externalEntryCount: number;
+  };
+  readonly scopes: {
+    readonly markerBackedCount: number;
+    readonly overlayOnlyCount: number;
+    readonly detachedCount: number;
+  };
+  readonly guard: {
+    readonly effectiveMode: InteractionGuardSnapshot["effectiveMode"];
+    readonly matchedScopeId: string | null;
+    readonly blockedReasonsCount: number;
+  };
+  readonly aiPolicy: {
+    readonly operationCount: number;
+    readonly categoryCount: number;
+  };
+}
+
+export interface ProjectWorkflowDebugEntryInput {
+  readonly overlay: WorkflowOverlay | null;
+  readonly metadataDefinitions: readonly WorkflowMetadataDefinition[];
+  readonly metadataEntries: readonly WorkflowMetadataEntry[];
+  readonly protectedRangeCount: number;
+  readonly scopeCounts: {
+    readonly markerBacked: number;
+    readonly overlayOnly: number;
+    readonly detached: number;
+  };
+  readonly guard: InteractionGuardSnapshot | null;
+}
+
+export function projectWorkflowDebugEntry(
+  input: ProjectWorkflowDebugEntryInput,
+): WorkflowDebugEntry {
+  const overlay = input.overlay;
+  let inlineEntryCount = 0;
+  let externalEntryCount = 0;
+  for (const entry of input.metadataEntries) {
+    if (entry.metadataPersistence === "external") {
+      externalEntryCount += 1;
+    } else {
+      inlineEntryCount += 1;
+    }
+  }
+
+  const uniqueCategories = new Set<AIActionCategory>();
+  for (const policy of AI_ACTION_POLICIES) {
+    uniqueCategories.add(policy.category);
+  }
+
+  return {
+    overlay: {
+      present: overlay !== null,
+      scopeCount: overlay?.scopes.length ?? 0,
+      candidateCount: overlay?.candidates?.length ?? 0,
+      protectedRangeCount: input.protectedRangeCount,
+      workItemCount: overlay?.workItems?.length ?? 0,
+      activeWorkItemId: overlay?.activeWorkItemId ?? null,
+      metadataPersistenceMode: overlay?.metadataPersistence ?? null,
+    },
+    metadata: {
+      definitionCount: input.metadataDefinitions.length,
+      entryCount: input.metadataEntries.length,
+      inlineEntryCount,
+      externalEntryCount,
+    },
+    scopes: {
+      markerBackedCount: input.scopeCounts.markerBacked,
+      overlayOnlyCount: input.scopeCounts.overlayOnly,
+      detachedCount: input.scopeCounts.detached,
+    },
+    guard: {
+      effectiveMode: input.guard?.effectiveMode ?? "edit",
+      matchedScopeId: input.guard?.matchedScopeId ?? null,
+      blockedReasonsCount: input.guard?.blockedReasons.length ?? 0,
+    },
+    aiPolicy: {
+      operationCount: AI_ACTION_POLICIES.length,
+      categoryCount: uniqueCategories.size,
+    },
+  };
+}

package/src/runtime/{query-scopes.ts → workflow/query-scopes.ts}

@@ -7,9 +7,9 @@ import type {
   WorkflowOverlay,
   WorkflowScope,
   WorkflowWorkItem,
-} from "../api/public-types.ts";
-import type { CanonicalDocument } from "../model/canonical-document.ts";
-import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+} from "../../api/public-types.ts";
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
 import { collectScopeLocations } from "./scope-resolver.ts";
 
 function storyTargetsEqual(a: EditorStoryTarget, b: EditorStoryTarget): boolean {

package/src/runtime/{workflow-rail-segments.ts → workflow/rail/compose.ts}

@@ -10,87 +10,73 @@
  * left-gutter label column and the flat block-tint.
  *
  * The segments are pure reads over canonical state; no DOM, no PM.
+ *
+ * ## Layer boundary rationale (Slice 4 closure note)
+ *
+ * The contents of this module span five data sources: workflow
+ * overlay (L06), page graph (L04 input), anchor index (L05 input),
+ * issue + review-action metadata markup (L06), and suggestion
+ * snapshot (L11 input). That range prompted the adversarial review
+ * to flag the file as "too broad." The answer is: this IS the
+ * integration site for W7 (scope rail page-anchored). Rail
+ * composition is inherently cross-layer — you cannot produce a
+ * page-anchored scope-rail segment without joining workflow state,
+ * page geometry, and anchor rects. Splitting further would push
+ * the join elsewhere and make the W7 contract harder to audit.
+ *
+ * Guard rails instead of split:
+ *   - `collectScopeRailSegments` consumes its inputs through a
+ *     value-typed `CollectScopeRailSegmentsInput` — it does not
+ *     reach back into the runtime.
+ *   - `attachScopeCardModel` consumes an optional `anchorIndex`,
+ *     optional `suggestions` snapshot, optional metadata arrays —
+ *     all opt-in, all value-typed. Callers that don't wire a
+ *     resolver get a card without external-metadata resolution.
+ *   - `buildExternalResolutions` is the ONE async helper; callers
+ *     who don't use external metadata never touch it.
+ *   - No imports from `src/runtime/render` or `src/ui*`. Page
+ *     graph + anchor index come through Layer-04/05 type files,
+ *     not through facet imports.
+ *
+ * If the rail needs to grow (e.g., adding a new metadata family),
+ * the composer extends here. The module is ~500 lines because the
+ * W7 join has ~5 inputs; it will grow slowly, not change shape.
  */
 
 import type {
   EditorAnchorProjection,
-  EditorStoryTarget,
   IssueMetadataValue,
   ReviewActionMetadataValue,
   ScopeCardModel,
-  ScopeMetadataResolver,
   SuggestionGroup,
   SuggestionsSnapshot,
-  WorkflowBlockedCommandReason,
   WorkflowCandidateRange,
-  WorkflowLockedZone,
   WorkflowMetadataMarkup,
   WorkflowScope,
-} from "../api/public-types";
-import { ISSUE_METADATA_ID, REVIEW_ACTION_METADATA_ID } from "../api/public-types";
-import { MAIN_STORY_TARGET, storyTargetsEqual } from "../core/selection/mapping.ts";
-import type { RuntimePageGraph } from "./layout/page-graph.ts";
+} from "../../../api/public-types";
+import { ISSUE_METADATA_ID, REVIEW_ACTION_METADATA_ID } from "../../../api/public-types";
+import { MAIN_STORY_TARGET, storyTargetsEqual } from "../../../core/selection/mapping.ts";
+import type { RuntimePageGraph } from "../../layout/page-graph.ts";
 import type {
-  RenderAnchorIndex,
-  RenderFrameRect,
-} from "./render/render-frame-types.ts";
-
-// ---------------------------------------------------------------------------
-// Public shape
-// ---------------------------------------------------------------------------
-
-export type ScopeRailPosture =
-  | "edit"
-  | "suggest"
-  | "comment"
-  | "view"
-  | "candidate"
-  | "preserve-only"
-  | "blocked-import";
-
-export interface ScopeRailSegment {
-  /** Identifier the chrome uses to sync with the Workflow rail tab. */
-  scopeId: string;
-  /** Visual+accessibility posture keyed off the scope mode or block reason. */
-  posture: ScopeRailPosture;
-  /** Human label; empty string when none was supplied by the host. */
-  label: string;
-  /** Runtime offsets (inclusive from, exclusive to) this segment spans on the active story. */
-  fromOffset: number;
-  toOffset: number;
-  /** Story the segment sits on. */
-  storyTarget: EditorStoryTarget;
-  /** Page index the segment renders on (may span multiple pages; emitted per page). */
-  pageIndex: number;
-  /** Section index derived from the page graph. */
-  sectionIndex: number;
-  /** True when the scope is the active work item. */
-  isActiveWorkItem: boolean;
-  /**
-   * Body-tint rect in overlay-space pixels, populated when the render kernel
-   * is available.  Chrome consumers read this directly instead of
-   * re-projecting per render via the overlay projector.  `null` when the
-   * segment is produced without a kernel (e.g., in tests or before the
-   * facet is bound to a page graph) — consumers fall back to per-render
-   * anchor resolution in that case.
-   */
-  bodyTintRect: RenderFrameRect | null;
-}
-
-// ---------------------------------------------------------------------------
-// Collector input
-// ---------------------------------------------------------------------------
-
-export interface CollectScopeRailSegmentsInput {
-  scopes: readonly WorkflowScope[] | undefined;
-  candidates?: readonly WorkflowCandidateRange[];
-  blockedReasons?: readonly WorkflowBlockedCommandReason[];
-  lockedZones?: readonly WorkflowLockedZone[];
-  activeWorkItemScopeIds?: readonly string[];
-  /** Active story scopes render on; segments for other stories are skipped. */
-  activeStory?: EditorStoryTarget;
-  pageGraph: RuntimePageGraph;
-}
+  AttachScopeCardModelInput,
+  BuildExternalResolutionsInput,
+  BuildExternalResolutionsResult,
+  CollectScopeRailSegmentsInput,
+  ScopeRailPosture,
+  ScopeRailSegment,
+} from "./types.ts";
+
+// Re-export the type surface so consumers that import directly from
+// `./compose.ts` (the historical home) keep compiling. The declarations
+// live in `./types.ts`.
+export type {
+  AttachScopeCardModelInput,
+  BuildExternalResolutionsInput,
+  BuildExternalResolutionsResult,
+  CollectScopeRailSegmentsInput,
+  ScopeRailPosture,
+  ScopeRailSegment,
+};
 
 // ---------------------------------------------------------------------------
 // Entry point
@@ -293,69 +279,7 @@ function resolveScopePosture(scope: WorkflowScope): ScopeRailPosture {
 // ---------------------------------------------------------------------------
 // Scope card projection (P1b — consumed by ref.layout.getAllScopeCardModels)
 // ---------------------------------------------------------------------------
-
-export interface AttachScopeCardModelInput {
-  /**
-   * Segments produced by `collectScopeRailSegments`. The card model
-   * keys off segments so per-scope card state stays aligned with the
-   * rail stripe rendering.
-   */
-  segments: readonly ScopeRailSegment[];
-  /**
-   * Original workflow scopes — used to resolve `workItemId` for each
-   * segment (the segment shape predates workItemId passthrough).
-   * Optional; when absent, cards drop `workItemId` and issue matching
-   * falls back to scope-id only.
-   */
-  scopes?: readonly WorkflowScope[];
-  /**
-   * Workflow metadata markup from `WorkflowMarkupSnapshot.metadata`.
-   * Entries with `metadataId === ISSUE_METADATA_ID` that match a
-   * segment's `workItemId` or `scopeId` attach as the card's issue.
-   */
-  metadata?: readonly WorkflowMetadataMarkup[];
-  /**
-   * Optional anchor index used to resolve each card's
-   * `primaryAnchorRect`. When omitted, cards are produced without
-   * rects — chrome consumers fall back to on-render positioning.
-   */
-  anchorIndex?: RenderAnchorIndex | null;
-  /**
-   * R3 — suggestion snapshot. Groups whose `issueId` matches the
-   * scope's issue attach as `ScopeCardModel.suggestionGroups`; their
-   * ids land in `suggestionGroupIds` as a convenience for consumers
-   * that want a flat lookup.
-   */
-  suggestions?: SuggestionsSnapshot | null;
-  /**
-   * K1-light — review-action markup. Entries with
-   * `metadataId === REVIEW_ACTION_METADATA_ID` whose coerced value's
-   * `issueId` matches the scope's issue attach newest-first as
-   * `ScopeCardModel.reviewActions`.
-   */
-  reviewActionMetadata?: readonly WorkflowMetadataMarkup[];
-  /**
-   * K2 — candidate ranges. Any entry with `source: "ai"` whose
-   * offset range overlaps the segment flips `agentPending` to true.
-   */
-  candidates?: readonly WorkflowCandidateRange[];
-  /**
-   * Pre-resolved external metadata values, keyed by entryId.  When an
-   * entry in `metadata` or `reviewActionMetadata` has
-   * `metadataPersistence === "external"` and its inline `value` is
-   * undefined, this map supplies the resolved value (fetched by the caller
-   * via `ScopeMetadataResolver.resolve`).
-   *
-   * Entries absent from the map render as if the metadata had no value —
-   * the card still shows the scope but drops the issue row, consistent with
-   * how malformed metadata is handled today.
-   *
-   * NOTE: The facet's `getAllScopeCardModels()` does NOT populate this.
-   * Callers that need resolved values build the map via
-   * `buildExternalResolutions()` and call `attachScopeCardModel()` directly.
-   */
-  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>;
-}
+// `AttachScopeCardModelInput` lives in `./types.ts` (re-exported above).
 
 /**
  * Project rail segments into per-scope `ScopeCardModel` values.
@@ -570,28 +494,8 @@ function coerceIssueValue(
 // buildExternalResolutions — caller utility for pre-resolving external refs
 // ---------------------------------------------------------------------------
 
-/**
- * Structured result from `buildExternalResolutions`.  Callers that previously
- * consumed the return value as a `Map` directly must now destructure `.resolutions`.
- */
-export interface BuildExternalResolutionsResult {
-  /**
-   * Resolved values keyed by `entryId`.  Suitable for passing into
-   * `AttachScopeCardModelInput.externalResolutions`.
-   */
-  resolutions: Map<string, { value: Record<string, unknown>; version?: number }>;
-  /**
-   * Detected version mismatches.  Non-empty only when the caller passes
-   * `detectConflicts: true`.  Each record includes both sides' value +
-   * version so the caller can emit a `metadata_conflict_detected` event.
-   */
-  conflicts: Array<{
-    scopeId?: string;
-    entryId?: string;
-    embedded: { value?: Record<string, unknown>; version?: number } | null;
-    external: { value?: Record<string, unknown>; version?: number } | null;
-  }>;
-}
+// `BuildExternalResolutionsResult` + `BuildExternalResolutionsInput`
+// live in `./types.ts` (re-exported above).
 
 /**
  * Pre-resolve every external-mode metadata entry's value via the supplied
@@ -615,18 +519,9 @@ export interface BuildExternalResolutionsResult {
  * The layout facet's `getAllScopeCardModels()` does NOT call this — it is a
  * React-layer concern where async is normal.
  */
-export async function buildExternalResolutions(input: {
-  metadata: readonly WorkflowMetadataMarkup[];
-  reviewActionMetadata?: readonly WorkflowMetadataMarkup[];
-  resolver: ScopeMetadataResolver;
-  /**
-   * When `true`, the helper compares each external entry's embedded
-   * `metadataVersion` against the resolver-returned version and records a
-   * conflict for every mismatch.  Absent / `false` → `conflicts` is always
-   * empty (backwards-compatible default).
-   */
-  detectConflicts?: boolean;
-}): Promise<BuildExternalResolutionsResult> {
+export async function buildExternalResolutions(
+  input: BuildExternalResolutionsInput,
+): Promise<BuildExternalResolutionsResult> {
   const externalEntries = [
     ...input.metadata,
     ...(input.reviewActionMetadata ?? []),

package/src/runtime/workflow/rail/types.ts

@@ -0,0 +1,198 @@
+/**
+ * Scope-rail public types (declarations).
+ *
+ * Physical home for the rail shape contracts. `./compose.ts` imports
+ * from here and re-exports for backward compatibility with consumers
+ * that import directly from the composer. Refactor/06 Slice 1 created
+ * the file as a re-export facade; Slice-3 cleanup migrated the
+ * declarations so the split is real.
+ */
+
+import type {
+  EditorStoryTarget,
+  ScopeCardModel,
+  ScopeMetadataResolver,
+  SuggestionsSnapshot,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
+  WorkflowLockedZone,
+  WorkflowMetadataMarkup,
+  WorkflowScope,
+} from "../../../api/public-types.ts";
+import type { RuntimePageGraph } from "../../layout/page-graph.ts";
+import type {
+  RenderAnchorIndex,
+  RenderFrameRect,
+} from "../../render/render-frame-types.ts";
+
+/**
+ * Visual+accessibility posture keyed off the scope mode or block reason.
+ */
+export type ScopeRailPosture =
+  | "edit"
+  | "suggest"
+  | "comment"
+  | "view"
+  | "candidate"
+  | "preserve-only"
+  | "blocked-import";
+
+export interface ScopeRailSegment {
+  /** Identifier the chrome uses to sync with the Workflow rail tab. */
+  scopeId: string;
+  /** Visual+accessibility posture keyed off the scope mode or block reason. */
+  posture: ScopeRailPosture;
+  /** Human label; empty string when none was supplied by the host. */
+  label: string;
+  /** Runtime offsets (inclusive from, exclusive to) this segment spans on the active story. */
+  fromOffset: number;
+  toOffset: number;
+  /** Story the segment sits on. */
+  storyTarget: EditorStoryTarget;
+  /** Page index the segment renders on (may span multiple pages; emitted per page). */
+  pageIndex: number;
+  /** Section index derived from the page graph. */
+  sectionIndex: number;
+  /** True when the scope is the active work item. */
+  isActiveWorkItem: boolean;
+  /**
+   * Body-tint rect in overlay-space pixels, populated when the render kernel
+   * is available.  Chrome consumers read this directly instead of
+   * re-projecting per render via the overlay projector.  `null` when the
+   * segment is produced without a kernel (e.g., in tests or before the
+   * facet is bound to a page graph) — consumers fall back to per-render
+   * anchor resolution in that case.
+   */
+  bodyTintRect: RenderFrameRect | null;
+}
+
+export interface CollectScopeRailSegmentsInput {
+  scopes: readonly WorkflowScope[] | undefined;
+  candidates?: readonly WorkflowCandidateRange[];
+  blockedReasons?: readonly WorkflowBlockedCommandReason[];
+  lockedZones?: readonly WorkflowLockedZone[];
+  activeWorkItemScopeIds?: readonly string[];
+  /** Active story scopes render on; segments for other stories are skipped. */
+  activeStory?: EditorStoryTarget;
+  pageGraph: RuntimePageGraph;
+}
+
+export interface AttachScopeCardModelInput {
+  /**
+   * Segments produced by `collectScopeRailSegments`. The card model
+   * keys off segments so per-scope card state stays aligned with the
+   * rail stripe rendering.
+   */
+  segments: readonly ScopeRailSegment[];
+  /**
+   * Original workflow scopes — used to resolve `workItemId` for each
+   * segment (the segment shape predates workItemId passthrough).
+   * Optional; when absent, cards drop `workItemId` and issue matching
+   * falls back to scope-id only.
+   */
+  scopes?: readonly WorkflowScope[];
+  /**
+   * Workflow metadata markup from `WorkflowMarkupSnapshot.metadata`.
+   * Entries with `metadataId === ISSUE_METADATA_ID` that match a
+   * segment's `workItemId` or `scopeId` attach as the card's issue.
+   */
+  metadata?: readonly WorkflowMetadataMarkup[];
+  /**
+   * Optional anchor index used to resolve each card's
+   * `primaryAnchorRect`. When omitted, cards are produced without
+   * rects — chrome consumers fall back to on-render positioning.
+   */
+  anchorIndex?: RenderAnchorIndex | null;
+  /**
+   * R3 — suggestion snapshot. Groups whose `issueId` matches the
+   * scope's issue attach as `ScopeCardModel.suggestionGroups`; their
+   * ids land in `suggestionGroupIds` as a convenience for consumers
+   * that want a flat lookup.
+   */
+  suggestions?: SuggestionsSnapshot | null;
+  /**
+   * K1-light — review-action markup. Entries with
+   * `metadataId === REVIEW_ACTION_METADATA_ID` whose coerced value's
+   * `issueId` matches the scope's issue attach newest-first as
+   * `ScopeCardModel.reviewActions`.
+   */
+  reviewActionMetadata?: readonly WorkflowMetadataMarkup[];
+  /**
+   * K2 — candidate ranges. Any entry with `source: "ai"` whose
+   * offset range overlaps the segment flips `agentPending` to true.
+   */
+  candidates?: readonly WorkflowCandidateRange[];
+  /**
+   * Pre-resolved external metadata values, keyed by entryId.  When an
+   * entry in `metadata` or `reviewActionMetadata` has
+   * `metadataPersistence === "external"` and its inline `value` is
+   * undefined, this map supplies the resolved value (fetched by the caller
+   * via `ScopeMetadataResolver.resolve`).
+   *
+   * Entries absent from the map render as if the metadata had no value —
+   * the card still shows the scope but drops the issue row, consistent with
+   * how malformed metadata is handled today.
+   *
+   * NOTE: The facet's `getAllScopeCardModels()` does NOT populate this.
+   * Callers that need resolved values build the map via
+   * `buildExternalResolutions()` and call `attachScopeCardModel()` directly.
+   */
+  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>;
+}
+
+/**
+ * Structured result from `buildExternalResolutions`.  Callers that previously
+ * consumed the return value as a `Map` directly must now destructure `.resolutions`.
+ */
+export interface BuildExternalResolutionsResult {
+  /**
+   * Resolved values keyed by `entryId`.  Suitable for passing into
+   * `AttachScopeCardModelInput.externalResolutions`.
+   */
+  resolutions: Map<string, { value: Record<string, unknown>; version?: number }>;
+  /**
+   * Detected version mismatches.  Non-empty only when the caller passes
+   * `detectConflicts: true`.  Each record includes both sides' value +
+   * version so the caller can emit a `metadata_conflict_detected` event.
+   */
+  conflicts: Array<{
+    scopeId?: string;
+    entryId?: string;
+    embedded: { value?: Record<string, unknown>; version?: number } | null;
+    external: { value?: Record<string, unknown>; version?: number } | null;
+  }>;
+}
+
+export interface BuildExternalResolutionsInput {
+  metadata: readonly WorkflowMetadataMarkup[];
+  reviewActionMetadata?: readonly WorkflowMetadataMarkup[];
+  resolver: ScopeMetadataResolver;
+  /**
+   * When `true`, the helper compares each external entry's embedded
+   * `metadataVersion` against the resolver-returned version and records a
+   * conflict for every mismatch.  Absent / `false` → `conflicts` is always
+   * empty (backwards-compatible default).
+   */
+  detectConflicts?: boolean;
+}
+
+
+/**
+ * Layer-06-owned workflow rail / scope-card facet. Implemented by the
+ * workflow coordinator (see `../coordinator.ts`). UI consumers receive
+ * this via `runtime.workflow` and use it in place of the deprecated
+ * layout-facet rail methods.
+ *
+ * Layer-06 Slice 4 (rail-seam inversion) made this the canonical seam
+ * for scope-rail + scope-card composition. The layout facet no longer
+ * exposes these methods.
+ */
+export interface WorkflowFacet {
+  /** Segments for a specific page index. */
+  getRailSegments(pageIndex: number): readonly ScopeRailSegment[];
+  /** All segments across all pages. */
+  getAllRailSegments(): readonly ScopeRailSegment[];
+  /** Full scope-card models with metadata + suggestions attached. */
+  getAllScopeCardModels(): readonly ScopeCardModel[];
+}
+

package/src/runtime/workflow/scope-rail-composer.ts

@@ -0,0 +1,39 @@
+/**
+ * Layer 06 — Scope-rail composer (null-input wrapper).
+ *
+ * Thin wrapper over `collectScopeRailSegments` in `./rail/compose.ts`.
+ * Accepts a possibly-null workflow input + a page graph, returns
+ * `ScopeRailSegment[]`. Returns `[]` when the caller has no overlay
+ * yet so downstream iteration never null-checks.
+ *
+ * History: originally parked in `src/runtime/geometry/project-anchors.ts`
+ * by refactor/05 Slice 2b as a transitional home. Moved here by
+ * refactor/06 (post-CLOSURE additive) per architecture 06's
+ * "Code that lives here" table — L06 is the canonical owner of scope-
+ * rail composition, and this is the null-input boundary.
+ *
+ * W9 purity: imports only sibling `./rail/compose.ts`.
+ */
+
+import type { RuntimePageGraph } from "../layout/page-graph.ts";
+import {
+  collectScopeRailSegments,
+  type CollectScopeRailSegmentsInput,
+  type ScopeRailSegment,
+} from "./rail/compose.ts";
+
+export function collectScopeRailSegmentsForQuery(
+  input:
+    | Omit<CollectScopeRailSegmentsInput, "pageGraph">
+    | null
+    | undefined,
+  graph: RuntimePageGraph,
+): ScopeRailSegment[] {
+  if (!input) {
+    // No overlay / no workflow input is a legitimate state — documents
+    // open without an overlay until the host calls `setWorkflowOverlay`
+    // or `addScope`. Callers iterate over an empty array in that case.
+    return [];
+  }
+  return collectScopeRailSegments({ ...input, pageGraph: graph });
+}

package/src/runtime/{scope-resolver.ts → workflow/scope-resolver.ts}

@@ -3,9 +3,9 @@ import type {
   DocumentRootNode,
   InlineNode,
   ParagraphNode,
-} from "../model/canonical-document.ts";
-import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
-import type { EditorAnchorProjection } from "../api/public-types.ts";
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { EditorAnchorProjection } from "../../api/public-types.ts";
 
 export interface ResolvedScopeLocation {
   scopeId: string;