@beyondwork/docx-react-component 1.0.136 → 1.0.137

package/dist/api/v3.cjs

@@ -40307,13 +40307,32 @@ function storyKeyFromHandle(handle) {
 function textLeafEditableTargetHint(entry, semanticBlockRange) {
   const storyKey = storyKeyFromHandle(entry.handle);
   if (!storyKey) return void 0;
+  const semanticBlockPath = textLeafBlockPathFromSemanticPath(entry.handle.semanticPath, storyKey);
   return {
     kind: "text-leaf",
     storyKey,
-    blockPath: `${storyKey}/block[${entry.blockIndex}]`,
+    blockPath: semanticBlockPath ?? `${storyKey}/block[${entry.blockIndex}]`,
     semanticBlockRange
   };
 }
+function textLeafBlockPathFromSemanticPath(semanticPath, storyKey) {
+  if (!semanticPath) return null;
+  const tableIndex = semanticPath.indexOf("table");
+  const rowIndex = semanticPath.indexOf("row", tableIndex + 1);
+  const cellIndex = semanticPath.indexOf("cell", rowIndex + 1);
+  const paragraphIndex = semanticPath.indexOf("paragraph", cellIndex + 1);
+  if (tableIndex < 0 || rowIndex < 0 || cellIndex < 0 || paragraphIndex < 0) {
+    return null;
+  }
+  const table = Number(semanticPath[tableIndex + 1]);
+  const row = Number(semanticPath[rowIndex + 1]);
+  const cell = Number(semanticPath[cellIndex + 1]);
+  const paragraph = Number(semanticPath[paragraphIndex + 1]);
+  if (!Number.isInteger(table) || !Number.isInteger(row) || !Number.isInteger(cell) || !Number.isInteger(paragraph)) {
+    return null;
+  }
+  return `${storyKey}/block[${table}]/row[${row}]/cell[${cell}]/block[${paragraph}]`;
+}
 function compileParagraphReplacement(entry, proposed, options) {
   if (proposed.operation !== "replace" && proposed.operation !== "insert-before" && proposed.operation !== "insert-after") {
     return null;
@@ -47610,6 +47629,29 @@ var createScopeFromAnchorMetadata = {
   broadcastsVia: "crdt",
   rwdReference: "\xA7Runtime API \xA7 runtime.workflow.createScopeFromAnchor. Companion to createScope({blockId}) for sub-block ranges. Consumes from/to once to plant inline scope_marker_start/end; the returned scopeId is the durable reference (KI-P9)."
 };
+var createScopesMetadata = {
+  name: "runtime.workflow.createScopes",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/workflow-create-scope-live.test.ts",
+    commit: "pending"
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "scope-created",
+    expectedDelta: "rail shows new scope chips; editor surface refreshes once after the bulk scope batch"
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "selection",
+    auditCategory: "scope-creation"
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "\xA7Runtime API \xA7 runtime.workflow.createScopes. Bulk companion to createScope/createScopeFromAnchor; resolves blockId/range inputs, plants marker-backed scopes via one runtime addScopes batch, and returns per-item results."
+};
 var setScopeGuardPolicyMetadata = {
   name: "runtime.workflow.setScopeGuardPolicy",
   status: "live",
@@ -47705,6 +47747,228 @@ var setMarkupModePolicyMetadata = {
   broadcastsVia: "crdt",
   rwdReference: "\xA7Runtime API \xA7 runtime.workflow.setMarkupModePolicy"
 };
+function isAnchorScopeInput(input) {
+  return "anchor" in input;
+}
+function normalizeCreateScopesAnchor(anchor) {
+  const candidate = anchor;
+  const activeRange = candidate.activeRange;
+  if (activeRange?.kind === "range") {
+    return {
+      from: activeRange.from,
+      to: activeRange.to,
+      storyTarget: candidate.storyTarget
+    };
+  }
+  if (candidate.kind === "range") {
+    return {
+      from: candidate.from ?? Number.NaN,
+      to: candidate.to ?? Number.NaN,
+      storyTarget: candidate.storyTarget
+    };
+  }
+  return {
+    from: candidate.from ?? Number.NaN,
+    to: candidate.to ?? Number.NaN,
+    storyTarget: candidate.storyTarget
+  };
+}
+function stableRefMetadataFields(stableRefHint) {
+  if (stableRefHint === void 0) return void 0;
+  return [{
+    key: "stableRefHint",
+    valueType: "string",
+    value: stableRefHint
+  }];
+}
+function createRangeInvalidResult(inputIndex, reason, from, to, storyLength, detail) {
+  const base = {
+    inputIndex,
+    scopeId: "",
+    status: "range-invalid",
+    reason,
+    from,
+    to,
+    storyLength,
+    ...detail?.blockIndex !== void 0 ? { blockIndex: detail.blockIndex } : {},
+    ...detail?.blockKind !== void 0 ? { blockKind: detail.blockKind } : {}
+  };
+  switch (reason) {
+    case "non-finite-range":
+      return {
+        ...base,
+        message: `createScopes requires finite numeric from/to values (received from=${from}, to=${to}). Pass selection.activeRange or an object shaped as {from, to}.`,
+        nextStep: "pass-selection-activeRange-or-finite-from-to"
+      };
+    case "from-negative":
+      return {
+        ...base,
+        message: `createScopes requires from >= 0 (received from=${from}). Clamp negative values to 0 before calling.`,
+        nextStep: "clamp-from-to-zero"
+      };
+    case "to-less-than-from":
+      return {
+        ...base,
+        message: `createScopes requires to >= from (received from=${from}, to=${to}). Swap the two values before calling.`,
+        nextStep: "swap-from-and-to"
+      };
+    case "range-exceeds-story-length":
+      return {
+        ...base,
+        message: `createScopes requires to <= storyLength (received to=${to}, storyLength=${storyLength}). Re-derive positions from the current document and retry.`,
+        nextStep: "clamp-to-to-storyLength-or-pick-a-different-range"
+      };
+    case "non-paragraph-target":
+      return {
+        ...base,
+        message: `createScopes refused range [${from}, ${to}]: it targets a ${detail?.blockKind ?? "non-paragraph"} block. Pick a paragraph target or use a structural workflow scope.`,
+        nextStep: "pick-a-paragraph-target"
+      };
+    case "empty-document":
+      return {
+        ...base,
+        message: "createScopes refused: the target document has no blocks; initialize a document before creating scopes.",
+        nextStep: "initialize-document-before-creating-scopes"
+      };
+  }
+}
+function plantFailureToCreateScopesResult(pending, result) {
+  const status = result.plantStatus;
+  if (!status || status.planted !== false) {
+    return {
+      inputIndex: pending.inputIndex,
+      status: "created",
+      scopeId: result.scopeId
+    };
+  }
+  if (status.reason === "non-paragraph-target") {
+    return createRangeInvalidResult(
+      pending.inputIndex,
+      "non-paragraph-target",
+      pending.from,
+      pending.to,
+      status.storyLength ?? pending.storyLength,
+      {
+        blockIndex: status.blockIndex ?? -1,
+        blockKind: status.blockKind ?? "unknown"
+      }
+    );
+  }
+  if (status.reason === "range-out-of-bounds") {
+    return createRangeInvalidResult(
+      pending.inputIndex,
+      "range-exceeds-story-length",
+      pending.from,
+      pending.to,
+      status.storyLength ?? pending.storyLength
+    );
+  }
+  return createRangeInvalidResult(
+    pending.inputIndex,
+    "empty-document",
+    pending.from,
+    pending.to,
+    status.storyLength ?? pending.storyLength
+  );
+}
+function createScopesBulk(runtime, input) {
+  const doc = runtime.getCanonicalDocument();
+  const storyLength = runtime.getRenderSnapshot().surface?.storySize ?? 0;
+  const results = [];
+  const pending = [];
+  input.scopes.forEach((item, inputIndex) => {
+    const assoc = item.assoc ?? { start: 1, end: -1 };
+    const scopeMetadataFields = stableRefMetadataFields(item.stableRefHint);
+    if (isAnchorScopeInput(item)) {
+      const normalizedAnchor = normalizeCreateScopesAnchor(item.anchor);
+      const { from, to } = normalizedAnchor;
+      const itemStoryLength = normalizedAnchor.storyTarget?.kind === void 0 || normalizedAnchor.storyTarget.kind === "main" ? storyLength : Number.MAX_SAFE_INTEGER;
+      if (!Number.isFinite(from) || !Number.isFinite(to)) {
+        results.push(createRangeInvalidResult(inputIndex, "non-finite-range", from, to, itemStoryLength));
+        return;
+      }
+      if (from < 0) {
+        results.push(createRangeInvalidResult(inputIndex, "from-negative", from, to, itemStoryLength));
+        return;
+      }
+      if (to < from) {
+        results.push(createRangeInvalidResult(inputIndex, "to-less-than-from", from, to, itemStoryLength));
+        return;
+      }
+      if (to > itemStoryLength) {
+        results.push(createRangeInvalidResult(inputIndex, "range-exceeds-story-length", from, to, itemStoryLength));
+        return;
+      }
+      const anchor2 = {
+        kind: "range",
+        from,
+        to,
+        assoc
+      };
+      pending.push({
+        inputIndex,
+        request: {
+          anchor: anchor2,
+          scopeId: item.scopeId,
+          mode: item.mode,
+          persistence: item.persistence,
+          metadata: item.metadata,
+          label: item.label,
+          storyTarget: normalizedAnchor.storyTarget ?? { kind: "main" },
+          ...item.visibility ? { visibility: item.visibility } : {},
+          ...item.guardPolicy ? { guardPolicy: item.guardPolicy } : {},
+          ...scopeMetadataFields ? { scopeMetadataFields } : {}
+        },
+        from,
+        to,
+        storyLength: itemStoryLength
+      });
+      return;
+    }
+    const anchor = resolveBlockAnchorFromCanonical(doc, item.blockId, assoc);
+    if (!anchor || anchor.kind !== "range") {
+      results.push({
+        inputIndex,
+        scopeId: "",
+        status: "block-not-found"
+      });
+      return;
+    }
+    pending.push({
+      inputIndex,
+      request: {
+        anchor,
+        scopeId: item.scopeId,
+        mode: item.mode,
+        persistence: item.persistence,
+        metadata: item.metadata,
+        label: item.label,
+        ...item.visibility ? { visibility: item.visibility } : {},
+        ...item.guardPolicy ? { guardPolicy: item.guardPolicy } : {},
+        ...scopeMetadataFields ? { scopeMetadataFields } : {}
+      },
+      from: anchor.from,
+      to: anchor.to,
+      storyLength
+    });
+  });
+  const created = runtime.addScopes(pending.map((item) => item.request));
+  created.forEach((result, index) => {
+    const item = pending[index];
+    if (!item) return;
+    results.push(plantFailureToCreateScopesResult(item, result));
+  });
+  const sorted = results.sort((a, b) => a.inputIndex - b.inputIndex);
+  const createdCount = sorted.filter((item) => item.status === "created").length;
+  const blocked2 = sorted.length - createdCount;
+  return {
+    status: blocked2 === 0 ? "created" : createdCount > 0 ? "partial" : "blocked",
+    total: input.scopes.length,
+    created: createdCount,
+    blocked: blocked2,
+    scopes: Object.freeze(sorted)
+  };
+}
 function createWorkflowFamily(runtime) {
   return {
     queryScopes(filter) {
@@ -47719,7 +47983,10 @@ function createWorkflowFamily(runtime) {
     createScope(input) {
       const adapterResult = createScopeFromBlockId(runtime, {
         blockId: input.blockId,
+        scopeId: input.scopeId,
         mode: input.mode,
+        persistence: input.persistence,
+        metadata: input.metadata,
         label: input.label,
         ...input.visibility ? { visibility: input.visibility } : {},
         ...input.guardPolicy ? { guardPolicy: input.guardPolicy } : {},
@@ -47753,6 +48020,25 @@ function createWorkflowFamily(runtime) {
       }
       return { scopeId: adapterResult.scopeId, status: "created" };
     },
+    createScopes(input) {
+      const result = createScopesBulk(runtime, input);
+      emitUxResponse(runtime, {
+        apiFn: createScopesMetadata.name,
+        intent: createScopesMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: createScopesMetadata.uxIntent.expectedDelta,
+        actualDelta: result.created > 0 ? {
+          kind: "inline-change",
+          payload: {
+            created: result.created,
+            blocked: result.blocked,
+            scopeIds: result.scopes.filter((scope) => scope.status === "created").map((scope) => scope.scopeId)
+          }
+        } : void 0
+      });
+      return result;
+    },
     getScopeGuardPolicy(scopeId) {
       return runtime.getScopeGuardPolicy(scopeId);
     },
@@ -47788,7 +48074,10 @@ function createWorkflowFamily(runtime) {
     createScopeFromAnchor(input) {
       const adapterResult = createScopeFromAnchor(runtime, {
         anchor: input.anchor,
+        scopeId: input.scopeId,
         mode: input.mode,
+        persistence: input.persistence,
+        metadata: input.metadata,
         label: input.label,
         ...input.visibility ? { visibility: input.visibility } : {},
         ...input.guardPolicy ? { guardPolicy: input.guardPolicy } : {},
@@ -57199,6 +57488,12 @@ function createListsFamily(runtime) {
       const resolved = resolveCurrentListTarget(runtime.getCanonicalDocument(), input);
       return resolved.kind === "resolved" ? toReadback(runtime.getCanonicalDocument(), resolved.target, resolved.paragraph) : null;
     },
+    canJoin(input) {
+      return sequencePreflight(runtime.getCanonicalDocument(), input, activeStoryKey(runtime));
+    },
+    canContinuePrevious(input) {
+      return sequencePreflight(runtime.getCanonicalDocument(), input, activeStoryKey(runtime));
+    },
     previewCommand(input) {
       return previewListCommand(runtime.getCanonicalDocument(), input, activeStoryKey(runtime));
     },
@@ -57263,6 +57558,37 @@ function createListsFamily(runtime) {
     }
   };
 }
+function sequencePreflight(document2, input, activeStoryKey2) {
+  const resolved = resolveCurrentListTarget(document2, input);
+  if (resolved.kind !== "resolved") {
+    return {
+      canJoin: false,
+      canContinuePrevious: false,
+      blockers: [resolved.blocker]
+    };
+  }
+  const target = toReadback(document2, resolved.target, resolved.paragraph);
+  const targetRef = { targetKey: target.targetKey, addressKey: target.addressKey };
+  if (activeStoryKey2 !== void 0 && target.storyKey !== activeStoryKey2) {
+    return {
+      target,
+      canJoin: false,
+      canContinuePrevious: false,
+      blockers: [{
+        code: "list-target-wrong-story",
+        ownerLayer: "L07",
+        message: "List target does not belong to the runtime active story.",
+        ...targetRef
+      }]
+    };
+  }
+  return {
+    target,
+    canJoin: canJoinPreviousSequence(document2, resolved.paragraphIndex),
+    canContinuePrevious: canContinuePreviousSequence(document2, resolved.paragraphIndex),
+    blockers: []
+  };
+}
 function previewListCommand(document2, input, activeStoryKey2) {
   const resolved = resolveCurrentListTarget(document2, input);
   if (resolved.kind !== "resolved") {
@@ -57454,7 +57780,7 @@ function collectParagraphEntriesInto(blocks, storyKey, basePath, out) {
     const blockPath = `${basePath}/block[${blockIndex}]`;
     switch (block.type) {
       case "paragraph":
-        out.push({ paragraph: block, storyKey, blockPath });
+        out.push({ paragraph: block, storyKey, blockPath, containerPath: basePath });
         break;
       case "table":
         for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
@@ -57526,6 +57852,7 @@ function canContinuePreviousSequence(document2, paragraphIndex) {
   for (let index = paragraphIndex - 1; index >= 0; index -= 1) {
     const previousEntry = paragraphs[index];
     if (previousEntry?.storyKey !== currentEntry.storyKey) break;
+    if (previousEntry.containerPath !== currentEntry.containerPath) break;
     const previous = previousEntry.paragraph;
     if (!previous?.numbering) continue;
     const previousKind = getListKind(document2.numbering, previous.numbering.numberingInstanceId);
@@ -57538,6 +57865,7 @@ function canJoinPreviousSequence(document2, paragraphIndex) {
   const currentEntry = paragraphs[paragraphIndex];
   const previousEntry = paragraphs[paragraphIndex - 1];
   if (previousEntry?.storyKey !== currentEntry?.storyKey) return false;
+  if (previousEntry?.containerPath !== currentEntry?.containerPath) return false;
   const current = currentEntry?.paragraph;
   const previous = previousEntry?.paragraph;
   if (!current?.numbering || !previous?.numbering) return false;
@@ -63024,6 +63352,9 @@ function applyRewrite(runtime, target, input) {
   if (target.kind === "editable-text") {
     return applyEditableTextRewrite(runtime, target, input);
   }
+  if (target.handle.provenance === "marker-backed" && (target.scope.kind === "paragraph" || target.scope.kind === "list-item")) {
+    return applyMarkerBackedRangeRewrite(runtime, target, input);
+  }
   if (target.scope.kind === "list-item") {
     const listTextTarget = uniqueListTextActionForScope(runtime, target.handle);
     if (!listTextTarget.ok) return blockedApplyFromResolution(listTextTarget);
@@ -63170,13 +63501,97 @@ function applyEditableTextRewrite(runtime, target, input) {
     afterReadback
   };
 }
+function applyMarkerBackedRangeRewrite(runtime, target, input) {
+  const range = buildScopePositionMap(runtime.getCanonicalDocument()).markerScopes.get(
+    target.handle.scopeId
+  );
+  if (!range) {
+    return blockedApply(
+      `actions:rewrite:marker-range-unresolved:${target.handle.scopeId}`,
+      "unresolved-target",
+      "The marker-backed scope could not be joined to its current marker range.",
+      "Refresh placeholder scopes and retry; route persistent failures to L06 marker scope tracking."
+    );
+  }
+  const beforeReadback = markerScopeReadback(runtime, target.handle.scopeId) ?? {
+    text: target.scope.content.text,
+    isEmpty: target.scope.content.text.length === 0
+  };
+  const before = runtime.getCanonicalDocument();
+  const origin = actionOrigin(runtime, input);
+  runtime.dispatch({
+    type: "selection.set",
+    selection: {
+      anchor: range.from,
+      head: range.to,
+      isCollapsed: range.from === range.to,
+      activeRange: {
+        kind: "range",
+        from: range.from,
+        to: range.to,
+        assoc: { start: -1, end: 1 }
+      }
+    },
+    origin
+  });
+  const ack = runtime.applyActiveStoryTextCommand({
+    type: "text.insert",
+    text: input.text,
+    origin
+  });
+  const changed = runtime.getCanonicalDocument() !== before;
+  const afterReadback = markerScopeReadback(runtime, target.handle.scopeId);
+  const compiledAfter = createScopeCompilerService(runtime).compileScopeById(target.handle.scopeId);
+  if (!changed || afterReadback?.text !== input.text) {
+    return {
+      status: "blocked",
+      applied: false,
+      changed,
+      target: summarizeTarget(
+        compiledAfter ? { ...target, scope: compiledAfter.scope, handle: compiledAfter.scope.handle } : target
+      ),
+      posture: "suspect-readback",
+      blockers: Object.freeze([
+        `actions:rewrite:marker-range-readback-mismatch:${target.handle.scopeId}`
+      ]),
+      blockerDetails: Object.freeze([
+        blocker(
+          `actions:rewrite:marker-range-readback-mismatch:${target.handle.scopeId}`,
+          "blocked",
+          ack.kind === "rejected" ? "The marker-backed rewrite command was rejected or did not produce the requested marker readback." : "The marker-backed rewrite command did not produce the requested marker readback.",
+          "Treat the mutation as suspect. Re-read the target and export before claiming success."
+        )
+      ]),
+      ...afterReadback ? { afterReadback } : {}
+    };
+  }
+  return {
+    status: "applied",
+    applied: true,
+    changed: true,
+    target: summarizeTarget(
+      compiledAfter ? { ...target, scope: compiledAfter.scope, handle: compiledAfter.scope.handle } : target
+    ),
+    commandReference: {
+      command: "text.insert",
+      actorId: input.actorId ?? "v3-ai-api",
+      origin: input.origin ?? "agent",
+      emittedAtUtc: currentAuditTimestamp(runtime)
+    },
+    beforeReadback,
+    afterReadback
+  };
+}
 function applyTableScopedMarkerRewrite(runtime, target, action, input) {
   const workflowScope = runtime.getScope(target.handle.scopeId);
+  const markerRange = buildScopePositionMap(runtime.getCanonicalDocument()).markerScopes.get(
+    target.handle.scopeId
+  );
   const editableTarget = tableEditableTargetForActionHandle(
     runtime,
     action.actionHandle
   );
-  if (!workflowScope || workflowScope.anchor.kind !== "range" || !editableTarget) {
+  if (!workflowScope || !markerRange || !editableTarget) {
     return blockedApply(
       `actions:rewrite:table-marker-target-unresolved:${target.handle.scopeId}`,
       "unresolved-target",
@@ -63184,19 +63599,23 @@ function applyTableScopedMarkerRewrite(runtime, target, action, input) {
       "Refresh placeholder scopes and retry; route persistent failures to L08 table scope target mapping."
     );
   }
+  const beforeReadback = markerScopeReadback(runtime, target.handle.scopeId) ?? {
+    text: target.scope.content.text,
+    isEmpty: target.scope.content.text.length === 0
+  };
   const before = runtime.getCanonicalDocument();
   try {
     runtime.dispatch({
       type: "selection.set",
       selection: {
-        anchor: workflowScope.anchor.from,
-        head: workflowScope.anchor.to,
-        isCollapsed: workflowScope.anchor.from === workflowScope.anchor.to,
+        anchor: markerRange.from,
+        head: markerRange.to,
+        isCollapsed: markerRange.from === markerRange.to,
         activeRange: {
           kind: "range",
-          from: workflowScope.anchor.from,
-          to: workflowScope.anchor.to,
-          assoc: workflowScope.anchor.assoc ?? { start: -1, end: 1 }
+          from: markerRange.from,
+          to: markerRange.to,
+          assoc: { start: -1, end: 1 }
         }
       },
       origin: actionOrigin(runtime, input)
@@ -63231,12 +63650,19 @@ function applyTableScopedMarkerRewrite(runtime, target, action, input) {
   );
   const afterText = paragraph ? collectInlineText3(paragraph.children) : void 0;
   const afterReadback = afterText === void 0 ? void 0 : { text: afterText, isEmpty: afterText.length === 0 };
-  if (!changed || afterReadback?.text !== input.text) {
+  const compiledAfter = createScopeCompilerService(runtime).compileScopeById(target.handle.scopeId);
+  const scopeReadback = markerScopeReadback(runtime, target.handle.scopeId) ?? (compiledAfter ? {
+    text: compiledAfter.scope.content.text,
+    isEmpty: compiledAfter.scope.content.text.length === 0
+  } : void 0);
+  if (!changed || scopeReadback?.text !== input.text) {
     return {
       status: "blocked",
       applied: false,
       changed,
-      target: summarizeTarget({ kind: "table-text", action }),
+      target: summarizeTarget(
+        compiledAfter ? { ...target, scope: compiledAfter.scope, handle: compiledAfter.scope.handle } : target
+      ),
       posture: "suspect-readback",
       blockers: Object.freeze([
         `actions:rewrite:table-marker-readback-mismatch:${target.handle.scopeId}`
@@ -63249,25 +63675,24 @@ function applyTableScopedMarkerRewrite(runtime, target, action, input) {
           "Treat the mutation as suspect. Re-read the target and export before claiming success."
         )
       ]),
-      ...afterReadback ? { afterReadback } : {}
+      ...scopeReadback ? { afterReadback: scopeReadback } : afterReadback ? { afterReadback } : {}
     };
   }
   return {
     status: "applied",
     applied: true,
     changed: true,
-    target: summarizeTarget({
-      kind: "table-text",
-      action: { ...action, readback: afterReadback }
-    }),
+    target: summarizeTarget(
+      compiledAfter ? { ...target, scope: compiledAfter.scope, handle: compiledAfter.scope.handle } : { kind: "table-text", action: { ...action, readback: scopeReadback } }
+    ),
     commandReference: {
       command: "text.insert",
       actorId: input.actorId ?? "v3-ai-api",
       origin: input.origin ?? "agent",
       emittedAtUtc: currentAuditTimestamp(runtime)
     },
-    ...action.readback ? { beforeReadback: action.readback } : {},
-    afterReadback
+    beforeReadback,
+    afterReadback: scopeReadback
   };
 }
 function projectRewriteScopeResult(runtime, result, target, beforeText, proposedText, documentMutated) {
@@ -63361,7 +63786,7 @@ function summarizeTarget(target) {
   if (target.kind === "editable-text") {
     return {
       kind: target.targetKind,
-      handle: target.ownerHandle,
+      handle: publicActionScopeHandle(target.ownerHandle),
       actionHandle: target.actionHandle,
       readback: target.readback,
       canRewriteText: true,
@@ -63372,13 +63797,21 @@ function summarizeTarget(target) {
   }
   return {
     kind: target.scope.kind,
-    handle: target.handle,
+    handle: publicActionScopeHandle(target.handle),
     canRewriteText: canRewriteScopeText(target.scope),
     canInsertAdjacentText: canInsertAdjacentScopeText(target.scope),
     canFlag: true,
     canMark: canMarkScope(target.scope)
   };
 }
+function publicActionScopeHandle(handle) {
+  const parentScopeId = handle.parentScopeId;
+  if (!parentScopeId || !/^(cell|table|row|column|span):/u.test(parentScopeId)) {
+    return handle;
+  }
+  const { parentScopeId: _parentScopeId, ...rest } = handle;
+  return rest;
+}
 function tableTextActionsForScope(runtime, handle) {
   const result = createTableActionFamily(runtime).listTableActions({
     handle,
@@ -63431,6 +63864,13 @@ function tableEditableTargetForActionHandle(runtime, actionHandle) {
   }
   return null;
 }
+function markerScopeReadback(runtime, scopeId) {
+  const document2 = runtime.getCanonicalDocument();
+  const range = buildScopePositionMap(document2).markerScopes.get(scopeId);
+  if (!range) return null;
+  const text = textForCanonicalRange(document2, range.from, range.to);
+  return { text, isEmpty: text.length === 0 };
+}
 function editableTextActionsForScope(runtime, handle) {
   const bundle = createScopeCompilerService(runtime).compileBundleById(
     handle.scopeId,
@@ -64783,6 +65223,86 @@ function blockTextLength(block) {
       return 0;
   }
 }
+function textForCanonicalRange(document2, from, to) {
+  let cursor = 0;
+  let text = "";
+  const append = (value, start, end) => {
+    const clippedFrom = Math.max(from, start);
+    const clippedTo = Math.min(to, end);
+    if (clippedTo <= clippedFrom) return;
+    const localFrom = clippedFrom - start;
+    const localTo = clippedTo - start;
+    text += Array.from(value).slice(localFrom, localTo).join("");
+  };
+  const walkInline = (inline) => {
+    const start = cursor;
+    switch (inline.type) {
+      case "text": {
+        const length = Array.from(inline.text).length;
+        cursor += length;
+        append(inline.text, start, cursor);
+        return length;
+      }
+      case "tab":
+        cursor += 1;
+        append("	", start, cursor);
+        return 1;
+      case "hard_break":
+        cursor += 1;
+        append("\n", start, cursor);
+        return 1;
+      case "hyperlink":
+      case "field": {
+        const before = cursor;
+        for (const child of inline.children) {
+          walkInline(child);
+        }
+        return cursor - before;
+      }
+      case "bookmark_start":
+      case "bookmark_end":
+      case "scope_marker_start":
+      case "scope_marker_end":
+        return 0;
+      default:
+        cursor += 1;
+        return 1;
+    }
+  };
+  const walkBlock = (block) => {
+    if (!block) return 0;
+    const before = cursor;
+    switch (block.type) {
+      case "paragraph":
+        for (const child of block.children) walkInline(child);
+        break;
+      case "table":
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            for (const child of cell.children) walkBlock(child);
+          }
+        }
+        break;
+      case "sdt":
+      case "custom_xml":
+        for (const child of block.children) walkBlock(child);
+        break;
+      default:
+        cursor += 1;
+        break;
+    }
+    return cursor - before;
+  };
+  const blocks = document2.content.children;
+  for (let index = 0; index < blocks.length; index += 1) {
+    walkBlock(blocks[index]);
+    if (index < blocks.length - 1 && blocks[index + 1]?.type === "paragraph") {
+      cursor += 1;
+      append("\n", cursor - 1, cursor);
+    }
+  }
+  return text;
+}
 function inlineTextLength(inline) {
   if (!inline) return 0;
   switch (inline.type) {
@@ -64938,6 +65458,109 @@ function summarizePlanResult(mode, steps) {
   };
 }
 
+// src/api/v3/ai/agent.ts
+function createAgentFamily(runtime, pe2Evidence) {
+  const inspect = createInspectFamily(runtime, pe2Evidence);
+  const resolve = createResolveFamily(runtime);
+  const bundle = createBundleFamily(runtime, pe2Evidence);
+  const actions2 = createActionsFamily(runtime).actions;
+  const table = createTableActionFamily(runtime);
+  const object = createObjectActionFamily(runtime);
+  const policy = createPolicyFamily(runtime);
+  const evaluate = createEvaluateFamily(runtime);
+  const outline = createOutlineFamily(runtime);
+  const stats = createStatsFamily(runtime);
+  const explain = createExplainFamily(runtime);
+  const review = createReviewFamily2(runtime);
+  const exportFamily = createExportFamily(runtime);
+  const read = Object.freeze({
+    inspectDocument: inspect.inspectDocument,
+    listScopes: inspect.listScopes,
+    getScope: bundle.getScope,
+    getScopeBundle: bundle.getScopeBundle,
+    resolveReference: resolve.resolveReference,
+    queryScopeAtPosition: resolve.queryScopeAtPosition,
+    queryScopeInRange: resolve.queryScopeInRange,
+    brief: actions2.brief,
+    getDocumentOutline: outline.getDocumentOutline,
+    getDocumentStatistics: stats.getDocumentStatistics,
+    explainFormatting: explain.explainFormatting
+  });
+  const target = Object.freeze({
+    discover: actions2.discover,
+    locate: actions2.locate,
+    locateAll: actions2.locateAll,
+    createPlaceholderScopes: actions2.createPlaceholderScopes
+  });
+  const edit = Object.freeze({
+    rewrite: actions2.rewrite,
+    runPlan: actions2.runPlan,
+    insertText: actions2.insertText,
+    mark: actions2.mark,
+    flag: actions2.flag,
+    flagMany: actions2.flagMany,
+    fieldRefresh: actions2.fieldRefresh,
+    tocRefresh: actions2.tocRefresh,
+    bookmarkEdit: actions2.bookmarkEdit,
+    hyperlinkDestinationEdit: actions2.hyperlinkDestinationEdit,
+    hyperlinkTextEdit: actions2.hyperlinkTextEdit
+  });
+  const template = Object.freeze({
+    validateTargets: actions2.validateTemplateTargets,
+    readTarget: actions2.templateTargetRead,
+    fillField: actions2.templateFieldFill
+  });
+  const tableGroup = Object.freeze({
+    replaceContent: actions2.tableContent,
+    applyFragment: actions2.tableFragment,
+    applySelection: actions2.tableSelection,
+    listActions: table.listTableActions,
+    applyAction: table.applyTableAction
+  });
+  const list = Object.freeze({
+    applyOperation: actions2.listOperation
+  });
+  const objectGroup = Object.freeze({
+    listActions: object.listObjectActions,
+    applyAction: object.applyObjectAction
+  });
+  const reviewGroup = Object.freeze({
+    acceptRevision: review.acceptRevision,
+    rejectRevision: review.rejectRevision,
+    resolveCommentThread: review.resolveCommentThread,
+    resolveIssue: review.resolveIssue,
+    reopenIssue: review.reopenIssue
+  });
+  const policyGroup = Object.freeze({
+    getPolicy: policy.getPolicy,
+    listActions: policy.listAIActions,
+    evaluateAction: evaluate.evaluateAction
+  });
+  const exportGroup = Object.freeze({
+    reviewedDocument: exportFamily.exportReviewedDocument
+  });
+  const category = Object.freeze({
+    read,
+    target,
+    edit,
+    template,
+    table: tableGroup,
+    list,
+    object: objectGroup,
+    review: reviewGroup,
+    policy: policyGroup,
+    export: exportGroup
+  });
+  const family = {
+    agent() {
+      return category;
+    }
+  };
+  return {
+    agent: family.agent()
+  };
+}
+
 // src/api/v3/ui/_context.ts
 function createUiApiContext(handle) {
   return {
@@ -67248,7 +67871,8 @@ function createApiV3(handle, opts) {
     ...createOutlineFamily(handle),
     ...createTableActionFamily(handle),
     ...createObjectActionFamily(handle),
-    ...createActionsFamily(handle)
+    ...createActionsFamily(handle),
+    ...createAgentFamily(handle, opts?.pe2Evidence)
   };
   const runtime = {
     document: createDocumentFamily(handle),