@superdoc/sdk 2.13.0-next.8 → 2.13.0

package/dist/agent/actions.cjs

@@ -65,7 +65,7 @@ const ACTION_HINTS = {
     delete_blocks: 'selectors[] (each resolving to ONE inspected block: list item, paragraph or heading), changeMode? — THE way to DELETE a whole LIST ITEM, paragraph or heading, bullet/number included. Use for "remove the first item under Article II" / "delete that clause". delete_text only strikes the text and leaves an empty numbered item behind. Deletes several blocks in ONE call; use delete_table for a whole table and delete_text to clear a table cell (a cell must keep a paragraph)',
     append_list: 'items[], kind?: ordered|bullet, headingText?, headingLevel?, placement? {at:"after"|"before",selector} builds the list at that block instead of document end',
     create_table: 'rows, columns, cellTexts? (2D: rows of cells; each cell is a plain string OR a STYLED object {runs:[{text,marks}], marks?} to format the cell — marks: bold/italic/underline/strikethrough/fontFamily/fontSize(points)/color(hex)/highlight), placement?, changeMode? — style cells HERE, do not format_text afterward; changeMode:"tracked" makes the table insertion itself a tracked change',
-    rewrite_block: "selector, text, changeMode? — REPLACES the whole block text; the block's intra-paragraph run pattern is preserved best-effort over the unchanged prefix/suffix. For appending a NEW paragraph/clause use insert_paragraphs, and for small wording edits prefer replace_text with a minimal find span",
+    rewrite_block: "selector, text, changeMode? — REPLACES the whole block text using the document API's formatting preservation. For appending a NEW paragraph/clause use insert_paragraphs, and for small wording edits prefer replace_text with a minimal find span",
     fill_placeholders: 'values[] and/or fields[{label?,value}], changeMode?',
     move_range: 'fromText (text in the FIRST block of the range to move), toText? (text in the LAST block — omit to auto-extend across the whole VISUAL SECTION: from fromText up to the next heading-like/ALL-CAPS/bold title), then exactly ONE destination: afterText OR beforeText (text in the block to land after/before). Direct-only today: changeMode:"tracked" fails with no mutation because block-range deletion cannot be tracked. Moves plain paragraph/heading text only; a range containing a table, list, or image is refused with nothing changed. THE way to MOVE a contiguous block range or a visual "section" identified BY TEXT (works on styled-paragraph sections like PREAMBLE / SCHEDULE A that are NOT Word heading nodes). afterText on a heading-like block lands the range after that block\'s WHOLE section.',
     comment_paragraphs: 'commentText, scope?: all|body, excludeBlockQuotes?',
@@ -226,6 +226,53 @@ const ACTION_ARGS = {
     insert_page_break: ['selector'],
     add_hyperlink: ['text', 'url', 'tooltip'],
 };
+const ACTION_DISPOSITIONS = {
+    insert_paragraphs: 'tracked',
+    insert_heading: 'tracked',
+    replace_text: 'tracked',
+    delete_text: 'tracked',
+    delete_blocks: 'tracked',
+    append_list: 'tracked',
+    create_table: 'tracked',
+    comment_paragraphs: 'direct',
+    add_comments: 'direct',
+    resolve_comments: 'direct',
+    reply_to_comment: 'direct',
+    rewrite_block: 'tracked',
+    accept_tracked_changes: 'direct',
+    reject_tracked_changes: 'direct',
+    normalize_body_font_size: 'tracked',
+    set_font_family: 'tracked',
+    apply_letter_spacing: 'tracked',
+    fill_placeholders: 'tracked',
+    move_range: 'direct',
+    insert_toc: 'tracked',
+    insert_table_row: 'tracked',
+    insert_table_column: 'tracked',
+    delete_table_row: 'tracked',
+    delete_table_column: 'tracked',
+    split_table: 'tracked',
+    convert_list: 'tracked',
+    split_list: 'direct',
+    undo_changes: 'direct',
+    redo_changes: 'direct',
+    attach_numbering: 'tracked',
+    add_list_items: 'tracked',
+    format_text: 'tracked',
+    apply_style: 'direct',
+    format_paragraph: 'tracked',
+    move_text: 'tracked',
+    style_table: 'direct',
+    move_table: 'direct',
+    delete_table: 'tracked',
+    set_paragraph_spacing: 'direct',
+    insert_page_break: 'direct',
+    add_hyperlink: 'direct',
+};
+/** Fresh copy of {@link ACTION_DISPOSITIONS} for integrators (safe to mutate). */
+function getActionDispositions() {
+    return { ...ACTION_DISPOSITIONS };
+}
 function isActionName(value) {
     return typeof value === 'string' && ACTION_NAMES.includes(value);
 }
@@ -641,8 +688,8 @@ function evaluateChecks(pre, post, checks) {
         else if (check.kind === 'tracked-change-count-delta') {
             results.push({
                 check,
-                passed: post.trackedChanges.length - pre.trackedChanges.length === check.delta,
-                detail: `pre=${pre.trackedChanges.length} post=${post.trackedChanges.length}`,
+                passed: post.counts.trackedChanges - pre.counts.trackedChanges === check.delta,
+                detail: `pre=${pre.counts.trackedChanges} post=${post.counts.trackedChanges}`,
             });
         }
         else if (check.kind === 'revision-changed') {
@@ -1149,11 +1196,6 @@ async function runReplaceTextUnchecked(doc, args) {
         let skippedEdits = [];
         let steps;
         let applyExpectedRevision;
-        // Blocks whose text this call rewrites, with their pre-mutation run layout:
-        // the engine replace lane renders the replaced range as uniform runs, so a
-        // whole-paragraph find/replace flattens intra-paragraph formatting (bold
-        // lead-ins). Restore it positionally after the mutation.
-        const preserveTargets = [];
         if (args.selector) {
             const target = selectorToBlockTarget(args.selector, pre);
             if (!target) {
@@ -1192,13 +1234,6 @@ async function runReplaceTextUnchecked(doc, args) {
             ];
             applyExpectedRevision = pre.revision;
             selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
-            preserveTargets.push({
-                nodeId: target.nodeId,
-                nodeType: target.nodeType ?? 'paragraph',
-                oldText: target.text,
-                newText: rewrittenText,
-                runs: await captureBlockRuns(doc, target.nodeId, target.text),
-            });
         }
         else {
             let candidates = args.edits.map((edit, editIndex) => ({
@@ -1256,12 +1291,6 @@ async function runReplaceTextUnchecked(doc, args) {
             steps = candidates.map((candidate) => candidate.step);
         }
         const result = await executeMutations(doc, steps, args.changeMode, applyExpectedRevision);
-        const preserved = [];
-        for (const entry of preserveTargets) {
-            const restored = await preserveRunPatternAfterRewrite(doc, entry.nodeId, entry.oldText, entry.runs, entry.newText);
-            if (restored)
-                preserved.push({ nodeId: entry.nodeId, ...restored });
-        }
         if (args.selector && selectedTargets[0]) {
             const post = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] });
             const blockId = selectedTargets[0].matched[0];
@@ -1290,10 +1319,7 @@ async function runReplaceTextUnchecked(doc, args) {
                 preSnapshot: { revision: pre.revision, counts: pre.counts },
                 postSnapshot: { revision: post.revision, counts: post.counts },
                 selectedTargets,
-                executedOperations: [
-                    { operationId: 'doc.mutations.apply', result },
-                    ...(preserved.length > 0 ? [{ operationId: 'doc.format.apply', result: { preserved } }] : []),
-                ],
+                executedOperations: [{ operationId: 'doc.mutations.apply', result }],
                 verification,
             };
         }
@@ -1317,7 +1343,6 @@ async function runReplaceTextUnchecked(doc, args) {
                     ...(skippedEditRationale ? { rationale: skippedEditRationale } : {}),
                     result,
                 },
-                ...(preserved.length > 0 ? [{ operationId: 'doc.format.apply', result: { preserved } }] : []),
             ],
             verification,
         };
@@ -1566,11 +1591,25 @@ async function runDeleteBlocks(doc, args) {
         const changeMode = parseChangeMode(args.changeMode);
         const executedOperations = [];
         const deleted = [];
+        const addressedTrackedChangeIds = new Set();
+        let allTrackedEffectsAddressed = true;
         for (const target of targets) {
             try {
                 const result = await deleteFn({ target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId } }, changeMode ? { changeMode } : undefined);
                 executedOperations.push({ operationId: 'doc.blocks.delete', result: compactOpResult(result) });
                 deleted.push({ nodeId: target.nodeId, nodeType: target.nodeType });
+                if (changeMode === 'tracked') {
+                    // One block transaction can create multiple logical review entities
+                    // (for example, text plus its section break). Exact receipt refs let
+                    // us fail closed on missing entities. Older handles omit refs, and
+                    // adjacent deletions can coalesce into one review entity, so their
+                    // truthful fallback is the positive observed inventory delta rather
+                    // than one assumed entity per operation.
+                    const refIds = trackedChangeRefIds(result);
+                    allTrackedEffectsAddressed &&= refIds.size > 0;
+                    for (const entityId of refIds)
+                        addressedTrackedChangeIds.add(entityId);
+                }
             }
             catch (err) {
                 errors$1.push({
@@ -1584,14 +1623,37 @@ async function runDeleteBlocks(doc, args) {
         // Tracked deletions leave the block in place until the revision is decided,
         // so the block count cannot move — count the structural revisions instead.
         // Direct deletions must show one fewer block of each deleted node type.
+        const observedTrackedChangeDelta = post.counts.trackedChanges - pre.counts.trackedChanges;
+        // A later deletion can coalesce the batch and replace entity identities
+        // returned by earlier operation receipts. For a multi-operation batch the
+        // final inventory is therefore the authoritative count. A single operation
+        // keeps using its addressed refs so fan-out remains verifiable even when
+        // the inventory listing is capped.
+        const expectedTrackedChangeDelta = deleted.length > 1
+            ? observedTrackedChangeDelta
+            : allTrackedEffectsAddressed
+                ? addressedTrackedChangeIds.size
+                : Math.max(observedTrackedChangeDelta, addressedTrackedChangeIds.size);
         const checks = changeMode === 'tracked'
-            ? [{ kind: 'tracked-change-count-delta', delta: deleted.length }]
+            ? [
+                {
+                    kind: 'tracked-change-count-delta',
+                    delta: expectedTrackedChangeDelta,
+                },
+            ]
             : [...new Set(deleted.map((entry) => entry.nodeType))].map((nodeType) => ({
                 kind: 'block-count-delta',
                 nodeType,
                 delta: -deleted.filter((entry) => entry.nodeType === nodeType).length,
             }));
         const verification = evaluateChecks(pre, post, checks);
+        if (changeMode === 'tracked' && observedTrackedChangeDelta <= 0) {
+            verification[0] = {
+                ...verification[0],
+                passed: false,
+                detail: `pre=${pre.counts.trackedChanges} post=${post.counts.trackedChanges}; no tracked review entity was created`,
+            };
+        }
         // Compare against the DEDUPED target list: two selectors naming the same
         // block are one deletion, and counting the raw selectors would report a
         // fully applied call as `partial` with no error to explain it. Selectors
@@ -2590,7 +2652,6 @@ async function runRewriteBlock(doc, args) {
             throw new Error('selector did not resolve to a body block');
         context.selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
         const text = normalizeTitleLikeRewriteText(target.text, args.text);
-        const runs = await captureBlockRuns(doc, target.nodeId, target.text);
         await executeMutations(context.document, [
             {
                 id: 'rewrite-block-1',
@@ -2599,7 +2660,6 @@ async function runRewriteBlock(doc, args) {
                 args: { replacement: { text }, style: preserveRewriteStyle() },
             },
         ], args.changeMode, pre.revision);
-        await preserveRunPatternAfterRewrite(context.document, target.nodeId, target.text, runs, text);
         const post = await context.finish();
         const rewritten = await post.block(target.nodeId);
         const verification = [
@@ -2672,23 +2732,8 @@ async function captureBlockRuns(doc, nodeId, text) {
     }
 }
 /**
- * Re-apply a block's pre-rewrite run pattern after a whole-block text.rewrite.
- * The engine renders the rewritten block as a single uniform run, which both
- * drops intra-paragraph formatting AND can smear the first run's marks over
- * everything. Marks are restored positionally over the parts of the text the
- * rewrite did NOT change (the common prefix and suffix of old vs new text),
- * and the changed middle takes the marks of the run it continues from —
- * Word's "typing continues formatting" rule. Best-effort: never fails the
- * rewrite.
- */
-/**
- * Span-aware run-pattern restore for scoped replaces. The generic
- * preserveRunPatternAfterRewrite diffs prefix/suffix and treats everything
- * between the FIRST and LAST change as one modified middle — with two
- * separated replacements that flattens independently-styled runs between
- * them. Here the exact spans are known, so every untouched interval keeps its
- * original run formatting at the offset-mapped position, and each replacement
- * inherits the marks of the run it starts in.
+ * Restore scoped replacements from their known spans: each untouched interval
+ * keeps its run formatting, and replacements inherit the marks at their start.
  * `spans` are FULL-TEXT coordinates, ascending, non-overlapping.
  */
 async function preserveScopedRunPattern(doc, nodeId, oldText, oldRuns, spans) {
@@ -2781,74 +2826,6 @@ async function preserveScopedRunPattern(doc, nodeId, oldText, oldRuns, spans) {
         return { skipped: reasonOf(err) };
     }
 }
-async function preserveRunPatternAfterRewrite(doc, nodeId, oldText, oldRuns, newText) {
-    // Nothing to restore when the block was uniformly plain; a single STYLED run
-    // still needs restoring (whole-block replaces drop even uniform marks).
-    if (!oldRuns || oldRuns.length === 0)
-        return null;
-    if (!oldRuns.some((run) => Object.keys(inlineFromSnapshotRun(run, new Set())).length > 0))
-        return null;
-    const formatFn = maybeMethod(doc, ['format', 'apply']);
-    if (!formatFn)
-        return null;
-    // Boolean marks any old run carried: plain ranges must explicitly clear
-    // these, because the rewritten single run may have smeared them everywhere.
-    const normalize = new Set(RUN_BOOL_MARKS.filter((key) => oldRuns.some((run) => run[key])));
-    // query.match run offsets are relative to the trimmed text used to match.
-    const oldTrim = oldText.trim();
-    const newTrimStart = newText.length - newText.trimStart().length;
-    const newTrim = newText.trim();
-    let prefix = 0;
-    const maxCommon = Math.min(oldTrim.length, newTrim.length);
-    while (prefix < maxCommon && oldTrim[prefix] === newTrim[prefix])
-        prefix += 1;
-    let suffix = 0;
-    while (suffix < maxCommon - prefix && oldTrim[oldTrim.length - 1 - suffix] === newTrim[newTrim.length - 1 - suffix])
-        suffix += 1;
-    const delta = newTrim.length - oldTrim.length;
-    let applied = 0;
-    const applyRange = async (start, end, inline) => {
-        if (end <= start || Object.keys(inline).length === 0)
-            return;
-        // Always direct, even under tracked mode. This pass RESTORES the marks the
-        // rewrite flattened; it is not new authorial formatting, and the text
-        // revision already owns the span's accept/reject fate. Applying it tracked
-        // adds a second reviewable change per rewrite (SD-4309's conformance matrix
-        // counts one per action), and rejecting that change alone would strand the
-        // text in the flattened look the rewrite produced.
-        const changed = await applyInlineQuiet(formatFn, {
-            blockId: nodeId,
-            start: newTrimStart + start,
-            end: newTrimStart + end,
-            inline,
-        });
-        if (changed)
-            applied += 1;
-    };
-    try {
-        for (const run of oldRuns) {
-            const inline = inlineFromSnapshotRun(run, normalize);
-            // Portion of the run inside the unchanged prefix.
-            await applyRange(run.start, Math.min(run.end, prefix), inline);
-            // Portion inside the unchanged suffix, shifted by the length delta.
-            const sufStart = Math.max(run.start, oldTrim.length - suffix);
-            if (run.end > sufStart)
-                await applyRange(sufStart + delta, run.end + delta, inline);
-        }
-        // The CHANGED middle keeps whatever the engine smeared; give it the marks
-        // of the run the change continues from (the one containing the last
-        // unchanged prefix character).
-        const middleEnd = newTrim.length - suffix;
-        if (middleEnd > prefix) {
-            const anchorRun = oldRuns.find((run) => prefix > run.start && prefix <= run.end) ?? oldRuns[oldRuns.length - 1];
-            await applyRange(prefix, middleEnd, inlineFromSnapshotRun(anchorRun, normalize));
-        }
-        return applied > 0 ? { restoredRunRanges: applied } : null;
-    }
-    catch (err) {
-        return { skipped: reasonOf(err) };
-    }
-}
 const NAMED_COLORS = {
     black: '000000',
     blue: '0000FF',
@@ -4620,6 +4597,15 @@ function compactOpResult(result) {
         compact.stepCount = result.steps.length;
     return compact;
 }
+function trackedChangeRefIds(result) {
+    const refs = asRecord(result)?.trackedChangeRefs;
+    if (!Array.isArray(refs))
+        return new Set();
+    return new Set(refs.flatMap((entry) => {
+        const entityId = asString(asRecord(entry)?.entityId);
+        return entityId ? [entityId] : [];
+    }));
+}
 function parseScopedReplaceArgs(args, changeMode) {
     if (args.action !== 'replace_text')
         return null;
@@ -4733,9 +4719,8 @@ async function runScopedReplaceUnchecked(doc, args) {
             },
             args: { replacement: { text: span.replace } },
         }));
-        // Select rewrites flatten the block's runs, so the tracked lane needs the
-        // same restoration the whole-block lane below performs. The preserve pass
-        // applies directly, so restoring marks adds no second reviewable change.
+        // Restore the known edit spans directly so the formatting pass adds no
+        // separate tracked change.
         const trackedPreRuns = await captureBlockRuns(doc, nodeId, block.text);
         try {
             result = await executeMutations(doc, spanSteps, args.changeMode, pre.revision);
@@ -4925,10 +4910,24 @@ function leadInShapeOf(blockText, labelText, quote) {
         if (occurrence > 0)
             return { kind: 'inside', delimiter: inside, occurrence };
     }
+    // A single emphasised word followed by a space and plain prose: the token
+    // itself is the label ("WHEREAS the Party…"). Multi-word runs stay
+    // unrecognised — an emphasised opening clause is prose, not a label.
+    if (/^\S+\s$/.test(labelText) && blockText.length > labelText.length && blockText.startsWith(labelText)) {
+        return { kind: 'word', label: labelText.trimEnd() };
+    }
     return null;
 }
 /** The span of `text` that carries the label look, or null when it has none. */
 function leadInSpanOf(text, shape) {
+    if (shape.kind === 'word') {
+        // Only the SAME token inherits the look — "WHEREAS the Parties…" does,
+        // "The Parties further agree…" does not (no guessing a label there).
+        const next = text.charAt(shape.label.length);
+        return text.startsWith(shape.label) && (next === '' || /\s/.test(next))
+            ? { start: 0, end: shape.label.length }
+            : null;
+    }
     if (shape.kind === 'quoted') {
         const opener = text.slice(0, 2).indexOf(shape.quote);
         if (opener < 0)
@@ -7411,8 +7410,10 @@ function parseSelector(value) {
 const ACTION_NAMES_LIST = ACTION_NAMES;
 
 exports.ACTION_ARGS = ACTION_ARGS;
+exports.ACTION_DISPOSITIONS = ACTION_DISPOSITIONS;
 exports.ACTION_GROUPS = ACTION_GROUPS;
 exports.ACTION_HINTS = ACTION_HINTS;
 exports.ACTION_NAMES_LIST = ACTION_NAMES_LIST;
+exports.getActionDispositions = getActionDispositions;
 exports.isActionName = isActionName;
 exports.superdocPerformAction = superdocPerformAction;

package/dist/agent/actions.d.ts

@@ -433,6 +433,25 @@ export declare const ACTION_GROUPS: ReadonlyArray<{
  * action at compile time.
  */
 export declare const ACTION_ARGS: Record<ActionName, readonly string[]>;
+/**
+ * What an action does with `changeMode`.
+ *
+ * - `tracked`: honors `changeMode: "tracked"` and records a reviewable tracked
+ *   change (a multi-step action may run a bookkeeping step directly on purpose —
+ *   insert_table_column fills the new cells directly so a column shows up as ONE
+ *   Word-style tracked change, not one per cell).
+ * - `direct`: edits the document directly whatever `changeMode` says. Either the
+ *   action never reads the argument (apply_style, insert_page_break, …), the
+ *   engine refuses the tracked form (move_range), or the action is a review /
+ *   comment operation that has no tracked form by nature.
+ *
+ * Source of truth for the tracked-only agent policy (`enforceChangeMode`):
+ * `direct` actions are hidden and refused unless a host allowlists them.
+ */
+export type ActionDisposition = 'tracked' | 'direct';
+export declare const ACTION_DISPOSITIONS: Record<ActionName, ActionDisposition>;
+/** Fresh copy of {@link ACTION_DISPOSITIONS} for integrators (safe to mutate). */
+export declare function getActionDispositions(): Record<ActionName, ActionDisposition>;
 export declare function isActionName(value: unknown): value is ActionName;
 export type ResolveCommentsArgs = {
     action: 'resolve_comments';