@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/runtime/scopes/evidence.ts

@@ -24,10 +24,21 @@ import type {
 } from "./_scope-dependencies.ts";
 
 import { AI_EXPLANATION_METADATA_ID } from "./attach-explanation.ts";
+import { deriveScopeCapabilities } from "./capabilities.ts";
+import { deriveScopeContentControlEvidence } from "./content-control-evidence.ts";
 import { AI_ISSUE_METADATA_ID } from "./create-issue.ts";
 import type { EnumeratedScope } from "./enumerate-scopes.ts";
+import {
+  deriveScopeGeometryEvidence,
+  type ScopeGeometryEvidenceProvider,
+} from "./geometry-evidence.ts";
+import {
+  deriveScopeLayoutEvidence,
+  type ScopeLayoutEvidenceProvider,
+} from "./layout-evidence.ts";
 import { buildScopePositionMap, type ScopePositionRange } from "./position-map.ts";
 import { rangesOverlap, resolveScopeRange } from "./scope-range.ts";
+import { deriveScopeVisualization } from "./visualization.ts";
 import type {
   AIExplanationSummary,
   AIIssueSummary,
@@ -86,6 +97,16 @@ export interface EvidenceInputs {
    * `runtime.getWorkflowMetadataSnapshot().entries` through here.
    */
   readonly workflowMetadataEntries?: readonly WorkflowMetadataEntry[];
+  /**
+   * Layer-05 geometry facet subset. When present, evidence includes the
+   * current replacement envelope or an explicit requires-rehydration status.
+   */
+  readonly geometry?: ScopeGeometryEvidenceProvider;
+  /**
+   * Optional lower-layer layout evidence seam. Missing provider or missing
+   * rows are surfaced explicitly in `ScopeBundleEvidence.layout`.
+   */
+  readonly layout?: ScopeLayoutEvidenceProvider;
 }
 
 function normalizeSeverity(raw: unknown): AIIssueSummary["severity"] {
@@ -98,6 +119,38 @@ function normalizeStatus(raw: unknown): AIIssueSummary["status"] {
   return "open";
 }
 
+function projectIssueTransition(raw: unknown): AIIssueSummary["lastTransition"] | undefined {
+  const value = raw as
+    | {
+        action?: unknown;
+        actorId?: unknown;
+        at?: unknown;
+        origin?: unknown;
+        fromStatus?: unknown;
+        toStatus?: unknown;
+      }
+    | undefined;
+  if (!value || typeof value !== "object") return undefined;
+  if (value.action !== "resolve" && value.action !== "reopen") return undefined;
+  if (typeof value.actorId !== "string") return undefined;
+  if (typeof value.at !== "string") return undefined;
+  if (typeof value.origin !== "string") return undefined;
+  if (value.fromStatus !== "open" && value.fromStatus !== "resolved") {
+    return undefined;
+  }
+  if (value.toStatus !== "open" && value.toStatus !== "resolved") {
+    return undefined;
+  }
+  return {
+    action: value.action,
+    actorId: value.actorId,
+    at: value.at,
+    origin: value.origin,
+    fromStatus: value.fromStatus,
+    toStatus: value.toStatus,
+  };
+}
+
 function projectAIExplanation(
   entry: WorkflowMetadataEntry,
 ): AIExplanationSummary | null {
@@ -127,9 +180,18 @@ function projectAIIssue(
         severity?: unknown;
         status?: unknown;
         createdAtUtc?: string;
+        statusUpdatedAtUtc?: string;
+        resolvedAtUtc?: string;
+        resolvedBy?: string;
+        reopenedAtUtc?: string;
+        reopenedBy?: string;
+        lifecycle?: unknown[];
       }
     | undefined;
   if (!value || typeof value.summary !== "string") return null;
+  const lastTransition = Array.isArray(value.lifecycle)
+    ? projectIssueTransition(value.lifecycle[value.lifecycle.length - 1])
+    : undefined;
   return {
     issueId:
       typeof value.issueId === "string" && value.issueId.length > 0
@@ -141,6 +203,22 @@ function projectAIIssue(
     ...(typeof value.createdAtUtc === "string"
       ? { createdAtUtc: value.createdAtUtc }
       : {}),
+    ...(typeof value.statusUpdatedAtUtc === "string"
+      ? { statusUpdatedAtUtc: value.statusUpdatedAtUtc }
+      : {}),
+    ...(typeof value.resolvedAtUtc === "string"
+      ? { resolvedAtUtc: value.resolvedAtUtc }
+      : {}),
+    ...(typeof value.resolvedBy === "string"
+      ? { resolvedBy: value.resolvedBy }
+      : {}),
+    ...(typeof value.reopenedAtUtc === "string"
+      ? { reopenedAtUtc: value.reopenedAtUtc }
+      : {}),
+    ...(typeof value.reopenedBy === "string"
+      ? { reopenedBy: value.reopenedBy }
+      : {}),
+    ...(lastTransition ? { lastTransition } : {}),
   };
 }
 
@@ -221,11 +299,24 @@ export function composeEvidence(inputs: EvidenceInputs): ScopeBundleEvidence {
   aiExplanations.sort((a, b) => a.explanationId.localeCompare(b.explanationId));
   aiIssues.sort((a, b) => a.issueId.localeCompare(b.issueId));
 
+  const layout = deriveScopeLayoutEvidence(scope.handle.scopeId, inputs.layout);
+  const geometry = deriveScopeGeometryEvidence(scope.handle.scopeId, inputs.geometry);
+  const contentControls = deriveScopeContentControlEvidence(document, selfRange);
+
   return {
     formattingSummary: formattingSummaryOf(scope),
     reviewItemIds,
     overlappingWorkflowScopeIds,
     compatibilityFlags,
+    layout,
+    geometry,
+    visualization: deriveScopeVisualization(scope),
+    contentControls,
+    capabilities: deriveScopeCapabilities(scope, {
+      layout,
+      geometry,
+      contentControls,
+    }),
     ...(inputs.workflowMetadataEntries
       ? { aiExplanations, aiIssues }
       : {}),

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

@@ -156,6 +156,7 @@ export function applyScopeFormatting(
   if (!resolvedScope || !resolvedEnumerated) {
     const validation: ValidationResult = {
       safe: false,
+      posture: "hard-refusal",
       blockedReasons: Object.freeze([
         `scope-not-resolvable:${proposed.targetHandle.scopeId}`,
       ]),
@@ -211,6 +212,7 @@ export function applyScopeFormatting(
         : `compile-refused:${resolvedScope.kind}:formatting-not-implemented`;
     const refused: ValidationResult = {
       safe: false,
+      posture: "hard-refusal",
       blockedReasons: Object.freeze([blocker]),
       warnings: verdict.warnings,
     };

package/src/runtime/scopes/geometry-evidence.ts

@@ -0,0 +1,130 @@
+/**
+ * Scope geometry evidence projection.
+ *
+ * Layer 08 consumes the Layer 05 replacement-envelope seam when it is wired,
+ * but it does not compute geometry itself. Cold or missing geometry remains
+ * explicit evidence, not a synthesized rectangle.
+ */
+
+import type {
+  ScopeGeometryEvidence,
+  ScopeGeometryEvidencePrecision,
+  ScopeGeometryEvidenceRect,
+  ScopeLayoutContinuationEvidence,
+} from "./semantic-scope-types.ts";
+
+type GeometrySpace = ScopeGeometryEvidenceRect["space"];
+
+interface EnvelopeRectLike {
+  readonly leftPx: number;
+  readonly topPx: number;
+  readonly widthPx: number;
+  readonly heightPx: number;
+  readonly space: GeometrySpace;
+  readonly precision?: ScopeGeometryEvidencePrecision;
+}
+
+interface EnvelopeLike {
+  readonly scopeRects: readonly EnvelopeRectLike[];
+  readonly pageIds?: readonly string[];
+  readonly continuation?: ScopeLayoutContinuationEvidence;
+  readonly attachPoint: {
+    readonly xPx: number;
+    readonly yPx: number;
+    readonly space: GeometrySpace;
+  };
+  readonly confidence: "exact" | "medium" | "detached";
+  readonly linesCrossed: number;
+  readonly rehydrationStatus?: "realized" | "requires-rehydration" | "unavailable";
+  readonly precision?: ScopeGeometryEvidencePrecision;
+  readonly sourceIdentity?: {
+    readonly storyKey?: string;
+    readonly blockPath?: string;
+    readonly tableKey?: string;
+    readonly rowKey?: string;
+    readonly cellKey?: string;
+    readonly scopeKey?: string;
+    readonly scopeId?: string;
+    readonly objectKey?: string;
+    readonly inlinePath?: string;
+    readonly objectKind?: string;
+    readonly editPosture?: string;
+    readonly joinKind?: string;
+  };
+}
+
+export interface ScopeGeometryEvidenceProvider {
+  getReplacementEnvelope(scopeId: string): EnvelopeLike | null;
+}
+
+function mapRect(rect: EnvelopeRectLike): ScopeGeometryEvidenceRect {
+  return {
+    x: rect.leftPx,
+    y: rect.topPx,
+    width: rect.widthPx,
+    height: rect.heightPx,
+    space: rect.space,
+    ...(rect.precision ? { precision: rect.precision } : {}),
+  };
+}
+
+export function deriveScopeGeometryEvidence(
+  scopeId: string,
+  provider?: ScopeGeometryEvidenceProvider,
+): ScopeGeometryEvidence {
+  if (!provider) {
+    return {
+      status: "unavailable",
+      requiresRehydration: false,
+      reason: "geometry-facet-unavailable",
+    };
+  }
+
+  const envelope = provider.getReplacementEnvelope(scopeId);
+  if (!envelope) {
+    return {
+      status: "requires-rehydration",
+      requiresRehydration: true,
+      reason: "replacement-envelope-unavailable",
+    };
+  }
+
+  if (envelope.rehydrationStatus === "unavailable") {
+    return {
+      status: "unavailable",
+      requiresRehydration: false,
+      reason: "replacement-envelope-unavailable",
+      ...(envelope.pageIds ? { pageIds: Object.freeze([...envelope.pageIds]) } : {}),
+      ...(envelope.continuation
+        ? { continuationState: { ...envelope.continuation } }
+        : {}),
+      ...(envelope.sourceIdentity
+        ? { sourceIdentity: { ...envelope.sourceIdentity } }
+        : {}),
+    };
+  }
+
+  const requiresRehydration =
+    envelope.rehydrationStatus === "requires-rehydration";
+  return {
+    status: requiresRehydration ? "requires-rehydration" : "available",
+    requiresRehydration,
+    ...(requiresRehydration ? { reason: "replacement-envelope-requires-rehydration" } : {}),
+    ...(envelope.pageIds ? { pageIds: Object.freeze([...envelope.pageIds]) } : {}),
+    confidence: envelope.confidence,
+    ...(envelope.precision ? { precision: envelope.precision } : {}),
+    rects: Object.freeze(envelope.scopeRects.map(mapRect)),
+    attachPoint: {
+      x: envelope.attachPoint.xPx,
+      y: envelope.attachPoint.yPx,
+      space: envelope.attachPoint.space,
+    },
+    linesCrossed: envelope.linesCrossed,
+    ...(envelope.continuation
+      ? { continuationState: { ...envelope.continuation } }
+      : {}),
+    ...(envelope.sourceIdentity
+      ? { sourceIdentity: { ...envelope.sourceIdentity } }
+      : {}),
+  };
+}

package/src/runtime/scopes/index.ts

@@ -26,8 +26,24 @@ export type {
   ReplacementOperationKind,
   ReplacementPreservePolicy,
   ReplacementScope,
+  ScopeReplacementOperationKind,
   ScopeActionOperationKind,
   ScopeActionProposal,
+  ScopeCapabilities,
+  ScopeCapabilityStatus,
+  ScopeCapabilityVerdict,
+  ScopeContentControlEvidence,
+  ScopeContentControlEvidenceEntry,
+  ScopeContentControlEvidenceStatus,
+  ScopeEvidenceAvailability,
+  ScopeGeometryEvidence,
+  ScopeGeometryEvidencePrecision,
+  ScopeGeometryEvidenceRect,
+  ScopeGeometryEvidenceStatus,
+  ScopeLayoutContinuationEvidence,
+  ScopeLayoutEvidence,
+  ScopeVisualizationClass,
+  ScopeVisualizationHint,
   RuntimeOperationPlan,
   RuntimeOperationStep,
   RuntimeOperationStepKind,
@@ -35,6 +51,7 @@ export type {
   ScopeFormattingAction,
   ScopeFormattingClearTarget,
   ScopeFormattingScope,
+  ScopeActionPosture,
   ScopeBundle,
   ScopeBundleEvidence,
   ScopeBundleNeighborhood,
@@ -56,6 +73,33 @@ export type {
   ValidationIssue,
   ValidationResult,
 } from "./semantic-scope-types.ts";
+export { deriveScopeCapabilities } from "./capabilities.ts";
+export type { ScopeCapabilityContext } from "./capabilities.ts";
+export {
+  deriveScopeContentControlEvidence,
+  findContentControlsIntersectingRange,
+} from "./content-control-evidence.ts";
+export {
+  deriveScopeGeometryEvidence,
+  type ScopeGeometryEvidenceProvider,
+} from "./geometry-evidence.ts";
+export {
+  deriveScopeLayoutEvidence,
+  collectTopLevelTableBlockIdsFromRenderSnapshot,
+  createRuntimeTableFrameLayoutEvidenceProvider,
+  type RuntimeTableFrameLayoutEvidenceOptions,
+  type ScopeLayoutEvidenceEntry,
+  type ScopeLayoutEvidenceProvider,
+  type ScopeRuntimeLayoutEvidenceSource,
+  type ScopeRuntimeLayoutFragment,
+  type ScopeRuntimeRenderSnapshotLike,
+} from "./layout-evidence.ts";
+export {
+  MULTI_PARAGRAPH_REPLACEMENT_REFUSAL,
+  multiParagraphReplacementBlockers,
+} from "./multi-paragraph-refusal.ts";
+export type { MultiParagraphReplacementShape } from "./multi-paragraph-refusal.ts";
+export { deriveScopeVisualization } from "./visualization.ts";
 
 export {
   buildParagraphIndexMap,
@@ -153,6 +197,15 @@ export {
   type IssueSeverity,
   type IssueStatus,
 } from "./create-issue.ts";
+export {
+  resolveIssueLifecycleTarget,
+  transitionScopeIssueLifecycle,
+  type IssueLifecycleAction,
+  type IssueLifecycleRuntime,
+  type IssueLifecycleTarget,
+  type TransitionScopeIssueLifecycleInputs,
+  type TransitionScopeIssueLifecycleResult,
+} from "./issue-lifecycle.ts";
 export {
   createScopeCompilerService,
   type ApplyFormattingRequest,
@@ -161,5 +214,6 @@ export {
   type CompileScopeByIdResult,
   type CompilerServiceRuntime,
   type CreateIssueRequest,
+  type TransitionIssueLifecycleRequest,
   type ScopeCompilerService,
 } from "./compiler-service.ts";

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

@@ -0,0 +1,224 @@
+/**
+ * Layer 08 issue lifecycle binding.
+ *
+ * Layer 06 owns durable `ai.issue` metadata status transitions. This module
+ * adds the scope-compiler binding that future L09 `resolveIssue` /
+ * `reopenIssue` APIs need: find the issue's scope, require that scope to still
+ * compile, preserve the existing metadata entry id, and emit scope-shaped audit
+ * evidence for the lifecycle transition.
+ */
+
+import type { TelemetryBus } from "../debug/telemetry-bus.ts";
+import {
+  projectAIIssueLifecycleReadback,
+  transitionAIIssueLifecycle,
+  type AIIssueLifecycleAction,
+  type AIIssueLifecycleAuditEntry,
+  type AIIssueStatus,
+} from "../workflow/ai-issue-lifecycle.ts";
+import type {
+  WorkflowEventOrigin,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+} from "./_scope-dependencies.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  ReplacementScope,
+  ScopeActionAudit,
+  SemanticScope,
+  ValidationResult,
+} from "./semantic-scope-types.ts";
+
+export type IssueLifecycleAction = AIIssueLifecycleAction;
+
+export interface IssueLifecycleRuntime {
+  getCanonicalDocument(): CanonicalDocumentEnvelope;
+  getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  setWorkflowMetadataEntries(
+    entries: readonly WorkflowMetadataEntry[],
+    origin?: WorkflowEventOrigin,
+  ): void;
+}
+
+export interface IssueLifecycleTarget {
+  readonly issueId: string;
+  readonly entryId: string;
+  readonly scopeId: string;
+  readonly status: AIIssueStatus;
+}
+
+export interface TransitionScopeIssueLifecycleInputs {
+  readonly runtime: IssueLifecycleRuntime;
+  readonly documentBefore: CanonicalDocumentEnvelope;
+  readonly targetScopeSnapshot: SemanticScope;
+  readonly issueId: string;
+  readonly action: IssueLifecycleAction;
+  readonly actorId: string;
+  readonly origin: "ui" | "agent" | "host";
+  readonly emittedAtUtc: string;
+  readonly bus?: TelemetryBus;
+}
+
+export type TransitionScopeIssueLifecycleResult =
+  | {
+      readonly transitioned: true;
+      readonly issueId: string;
+      readonly entryId: string;
+      readonly scopeId: string;
+      readonly fromStatus: AIIssueStatus;
+      readonly toStatus: AIIssueStatus;
+      readonly lifecycleAudit: AIIssueLifecycleAuditEntry;
+      readonly targetScopeSnapshot: SemanticScope;
+      readonly audit: ScopeActionAudit;
+    }
+  | {
+      readonly transitioned: false;
+      readonly issueId: string;
+      readonly reason: string;
+      readonly blockers: readonly string[];
+      readonly scopeId?: string;
+      readonly targetScopeSnapshot?: SemanticScope;
+    };
+
+function documentHash(doc: CanonicalDocumentEnvelope): string {
+  let textLength = 0;
+  for (const block of doc.content.children) {
+    if (block.type !== "paragraph") continue;
+    for (const child of block.children) {
+      if (child.type === "text") textLength += child.text.length;
+    }
+  }
+  return `blocks:${doc.content.children.length}|text:${textLength}`;
+}
+
+function freezeBlocker(reason: string): readonly string[] {
+  return Object.freeze([reason]);
+}
+
+export function resolveIssueLifecycleTarget(
+  snapshot: WorkflowMetadataSnapshot,
+  issueIdOrEntryId: string,
+): IssueLifecycleTarget | null {
+  const readback = projectAIIssueLifecycleReadback(snapshot.entries).find(
+    (issue) =>
+      issue.issueId === issueIdOrEntryId || issue.entryId === issueIdOrEntryId,
+  );
+  if (!readback || !readback.scopeId) return null;
+  return {
+    issueId: readback.issueId,
+    entryId: readback.entryId,
+    scopeId: readback.scopeId,
+    status: readback.status,
+  };
+}
+
+function buildLifecycleAudit(
+  inputs: TransitionScopeIssueLifecycleInputs,
+  transition: {
+    readonly issueId: string;
+    readonly entryId: string;
+    readonly fromStatus: AIIssueStatus;
+    readonly toStatus: AIIssueStatus;
+    readonly audit: AIIssueLifecycleAuditEntry;
+  },
+): ScopeActionAudit {
+  const snapshot = inputs.targetScopeSnapshot;
+  const proposed: ReplacementScope = {
+    targetHandle: snapshot.handle,
+    operation: "annotate",
+    proposedContent: {
+      kind: "structured",
+      structured: {
+        metadataKind: "issue-lifecycle",
+        issueId: transition.issueId,
+        entryId: transition.entryId,
+        action: inputs.action,
+        fromStatus: transition.fromStatus,
+        toStatus: transition.toStatus,
+      },
+    },
+    proposedAtUtc: inputs.emittedAtUtc,
+  };
+  const validation: ValidationResult = {
+    safe: true,
+    posture: "supported",
+    blockedReasons: Object.freeze([]),
+    warnings: Object.freeze([]),
+  };
+  return {
+    actionId:
+      inputs.action === "resolve" ? "ai.resolveIssue" : "ai.reopenIssue",
+    actorId: inputs.actorId,
+    origin: inputs.origin,
+    documentHashBefore: documentHash(inputs.documentBefore),
+    documentHashAfter: documentHash(inputs.runtime.getCanonicalDocument()),
+    targetScopeSnapshot: snapshot,
+    proposed,
+    compiledOperations: Object.freeze([
+      {
+        kind:
+          inputs.action === "resolve"
+            ? "metadata-issue-resolve"
+            : "metadata-issue-reopen",
+        summary: `${inputs.action} issue ${transition.issueId} on scope ${snapshot.handle.scopeId}`,
+      },
+    ]),
+    validation,
+    emittedAtUtc: inputs.emittedAtUtc,
+  };
+}
+
+export function transitionScopeIssueLifecycle(
+  inputs: TransitionScopeIssueLifecycleInputs,
+): TransitionScopeIssueLifecycleResult {
+  const target = resolveIssueLifecycleTarget(
+    inputs.runtime.getWorkflowMetadataSnapshot(),
+    inputs.issueId,
+  );
+  if (!target) {
+    const reason = `issue-not-found:${inputs.issueId}`;
+    return {
+      transitioned: false,
+      issueId: inputs.issueId,
+      reason,
+      blockers: freezeBlocker(reason),
+    };
+  }
+
+  const transition = transitionAIIssueLifecycle(inputs.runtime, {
+    issueId: target.issueId,
+    action: inputs.action,
+    actorId: inputs.actorId,
+    at: inputs.emittedAtUtc,
+    origin: { source: inputs.origin, at: inputs.emittedAtUtc },
+  });
+
+  if (!transition.transitioned) {
+    const reason = `${transition.reason}:${transition.issueId}`;
+    return {
+      transitioned: false,
+      issueId: transition.issueId,
+      reason,
+      blockers: freezeBlocker(reason),
+      scopeId: target.scopeId,
+      targetScopeSnapshot: inputs.targetScopeSnapshot,
+    };
+  }
+
+  const audit = buildLifecycleAudit(inputs, transition);
+  inputs.bus?.emitLazy("scope", () => ({
+    type: "scope.action_audit",
+    payload: audit,
+  }));
+  return {
+    transitioned: true,
+    issueId: transition.issueId,
+    entryId: transition.entryId,
+    scopeId: target.scopeId,
+    fromStatus: transition.fromStatus,
+    toStatus: transition.toStatus,
+    lifecycleAudit: transition.audit,
+    targetScopeSnapshot: inputs.targetScopeSnapshot,
+    audit,
+  };
+}