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

package/dist/agent/execution-context.js

@@ -0,0 +1,376 @@
+import { getDocumentRevisionReader, supportsDocumentFacts, forwardDocumentEvidence, getMutationRevision, } from '../runtime/document-evidence.js';
+import { SuperDocCliError } from '../runtime/errors.js';
+import { buildDocumentSnapshot, buildMutationSnapshot, resolveSnapshotSelector, } from './doc-snapshot.js';
+import { getOperationCatalogEntry } from './operation-catalog.js';
+export function supportsLocalSelector(selector) {
+    return (selector.kind === 'nodeId' ||
+        selector.kind === 'textSearch' ||
+        selector.kind === 'placement' ||
+        (selector.kind === 'ordinal' &&
+            ['blockOrdinal', 'headingOrdinal', 'tableOrdinal'].includes(selector.ordinalKind)) ||
+        (selector.kind === 'relative' && supportsLocalSelector(selector.target)));
+}
+function localCheck(check) {
+    return (['revision-changed', 'revision-unchanged', 'block-text-contains', 'block-text-equals', 'table-shape'].includes(check.kind) ||
+        (check.kind === 'block-count-delta' && ['paragraph', 'heading', 'listItem', 'table'].includes(check.nodeType)));
+}
+export async function readPublicRevision(doc) {
+    const revision = await getDocumentRevisionReader(doc)?.();
+    if (revision !== undefined)
+        return revision;
+    const page = await doc.blocks.list({ offset: Number.MAX_SAFE_INTEGER, limit: 1 });
+    if (!page.revision || page.revision === 'unknown')
+        throw new SuperDocCliError('Required document revision is unavailable.', { code: 'EVIDENCE_UNAVAILABLE' });
+    return page.revision;
+}
+export class DocumentFacts {
+    doc;
+    revision;
+    complete;
+    summaryCounts;
+    blocks = new Map();
+    counts = new Map();
+    selections = new Map();
+    constructor(doc, revision, complete, summaryCounts = complete?.counts) {
+        this.doc = doc;
+        this.revision = revision;
+        this.complete = complete;
+        this.summaryCounts = summaryCounts;
+    }
+    get summary() {
+        return { revision: this.revision, ...(this.summaryCounts ? { counts: this.summaryCounts } : {}) };
+    }
+    async fence() {
+        if ((await readPublicRevision(this.doc)) !== this.revision)
+            throw new SuperDocCliError('Document changed while acquiring execution evidence.', { code: 'REVISION_CONFLICT' });
+    }
+    async page(input) {
+        const result = await this.doc.blocks.list({ ...input, includeText: true });
+        if (result.revision !== this.revision)
+            throw new SuperDocCliError('Document changed while resolving a target.', { code: 'REVISION_CONFLICT' });
+        const blocks = result.blocks.map((block) => ({
+            ...block,
+            ordinal: block.ordinal + 1,
+            text: block.text ?? '',
+            textPreview: block.textPreview ?? null,
+            styleId: block.styleId ?? null,
+        }));
+        for (const block of blocks)
+            this.blocks.set(block.nodeId, block);
+        return blocks;
+    }
+    async count(nodeType) {
+        const key = nodeType ?? '*';
+        if (this.counts.has(key))
+            return this.counts.get(key);
+        if (this.complete)
+            return nodeType
+                ? this.complete.blocks.filter((block) => block.nodeType === nodeType).length
+                : this.complete.blocks.length;
+        const result = await this.doc.blocks.list({
+            offset: Number.MAX_SAFE_INTEGER,
+            limit: 1,
+            ...(nodeType ? { nodeTypes: [nodeType] } : {}),
+        });
+        if (result.revision !== this.revision || !Number.isSafeInteger(result.total))
+            throw new SuperDocCliError('Required count is unavailable at the execution revision.', {
+                code: 'EVIDENCE_UNAVAILABLE',
+            });
+        this.counts.set(key, result.total);
+        return result.total;
+    }
+    async block(nodeId) {
+        if (this.complete)
+            return this.complete.blocks.find((block) => block.nodeId === nodeId);
+        if (!this.blocks.has(nodeId))
+            await this.page({ nodeIds: [nodeId], limit: 1 });
+        return this.blocks.get(nodeId);
+    }
+    async select(selector) {
+        if (this.complete)
+            return resolveSnapshotSelector(this.complete, selector);
+        const key = JSON.stringify(selector);
+        if (this.selections.has(key))
+            return this.selections.get(key);
+        let blocks = [];
+        if (selector.kind === 'nodeId') {
+            const block = await this.block(selector.nodeId);
+            if (block)
+                blocks = [block];
+        }
+        else if (selector.kind === 'textSearch') {
+            const terms = selector.terms.filter((term) => term.trim());
+            if (terms.length && selector.nodeTypes?.length !== 0)
+                blocks = await this.page({
+                    textSearch: { terms: [...terms], match: selector.match, caseSensitive: selector.caseSensitive },
+                    nodeTypes: [...(selector.nodeTypes ?? ['paragraph', 'heading', 'listItem'])],
+                    offset: (selector.occurrence ?? 1) - 1,
+                    limit: 1,
+                });
+        }
+        else if (selector.kind === 'placement') {
+            const offset = selector.at === 'document_start' ? 0 : (await this.count()) - 1;
+            if (offset >= 0)
+                blocks = await this.page({ offset, limit: 1 });
+        }
+        else if (selector.kind === 'ordinal') {
+            blocks = await this.page({
+                offset: selector.value - 1,
+                limit: 1,
+                ...(selector.ordinalKind === 'headingOrdinal'
+                    ? { nodeTypes: ['heading'] }
+                    : selector.ordinalKind === 'tableOrdinal'
+                        ? { nodeTypes: ['table'] }
+                        : {}),
+            });
+        }
+        else if (selector.kind === 'relative') {
+            for (const id of await this.select(selector.target)) {
+                const target = await this.block(id);
+                const offset = target ? target.ordinal - 1 + (selector.position === 'before' ? -1 : 1) : -1;
+                if (offset >= 0)
+                    blocks.push(...(await this.page({ offset, limit: 1 })));
+            }
+        }
+        else
+            throw new SuperDocCliError('Selector requires complete evidence.', { code: 'EVIDENCE_UNAVAILABLE' });
+        const ids = [...new Set(blocks.map((block) => block.nodeId))];
+        this.selections.set(key, ids);
+        return ids;
+    }
+    async target(selector) {
+        const ids = await this.select(selector);
+        if (this.complete && selector.kind === 'tableCell' && ids.length === 1) {
+            const cell = this.complete.tables.flatMap((table) => table.cells).find((cell) => cell.nodeId === ids[0]);
+            if (cell?.nodeId)
+                return {
+                    nodeId: cell.nodeId,
+                    nodeType: 'paragraph',
+                    text: cell.text,
+                    textPreview: cell.text,
+                    styleId: null,
+                    ordinal: 0,
+                };
+        }
+        return ids.length === 1 ? this.block(ids[0]) : undefined;
+    }
+    async tableShape(nodeId) {
+        if (this.complete)
+            return this.complete.tables.find((table) => table.nodeId === nodeId);
+        return this.doc.tables.get({ nodeId });
+    }
+    async completeIndex(reason, acquire) {
+        const value = await acquire();
+        await this.fence();
+        return { value, coverage: 'complete', reason };
+    }
+    async prepare(checks) {
+        for (const check of checks)
+            if (check.kind === 'block-count-delta')
+                await this.count(check.nodeType);
+    }
+}
+export class ExecutionContext {
+    source;
+    requirements;
+    document;
+    executedOperations = [];
+    selectedTargets = [];
+    pre;
+    post;
+    fallbackReason;
+    currentRevision;
+    legacyRevisionOnly = false;
+    constructor(source, requirements = {}) {
+        this.source = source;
+        this.requirements = requirements;
+        if (requirements.evidence !== undefined && !['required', 'full'].includes(requirements.evidence))
+            throw new SuperDocCliError('evidence must be required or full.', { code: 'INVALID_ARGUMENT' });
+        const wrap = (value, path) => new Proxy(value, {
+            get: (target, property, receiver) => {
+                const member = Reflect.get(target, property, receiver);
+                if (typeof property !== 'string')
+                    return member;
+                const memberPath = [...path, property];
+                const operationId = `doc.${memberPath.join('.')}`;
+                if (typeof member === 'function' && getOperationCatalogEntry(operationId)?.isMutating) {
+                    return async (args = {}, options) => {
+                        if (operationId === 'doc.format.apply' &&
+                            supportsDocumentFacts(this.source) &&
+                            typeof args.blockId === 'string') {
+                            const { blockId, start, end, ...rest } = args;
+                            args = {
+                                ...rest,
+                                target: {
+                                    kind: 'selection',
+                                    start: { kind: 'text', blockId, offset: start },
+                                    end: { kind: 'text', blockId, offset: end },
+                                },
+                            };
+                        }
+                        if (this.legacyRevisionOnly && this.executedOperations.length)
+                            throw new SuperDocCliError('This host cannot bind revisions across multiple writes.', {
+                                code: 'EVIDENCE_UNAVAILABLE',
+                            });
+                        const guarded = (supportsDocumentFacts(this.source) || this.legacyRevisionOnly) &&
+                            !['doc.history.undo', 'doc.history.redo', 'doc.plan.execute'].includes(operationId);
+                        const revision = guarded ? (this.currentRevision ?? (await readPublicRevision(this.source))) : undefined;
+                        const result = await Reflect.apply(member, target, guarded
+                            ? [
+                                { ...args, expectedRevision: args.expectedRevision ?? revision },
+                                { ...options, expectedRevision: options?.expectedRevision ?? revision },
+                            ]
+                            : [args, options]);
+                        this.executedOperations.push({ operationId, result });
+                        if (result?.success === false)
+                            throw new SuperDocCliError('Document operation did not apply.', {
+                                code: result.failure?.code ?? 'APPLY_FAILED',
+                                details: result,
+                            });
+                        if (supportsDocumentFacts(this.source)) {
+                            const applied = getMutationRevision(result);
+                            if (!applied ||
+                                applied.before !== this.currentRevision ||
+                                !applied.after ||
+                                applied.after === 'unknown')
+                                throw new SuperDocCliError('Committed operation revision is unavailable or changed.', {
+                                    code: 'EVIDENCE_UNAVAILABLE',
+                                });
+                            this.currentRevision = applied.after;
+                        }
+                        return result;
+                    };
+                }
+                if (member && typeof member === 'object')
+                    return wrap(member, memberPath);
+                return member;
+            },
+        });
+        this.document = wrap(source, []);
+        forwardDocumentEvidence(source, this.document);
+    }
+    async start() {
+        const { evidence, selectors = [], checks = [], completeReason } = this.requirements;
+        const compactRevision = this.requirements.revisionOnly && evidence !== 'full' && !completeReason
+            ? await getDocumentRevisionReader(this.source)?.()
+            : undefined;
+        this.legacyRevisionOnly = compactRevision !== undefined && !supportsDocumentFacts(this.source);
+        this.fallbackReason =
+            completeReason ??
+                (!supportsDocumentFacts(this.source) && !this.legacyRevisionOnly
+                    ? 'host lacks typed execution facts'
+                    : selectors.some((selector) => !supportsLocalSelector(selector))
+                        ? 'selector requires complete index'
+                        : checks.some((check) => !localCheck(check))
+                            ? 'verification requires complete evidence'
+                            : undefined);
+        const complete = evidence === 'full' || this.fallbackReason ? await buildMutationSnapshot(this.source) : undefined;
+        if (complete && (complete.revision === 'unknown' || complete.diagnostics.some((item) => item.section === 'info')))
+            throw new SuperDocCliError('Required complete evidence is unavailable.', { code: 'EVIDENCE_UNAVAILABLE' });
+        this.pre = new DocumentFacts(this.source, complete?.revision ?? compactRevision ?? (await readPublicRevision(this.source)), complete);
+        this.currentRevision = this.pre.revision;
+        await this.pre.prepare(checks);
+        return this.pre;
+    }
+    async finishRevision() {
+        if (this.requirements.evidence === 'full')
+            return this.finish();
+        const summary = this.pre?.complete ? await buildDocumentSnapshot(this.source, { countsOnly: true }) : undefined;
+        if (summary && (summary.revision === 'unknown' || summary.diagnostics.some((item) => item.section === 'info')))
+            throw new SuperDocCliError('Required summary is unavailable.', { code: 'EVIDENCE_UNAVAILABLE' });
+        const revision = summary?.revision ?? (await readPublicRevision(this.source));
+        this.assertExecutionRevision(revision);
+        this.post = new DocumentFacts(this.source, revision, undefined, summary?.counts);
+        this.currentRevision = this.post.revision;
+        return this.post;
+    }
+    async finish() {
+        const complete = this.pre?.complete ? await buildMutationSnapshot(this.source) : undefined;
+        if (complete && (complete.revision === 'unknown' || complete.diagnostics.some((item) => item.section === 'info')))
+            throw new SuperDocCliError('Required complete evidence is unavailable.', { code: 'EVIDENCE_UNAVAILABLE' });
+        const revision = complete?.revision ?? (await readPublicRevision(this.source));
+        this.assertExecutionRevision(revision);
+        this.post = new DocumentFacts(this.source, revision, complete);
+        this.currentRevision = this.post.revision;
+        return this.post;
+    }
+    assertExecutionRevision(revision) {
+        if (supportsDocumentFacts(this.source) && this.currentRevision !== revision)
+            throw new SuperDocCliError('Document changed outside this execution.', { code: 'REVISION_CONFLICT' });
+    }
+    receipt(intent, verification, extra = {}) {
+        return {
+            status: verification.every((check) => check.passed) ? 'ok' : 'failed',
+            intent,
+            preSnapshot: this.pre?.summary,
+            postSnapshot: this.post?.summary,
+            selectedTargets: this.selectedTargets,
+            executedOperations: this.executedOperations,
+            verification,
+            ...(this.fallbackReason ? { evidenceFallback: this.fallbackReason } : {}),
+            ...extra,
+        };
+    }
+    failure(intent, error) {
+        const err = error;
+        return this.receipt(intent, [], {
+            status: err?.code === 'AMBIGUOUS_SELECTOR' ? 'aborted' : 'failed',
+            errors: [
+                { code: err?.code ?? 'ACTION_FAILED', message: err?.message ?? String(error), recovery: { kind: 'reinspect' } },
+            ],
+        });
+    }
+}
+export async function evaluateFactChecks(pre, post, checks) {
+    const results = [];
+    for (const check of checks) {
+        if ([
+            'revision-changed',
+            'revision-unchanged',
+            'block-count-delta',
+            'comment-count-delta',
+            'tracked-change-count-delta',
+        ].includes(check.kind) &&
+            !pre) {
+            results.push({ check, passed: false, detail: `${check.kind} requires a baseline snapshot` });
+            continue;
+        }
+        if (check.kind === 'revision-changed' || check.kind === 'revision-unchanged')
+            results.push({
+                check,
+                passed: check.kind === 'revision-changed' ? pre.revision !== post.revision : pre.revision === post.revision,
+                detail: `pre=${pre.revision} post=${post.revision}`,
+            });
+        else if (check.kind === 'block-count-delta') {
+            const before = await pre.count(check.nodeType), after = await post.count(check.nodeType);
+            results.push({
+                check,
+                passed: after - before === check.delta,
+                detail: `pre=${before} post=${after} delta=${after - before}`,
+            });
+        }
+        else if (check.kind === 'block-text-contains' || check.kind === 'block-text-equals') {
+            const block = await post.block(check.nodeId);
+            results.push({
+                check,
+                passed: !!block && (check.kind === 'block-text-equals' ? block.text === check.text : block.text.includes(check.text)),
+            });
+        }
+        else if (check.kind === 'table-shape') {
+            const table = await post.tableShape(check.nodeId);
+            results.push({ check, passed: !!table && table.rows === check.rows && table.columns === check.columns });
+        }
+        else if (check.kind === 'comment-count-delta' || check.kind === 'tracked-change-count-delta') {
+            const key = check.kind === 'comment-count-delta' ? 'comments' : 'trackedChanges';
+            const before = pre?.complete?.counts[key], after = post.complete?.counts[key];
+            results.push({
+                check,
+                passed: before !== undefined && after !== undefined && after - before === check.delta,
+                detail: `pre=${before} post=${after}`,
+            });
+        }
+        else
+            results.push({ check, passed: false, detail: 'Check requires domain-specific evidence.' });
+    }
+    return results;
+}

package/dist/agent/runtime.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var executionContext = require('./execution-context.cjs');
 var contract = require('../generated/contract.cjs');
 var errors = require('../runtime/errors.cjs');
 var ir = require('./ir.cjs');
@@ -227,8 +228,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') {
@@ -313,7 +314,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 docSnapshot.buildDocumentSnapshot(doc);
+        const fresh = await docSnapshot.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));
@@ -336,124 +337,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;
+}
 async function agentApply(doc, args) {
     const plan = args.plan;
     const validation = ir.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 docSnapshot.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.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 docSnapshot.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 && operationCatalog.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 && operationCatalog.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 executionContext.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 docSnapshot.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 docSnapshot.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,
-    };
 }
 async function agentVerify(doc, args) {
-    const snapshot = await docSnapshot.buildDocumentSnapshot(doc);
-    let saveReopen;
-    if (args.saveReopen || verificationNeedsSaveReopen(args.checks)) {
-        saveReopen = await trySaveReopen(doc, args.checks);
+    const context = new executionContext.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 executionContext.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.
@@ -481,27 +508,6 @@ 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,
-    };
-}
 
 exports.agentApply = agentApply;
 exports.agentInspect = agentInspect;