@superdoc/sdk 2.9.1-next.2 → 2.10.0-next.10

package/dist/agent/runtime.d.ts

@@ -1,3 +1,4 @@
+import { type EvidencePolicy } from './execution-context.js';
 /**
  * Clean agent runtime.
  *
@@ -43,9 +44,11 @@ export type AgentInspectArgs = {
     blockRunsLimit?: number;
 };
 export type AgentApplyArgs = {
+    evidence?: EvidencePolicy;
     plan: AgentPlan;
 };
 export type AgentVerifyArgs = {
+    evidence?: EvidencePolicy;
     checks: readonly AgentVerificationCheck[];
     saveReopen?: boolean;
 };

package/dist/agent/runtime.js

@@ -1,7 +1,8 @@
+import { ExecutionContext, evaluateFactChecks } from './execution-context.js';
 import { CONTRACT } from '../generated/contract.js';
 import { SuperDocCliError } from '../runtime/errors.js';
 import { validatePlan } from './ir.js';
-import { buildDocumentSnapshot, resolveSnapshotSelector, AmbiguousSelectorError, } from './doc-snapshot.js';
+import { buildDocumentSnapshot, buildMutationSnapshot, resolveSnapshotSelector, AmbiguousSelectorError, } from './doc-snapshot.js';
 import { getOperationCatalogEntry } from './operation-catalog.js';
 const RESERVED_ARG_KEYS = new Set(['sessionId', 'doc']);
 function ensureKnownOperation(operationId) {
@@ -224,8 +225,8 @@ function computeDeltaChecks(pre, post, checks, saveReopen) {
         else if (check.kind === 'comment-count-delta') {
             results.push({
                 check,
-                passed: post.comments.length - pre.comments.length === check.delta,
-                detail: `pre=${pre.comments.length} post=${post.comments.length}`,
+                passed: post.counts.comments - pre.counts.comments === check.delta,
+                detail: `pre=${pre.counts.comments} post=${post.counts.comments}`,
             });
         }
         else if (check.kind === 'tracked-change-count-delta') {
@@ -310,7 +311,7 @@ async function trySaveReopen(doc, checks) {
         await saveAny.call(doc, {});
         // Rebuild a fresh snapshot after save. Host-level true reopen still needs
         // a new document handle, which this runtime cannot force on its own.
-        const fresh = await buildDocumentSnapshot(doc);
+        const fresh = await buildMutationSnapshot(doc);
         for (const check of checks) {
             if (check.kind === 'save-reopen-text-contains') {
                 const found = fresh.blocks.some((b) => b.text.includes(check.text));
@@ -333,124 +334,150 @@ async function trySaveReopen(doc, checks) {
 function verificationNeedsSaveReopen(checks) {
     return checks.some((check) => check.kind === 'document-saves-cleanly' || check.kind === 'save-reopen-text-contains');
 }
+function revisionOnlyParagraphStep(plan) {
+    if (plan.atomic || plan.preconditions || plan.postconditions || plan.expectedDiff || plan.steps.length !== 2) {
+        return undefined;
+    }
+    const [apply, verify] = plan.steps;
+    if (apply?.kind !== 'apply' ||
+        apply.operationId !== 'doc.create.paragraph' ||
+        apply.atomic ||
+        verify?.kind !== 'verify' ||
+        verify.saveReopen ||
+        verify.checks.length === 0 ||
+        !verify.checks.every((check) => check.kind === 'revision-changed' || check.kind === 'revision-unchanged')) {
+        return undefined;
+    }
+    // Only literal body inputs are eligible. Binding tokens, story targets and
+    // additional operation options must retain the complete evidence path.
+    if (Object.keys(apply.args).some((key) => key !== 'text' && key !== 'at'))
+        return undefined;
+    if (apply.args.text !== undefined && typeof apply.args.text !== 'string')
+        return undefined;
+    const at = apply.args.at;
+    if (at !== undefined) {
+        if (!isRecord(at))
+            return undefined;
+        if (at.kind === 'documentStart' || at.kind === 'documentEnd') {
+            if (Object.keys(at).some((key) => key !== 'kind'))
+                return undefined;
+        }
+        else if (at.kind === 'before' || at.kind === 'after') {
+            if (Object.keys(at).some((key) => key !== 'kind' && key !== 'target') ||
+                !isRecord(at.target) ||
+                at.target.kind !== 'block' ||
+                typeof at.target.nodeId !== 'string' ||
+                typeof at.target.nodeType !== 'string' ||
+                Object.keys(at.target).some((key) => !['kind', 'nodeId', 'nodeType'].includes(key))) {
+                return undefined;
+            }
+        }
+        else
+            return undefined;
+    }
+    return apply;
+}
 export async function agentApply(doc, args) {
     const plan = args.plan;
     const validation = validatePlan(plan);
-    if (!validation.ok) {
+    if (!validation.ok)
         return {
             status: 'failed',
             intent: plan.intent,
-            preSnapshot: { revision: 'unknown', counts: emptyCounts() },
             selectedTargets: [],
             executedOperations: [],
             verification: [],
-            errors: validation.errors.map((e) => ({ code: e.code, message: e.message })),
+            errors: validation.errors.map((error) => ({ code: error.code, message: error.message })),
         };
-    }
-    const preSnapshot = await buildDocumentSnapshot(doc);
-    const selectedTargets = [];
-    const executedOperations = [];
+    const verifyStep = plan.steps.find((step) => step.kind === 'verify');
+    const checks = verifyStep?.kind === 'verify' ? verifyStep.checks : [];
+    let written = false;
+    const baselineAfterWrite = plan.steps.some((step) => {
+        if (step.kind === 'apply')
+            written = true;
+        return written && step.kind === 'select' && step.selector.kind !== 'ref';
+    });
+    const context = new ExecutionContext(doc, {
+        evidence: args.evidence,
+        revisionOnly: !!revisionOnlyParagraphStep(plan),
+        checks,
+        selectors: plan.steps.flatMap((step) => step.kind === 'select' && step.selector.kind !== 'ref' ? [step.selector] : []),
+        completeReason: plan.atomic ||
+            plan.preconditions ||
+            plan.postconditions ||
+            plan.expectedDiff ||
+            plan.steps.some((step) => step.kind === 'inspect') ||
+            plan.steps.filter((step) => step.kind === 'apply').length > 1
+            ? 'plan requires complete baseline evidence'
+            : baselineAfterWrite
+                ? 'plan selects baseline targets after a write'
+                : planTouchesRiskyDomain(plan)
+                    ? 'plan requires document-wide save/reopen evidence'
+                    : plan.steps.some((step) => step.kind === 'apply' &&
+                        ['doc.history.undo', 'doc.history.redo', 'doc.plan.execute'].includes(step.operationId))
+                        ? 'operation requires complete execution evidence'
+                        : undefined,
+    });
     const bindings = new Map();
     try {
+        const pre = await context.start();
         for (const step of plan.steps) {
             if (step.kind === 'select') {
-                const matched = resolveSelectorWithBindings(preSnapshot, step.selector, bindings);
-                if (step.requireUnique && matched.length !== 1) {
+                const matched = pre.complete
+                    ? resolveSelectorWithBindings(pre.complete, step.selector, bindings)
+                    : step.selector.kind === 'ref'
+                        ? extractBoundNodeIds(resolveBindingRef(bindings, step.selector.ref))
+                        : await pre.select(step.selector);
+                if (step.requireUnique && matched.length !== 1)
                     throw new AmbiguousSelectorError(`Selector did not resolve uniquely (matched ${matched.length}).`, matched.map((nodeId) => ({ nodeId, description: nodeId })));
-                }
-                selectedTargets.push({ selector: step.selector, matched });
-                if (step.bind) {
+                context.selectedTargets.push({ selector: step.selector, matched });
+                if (step.bind)
                     bindings.set(step.bind, matched.length === 1 ? matched[0] : [...matched]);
-                }
-                continue;
             }
-            if (step.kind === 'inspect') {
-                const inspectArgs = ensureClean(resolveBindingTokens(step.args, bindings));
-                const method = resolveDocMethod(doc, step.operationId);
-                const result = await method(inspectArgs);
-                if (step.bind)
+            else if (step.kind === 'inspect' || step.kind === 'apply') {
+                const input = ensureClean(resolveBindingTokens(step.args, bindings));
+                const method = resolveDocMethod(context.document, step.operationId);
+                const result = await method(step.kind === 'apply' && step.changeMode && getOperationCatalogEntry(step.operationId)?.supportsChangeMode
+                    ? { ...input, changeMode: step.changeMode }
+                    : input);
+                if (step.kind === 'inspect' && step.bind)
                     bindings.set(step.bind, result);
-                continue;
-            }
-            if (step.kind === 'apply') {
-                ensureKnownOperation(step.operationId);
-                const applyArgs = ensureClean(resolveBindingTokens(step.args, bindings));
-                const method = resolveDocMethod(doc, step.operationId);
-                const argsWithMode = step.changeMode != null && getOperationCatalogEntry(step.operationId)?.supportsChangeMode
-                    ? { ...applyArgs, changeMode: step.changeMode }
-                    : applyArgs;
-                const result = await method(argsWithMode);
-                executedOperations.push({ operationId: step.operationId, rationale: step.rationale, result });
+                if (step.kind === 'apply' && context.executedOperations.length)
+                    context.executedOperations.at(-1).rationale = step.rationale;
             }
         }
+        const post = await context.finish();
+        const saveReopen = (verifyStep?.kind === 'verify' && (verifyStep.saveReopen || verificationNeedsSaveReopen(checks))) ||
+            planTouchesRiskyDomain(plan)
+            ? await trySaveReopen(doc, checks)
+            : undefined;
+        const verification = pre.complete && post.complete
+            ? computeDeltaChecks(pre.complete, post.complete, checks, saveReopen)
+            : await evaluateFactChecks(pre, post, checks);
+        if (!post.complete && checks.some((check) => !['revision-changed', 'revision-unchanged'].includes(check.kind)))
+            await post.fence();
+        return context.receipt(plan.intent, verification, { saveReopen });
     }
-    catch (err) {
-        if (err instanceof AmbiguousSelectorError) {
-            return {
-                status: 'aborted',
-                intent: plan.intent,
-                preSnapshot: { revision: preSnapshot.revision, counts: preSnapshot.counts },
-                selectedTargets,
-                executedOperations,
-                verification: [],
-                errors: [
-                    {
-                        code: err.code,
-                        message: err.message,
-                    },
-                ],
-            };
-        }
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-            status: 'failed',
-            intent: plan.intent,
-            preSnapshot: { revision: preSnapshot.revision, counts: preSnapshot.counts },
-            selectedTargets,
-            executedOperations,
-            verification: [],
-            errors: [{ code: 'APPLY_FAILED', message }],
-        };
+    catch (error) {
+        return context.failure(plan.intent, error);
     }
-    const postSnapshot = await buildDocumentSnapshot(doc);
-    const verifyStep = plan.steps.find((s) => s.kind === 'verify');
-    let saveReopen;
-    const shouldSaveReopen = (verifyStep?.kind === 'verify' && (verifyStep.saveReopen || verificationNeedsSaveReopen(verifyStep.checks))) ||
-        planTouchesRiskyDomain(plan);
-    if (shouldSaveReopen) {
-        saveReopen = await trySaveReopen(doc, verifyStep?.kind === 'verify' ? verifyStep.checks : []);
-    }
-    const verification = verifyStep?.kind === 'verify' ? computeDeltaChecks(preSnapshot, postSnapshot, verifyStep.checks, saveReopen) : [];
-    const allVerified = verification.every((v) => v.passed);
-    return {
-        status: allVerified ? 'ok' : 'failed',
-        intent: plan.intent,
-        preSnapshot: { revision: preSnapshot.revision, counts: preSnapshot.counts },
-        postSnapshot: { revision: postSnapshot.revision, counts: postSnapshot.counts },
-        selectedTargets,
-        executedOperations,
-        verification,
-        saveReopen,
-    };
 }
 export async function agentVerify(doc, args) {
-    const snapshot = await buildDocumentSnapshot(doc);
-    let saveReopen;
-    if (args.saveReopen || verificationNeedsSaveReopen(args.checks)) {
-        saveReopen = await trySaveReopen(doc, args.checks);
+    const context = new ExecutionContext(doc, { evidence: args.evidence, checks: args.checks });
+    try {
+        const current = await context.start();
+        context.post = current;
+        const saveReopen = args.saveReopen || verificationNeedsSaveReopen(args.checks) ? await trySaveReopen(doc, args.checks) : undefined;
+        const verification = current.complete
+            ? computeCurrentChecks(current.complete, args.checks, saveReopen)
+            : await evaluateFactChecks(undefined, current, args.checks);
+        if (!current.complete)
+            await current.fence();
+        return context.receipt('verify', verification, { saveReopen });
+    }
+    catch (error) {
+        return context.failure('verify', error);
     }
-    const verification = computeCurrentChecks(snapshot, args.checks, saveReopen);
-    const allPassed = verification.every((v) => v.passed);
-    return {
-        status: allPassed ? 'ok' : 'failed',
-        intent: 'verify',
-        preSnapshot: { revision: snapshot.revision, counts: snapshot.counts },
-        postSnapshot: { revision: snapshot.revision, counts: snapshot.counts },
-        selectedTargets: [],
-        executedOperations: [],
-        verification,
-        saveReopen,
-    };
 }
 /**
  * Controlled escape hatch — dispatches a single generated operation by id.
@@ -478,24 +505,3 @@ export async function agentOperation(doc, args) {
     const method = resolveDocMethod(doc, args.operationId);
     return method(callArgs);
 }
-function emptyCounts() {
-    return {
-        blocks: 0,
-        paragraphs: 0,
-        headings: 0,
-        tables: 0,
-        lists: 0,
-        images: 0,
-        comments: 0,
-        trackedChanges: 0,
-        sections: 0,
-        fields: 0,
-        hyperlinks: 0,
-        bookmarks: 0,
-        contentControls: 0,
-        permissionRanges: 0,
-        styles: 0,
-        headers: 0,
-        footers: 0,
-    };
-}

package/dist/agent/v2-preset-compat.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var documentEvidence = require('../runtime/document-evidence.cjs');
+
 const LEGACY_TRACKED_CHANGE_TYPES = {
     insertion: 'insert',
     deletion: 'delete',
@@ -57,13 +59,15 @@ function wrapV2PresetCompat(doc) {
             return value;
         },
     });
-    return new Proxy(doc, {
+    const wrapped = new Proxy(doc, {
         get(target, property, receiver) {
             if (property === 'trackChanges')
                 return trackChanges;
             return Reflect.get(target, property, receiver);
         },
     });
+    documentEvidence.forwardDocumentEvidence(doc, wrapped);
+    return wrapped;
 }
 
 exports.wrapV2PresetCompat = wrapV2PresetCompat;

package/dist/agent/v2-preset-compat.js

@@ -1,3 +1,4 @@
+import { forwardDocumentEvidence } from '../runtime/document-evidence.js';
 const LEGACY_TRACKED_CHANGE_TYPES = {
     insertion: 'insert',
     deletion: 'delete',
@@ -55,11 +56,13 @@ export function wrapV2PresetCompat(doc) {
             return value;
         },
     });
-    return new Proxy(doc, {
+    const wrapped = new Proxy(doc, {
         get(target, property, receiver) {
             if (property === 'trackChanges')
                 return trackChanges;
             return Reflect.get(target, property, receiver);
         },
     });
+    forwardDocumentEvidence(doc, wrapped);
+    return wrapped;
 }