@superdoc/sdk 2.10.0-next.7 → 2.10.0-next.8

package/dist/agent/execution-context.d.ts

@@ -0,0 +1,97 @@
+import type { BoundDocApi, DocBlocksListBoundParams } from '../generated/client.js';
+import { type DocumentSnapshot, type SnapshotBlock } from './doc-snapshot.js';
+import type { AgentSelector, AgentVerificationCheck } from './ir.js';
+import type { AgentReceipt, VerificationResult } from './runtime.js';
+export type EvidencePolicy = 'required' | 'full';
+export type EvidenceRequirements = {
+    evidence?: EvidencePolicy;
+    selectors?: readonly AgentSelector[];
+    checks?: readonly AgentVerificationCheck[];
+    completeReason?: string;
+    revisionOnly?: boolean;
+};
+export declare function supportsLocalSelector(selector: AgentSelector): boolean;
+export declare function readPublicRevision(doc: BoundDocApi): Promise<string>;
+export declare class DocumentFacts {
+    readonly doc: BoundDocApi;
+    readonly revision: string;
+    readonly complete?: DocumentSnapshot | undefined;
+    readonly summaryCounts: {
+        blocks: number;
+        paragraphs: number;
+        headings: number;
+        tables: number;
+        lists: number;
+        images: number;
+        comments: number;
+        trackedChanges: number;
+        sections: number;
+        fields: number;
+        hyperlinks: number;
+        bookmarks: number;
+        contentControls: number;
+        permissionRanges: number;
+        styles: number;
+        headers: number;
+        footers: number;
+    } | undefined;
+    readonly blocks: Map<string, SnapshotBlock>;
+    private readonly counts;
+    private readonly selections;
+    constructor(doc: BoundDocApi, revision: string, complete?: DocumentSnapshot | undefined, summaryCounts?: {
+        blocks: number;
+        paragraphs: number;
+        headings: number;
+        tables: number;
+        lists: number;
+        images: number;
+        comments: number;
+        trackedChanges: number;
+        sections: number;
+        fields: number;
+        hyperlinks: number;
+        bookmarks: number;
+        contentControls: number;
+        permissionRanges: number;
+        styles: number;
+        headers: number;
+        footers: number;
+    } | undefined);
+    get summary(): NonNullable<AgentReceipt['preSnapshot']>;
+    fence(): Promise<void>;
+    page(input: DocBlocksListBoundParams): Promise<SnapshotBlock[]>;
+    count(nodeType?: string): Promise<number>;
+    block(nodeId: string): Promise<SnapshotBlock | undefined>;
+    select(selector: AgentSelector): Promise<readonly string[]>;
+    target(selector: AgentSelector): Promise<SnapshotBlock | undefined>;
+    tableShape(nodeId: string): Promise<{
+        rows: number;
+        columns: number;
+    } | undefined>;
+    completeIndex<T>(reason: string, acquire: () => Promise<T>): Promise<{
+        value: T;
+        coverage: 'complete';
+        reason: string;
+    }>;
+    prepare(checks: readonly AgentVerificationCheck[]): Promise<void>;
+}
+export declare class ExecutionContext {
+    readonly source: BoundDocApi;
+    readonly requirements: EvidenceRequirements;
+    readonly document: BoundDocApi;
+    readonly executedOperations: NonNullable<AgentReceipt['executedOperations']>[number][];
+    readonly selectedTargets: NonNullable<AgentReceipt['selectedTargets']>[number][];
+    pre?: DocumentFacts;
+    post?: DocumentFacts;
+    fallbackReason?: string;
+    private currentRevision?;
+    private legacyRevisionOnly;
+    constructor(source: BoundDocApi, requirements?: EvidenceRequirements);
+    start(): Promise<DocumentFacts>;
+    finishRevision(): Promise<DocumentFacts>;
+    finish(): Promise<DocumentFacts>;
+    private assertExecutionRevision;
+    receipt(intent: string, verification: readonly VerificationResult[], extra?: Partial<AgentReceipt>): AgentReceipt;
+    failure(intent: string, error: unknown): AgentReceipt;
+}
+export declare function evaluateFactChecks(pre: DocumentFacts | undefined, post: DocumentFacts, checks: readonly AgentVerificationCheck[]): Promise<VerificationResult[]>;

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;
+}