@superdoc-dev/sdk 1.19.1 → 1.20.0

package/dist/agent/operation-catalog.cjs

@@ -0,0 +1,418 @@
+'use strict';
+
+var contract = require('../generated/contract.cjs');
+
+/**
+ * Operation catalog derived from the generated contract.
+ *
+ * This module turns every `doc.*` operation in `generated/contract.ts` into a
+ * row classified by domain, mutating vs read, target shape, change-mode
+ * support, dry-run support, atomicity, verification hints, exposure status,
+ * and action eligibility. The classification is built deterministically from
+ * the contract so the catalog cannot silently drift out of sync.
+ *
+ * The catalog is the source of truth used by:
+ * - the IR validator (every IR operation must resolve to a catalog row)
+ * - anti-overfit gates (tests that assert every generated operation is
+ *   classified)
+ * - holdout-style conformance checks
+ *
+ * Do not hand-classify operations here. Add rules to the derivation pass.
+ */
+const MUTATING_VERBS = new Set([
+    'insert',
+    'create',
+    'delete',
+    'remove',
+    'patch',
+    'update',
+    'set',
+    'apply',
+    'replace',
+    'rewrite',
+    'merge',
+    'split',
+    'attach',
+    'detach',
+    'rebuild',
+    'configure',
+    'rename',
+    'clear',
+    'clearcontent',
+    'append',
+    'appendcontent',
+    'indent',
+    'outdent',
+    'decide',
+    'continueprevious',
+    'setlevel',
+    'setvalue',
+    'settype',
+    'setstate',
+    'undo',
+    'redo',
+    'insertlinebreak',
+    'inserttab',
+    'mutations',
+    'commit',
+    'rollback',
+    'transact',
+]);
+const READ_VERBS = new Set([
+    'get',
+    'list',
+    'find',
+    'info',
+    'capabilities',
+    'extract',
+    'gettext',
+    'gethtml',
+    'getmarkdown',
+    'getnode',
+    'getnodebyid',
+    'diff',
+    'history',
+    'describe',
+    'describecommand',
+    'status',
+    'query',
+    'markdowntofragment',
+    'getstate',
+]);
+const SESSION_OP_IDS = new Set(['doc.open', 'doc.close', 'doc.save', 'doc.session']);
+const META_OP_IDS = new Set(['doc.describe', 'doc.describeCommand', 'doc.capabilities.get', 'doc.status']);
+const BENCHMARK_ONLY_HINTS = [
+// Anything we explicitly mark as not for product-default coverage. Empty
+// for now — concrete benchmark surfaces live in profile config, not the
+// contract-derived catalog.
+];
+function tokensFromOperationId(operationId) {
+    return operationId.split('.').slice(1);
+}
+function lastToken(operationId) {
+    const tokens = tokensFromOperationId(operationId);
+    return (tokens[tokens.length - 1] ?? '').toLowerCase();
+}
+function deriveDomain(operationId) {
+    const tokens = tokensFromOperationId(operationId);
+    const first = (tokens[0] ?? '').toLowerCase();
+    switch (first) {
+        case 'open':
+        case 'close':
+        case 'save':
+        case 'session':
+            return 'session';
+        case 'describe':
+        case 'describecommand':
+        case 'capabilities':
+        case 'status':
+            return 'meta';
+        case 'gettext':
+        case 'getmarkdown':
+        case 'gethtml':
+        case 'getnode':
+        case 'getnodebyid':
+        case 'info':
+        case 'extract':
+        case 'find':
+        case 'markdowntofragment':
+            return 'document-read';
+        case 'create':
+            // create.* domain-specific; classify by sub-domain
+            switch ((tokens[1] ?? '').toLowerCase()) {
+                case 'table':
+                    return 'tables';
+                case 'image':
+                    return 'images';
+                case 'paragraph':
+                case 'heading':
+                case 'sectionbreak':
+                case 'tableofcontents':
+                    return 'blocks';
+                default:
+                    return 'document-write';
+            }
+        case 'blocks':
+            return 'blocks';
+        case 'text':
+        case 'replace':
+        case 'delete':
+        case 'insert':
+        case 'insertlinebreak':
+        case 'inserttab':
+        case 'clearcontent':
+            return 'text';
+        case 'format':
+            return 'format';
+        case 'styles':
+            return 'styles';
+        case 'lists':
+            return 'lists';
+        case 'tables':
+            return 'tables';
+        case 'images':
+            return 'images';
+        case 'comments':
+            return 'comments';
+        case 'trackchanges':
+            return 'tracked-changes';
+        case 'sections':
+            return 'sections';
+        case 'fields':
+            return 'fields';
+        case 'hyperlinks':
+            return 'hyperlinks';
+        case 'bookmarks':
+            return 'bookmarks';
+        case 'crossrefs':
+            return 'cross-refs';
+        case 'footnotes':
+            return 'footnotes';
+        case 'headerfooters':
+            return 'header-footer';
+        case 'contentcontrols':
+            return 'content-controls';
+        case 'permissionranges':
+            return 'permission-ranges';
+        case 'protection':
+            return 'protection';
+        case 'toc':
+            return 'toc';
+        case 'authorities':
+            return 'authorities';
+        case 'captions':
+            return 'captions';
+        case 'citations':
+            return 'citations';
+        case 'mutations':
+            return 'mutations';
+        case 'selection':
+            return 'selection';
+        case 'history':
+            return 'history';
+        case 'index':
+            return 'index';
+        case 'query':
+            return 'query';
+        case 'ranges':
+            return 'ranges';
+        case 'diff':
+            return 'diff';
+        case 'get':
+            return 'document-read';
+        default:
+            return 'document-write';
+    }
+}
+function deriveMode(operationId, entry) {
+    if (SESSION_OP_IDS.has(operationId))
+        return 'session';
+    const last = lastToken(operationId);
+    if (READ_VERBS.has(last))
+        return 'read';
+    if (entry?.mutates === true)
+        return 'write';
+    if (MUTATING_VERBS.has(last))
+        return 'write';
+    // Operations that don't end with a mutating verb but still mutate (e.g.
+    // doc.replace, doc.delete) are caught by the verb sets above or by the
+    // generated contract's `mutates` flag; the rest default to read.
+    if (last === 'replace' || last === 'delete' || last === 'insert')
+        return 'write';
+    return 'read';
+}
+function deriveTargetShape(operationId) {
+    const tokens = tokensFromOperationId(operationId).map((t) => t.toLowerCase());
+    if (tokens.length === 0)
+        return 'document';
+    if (tokens[0] === 'blocks')
+        return 'block';
+    if (tokens[0] === 'tables')
+        return 'table';
+    if (tokens[0] === 'lists')
+        return 'list';
+    if (tokens[0] === 'images')
+        return 'image';
+    if (tokens[0] === 'comments')
+        return 'comment';
+    if (tokens[0] === 'sections' || tokens[0] === 'headerfooters')
+        return 'document';
+    if (tokens[0] === 'find' || tokens[0] === 'query')
+        return 'range';
+    if (tokens[0] === 'selection' || tokens[0] === 'ranges')
+        return 'range';
+    if (tokens[0] === 'mutations')
+        return 'mixed';
+    if (tokens[0] === 'create')
+        return 'document';
+    if (tokens[0] === 'trackchanges' ||
+        tokens[0] === 'bookmarks' ||
+        tokens[0] === 'hyperlinks' ||
+        tokens[0] === 'crossrefs' ||
+        tokens[0] === 'footnotes' ||
+        tokens[0] === 'fields' ||
+        tokens[0] === 'permissionranges' ||
+        tokens[0] === 'contentcontrols' ||
+        tokens[0] === 'captions' ||
+        tokens[0] === 'authorities' ||
+        tokens[0] === 'citations') {
+        return 'entity';
+    }
+    if (tokens[0] === 'format' || tokens[0] === 'styles')
+        return 'range';
+    if (tokens[0] === 'index')
+        return 'document';
+    return 'none';
+}
+function hasParam(params, name) {
+    if (!params)
+        return false;
+    return params.some((p) => p?.name === name);
+}
+function deriveSupportsChangeMode(entry) {
+    return hasParam(entry.params, 'changeMode');
+}
+function deriveSupportsDryRun(entry) {
+    return hasParam(entry.params, 'dryRun');
+}
+function deriveAtomic(operationId, entry) {
+    // All mutating operations are atomic by contract: each operation either
+    // succeeds end-to-end or fails. doc.mutations.apply is the only batched
+    // form and is explicitly atomic when its `atomic` flag is set.
+    if (operationId === 'doc.mutations.apply')
+        return hasParam(entry.params, 'atomic');
+    return deriveMode(operationId, entry) === 'write';
+}
+function deriveVerificationHints(operationId) {
+    const domain = deriveDomain(operationId);
+    const hints = [];
+    switch (domain) {
+        case 'blocks':
+        case 'text':
+            hints.push('reread-block-text', 'verify-revision');
+            break;
+        case 'tables':
+            hints.push('reread-table-shape', 'verify-cell-text');
+            break;
+        case 'lists':
+            hints.push('reread-list-items', 'verify-list-count');
+            break;
+        case 'images':
+            hints.push('reread-image-anchor', 'verify-image-id');
+            break;
+        case 'comments':
+            hints.push('list-comments', 'verify-anchor-text');
+            break;
+        case 'tracked-changes':
+            hints.push('list-tracked-changes', 'verify-counts');
+            break;
+        case 'format':
+        case 'styles':
+            hints.push('reread-resolved-style', 'verify-revision');
+            break;
+        case 'sections':
+        case 'header-footer':
+            hints.push('reread-section-shape', 'save-reopen');
+            break;
+        case 'protection':
+        case 'permission-ranges':
+            hints.push('save-reopen', 'verify-xml-shape');
+            break;
+        case 'document-write':
+        case 'mutations':
+            hints.push('verify-revision', 'verify-text-snapshot');
+            break;
+        default:
+            hints.push('verify-revision');
+    }
+    return hints;
+}
+function deriveStoryHints(entry) {
+    const hints = [];
+    if (hasParam(entry.params, 'in'))
+        hints.push('story-scoped');
+    if (hasParam(entry.params, 'story'))
+        hints.push('story-scoped');
+    if (hasParam(entry.params, 'sectionId'))
+        hints.push('section-scoped');
+    return hints;
+}
+function deriveDomainHints(entry) {
+    const hints = new Set();
+    for (const param of entry.params ?? []) {
+        if (!param?.name)
+            continue;
+        if (param.name === 'changeMode')
+            hints.add('change-mode');
+        if (param.name === 'dryRun')
+            hints.add('dry-run');
+        if (param.name === 'atomic')
+            hints.add('atomic-batch');
+        if (param.name === 'force')
+            hints.add('force-allowed');
+        if (param.name === 'preserveStyle')
+            hints.add('preserve-style');
+        if (param.name === 'caseSensitive')
+            hints.add('case-sensitive');
+    }
+    if (typeof entry.category === 'string') {
+        hints.add(`category:${entry.category}`);
+    }
+    return [...hints];
+}
+function deriveExposure(operationId) {
+    if (META_OP_IDS.has(operationId))
+        return 'internal';
+    if (BENCHMARK_ONLY_HINTS.includes(operationId))
+        return 'benchmark-only';
+    if (operationId.startsWith('doc.session.'))
+        return 'internal';
+    return 'stable';
+}
+function deriveActionEligible(operationId) {
+    if (SESSION_OP_IDS.has(operationId))
+        return false;
+    if (META_OP_IDS.has(operationId))
+        return false;
+    if (deriveExposure(operationId) === 'internal')
+        return false;
+    return true;
+}
+function classifyEntry(operationId, entry) {
+    const mode = deriveMode(operationId, entry);
+    return {
+        operationId,
+        domain: deriveDomain(operationId),
+        mode,
+        isMutating: mode === 'write',
+        targetShape: deriveTargetShape(operationId),
+        storyHints: deriveStoryHints(entry),
+        domainHints: deriveDomainHints(entry),
+        supportsChangeMode: deriveSupportsChangeMode(entry),
+        supportsDryRun: deriveSupportsDryRun(entry),
+        atomic: deriveAtomic(operationId, entry),
+        verificationHints: deriveVerificationHints(operationId),
+        exposure: deriveExposure(operationId),
+        actionEligible: deriveActionEligible(operationId),
+        description: typeof entry.description === 'string'
+            ? entry.description
+            : '',
+    };
+}
+function buildCatalog() {
+    const entries = [];
+    for (const [operationId, entry] of Object.entries(contract.CONTRACT.operations)) {
+        entries.push(classifyEntry(operationId, entry));
+    }
+    entries.sort((a, b) => a.operationId.localeCompare(b.operationId));
+    return entries;
+}
+/** Full operation catalog derived from the generated contract. */
+const OPERATION_CATALOG = Object.freeze(buildCatalog());
+const CATALOG_BY_ID = new Map(OPERATION_CATALOG.map((entry) => [entry.operationId, entry]));
+function getOperationCatalogEntry(operationId) {
+    return CATALOG_BY_ID.get(operationId);
+}
+
+exports.OPERATION_CATALOG = OPERATION_CATALOG;
+exports.getOperationCatalogEntry = getOperationCatalogEntry;

package/dist/agent/operation-catalog.d.ts

@@ -0,0 +1,36 @@
+export type OperationDomain = 'session' | 'meta' | 'document-read' | 'document-write' | 'blocks' | 'text' | 'format' | 'styles' | 'lists' | 'tables' | 'images' | 'comments' | 'tracked-changes' | 'sections' | 'fields' | 'hyperlinks' | 'bookmarks' | 'cross-refs' | 'footnotes' | 'header-footer' | 'content-controls' | 'permission-ranges' | 'protection' | 'toc' | 'authorities' | 'captions' | 'citations' | 'mutations' | 'selection' | 'history' | 'index' | 'query' | 'ranges' | 'diff';
+export type OperationMode = 'read' | 'write' | 'session';
+export type TargetShape = 'none' | 'block' | 'range' | 'entity' | 'paragraph' | 'table' | 'list' | 'document' | 'image' | 'comment' | 'mixed';
+export type ExposureStatus = 'stable' | 'experimental' | 'benchmark-only' | 'internal';
+export type OperationCatalogEntry = {
+    operationId: string;
+    domain: OperationDomain;
+    mode: OperationMode;
+    isMutating: boolean;
+    targetShape: TargetShape;
+    storyHints: readonly string[];
+    domainHints: readonly string[];
+    supportsChangeMode: boolean;
+    supportsDryRun: boolean;
+    atomic: boolean;
+    verificationHints: readonly string[];
+    exposure: ExposureStatus;
+    actionEligible: boolean;
+    description: string;
+};
+/** Full operation catalog derived from the generated contract. */
+export declare const OPERATION_CATALOG: readonly OperationCatalogEntry[];
+export declare function getOperationCatalogEntry(operationId: string): OperationCatalogEntry | undefined;
+export declare function listOperationsByDomain(domain: OperationDomain): readonly OperationCatalogEntry[];
+export declare function listMutatingOperations(): readonly OperationCatalogEntry[];
+/** Returns operations that are classified but have no specific verification hint other than verify-revision. */
+export declare function listOperationsMissingStructuralVerification(): readonly OperationCatalogEntry[];
+export declare function getOperationCatalogSummary(): {
+    total: number;
+    byDomain: Record<string, number>;
+    byMode: Record<string, number>;
+    byExposure: Record<string, number>;
+    mutatingCount: number;
+    actionEligibleCount: number;
+};
+//# sourceMappingURL=operation-catalog.d.ts.map

package/dist/agent/operation-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-catalog.d.ts","sourceRoot":"","sources":["../../src/agent/operation-catalog.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,MAAM,GACN,eAAe,GACf,gBAAgB,GAChB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,iBAAiB,GACjB,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,WAAW,GACX,YAAY,GACZ,WAAW,GACX,eAAe,GACf,kBAAkB,GAClB,mBAAmB,GACnB,YAAY,GACZ,KAAK,GACL,aAAa,GACb,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,SAAS,GACT,OAAO,GACP,OAAO,GACP,QAAQ,GACR,MAAM,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEzD,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,OAAO,GACP,OAAO,GACP,QAAQ,GACR,WAAW,GACX,OAAO,GACP,MAAM,GACN,UAAU,GACV,OAAO,GACP,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,cAAc,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAEvF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAyXF,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,SAAS,qBAAqB,EAAkC,CAAC;AAMjG,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAE/F;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,qBAAqB,EAAE,CAEhG;AAED,wBAAgB,sBAAsB,IAAI,SAAS,qBAAqB,EAAE,CAEzE;AAED,gHAAgH;AAChH,wBAAgB,2CAA2C,IAAI,SAAS,qBAAqB,EAAE,CAK9F;AAED,wBAAgB,0BAA0B,IAAI;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;CAC7B,CAqBA"}