@beyondwork/docx-react-component 1.0.105 → 1.0.108

package/src/api/v3/ai/replacement.ts

@@ -9,12 +9,10 @@
  *   `composeScopeValidation`, and projects the richer compiler verdict
  *   into the v3-facing `ValidationResult` shape.
  *
- * The v3 `ValidationResult` shape (`{ proposalId, safe, blockers? }`)
- * stays narrow by design. The compiler-side `ValidationResult`
- * (`{ safe, blockedReasons, warnings, approval }`) remains the authority
- * for internal consumers; the v3 projection trades richness for a
- * stable external contract. Slice 5's apply pipeline reads the
- * compiler verdict directly rather than the v3 projection.
+ * The v3 `ValidationResult` shape stays narrow by design. The compiler-side
+ * `ValidationResult` remains the authority for internal consumers; the v3
+ * projection carries only stable routing facts (`safe`, blockers, warnings,
+ * approval, and the hard-refusal / warn-and-proceed posture).
  */
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
@@ -26,17 +24,23 @@ import {
   createScopeCompilerService,
 } from "../../../runtime/scopes/index.ts";
 import type {
-  ReplacementOperationKind,
   ReplacementPreservePolicy,
+  ScopeActionPosture,
+  ScopeReplacementOperationKind,
   ScopeFormattingAction,
   ValidationResult as CompilerValidationResult,
 } from "../../../runtime/scopes/index.ts";
 import type { AIAction } from "../../../runtime/workflow/ai-action-policy.ts";
 import type { TextFormattingDirective } from "../../public-types.ts";
+import {
+  projectAuditReference,
+  type AiActionAuditReference,
+} from "./_audit-reference.ts";
+import { currentAuditTimestamp } from "./_audit-time.ts";
 
 export interface ReplacementProposalInput {
   readonly targetScopeId: string;
-  readonly operation: ReplacementOperationKind;
+  readonly operation: ScopeReplacementOperationKind;
   readonly proposedText?: string;
   readonly formatting?: TextFormattingDirective;
   readonly preserve?: ReplacementPreservePolicy;
@@ -90,6 +94,7 @@ export const proposeReplacementScopeMetadata: ApiV3FnMetadata = {
 export interface ValidationResult {
   readonly proposalId: string;
   readonly safe: boolean;
+  readonly posture?: ScopeActionPosture;
   readonly blockers?: readonly string[];
   readonly warnings?: readonly string[];
   readonly approvalRequired?: boolean;
@@ -121,10 +126,12 @@ export const validateReplacementScopeMetadata: ApiV3FnMetadata = {
 export interface ApplyResult {
   readonly proposalId: string;
   readonly applied: boolean;
+  readonly posture?: ScopeActionPosture;
   readonly reason?: string;
   readonly blockers?: readonly string[];
   readonly blockerDetails?: readonly ActionBlockerDetail[];
   readonly auditHint?: string;
+  readonly auditReference?: AiActionAuditReference;
   /**
    * Gap A (post-Slice-7 integration) — revision IDs authored during
    * the apply. Populated for suggest-mode (tracked insert + delete);
@@ -140,16 +147,20 @@ export interface ActionBlockerDetail {
     | "unsupported-scope-kind"
     | "unsupported-operation"
     | "unresolved-scope"
-    | "policy-or-guard";
+    | "preservation-boundary"
+    | "policy-or-guard"
+    | "capability-prerequisite";
   readonly message: string;
   readonly nextStep: string;
   readonly scopeKind?: string;
   readonly operation?: string;
+  readonly fragmentId?: string;
+  readonly payloadKind?: string;
 }
 
 export interface ApplyReplacementScopeInput {
   readonly targetScopeId: string;
-  readonly operation?: ReplacementOperationKind;
+  readonly operation?: ScopeReplacementOperationKind;
   /**
    * Flat text payload. Shorthand for
    * `proposedContent: {kind: "text", text}`. Ignored when
@@ -249,7 +260,7 @@ export const applyScopeActionMetadata: ApiV3FnMetadata = {
 export interface ValidateReplacementScopeInput {
   readonly proposalId?: string;
   readonly targetScopeId?: string;
-  readonly operation?: ReplacementOperationKind;
+  readonly operation?: ScopeReplacementOperationKind;
   readonly proposedText?: string;
   /** Optional action id override; composer derives a default otherwise. */
   readonly actionId?: AIAction;
@@ -270,6 +281,7 @@ function projectValidationResult(
   return {
     proposalId,
     safe: verdict.safe,
+    ...(verdict.posture ? { posture: verdict.posture } : {}),
     ...(blockers ? { blockers } : {}),
     ...(warnings ? { warnings } : {}),
     ...(verdict.approval?.required ? { approvalRequired: true } : {}),
@@ -288,6 +300,22 @@ function blockerDetailFor(code: string): ActionBlockerDetail | null {
     };
   }
 
+  if (code.startsWith("preserve:opaque-fragment:")) {
+    const parts = code.split(":");
+    const payloadKind = parts.at(-1) ?? "unknown";
+    const fragmentId =
+      parts.length > 4 ? parts.slice(2, -1).join(":") : "unknown";
+    return {
+      code,
+      category: "preservation-boundary",
+      fragmentId,
+      payloadKind,
+      message: `Replacement crosses preserve-only opaque fragment ${fragmentId} (${payloadKind}).`,
+      nextStep:
+        "Retry with preserve:{opaqueFragments:true} only when preserving opaque payloads in place is acceptable, or attach an explanation/issue instead of mutating.",
+    };
+  }
+
   if (!code.startsWith("compile-refused:")) return null;
 
   const [, scopeKind = "unknown", ...rest] = code.split(":");
@@ -305,12 +333,45 @@ function blockerDetailFor(code: string): ActionBlockerDetail | null {
     };
   }
 
-  if (scopeKind === "scope" && suffix === "multi-paragraph-replace-not-implemented") {
+  if (
+    suffix === "formatting-not-implemented" ||
+    suffix === "formatting-suggesting-not-implemented"
+  ) {
+    return {
+      code,
+      category: "unsupported-operation",
+      scopeKind,
+      operation: "formatting",
+      message:
+        suffix === "formatting-suggesting-not-implemented"
+          ? `Suggest-mode formatting is not implemented for ${scopeKind} scopes.`
+          : `Formatting actions are not implemented for ${scopeKind} scopes.`,
+      nextStep:
+        "Use a supported paragraph-like scope in direct-edit mode, or attach an explanation/issue instead of mutating.",
+    };
+  }
+
+  if (
+    scopeKind === "scope" &&
+    (suffix === "multi-paragraph-replace-not-implemented" ||
+      suffix === "multi-paragraph-text-replace-not-implemented" ||
+      suffix === "multi-paragraph-fragment-replace-not-implemented")
+  ) {
+    const operation =
+      suffix === "multi-paragraph-text-replace-not-implemented"
+        ? "replace-text"
+        : suffix === "multi-paragraph-fragment-replace-not-implemented"
+          ? "replace-fragment"
+          : "replace";
     return {
       code,
       category: "unsupported-scope-kind",
       scopeKind,
-      message: "Multi-paragraph scope replacement is not implemented.",
+      operation,
+      message:
+        operation === "replace"
+          ? "Multi-paragraph scope replacement is not implemented."
+          : `Multi-paragraph scope ${operation} is not implemented.`,
       nextStep:
         "Split the request into paragraph-scoped replacements, or attach an explanation/issue until the multi-paragraph planner ships.",
     };
@@ -323,7 +384,7 @@ function blockerDetailFor(code: string): ActionBlockerDetail | null {
       scopeKind,
       message: `Flat text replacement is not implemented for ${scopeKind} scopes because it can break table structure.`,
       nextStep:
-        "Use ai.attachExplanation or ai.createIssue for now, or wait for the Layer 08 table-family replacement planner.",
+        "Use ai.attachExplanation or ai.createIssue on this scopeId for metadata fallback. For realized table-cell text edits, a host can route through runtime.content.replaceText; whole-table and row edits wait for the Layer 08 table-family replacement planner.",
     };
   }
 
@@ -359,11 +420,34 @@ function blockerDetailFor(code: string): ActionBlockerDetail | null {
   };
 }
 
+function capabilityBlockerDetailFor(code: string): ActionBlockerDetail | null {
+  if (!code.startsWith("capability:scope:")) return null;
+  const requirement = code.slice("capability:scope:".length);
+  const labels: Record<string, string> = {
+    "block-granular-replacement-lowering-required":
+      "block-granular replacement lowering",
+    "provenance:marker-backed-required": "marker-backed scope provenance",
+    "layout-completeness-required": "complete layout evidence",
+    "geometry-completeness-required": "complete geometry evidence",
+    "continuation-state-required": "page-continuation state",
+    "preservation-verdict-required": "preservation verdict evidence",
+  };
+  const label = labels[requirement] ?? requirement.replaceAll("-", " ");
+  return {
+    code,
+    category: "capability-prerequisite",
+    scopeKind: "scope",
+    message: `Multi-paragraph scope replacement requires ${label}.`,
+    nextStep:
+      "Keep the action blocked and use paragraph-scoped replacements or attach an explanation/issue until the Scopes2 planner provides this prerequisite.",
+  };
+}
+
 function projectBlockerDetails(
   blockers: readonly string[],
 ): readonly ActionBlockerDetail[] | undefined {
   const details = blockers
-    .map((code) => blockerDetailFor(code))
+    .map((code) => capabilityBlockerDetailFor(code) ?? blockerDetailFor(code))
     .filter((detail): detail is ActionBlockerDetail => detail !== null);
   return details.length > 0 ? Object.freeze(details) : undefined;
 }
@@ -401,6 +485,7 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         return {
           proposalId,
           safe: false,
+          posture: "hard-refusal",
           blockers: Object.freeze([
             "legacy-proposalId-only:pass-targetScopeId-to-validate-now",
           ]),
@@ -412,13 +497,14 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         return {
           proposalId,
           safe: false,
+          posture: "hard-refusal",
           blockers: Object.freeze([
             `scope-not-resolvable:${input.targetScopeId}`,
           ]),
         };
       }
 
-      const operation: ReplacementOperationKind = input.operation ?? "replace";
+      const operation: ScopeReplacementOperationKind = input.operation ?? "replace";
       const proposedContent =
         typeof input.proposedText === "string"
           ? ({ kind: "text", text: input.proposedText } as const)
@@ -465,7 +551,7 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         ...(input.actionId ? { actionId: input.actionId } : {}),
         actorId: input.actorId ?? "agent",
         origin: input.origin ?? "agent",
-        emittedAtUtc: new Date(0).toISOString(),
+        emittedAtUtc: currentAuditTimestamp(runtime),
       });
 
       emitUxResponse(runtime, {
@@ -482,12 +568,16 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
       return {
         proposalId,
         applied: result.applied,
+        ...(result.validation.posture ? { posture: result.validation.posture } : {}),
         ...(result.reason ? { reason: result.reason } : {}),
         ...(result.validation.blockedReasons.length > 0
           ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
           : {}),
         ...(blockerDetails ? { blockerDetails } : {}),
         ...(result.audit ? { auditHint: result.audit.actionId } : {}),
+        ...(result.audit
+          ? { auditReference: projectAuditReference(result.audit) }
+          : {}),
         authoredRevisionIds: result.authoredRevisionIds,
       };
     },
@@ -510,7 +600,7 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
         ...(input.actionId ? { actionId: input.actionId } : {}),
         actorId: input.actorId ?? "agent",
         origin: input.origin ?? "agent",
-        emittedAtUtc: new Date(0).toISOString(),
+        emittedAtUtc: currentAuditTimestamp(runtime),
       });
 
       emitUxResponse(runtime, {
@@ -527,12 +617,16 @@ export function createReplacementFamily(runtime: RuntimeApiHandle) {
       return {
         proposalId,
         applied: result.applied,
+        ...(result.validation.posture ? { posture: result.validation.posture } : {}),
         ...(result.reason ? { reason: result.reason } : {}),
         ...(result.validation.blockedReasons.length > 0
           ? { blockers: Object.freeze([...result.validation.blockedReasons]) }
           : {}),
         ...(blockerDetails ? { blockerDetails } : {}),
         ...(result.audit ? { auditHint: result.audit.actionId } : {}),
+        ...(result.audit
+          ? { auditReference: projectAuditReference(result.audit) }
+          : {}),
         authoredRevisionIds: result.authoredRevisionIds,
       };
     },

package/src/api/v3/ai/resolve.ts

@@ -117,7 +117,7 @@ export const queryScopeAtPositionMetadata: ApiV3FnMetadata = {
   sourceLayer: "semantic-scope-compiler",
   liveEvidence: {
     runnerTest: "test/api/v3/ai/query-scope-position.test.ts",
-    commit: "pending",
+    commit: "a7518fb46",
   },
   uxIntent: { uiVisible: false, expectsUxResponse: "none" },
   agentMetadata: {
@@ -139,7 +139,7 @@ export const queryScopeInRangeMetadata: ApiV3FnMetadata = {
   sourceLayer: "semantic-scope-compiler",
   liveEvidence: {
     runnerTest: "test/api/v3/ai/query-scope-position.test.ts",
-    commit: "pending",
+    commit: "a7518fb46",
   },
   uxIntent: { uiVisible: false, expectsUxResponse: "none" },
   agentMetadata: {

package/src/api/v3/ai/review.ts

@@ -32,11 +32,17 @@
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import { emitUxResponse } from "../_ux-response.ts";
+import { createScopeCompilerService } from "../../../runtime/scopes/index.ts";
 import {
   captureScopeSnapshot,
   emitScopeMetadataAudit,
   snapshotDocumentHash,
 } from "./_metadata-audit.ts";
+import { currentAuditTimestamp } from "./_audit-time.ts";
+import {
+  projectAuditReference,
+  type AiActionAuditReference,
+} from "./_audit-reference.ts";
 
 export interface AcceptRevisionInput {
   readonly revisionId: string;
@@ -76,6 +82,42 @@ export interface ResolveCommentThreadResult {
   readonly reason?: string;
 }
 
+export interface ResolveIssueInput {
+  readonly issueId: string;
+  readonly actorId?: string;
+  readonly origin?: "ui" | "agent" | "host";
+}
+
+export interface ResolveIssueResult {
+  readonly issueId: string;
+  readonly resolved: boolean;
+  readonly reason?: string;
+  readonly blockers?: readonly string[];
+  readonly entryId?: string;
+  readonly scopeId?: string;
+  readonly fromStatus?: "open" | "resolved";
+  readonly toStatus?: "open" | "resolved";
+  readonly auditReference?: AiActionAuditReference;
+}
+
+export interface ReopenIssueInput {
+  readonly issueId: string;
+  readonly actorId?: string;
+  readonly origin?: "ui" | "agent" | "host";
+}
+
+export interface ReopenIssueResult {
+  readonly issueId: string;
+  readonly reopened: boolean;
+  readonly reason?: string;
+  readonly blockers?: readonly string[];
+  readonly entryId?: string;
+  readonly scopeId?: string;
+  readonly fromStatus?: "open" | "resolved";
+  readonly toStatus?: "open" | "resolved";
+  readonly auditReference?: AiActionAuditReference;
+}
+
 export const acceptRevisionMetadata: ApiV3FnMetadata = {
   name: "ai.acceptRevision",
   status: "live-with-adapter",
@@ -157,7 +199,64 @@ export const resolveCommentThreadMetadata: ApiV3FnMetadata = {
     "§AI API § ai.resolveCommentThread. Adapter over runtime.resolveComment (Layer-06 review-workflow). A4 audit emitted when scopeId hint resolves.",
 };
 
+export const resolveIssueMetadata: ApiV3FnMetadata = {
+  name: "ai.resolveIssue",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest:
+      "test/runtime/scopes/issue-lifecycle.test.ts,test/api/v3/ai/ai-review-workflow.test.ts",
+    commit: "refactor-09-issue-lifecycle-projection",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "AI issue status changes to resolved",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "scope",
+    auditCategory: "issue-resolve",
+    contextPromptShape:
+      "Resolve an AI-created issue by issueId or metadata entry id. Refuses if the issue target scope no longer compiles.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§AI API § ai.resolveIssue. Adapter over the Layer-08 issue lifecycle binding and Layer-06 durable ai.issue status transition. Finds the issue metadata entry, recompiles its target scope, transitions open -> resolved, and returns a compact auditReference on success.",
+};
+
+export const reopenIssueMetadata: ApiV3FnMetadata = {
+  name: "ai.reopenIssue",
+  status: "live-with-adapter",
+  sourceLayer: "semantic-scope-compiler",
+  liveEvidence: {
+    runnerTest:
+      "test/runtime/scopes/issue-lifecycle.test.ts,test/api/v3/ai/ai-review-workflow.test.ts",
+    commit: "refactor-09-issue-lifecycle-projection",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "AI issue status changes back to open",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "scope",
+    auditCategory: "issue-reopen",
+    contextPromptShape:
+      "Reopen a resolved AI-created issue by issueId or metadata entry id. Refuses if the issue target scope no longer compiles.",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§AI API § ai.reopenIssue. Adapter over the Layer-08 issue lifecycle binding and Layer-06 durable ai.issue status transition. Finds the issue metadata entry, recompiles its target scope, transitions resolved -> open, and returns a compact auditReference on success.",
+};
+
 export function createReviewFamily(runtime: RuntimeApiHandle) {
+  const compiler = createScopeCompilerService(runtime);
   return {
     acceptRevision(input: AcceptRevisionInput): AcceptRevisionResult {
       // @endStateApi — live-with-adapter. Routes through Layer-06's
@@ -199,7 +298,7 @@ export function createReviewFamily(runtime: RuntimeApiHandle) {
           },
           compiledOperationKind: "metadata-attach-explanation",
           compiledOperationSummary: `accept revision ${revisionId}`,
-          emittedAtUtc: new Date(0).toISOString(),
+          emittedAtUtc: currentAuditTimestamp(runtime),
           documentHashBefore,
         });
       }
@@ -258,7 +357,7 @@ export function createReviewFamily(runtime: RuntimeApiHandle) {
           },
           compiledOperationKind: "metadata-attach-explanation",
           compiledOperationSummary: `reject revision ${revisionId}`,
-          emittedAtUtc: new Date(0).toISOString(),
+          emittedAtUtc: currentAuditTimestamp(runtime),
           documentHashBefore,
         });
       }
@@ -319,7 +418,7 @@ export function createReviewFamily(runtime: RuntimeApiHandle) {
           },
           compiledOperationKind: "metadata-attach-explanation",
           compiledOperationSummary: `resolve comment thread ${threadId}`,
-          emittedAtUtc: new Date(0).toISOString(),
+          emittedAtUtc: currentAuditTimestamp(runtime),
           documentHashBefore,
         });
       }
@@ -338,5 +437,80 @@ export function createReviewFamily(runtime: RuntimeApiHandle) {
             reason: `thread-not-resolvable:${threadId}`,
           };
     },
+
+    resolveIssue(input: ResolveIssueInput): ResolveIssueResult {
+      // @endStateApi — live-with-adapter. L06 owns durable ai.issue
+      // transitions; L08 owns the scope/evidence join. This adapter keeps the
+      // public AI surface flat and projects a compact audit reference.
+      const result = compiler.transitionIssueLifecycle({
+        issueId: input.issueId,
+        action: "resolve",
+        actorId: input.actorId ?? "agent",
+        origin: input.origin ?? "agent",
+        emittedAtUtc: currentAuditTimestamp(runtime),
+      });
+      emitUxResponse(runtime, {
+        apiFn: resolveIssueMetadata.name,
+        intent: resolveIssueMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: resolveIssueMetadata.uxIntent.expectedDelta,
+      });
+      if (!result.transitioned) {
+        return {
+          issueId: result.issueId,
+          resolved: false,
+          reason: result.reason,
+          blockers: Object.freeze([...result.blockers]),
+          ...(result.scopeId ? { scopeId: result.scopeId } : {}),
+        };
+      }
+      return {
+        issueId: result.issueId,
+        resolved: true,
+        entryId: result.entryId,
+        scopeId: result.scopeId,
+        fromStatus: result.fromStatus,
+        toStatus: result.toStatus,
+        auditReference: projectAuditReference(result.audit),
+      };
+    },
+
+    reopenIssue(input: ReopenIssueInput): ReopenIssueResult {
+      // @endStateApi — live-with-adapter. Symmetric with resolveIssue, but
+      // transitions resolved ai.issue metadata back to open.
+      const result = compiler.transitionIssueLifecycle({
+        issueId: input.issueId,
+        action: "reopen",
+        actorId: input.actorId ?? "agent",
+        origin: input.origin ?? "agent",
+        emittedAtUtc: currentAuditTimestamp(runtime),
+      });
+      emitUxResponse(runtime, {
+        apiFn: reopenIssueMetadata.name,
+        intent: reopenIssueMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: reopenIssueMetadata.uxIntent.expectedDelta,
+      });
+      if (!result.transitioned) {
+        return {
+          issueId: result.issueId,
+          reopened: false,
+          reason: result.reason,
+          blockers: Object.freeze([...result.blockers]),
+          ...(result.scopeId ? { scopeId: result.scopeId } : {}),
+        };
+      }
+      return {
+        issueId: result.issueId,
+        reopened: true,
+        entryId: result.entryId,
+        scopeId: result.scopeId,
+        fromStatus: result.fromStatus,
+        toStatus: result.toStatus,
+        auditReference: projectAuditReference(result.audit),
+      };
+    },
   };
 }

package/src/api/v3/index.ts

@@ -14,6 +14,14 @@
 
 export { createApiV3 } from "./_create.ts";
 export type { ApiV3, CreateApiV3Opts } from "./_create.ts";
+export type {
+  AiPe2EvidenceOptions,
+  AiPe2GraphOracleReference,
+  AiPe2OracleEvidence,
+  AiPe2OracleEvidenceProvider,
+  AiPe2OracleEvidenceProviderInput,
+  AiPe2OracleVerdict,
+} from "./ai/_pe2-evidence.ts";
 
 export type {
   ApiStatus,