@superdoc/sdk 2.18.0-next.1 → 2.18.0-next.3

package/dist/agent/doc-snapshot.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var documentEvidence = require('../runtime/document-evidence.cjs');
+
 function asString(v, fallback = '') {
     return typeof v === 'string' ? v : fallback;
 }
@@ -278,14 +280,34 @@ async function buildDocumentSnapshot(doc, options = {}) {
         };
     }
     // Blocks
-    const includeBlocksInSnapshot = includesDomain(requestedDomains, 'blocks');
-    const needBlocksRead = includeBlocksInSnapshot || includesDomain(requestedDomains, 'tables');
+    const includeBlocksInSnapshot = !options.countSummary && includesDomain(requestedDomains, 'blocks');
+    const needBlocksRead = options.countSummary || includeBlocksInSnapshot || includesDomain(requestedDomains, 'tables');
     const blocksFn = maybeMethod(doc, ['blocks', 'list']);
     const blocksRaw = needBlocksRead && blocksFn
-        ? await safeCall(() => blocksFn({ offset: blockOffset, limit: blockLimit, includeText: includeBlocksInSnapshot }), null, recordError('blocks.list'))
+        ? await safeCall(() => blocksFn({
+            offset: options.countSummary ? Number.MAX_SAFE_INTEGER : blockOffset,
+            limit: options.countSummary ? 1 : blockLimit,
+            includeText: includeBlocksInSnapshot,
+        }), null, recordError('blocks.list'))
         : null;
     const blocksRec = asRecord(blocksRaw);
     const totalBlocks = explicitCount(blocksRec ?? {}, 'total') ?? countsFromInfo.blocks;
+    if (options.countSummary && blocksFn) {
+        if (blocksRec?.revision !== revision)
+            throw new MutationSnapshotError('REVISION_CONFLICT', 'Count summary revision changed.');
+        for (const [key, nodeType] of [
+            ['paragraphs', 'paragraph'],
+            ['headings', 'heading'],
+            ['tables', 'table'],
+        ]) {
+            if (countsFromInfo[key] !== 0)
+                continue;
+            const page = asRecord(await blocksFn({ nodeTypes: [nodeType], offset: Number.MAX_SAFE_INTEGER, limit: 1, includeText: false }));
+            if (page?.revision !== revision || typeof page.total !== 'number')
+                throw new MutationSnapshotError('REVISION_CONFLICT', 'Required count summary is unavailable.');
+            countsFromInfo[key] = page.total;
+        }
+    }
     const rawBlocks = Array.isArray(blocksRec?.blocks) ? blocksRec.blocks : [];
     const fullBlockText = new Map();
     const normalizedBlocks = rawBlocks.map((b, index) => {
@@ -743,6 +765,18 @@ class MutationSnapshotError extends Error {
         this.name = 'MutationSnapshotError';
     }
 }
+async function buildExecutionSummary(doc) {
+    const summary = await buildDocumentSnapshot(doc, { countSummary: true });
+    if (summary.revision === 'unknown' ||
+        summary.diagnostics.some((item) => ['info', 'blocks.list'].includes(item.section)))
+        throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', 'Required summary evidence is unavailable.');
+    const readRevision = documentEvidence.getDocumentRevisionReader(doc);
+    const revision = readRevision
+        ? await readRevision()
+        : (await doc.blocks.list({ offset: Number.MAX_SAFE_INTEGER, limit: 1 })).revision;
+    assertMutationSnapshotRevision(summary.revision, revision ?? 'unknown');
+    return summary;
+}
 const MUTATION_BLOCK_PAGE_SIZE = 1000;
 const MUTATION_BLOCK_PAGE_CONCURRENCY = 4;
 const MUTATION_NON_TABLE_DOMAINS = [
@@ -1009,6 +1043,7 @@ function resolveSnapshotSelector(snapshot, selector) {
 exports.AmbiguousSelectorError = AmbiguousSelectorError;
 exports.MutationSnapshotError = MutationSnapshotError;
 exports.buildDocumentSnapshot = buildDocumentSnapshot;
+exports.buildExecutionSummary = buildExecutionSummary;
 exports.buildMutationSnapshot = buildMutationSnapshot;
 exports.matchRunsForBlock = matchRunsForBlock;
 exports.normalizeSnapshotBlock = normalizeSnapshotBlock;

package/dist/agent/doc-snapshot.d.ts

@@ -234,6 +234,7 @@ export type DocumentSnapshot = {
 export declare function matchRunsForBlock(queryFn: (args: Record<string, unknown>) => Promise<unknown>, text: string, nodeId: string): Promise<SnapshotRun[]>;
 type SnapshotOptions = {
     countsOnly?: boolean;
+    countSummary?: boolean;
     includeDomains?: readonly SnapshotDomain[];
     blockNodeTypes?: readonly string[];
     blockTextLimit?: number;
@@ -319,6 +320,7 @@ export declare class MutationSnapshotError extends Error {
     readonly code: 'SNAPSHOT_INCOMPLETE' | 'REVISION_CONFLICT';
     constructor(code: 'SNAPSHOT_INCOMPLETE' | 'REVISION_CONFLICT', message: string);
 }
+export declare function buildExecutionSummary(doc: BoundDocApi): Promise<DocumentSnapshot>;
 /**
  * Build the complete block index used to authorize mutations. Inspection
  * snapshots stay windowed; mutation selectors must not treat that presentation

package/dist/agent/doc-snapshot.js

@@ -1,3 +1,4 @@
+import { getDocumentRevisionReader } from '../runtime/document-evidence.js';
 function asString(v, fallback = '') {
     return typeof v === 'string' ? v : fallback;
 }
@@ -276,14 +277,34 @@ export async function buildDocumentSnapshot(doc, options = {}) {
         };
     }
     // Blocks
-    const includeBlocksInSnapshot = includesDomain(requestedDomains, 'blocks');
-    const needBlocksRead = includeBlocksInSnapshot || includesDomain(requestedDomains, 'tables');
+    const includeBlocksInSnapshot = !options.countSummary && includesDomain(requestedDomains, 'blocks');
+    const needBlocksRead = options.countSummary || includeBlocksInSnapshot || includesDomain(requestedDomains, 'tables');
     const blocksFn = maybeMethod(doc, ['blocks', 'list']);
     const blocksRaw = needBlocksRead && blocksFn
-        ? await safeCall(() => blocksFn({ offset: blockOffset, limit: blockLimit, includeText: includeBlocksInSnapshot }), null, recordError('blocks.list'))
+        ? await safeCall(() => blocksFn({
+            offset: options.countSummary ? Number.MAX_SAFE_INTEGER : blockOffset,
+            limit: options.countSummary ? 1 : blockLimit,
+            includeText: includeBlocksInSnapshot,
+        }), null, recordError('blocks.list'))
         : null;
     const blocksRec = asRecord(blocksRaw);
     const totalBlocks = explicitCount(blocksRec ?? {}, 'total') ?? countsFromInfo.blocks;
+    if (options.countSummary && blocksFn) {
+        if (blocksRec?.revision !== revision)
+            throw new MutationSnapshotError('REVISION_CONFLICT', 'Count summary revision changed.');
+        for (const [key, nodeType] of [
+            ['paragraphs', 'paragraph'],
+            ['headings', 'heading'],
+            ['tables', 'table'],
+        ]) {
+            if (countsFromInfo[key] !== 0)
+                continue;
+            const page = asRecord(await blocksFn({ nodeTypes: [nodeType], offset: Number.MAX_SAFE_INTEGER, limit: 1, includeText: false }));
+            if (page?.revision !== revision || typeof page.total !== 'number')
+                throw new MutationSnapshotError('REVISION_CONFLICT', 'Required count summary is unavailable.');
+            countsFromInfo[key] = page.total;
+        }
+    }
     const rawBlocks = Array.isArray(blocksRec?.blocks) ? blocksRec.blocks : [];
     const fullBlockText = new Map();
     const normalizedBlocks = rawBlocks.map((b, index) => {
@@ -741,6 +762,18 @@ export class MutationSnapshotError extends Error {
         this.name = 'MutationSnapshotError';
     }
 }
+export async function buildExecutionSummary(doc) {
+    const summary = await buildDocumentSnapshot(doc, { countSummary: true });
+    if (summary.revision === 'unknown' ||
+        summary.diagnostics.some((item) => ['info', 'blocks.list'].includes(item.section)))
+        throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', 'Required summary evidence is unavailable.');
+    const readRevision = getDocumentRevisionReader(doc);
+    const revision = readRevision
+        ? await readRevision()
+        : (await doc.blocks.list({ offset: Number.MAX_SAFE_INTEGER, limit: 1 })).revision;
+    assertMutationSnapshotRevision(summary.revision, revision ?? 'unknown');
+    return summary;
+}
 const MUTATION_BLOCK_PAGE_SIZE = 1000;
 const MUTATION_BLOCK_PAGE_CONCURRENCY = 4;
 const MUTATION_NON_TABLE_DOMAINS = [

package/dist/agent/execution-context.cjs

@@ -184,6 +184,7 @@ class ExecutionContext {
     fallbackReason;
     currentRevision;
     legacyRevisionOnly = false;
+    preserveSummaryCounts = false;
     constructor(source, requirements = {}) {
         this.source = source;
         this.requirements = requirements;
@@ -268,9 +269,11 @@ class ExecutionContext {
                             ? 'verification requires complete evidence'
                             : undefined);
         const complete = evidence === 'full' || this.fallbackReason ? await docSnapshot.buildMutationSnapshot(this.source) : undefined;
+        this.preserveSummaryCounts = !complete && documentEvidence.requiresSummaryCounts(this.source);
+        const summary = this.preserveSummaryCounts ? await docSnapshot.buildExecutionSummary(this.source) : undefined;
         if (complete && (complete.revision === 'unknown' || complete.diagnostics.some((item) => item.section === 'info')))
             throw new errors.SuperDocCliError('Required complete evidence is unavailable.', { code: 'EVIDENCE_UNAVAILABLE' });
-        this.pre = new DocumentFacts(this.source, complete?.revision ?? compactRevision ?? (await readPublicRevision(this.source)), complete);
+        this.pre = new DocumentFacts(this.source, complete?.revision ?? summary?.revision ?? compactRevision ?? (await readPublicRevision(this.source)), complete, summary?.counts);
         this.currentRevision = this.pre.revision;
         await this.pre.prepare(checks);
         return this.pre;
@@ -278,7 +281,11 @@ class ExecutionContext {
     async finishRevision() {
         if (this.requirements.evidence === 'full')
             return this.finish();
-        const summary = this.pre?.complete ? await docSnapshot.buildDocumentSnapshot(this.source, { countsOnly: true }) : undefined;
+        const summary = this.preserveSummaryCounts
+            ? await docSnapshot.buildExecutionSummary(this.source)
+            : this.pre?.complete
+                ? await docSnapshot.buildDocumentSnapshot(this.source, { countsOnly: true })
+                : undefined;
         if (summary && (summary.revision === 'unknown' || summary.diagnostics.some((item) => item.section === 'info')))
             throw new errors.SuperDocCliError('Required summary is unavailable.', { code: 'EVIDENCE_UNAVAILABLE' });
         const revision = summary?.revision ?? (await readPublicRevision(this.source));
@@ -289,11 +296,12 @@ class ExecutionContext {
     }
     async finish() {
         const complete = this.pre?.complete ? await docSnapshot.buildMutationSnapshot(this.source) : undefined;
+        const summary = this.preserveSummaryCounts ? await docSnapshot.buildExecutionSummary(this.source) : undefined;
         if (complete && (complete.revision === 'unknown' || complete.diagnostics.some((item) => item.section === 'info')))
             throw new errors.SuperDocCliError('Required complete evidence is unavailable.', { code: 'EVIDENCE_UNAVAILABLE' });
-        const revision = complete?.revision ?? (await readPublicRevision(this.source));
+        const revision = complete?.revision ?? summary?.revision ?? (await readPublicRevision(this.source));
         this.assertExecutionRevision(revision);
-        this.post = new DocumentFacts(this.source, revision, complete);
+        this.post = new DocumentFacts(this.source, revision, complete, summary?.counts);
         this.currentRevision = this.post.revision;
         return this.post;
     }

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

@@ -86,6 +86,7 @@ export declare class ExecutionContext {
     fallbackReason?: string;
     private currentRevision?;
     private legacyRevisionOnly;
+    private preserveSummaryCounts;
     constructor(source: BoundDocApi, requirements?: EvidenceRequirements);
     start(): Promise<DocumentFacts>;
     finishRevision(): Promise<DocumentFacts>;

package/dist/agent/execution-context.js

@@ -1,6 +1,6 @@
-import { getDocumentRevisionReader, supportsDocumentFacts, forwardDocumentEvidence, getMutationRevision, } from '../runtime/document-evidence.js';
+import { getDocumentRevisionReader, supportsDocumentFacts, requiresSummaryCounts, forwardDocumentEvidence, getMutationRevision, } from '../runtime/document-evidence.js';
 import { SuperDocCliError } from '../runtime/errors.js';
-import { buildDocumentSnapshot, buildMutationSnapshot, resolveSnapshotSelector, } from './doc-snapshot.js';
+import { buildDocumentSnapshot, buildMutationSnapshot, buildExecutionSummary, resolveSnapshotSelector, } from './doc-snapshot.js';
 import { getOperationCatalogEntry } from './operation-catalog.js';
 export function supportsLocalSelector(selector) {
     return (selector.kind === 'nodeId' ||
@@ -181,6 +181,7 @@ export class ExecutionContext {
     fallbackReason;
     currentRevision;
     legacyRevisionOnly = false;
+    preserveSummaryCounts = false;
     constructor(source, requirements = {}) {
         this.source = source;
         this.requirements = requirements;
@@ -265,9 +266,11 @@ export class ExecutionContext {
                             ? 'verification requires complete evidence'
                             : undefined);
         const complete = evidence === 'full' || this.fallbackReason ? await buildMutationSnapshot(this.source) : undefined;
+        this.preserveSummaryCounts = !complete && requiresSummaryCounts(this.source);
+        const summary = this.preserveSummaryCounts ? await buildExecutionSummary(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.pre = new DocumentFacts(this.source, complete?.revision ?? summary?.revision ?? compactRevision ?? (await readPublicRevision(this.source)), complete, summary?.counts);
         this.currentRevision = this.pre.revision;
         await this.pre.prepare(checks);
         return this.pre;
@@ -275,7 +278,11 @@ export class ExecutionContext {
     async finishRevision() {
         if (this.requirements.evidence === 'full')
             return this.finish();
-        const summary = this.pre?.complete ? await buildDocumentSnapshot(this.source, { countsOnly: true }) : undefined;
+        const summary = this.preserveSummaryCounts
+            ? await buildExecutionSummary(this.source)
+            : 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));
@@ -286,11 +293,12 @@ export class ExecutionContext {
     }
     async finish() {
         const complete = this.pre?.complete ? await buildMutationSnapshot(this.source) : undefined;
+        const summary = this.preserveSummaryCounts ? await buildExecutionSummary(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));
+        const revision = complete?.revision ?? summary?.revision ?? (await readPublicRevision(this.source));
         this.assertExecutionRevision(revision);
-        this.post = new DocumentFacts(this.source, revision, complete);
+        this.post = new DocumentFacts(this.source, revision, complete, summary?.counts);
         this.currentRevision = this.post.revision;
         return this.post;
     }