@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/runtime/scopes/capabilities.ts

@@ -0,0 +1,316 @@
+/**
+ * Scope action capability projection.
+ *
+ * This module reports what the shipped L08 compiler/runtime can lower today.
+ * It does not validate a specific payload and does not authorize a mutation;
+ * every apply path still re-runs validation and compile.
+ */
+
+import type {
+  ScopeContentControlEvidence,
+  ScopeGeometryEvidence,
+  ScopeLayoutEvidence,
+  ScopeCapabilities,
+  ScopeCapabilityVerdict,
+  SemanticScope,
+  SemanticScopeKind,
+} from "./semantic-scope-types.ts";
+import {
+  MULTI_PARAGRAPH_REPLACEMENT_REFUSAL,
+  multiParagraphReplacementBlockers,
+} from "./multi-paragraph-refusal.ts";
+
+const PARAGRAPH_LIKE = new Set<SemanticScopeKind>([
+  "paragraph",
+  "heading",
+  "list-item",
+]);
+
+const FORMATTING_SUPPORTED = new Set<SemanticScopeKind>([
+  "paragraph",
+  "heading",
+  "list-item",
+  "scope",
+]);
+
+const METADATA_SUPPORTED = new Set<SemanticScopeKind>([
+  "paragraph",
+  "heading",
+  "list-item",
+  "table",
+  "table-row",
+  "table-cell",
+  "scope",
+]);
+
+export interface ScopeCapabilityContext {
+  readonly layout?: ScopeLayoutEvidence;
+  readonly geometry?: ScopeGeometryEvidence;
+  readonly contentControls?: ScopeContentControlEvidence;
+}
+
+function freezeList(values: readonly string[]): readonly string[] {
+  return Object.freeze([...values]);
+}
+
+function supported(
+  reason: string,
+  warnings: readonly string[] = [],
+): ScopeCapabilityVerdict {
+  const hasWarnings = warnings.length > 0;
+  return {
+    supported: true,
+    status: hasWarnings ? "degraded" : "supported",
+    posture: hasWarnings ? "warn-and-proceed" : "supported",
+    reason,
+    ...(hasWarnings ? { warnings: freezeList(warnings) } : {}),
+  };
+}
+
+function unsupported(
+  reason: string,
+  blockers: readonly string[] = [reason],
+  warnings: readonly string[] = [],
+): ScopeCapabilityVerdict {
+  return {
+    supported: false,
+    status: "unsupported",
+    posture: "hard-refusal",
+    reason,
+    blockers: freezeList(blockers),
+    ...(warnings.length > 0 ? { warnings: freezeList(warnings) } : {}),
+  };
+}
+
+function blocked(
+  reason: string,
+  blockers: readonly string[] = [reason],
+): ScopeCapabilityVerdict {
+  return {
+    supported: false,
+    status: "blocked",
+    posture: "hard-refusal",
+    reason,
+    blockers: freezeList(blockers),
+  };
+}
+
+function guardBlocker(scope: SemanticScope): string | null {
+  switch (scope.workflow.effectiveMode) {
+    case "view":
+      return "guard:view-mode-active";
+    case "comment":
+      return "guard:comment-only";
+    case "blocked": {
+      const [first] = scope.workflow.blockedReasons ?? [];
+      return first ? `guard:block-${first}` : "guard:block-scope-overlay";
+    }
+    default:
+      return null;
+  }
+}
+
+function operationRefusal(scope: SemanticScope): string {
+  return `compile-refused:${scope.kind}`;
+}
+
+function contentControlBlockers(
+  context: ScopeCapabilityContext | undefined,
+): readonly string[] {
+  const entries = context?.contentControls?.entries ?? [];
+  if (entries.length === 0) return [];
+  return freezeList(entries.map((entry) => `preserve:content-control:${entry.evidenceId}`));
+}
+
+function evidenceWarnings(
+  context: ScopeCapabilityContext | undefined,
+): readonly string[] {
+  const warnings: string[] = [];
+  if (context?.layout) {
+    if (
+      context.layout.status === "requires-rehydration" ||
+      context.layout.status === "unavailable" ||
+      context.layout.completeness !== "complete"
+    ) {
+      warnings.push(`layout:${context.layout.completeness}`);
+    }
+  }
+  if (context?.geometry) {
+    if (context.geometry.requiresRehydration) {
+      warnings.push("geometry:requires-rehydration");
+    } else if (context.geometry.status === "unavailable") {
+      warnings.push("geometry:unavailable");
+    }
+    if (context.geometry.continuationState?.crossesPageBoundary) {
+      warnings.push("geometry:crosses-page-boundary");
+    }
+  }
+  return freezeList(warnings);
+}
+
+function insertCapability(
+  scope: SemanticScope,
+  edge: "before" | "after",
+  context?: ScopeCapabilityContext,
+): ScopeCapabilityVerdict {
+  const guard = guardBlocker(scope);
+  if (guard) return blocked(guard);
+
+  if (!PARAGRAPH_LIKE.has(scope.kind)) {
+    return unsupported(operationRefusal(scope));
+  }
+
+  if (
+    scope.replaceability.level === "blocked" ||
+    scope.replaceability.level === "preserve-only"
+  ) {
+    const reason = scope.replaceability.reason
+      ? `replaceability:${scope.replaceability.reason}`
+      : `replaceability:${scope.replaceability.level}`;
+    return unsupported(reason);
+  }
+
+  return supported(
+    `compile-supported:paragraph-like:insert-${edge}`,
+    [
+      ...(scope.workflow.effectiveMode === "suggest" ? ["guard:suggest-mode"] : []),
+      ...evidenceWarnings(context),
+    ],
+  );
+}
+
+function replaceTextCapability(
+  scope: SemanticScope,
+  context?: ScopeCapabilityContext,
+): ScopeCapabilityVerdict {
+  const guard = guardBlocker(scope);
+  if (guard) return blocked(guard);
+
+  const contentControls = contentControlBlockers(context);
+  if (contentControls.length > 0) {
+    return blocked("preserve:content-control", contentControls);
+  }
+
+  if (!PARAGRAPH_LIKE.has(scope.kind)) {
+    const reason =
+      scope.kind === "scope" && scope.replaceability.reason
+        ? MULTI_PARAGRAPH_REPLACEMENT_REFUSAL
+        : `compile-refused:${scope.kind}`;
+    return unsupported(
+      reason,
+      scope.kind === "scope"
+        ? multiParagraphReplacementBlockers("text")
+        : [reason],
+      evidenceWarnings(context),
+    );
+  }
+
+  if (
+    scope.replaceability.level === "blocked" ||
+    scope.replaceability.level === "preserve-only" ||
+    scope.replaceability.level === "formatting-only"
+  ) {
+    const reason = scope.replaceability.reason
+      ? `replaceability:${scope.replaceability.reason}`
+      : `replaceability:${scope.replaceability.level}`;
+    return unsupported(reason);
+  }
+
+  return supported(
+    "compile-supported:paragraph-like:text-replace",
+    [
+      ...(scope.workflow.effectiveMode === "suggest" ? ["guard:suggest-mode"] : []),
+      ...evidenceWarnings(context),
+    ],
+  );
+}
+
+function replaceFragmentCapability(
+  scope: SemanticScope,
+  context?: ScopeCapabilityContext,
+): ScopeCapabilityVerdict {
+  const guard = guardBlocker(scope);
+  if (guard) return blocked(guard);
+
+  const contentControls = contentControlBlockers(context);
+  if (contentControls.length > 0) {
+    return blocked("preserve:content-control", contentControls);
+  }
+
+  if (!PARAGRAPH_LIKE.has(scope.kind)) {
+    const reason =
+      scope.kind === "scope" && scope.replaceability.reason
+        ? MULTI_PARAGRAPH_REPLACEMENT_REFUSAL
+        : `compile-refused:${scope.kind}`;
+    return unsupported(
+      reason,
+      scope.kind === "scope"
+        ? multiParagraphReplacementBlockers("fragment")
+        : [reason],
+      evidenceWarnings(context),
+    );
+  }
+
+  if (scope.workflow.effectiveMode === "suggest") {
+    return unsupported(
+      `compile-refused:${scope.kind}:structured-suggesting-not-implemented`,
+      [`compile-refused:${scope.kind}:structured-suggesting-not-implemented`],
+      ["guard:suggest-mode"],
+    );
+  }
+
+  return supported(
+    "compile-supported:paragraph-like:fragment-replace",
+    evidenceWarnings(context),
+  );
+}
+
+function formattingCapability(
+  scope: SemanticScope,
+  context?: ScopeCapabilityContext,
+): ScopeCapabilityVerdict {
+  const guard = guardBlocker(scope);
+  if (guard) return blocked(guard);
+
+  if (!FORMATTING_SUPPORTED.has(scope.kind)) {
+    return unsupported(`compile-refused:${scope.kind}:formatting-not-implemented`);
+  }
+
+  if (scope.workflow.effectiveMode === "suggest") {
+    return unsupported(
+      `compile-refused:${scope.kind}:formatting-suggesting-not-implemented`,
+      [`compile-refused:${scope.kind}:formatting-suggesting-not-implemented`],
+      ["guard:suggest-mode"],
+    );
+  }
+
+  return supported("compile-supported:scope-formatting", evidenceWarnings(context));
+}
+
+function metadataCapability(scope: SemanticScope): ScopeCapabilityVerdict {
+  if (METADATA_SUPPORTED.has(scope.kind)) {
+    return supported(
+      scope.kind === "table" ||
+        scope.kind === "table-row" ||
+        scope.kind === "table-cell"
+        ? "metadata-supported:derived-table-family"
+        : "metadata-supported:scope-id",
+    );
+  }
+  return unsupported(`scope-not-resolvable:${scope.handle.scopeId}`);
+}
+
+export function deriveScopeCapabilities(
+  scope: SemanticScope,
+  context: ScopeCapabilityContext = {},
+): ScopeCapabilities {
+  return {
+    canReplaceText: replaceTextCapability(scope, context),
+    canReplaceFragment: replaceFragmentCapability(scope, context),
+    canInsertBefore: insertCapability(scope, "before", context),
+    canInsertAfter: insertCapability(scope, "after", context),
+    canApplyFormatting: formattingCapability(scope, context),
+    canClearFormattingLayer: formattingCapability(scope, context),
+    canAttachMetadata: metadataCapability(scope),
+  };
+}

package/src/runtime/scopes/compile-scope-bundle.ts

@@ -17,6 +17,7 @@ import type {
   WorkflowMetadataEntry,
   WorkflowOverlay,
 } from "./_scope-dependencies.ts";
+import type { ScopeGeometryEvidenceProvider } from "./geometry-evidence.ts";
 
 import {
   buildParagraphIndexMap,
@@ -26,6 +27,7 @@ import {
 import type { EnumeratedScope } from "./enumerate-scopes.ts";
 import { enumerateScopes } from "./enumerate-scopes.ts";
 import { composeEvidence } from "./evidence.ts";
+import type { ScopeLayoutEvidenceProvider } from "./layout-evidence.ts";
 import type {
   ScopeBundle,
   ScopeBundleNeighborhood,
@@ -47,6 +49,16 @@ export interface ScopeBundleInputs {
    * to walk the metadata snapshot.
    */
   readonly workflowMetadataEntries?: readonly WorkflowMetadataEntry[];
+  /**
+   * Optional Layer-05 replacement-envelope read seam. When omitted, bundle
+   * evidence records geometry as unavailable rather than synthesizing rects.
+   */
+  readonly geometry?: ScopeGeometryEvidenceProvider;
+  /**
+   * Optional lower-layer layout evidence seam. When absent, bundle evidence
+   * records layout as unavailable instead of deriving page slices in L08.
+   */
+  readonly layout?: ScopeLayoutEvidenceProvider;
 }
 
 /**
@@ -126,6 +138,8 @@ export function compileScopeBundle(
     ...(inputs.workflowMetadataEntries
       ? { workflowMetadataEntries: inputs.workflowMetadataEntries }
       : {}),
+    ...(inputs.geometry ? { geometry: inputs.geometry } : {}),
+    ...(inputs.layout ? { layout: inputs.layout } : {}),
   });
   return {
     scope,

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

@@ -37,10 +37,12 @@ import type {
   WorkflowMetadataEntry,
   WorkflowMetadataSnapshot,
   WorkflowOverlay,
+  WorkflowEventOrigin,
 } 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 type { ScopeGeometryEvidenceProvider } from "./geometry-evidence.ts";
 
 import {
   buildParagraphIndexMap,
@@ -49,6 +51,12 @@ import {
 } from "./compile-scope.ts";
 import { compileScopeBundleById } from "./compile-scope-bundle.ts";
 import { enumerateScopes, type EnumeratedScope } from "./enumerate-scopes.ts";
+import {
+  collectTopLevelTableBlockIdsFromRenderSnapshot,
+  createRuntimeTableFrameLayoutEvidenceProvider,
+  type ScopeRuntimeLayoutEvidenceSource,
+  type ScopeRuntimeRenderSnapshotLike,
+} from "./layout-evidence.ts";
 import {
   attachExplanation,
   type AttachExplanationResult,
@@ -59,6 +67,12 @@ import {
   type IssueSeverity,
   type IssueStatus,
 } from "./create-issue.ts";
+import {
+  resolveIssueLifecycleTarget,
+  transitionScopeIssueLifecycle,
+  type IssueLifecycleAction,
+  type TransitionScopeIssueLifecycleResult,
+} from "./issue-lifecycle.ts";
 import {
   applyScopeReplacement,
   type ApplyScopeReplacementResult,
@@ -69,12 +83,12 @@ import {
 } from "./formatting/apply.ts";
 import { proposeReplacement } from "./replacement/propose.ts";
 import type {
-  ReplacementOperationKind,
   ReplacementPreservePolicy,
   ReplacementScope,
   RuntimeOperationPlan,
   ScopeFormattingAction,
   ScopeFormattingScope,
+  ScopeReplacementOperationKind,
   ScopeBundle,
   ScopeHandle,
   SemanticScope,
@@ -98,10 +112,16 @@ export interface CompilerServiceRuntime {
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getCompatibilityReport(): CompatibilityReport;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
-  setWorkflowMetadataEntries(entries: readonly WorkflowMetadataEntry[]): void;
+  setWorkflowMetadataEntries(
+    entries: readonly WorkflowMetadataEntry[],
+    origin?: WorkflowEventOrigin,
+  ): void;
+  getRenderSnapshot?(): ScopeRuntimeRenderSnapshotLike;
   getSessionState(): ScopeSessionState;
   applyScopeReplacement(plan: RuntimeOperationPlan): void;
   applyScopeFormatting(plan: RuntimeOperationPlan): boolean;
+  readonly geometry?: ScopeGeometryEvidenceProvider;
+  readonly layout?: ScopeRuntimeLayoutEvidenceSource;
   debug?: { bus: TelemetryBus };
 }
 
@@ -113,7 +133,7 @@ export interface CompileScopeByIdResult {
 
 export interface ApplyReplacementRequest {
   readonly targetScopeId: string;
-  readonly operation: ReplacementOperationKind;
+  readonly operation: ScopeReplacementOperationKind;
   /**
    * Flat text payload. Shorthand for
    * `proposedContent: {kind: "text", text}`. Ignored when
@@ -165,6 +185,14 @@ export interface CreateIssueRequest {
   readonly status?: IssueStatus;
 }
 
+export interface TransitionIssueLifecycleRequest {
+  readonly issueId: string;
+  readonly action: IssueLifecycleAction;
+  readonly actorId: string;
+  readonly origin: "ui" | "agent" | "host";
+  readonly emittedAtUtc: string;
+}
+
 export interface ScopeCompilerService {
   /**
    * Enumerate + compile every live scope in the document. Per-call the
@@ -197,7 +225,7 @@ export interface ScopeCompilerService {
   buildReplacementScope(
     targetHandle: ScopeHandle,
     input: {
-      readonly operation: ReplacementOperationKind;
+      readonly operation: ScopeReplacementOperationKind;
       readonly proposedText?: string;
       readonly formatting?: ReplacementScope["formatting"];
       readonly preserve?: ReplacementPreservePolicy;
@@ -238,6 +266,17 @@ export interface ScopeCompilerService {
    * overlay-only constraint as `attachExplanation`.
    */
   createIssue(request: CreateIssueRequest): CreateIssueResult;
+
+  /**
+   * Resolve/reopen an existing `ai.issue` metadata entry through the L06
+   * durable lifecycle substrate, but only after its scope target still compiles
+   * through Layer 08. This is intentionally not a public L09 API yet; it is the
+   * scope/evidence join that L09 will consume when `ai.resolveIssue` /
+   * `ai.reopenIssue` graduate.
+   */
+  transitionIssueLifecycle(
+    request: TransitionIssueLifecycleRequest,
+  ): TransitionScopeIssueLifecycleResult;
 }
 
 /**
@@ -324,12 +363,24 @@ export function createScopeCompilerService(
       // operations go through `attachScopeMetadata` via this same
       // runtime surface, so the snapshot is always fresh here.
       const workflowMetadataEntries = runtime.getWorkflowMetadataSnapshot().entries;
+      const layout =
+        runtime.layout
+          ? createRuntimeTableFrameLayoutEvidenceProvider({
+              layout: runtime.layout,
+              tableBlockIdsByBlockIndex:
+                collectTopLevelTableBlockIdsFromRenderSnapshot(
+                  runtime.getRenderSnapshot?.(),
+                ),
+            })
+          : undefined;
       return compileScopeBundleById(scopeId, {
         document,
         ...(overlay ? { overlay } : {}),
         nowUtc,
         catalog: document.styles,
         workflowMetadataEntries,
+        ...(runtime.geometry ? { geometry: runtime.geometry } : {}),
+        ...(layout ? { layout } : {}),
       });
     },
 
@@ -361,6 +412,7 @@ export function createScopeCompilerService(
           reason: "scope-not-resolvable",
           validation: {
             safe: false,
+            posture: "hard-refusal",
             blockedReasons: Object.freeze([
               `scope-not-resolvable:${request.targetScopeId}`,
             ]),
@@ -400,6 +452,7 @@ export function createScopeCompilerService(
             runtime.getInteractionGuardSnapshot(),
           getCompatibilityReport: () => runtime.getCompatibilityReport(),
           applyScopeReplacement: (plan) => runtime.applyScopeReplacement(plan),
+          verifyReadback: true,
         },
         proposed,
         ...(request.actionId ? { actionId: request.actionId } : {}),
@@ -418,6 +471,7 @@ export function createScopeCompilerService(
           reason: "scope-not-resolvable",
           validation: {
             safe: false,
+            posture: "hard-refusal",
             blockedReasons: Object.freeze([
               `scope-not-resolvable:${request.targetScopeId}`,
             ]),
@@ -498,5 +552,55 @@ export function createScopeCompilerService(
         },
       );
     },
+
+    transitionIssueLifecycle(
+      request: TransitionIssueLifecycleRequest,
+    ): TransitionScopeIssueLifecycleResult {
+      const target = resolveIssueLifecycleTarget(
+        runtime.getWorkflowMetadataSnapshot(),
+        request.issueId,
+      );
+      if (!target) {
+        const reason = `issue-not-found:${request.issueId}`;
+        return {
+          transitioned: false,
+          issueId: request.issueId,
+          reason,
+          blockers: Object.freeze([reason]),
+        };
+      }
+
+      const compiled = this.compileScopeById(target.scopeId);
+      if (!compiled) {
+        const reason = `scope-not-resolvable:${target.scopeId}`;
+        return {
+          transitioned: false,
+          issueId: target.issueId,
+          reason,
+          blockers: Object.freeze([reason]),
+          scopeId: target.scopeId,
+        };
+      }
+
+      const documentBefore = runtime.getCanonicalDocument();
+      const result = transitionScopeIssueLifecycle({
+        runtime: {
+          getCanonicalDocument: () => runtime.getCanonicalDocument(),
+          getWorkflowMetadataSnapshot: () =>
+            runtime.getWorkflowMetadataSnapshot(),
+          setWorkflowMetadataEntries: (entries, origin) =>
+            runtime.setWorkflowMetadataEntries([...entries], origin),
+        },
+        documentBefore,
+        targetScopeSnapshot: compiled.scope,
+        issueId: target.issueId,
+        action: request.action,
+        actorId: request.actorId,
+        origin: request.origin,
+        emittedAtUtc: request.emittedAtUtc,
+        ...(runtime.debug?.bus ? { bus: runtime.debug.bus } : {}),
+      });
+      return result;
+    },
   };
 }

package/src/runtime/scopes/content-control-evidence.ts

@@ -0,0 +1,79 @@
+/**
+ * Content-control / SDT evidence for scope bundles and preservation checks.
+ *
+ * SDTs are package-backed wrappers, not L08 scope truth. This helper only
+ * reports overlap with a scope range so capability and validation surfaces can
+ * stay preserve-first until L02/L04 expose richer source/layout refs.
+ */
+
+import type {
+  CanonicalDocument,
+  DocumentRootNode,
+  SdtNode,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+
+import { computeBlockPositions, type ScopePositionRange } from "./position-map.ts";
+import { rangesOverlap } from "./scope-range.ts";
+import type {
+  ScopeContentControlEvidence,
+  ScopeContentControlEvidenceEntry,
+} from "./semantic-scope-types.ts";
+
+function documentRoot(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+): DocumentRootNode {
+  const envelope = document as CanonicalDocumentEnvelope;
+  return "content" in envelope
+    ? (envelope.content as DocumentRootNode)
+    : (document as unknown as DocumentRootNode);
+}
+
+function entryForSdt(
+  blockIndex: number,
+  sdt: SdtNode,
+): ScopeContentControlEvidenceEntry {
+  const typePart = sdt.properties.sdtType ?? "unknown";
+  return {
+    evidenceId: `sdt:${blockIndex}:${typePart}`,
+    blockIndex,
+    ...(sdt.properties.sdtType ? { sdtType: sdt.properties.sdtType } : {}),
+    ...(sdt.properties.alias ? { alias: sdt.properties.alias } : {}),
+    ...(sdt.properties.tag ? { tag: sdt.properties.tag } : {}),
+    ...(sdt.properties.lock ? { lock: sdt.properties.lock } : {}),
+  };
+}
+
+export function findContentControlsIntersectingRange(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+  range: ScopePositionRange | null,
+): readonly ScopeContentControlEvidenceEntry[] {
+  if (!range) return Object.freeze([]);
+
+  const root = documentRoot(document);
+  const blockRanges = computeBlockPositions(document);
+  const entries: ScopeContentControlEvidenceEntry[] = [];
+
+  for (const blockRange of blockRanges) {
+    const block = root.children[blockRange.blockIndex];
+    if (!block || block.type !== "sdt") continue;
+    if (!rangesOverlap(range, { from: blockRange.from, to: blockRange.to })) {
+      continue;
+    }
+    entries.push(entryForSdt(blockRange.blockIndex, block));
+  }
+
+  return Object.freeze(entries);
+}
+
+export function deriveScopeContentControlEvidence(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+  range: ScopePositionRange | null,
+): ScopeContentControlEvidence {
+  const entries = findContentControlsIntersectingRange(document, range);
+  return {
+    status: entries.length > 0 ? "present" : "none",
+    count: entries.length,
+    entries,
+  };
+}

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

@@ -9,10 +9,9 @@
  * 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.
+ * overlay-schema minor bump. Layer 06 owns the durable lifecycle substrate for
+ * the stable metadataId; L08/L09 still own scope/API shaped resolve/reopen
+ * exposure.
  *
  * Scope coverage (coord-06 §13c shipped 2026-04-23): both overlay
  * (workflow) scopes AND derived paragraph / heading / list-item
@@ -28,9 +27,10 @@ import type {
   MetadataWriterRuntime,
 } from "../workflow/metadata-writer.ts";
 import { attachScopeMetadata } from "../workflow/metadata-writer.ts";
+import { AI_ISSUE_METADATA_ID } from "../workflow/ai-issue-lifecycle.ts";
 
 /** Stable metadataId for AI-authored issues. */
-export const AI_ISSUE_METADATA_ID = "ai.issue" as const;
+export { AI_ISSUE_METADATA_ID };
 
 export type IssueSeverity = "info" | "warning" | "error";
 export type IssueStatus = "open" | "resolved";