@superdoc-dev/sdk 1.19.2 → 1.20.1

package/dist/action-primitives/resolve.cjs

@@ -0,0 +1,252 @@
+'use strict';
+
+function failure(code, message, details) {
+    return { ok: false, code, message, details };
+}
+function isResolveFailure(value) {
+    return value.ok === false;
+}
+function parseOrdinal(value) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        return undefined;
+    }
+    return value;
+}
+function parseWorkflowTargetRequest(raw) {
+    if (typeof raw === 'string') {
+        const ref = raw.trim();
+        if (ref.length === 0) {
+            return failure('TARGET_UNSUPPORTED', 'Target reference cannot be empty.');
+        }
+        return { mode: 'ref', ref };
+    }
+    if (raw == null || typeof raw !== 'object') {
+        return failure('TARGET_UNSUPPORTED', 'Target must be a string ref or a supported target object.', {
+            receivedType: raw == null ? 'nullish' : typeof raw,
+        });
+    }
+    const target = raw;
+    if (typeof target.by === 'string' && 'value' in target) {
+        const by = target.by;
+        const value = target.value;
+        if (by === 'ref' && typeof value === 'string') {
+            return parseWorkflowTargetRequest(value);
+        }
+        if (by === 'nodeId' && typeof value === 'string' && value.length > 0) {
+            return { mode: 'nodeId', nodeId: value };
+        }
+        if (by === 'blockOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'blockOrdinal', blockOrdinal: parsed };
+        }
+        if (by === 'paragraphOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'paragraphOrdinal', paragraphOrdinal: parsed };
+        }
+        if (by === 'bodyParagraphOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'bodyParagraphOrdinal', bodyParagraphOrdinal: parsed };
+        }
+        if (by === 'headingOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'headingOrdinal', headingOrdinal: parsed };
+        }
+        if (by === 'listOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'listOrdinal', listOrdinal: parsed };
+        }
+        if (by === 'tableOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'tableOrdinal', tableOrdinal: parsed };
+        }
+        return failure('TARGET_UNSUPPORTED', 'Target object has unsupported {by,value} shape.', {
+            by,
+            valueType: typeof value,
+        });
+    }
+    const supportedKeys = [
+        'ref',
+        'nodeId',
+        'blockOrdinal',
+        'paragraphOrdinal',
+        'bodyParagraphOrdinal',
+        'headingOrdinal',
+        'listOrdinal',
+        'tableOrdinal',
+    ];
+    const presentKeys = supportedKeys.filter((key) => target[key] != null);
+    if (presentKeys.length !== 1) {
+        return failure('TARGET_UNSUPPORTED', 'Target object must include exactly one supported key: ref, nodeId, blockOrdinal, paragraphOrdinal, bodyParagraphOrdinal, headingOrdinal, listOrdinal, tableOrdinal.', { presentKeys });
+    }
+    const key = presentKeys[0];
+    if (key === 'ref') {
+        return parseWorkflowTargetRequest(target.ref);
+    }
+    if (key === 'nodeId' && typeof target.nodeId === 'string' && target.nodeId.length > 0) {
+        return { mode: 'nodeId', nodeId: target.nodeId };
+    }
+    if (key === 'blockOrdinal') {
+        const parsed = parseOrdinal(target.blockOrdinal);
+        if (parsed != null)
+            return { mode: 'blockOrdinal', blockOrdinal: parsed };
+    }
+    if (key === 'paragraphOrdinal') {
+        const parsed = parseOrdinal(target.paragraphOrdinal);
+        if (parsed != null)
+            return { mode: 'paragraphOrdinal', paragraphOrdinal: parsed };
+    }
+    if (key === 'bodyParagraphOrdinal') {
+        const parsed = parseOrdinal(target.bodyParagraphOrdinal);
+        if (parsed != null)
+            return { mode: 'bodyParagraphOrdinal', bodyParagraphOrdinal: parsed };
+    }
+    if (key === 'headingOrdinal') {
+        const parsed = parseOrdinal(target.headingOrdinal);
+        if (parsed != null)
+            return { mode: 'headingOrdinal', headingOrdinal: parsed };
+    }
+    if (key === 'listOrdinal') {
+        const parsed = parseOrdinal(target.listOrdinal);
+        if (parsed != null)
+            return { mode: 'listOrdinal', listOrdinal: parsed };
+    }
+    if (key === 'tableOrdinal') {
+        const parsed = parseOrdinal(target.tableOrdinal);
+        if (parsed != null)
+            return { mode: 'tableOrdinal', tableOrdinal: parsed };
+    }
+    return failure('TARGET_UNSUPPORTED', `Target ${key} value is invalid.`, {
+        key,
+        value: target[key],
+    });
+}
+function toResolvedTarget(mode, entity) {
+    if (entity.kind === 'block') {
+        return {
+            mode,
+            entityKind: entity.kind,
+            nodeId: entity.nodeId,
+            ref: entity.ref,
+            blockOrdinal: entity.ordinal,
+            paragraphOrdinal: entity.paragraphOrdinal,
+            bodyParagraphOrdinal: entity.bodyParagraphOrdinal,
+            headingOrdinal: entity.headingOrdinal,
+            tableOrdinal: entity.tableOrdinal,
+            entity,
+        };
+    }
+    if (entity.kind === 'listItem') {
+        return {
+            mode,
+            entityKind: entity.kind,
+            nodeId: entity.nodeId,
+            ref: entity.ref,
+            listOrdinal: entity.apiOrdinal,
+            entity,
+        };
+    }
+    return {
+        mode,
+        entityKind: entity.kind,
+        nodeId: entity.nodeId,
+        ref: entity.ref,
+        blockOrdinal: entity.blockOrdinal,
+        tableOrdinal: entity.tableOrdinal,
+        entity,
+    };
+}
+function resolveUnique(request, candidates, details) {
+    const mode = request.mode;
+    if (candidates.length === 0) {
+        return failure('TARGET_NOT_FOUND', `No workflow target matched ${mode}.`, details);
+    }
+    if (candidates.length > 1) {
+        return failure('TARGET_AMBIGUOUS', `Multiple workflow targets matched ${mode}.`, {
+            ...details,
+            candidateCount: candidates.length,
+            candidateKinds: candidates.map((candidate) => candidate.kind),
+            candidateNodeIds: candidates.map((candidate) => candidate.nodeId),
+        });
+    }
+    const matched = candidates[0];
+    if (matched == null) {
+        return failure('TARGET_NOT_FOUND', `No workflow target matched ${mode}.`, details);
+    }
+    return { ok: true, request, target: toResolvedTarget(mode, matched) };
+}
+function resolveWorkflowTarget(index, request) {
+    if (request.mode === 'ref') {
+        const candidates = index.lookup.byRef.get(request.ref) ?? [];
+        if (candidates.length > 0) {
+            return resolveUnique(request, candidates, { ref: request.ref });
+        }
+        const nodeIdCandidates = index.lookup.byNodeId.get(request.ref) ?? [];
+        return resolveUnique(request, nodeIdCandidates, { ref: request.ref, nodeIdFallback: true });
+    }
+    if (request.mode === 'nodeId') {
+        const candidates = index.lookup.byNodeId.get(request.nodeId) ?? [];
+        return resolveUnique(request, candidates, { nodeId: request.nodeId });
+    }
+    if (request.mode === 'blockOrdinal') {
+        // Requests use the 1-based convention (parseOrdinal rejects < 1); the
+        // index keys on the doc-api block.ordinal, which is 0-based.
+        const block = index.lookup.byBlockOrdinal.get(request.blockOrdinal - 1);
+        return resolveUnique(request, block == null ? [] : [block], {
+            blockOrdinal: request.blockOrdinal,
+        });
+    }
+    if (request.mode === 'paragraphOrdinal') {
+        const block = index.lookup.byParagraphOrdinal.get(request.paragraphOrdinal);
+        return resolveUnique(request, block == null ? [] : [block], {
+            paragraphOrdinal: request.paragraphOrdinal,
+        });
+    }
+    if (request.mode === 'bodyParagraphOrdinal') {
+        const block = index.lookup.byBodyParagraphOrdinal.get(request.bodyParagraphOrdinal);
+        return resolveUnique(request, block == null ? [] : [block], {
+            bodyParagraphOrdinal: request.bodyParagraphOrdinal,
+        });
+    }
+    if (request.mode === 'headingOrdinal') {
+        const block = index.lookup.byHeadingOrdinal.get(request.headingOrdinal);
+        return resolveUnique(request, block == null ? [] : [block], {
+            headingOrdinal: request.headingOrdinal,
+        });
+    }
+    if (request.mode === 'listOrdinal') {
+        if (index.lookup.byListOrdinal.size === 0) {
+            return failure('TARGET_MODE_UNAVAILABLE', 'List ordinal resolution is unavailable: index has no API list ordinals.', {
+                listCount: index.lists.length,
+            });
+        }
+        const candidates = index.lookup.byListOrdinal.get(request.listOrdinal) ?? [];
+        return resolveUnique(request, candidates, { listOrdinal: request.listOrdinal });
+    }
+    if (index.lookup.byTableOrdinal.size === 0) {
+        return failure('TARGET_MODE_UNAVAILABLE', 'Table ordinal resolution is unavailable: index has no tables.', {
+            tableCount: index.tables.length,
+        });
+    }
+    const table = index.lookup.byTableOrdinal.get(request.tableOrdinal);
+    return resolveUnique(request, table == null ? [] : [table], { tableOrdinal: request.tableOrdinal });
+}
+function resolveWorkflowTargetFromUnknown(index, rawTarget) {
+    if (rawTarget == null) {
+        return failure('TARGET_REQUIRED', 'No target value was provided.');
+    }
+    const parsed = parseWorkflowTargetRequest(rawTarget);
+    if (isResolveFailure(parsed)) {
+        return parsed;
+    }
+    return resolveWorkflowTarget(index, parsed);
+}
+
+exports.parseWorkflowTargetRequest = parseWorkflowTargetRequest;
+exports.resolveWorkflowTarget = resolveWorkflowTarget;
+exports.resolveWorkflowTargetFromUnknown = resolveWorkflowTargetFromUnknown;

package/dist/action-primitives/resolve.d.ts

@@ -0,0 +1,56 @@
+import type { WorkflowDocIndex, WorkflowIndexedEntity } from './doc-index.js';
+export type WorkflowTargetRequest = {
+    mode: 'ref';
+    ref: string;
+} | {
+    mode: 'nodeId';
+    nodeId: string;
+} | {
+    mode: 'blockOrdinal';
+    blockOrdinal: number;
+} | {
+    mode: 'paragraphOrdinal';
+    paragraphOrdinal: number;
+} | {
+    mode: 'bodyParagraphOrdinal';
+    bodyParagraphOrdinal: number;
+} | {
+    mode: 'headingOrdinal';
+    headingOrdinal: number;
+} | {
+    mode: 'listOrdinal';
+    listOrdinal: number;
+} | {
+    mode: 'tableOrdinal';
+    tableOrdinal: number;
+};
+export type WorkflowResolveFailureCode = 'TARGET_REQUIRED' | 'TARGET_UNSUPPORTED' | 'TARGET_NOT_FOUND' | 'TARGET_AMBIGUOUS' | 'TARGET_MODE_UNAVAILABLE';
+export type WorkflowResolveFailure = {
+    ok: false;
+    code: WorkflowResolveFailureCode;
+    message: string;
+    details?: Record<string, unknown>;
+};
+export type WorkflowResolvedTarget = {
+    mode: WorkflowTargetRequest['mode'];
+    entityKind: WorkflowIndexedEntity['kind'];
+    nodeId: string;
+    ref?: string;
+    blockOrdinal?: number;
+    paragraphOrdinal?: number;
+    bodyParagraphOrdinal?: number;
+    headingOrdinal?: number;
+    listOrdinal?: number;
+    tableOrdinal?: number;
+    entity: WorkflowIndexedEntity;
+};
+export type WorkflowResolveSuccess = {
+    ok: true;
+    request: WorkflowTargetRequest;
+    target: WorkflowResolvedTarget;
+};
+export type WorkflowResolveResult = WorkflowResolveSuccess | WorkflowResolveFailure;
+export declare function parseWorkflowTargetRequest(raw: unknown): WorkflowTargetRequest | WorkflowResolveFailure;
+export declare function resolveWorkflowTarget(index: WorkflowDocIndex, request: WorkflowTargetRequest): WorkflowResolveResult;
+export declare function resolveWorkflowTargetFromUnknown(index: WorkflowDocIndex, rawTarget: unknown): WorkflowResolveResult;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/action-primitives/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/action-primitives/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAE9E,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,MAAM,MAAM,0BAA0B,GAClC,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,kBAAkB,GAClB,yBAAyB,CAAC;AAE9B,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,0BAA0B,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACpC,UAAU,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,qBAAqB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,qBAAqB,CAAC;IAC/B,MAAM,EAAE,sBAAsB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,sBAAsB,GAAG,sBAAsB,CAAC;AAqBpF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,GAAG,sBAAsB,CAqHvG;AAiED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,qBAAqB,GAAG,qBAAqB,CAkEpH;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,OAAO,GAAG,qBAAqB,CASnH"}

package/dist/action-primitives/resolve.js

@@ -0,0 +1,246 @@
+function failure(code, message, details) {
+    return { ok: false, code, message, details };
+}
+function isResolveFailure(value) {
+    return value.ok === false;
+}
+function parseOrdinal(value) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        return undefined;
+    }
+    return value;
+}
+export function parseWorkflowTargetRequest(raw) {
+    if (typeof raw === 'string') {
+        const ref = raw.trim();
+        if (ref.length === 0) {
+            return failure('TARGET_UNSUPPORTED', 'Target reference cannot be empty.');
+        }
+        return { mode: 'ref', ref };
+    }
+    if (raw == null || typeof raw !== 'object') {
+        return failure('TARGET_UNSUPPORTED', 'Target must be a string ref or a supported target object.', {
+            receivedType: raw == null ? 'nullish' : typeof raw,
+        });
+    }
+    const target = raw;
+    if (typeof target.by === 'string' && 'value' in target) {
+        const by = target.by;
+        const value = target.value;
+        if (by === 'ref' && typeof value === 'string') {
+            return parseWorkflowTargetRequest(value);
+        }
+        if (by === 'nodeId' && typeof value === 'string' && value.length > 0) {
+            return { mode: 'nodeId', nodeId: value };
+        }
+        if (by === 'blockOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'blockOrdinal', blockOrdinal: parsed };
+        }
+        if (by === 'paragraphOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'paragraphOrdinal', paragraphOrdinal: parsed };
+        }
+        if (by === 'bodyParagraphOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'bodyParagraphOrdinal', bodyParagraphOrdinal: parsed };
+        }
+        if (by === 'headingOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'headingOrdinal', headingOrdinal: parsed };
+        }
+        if (by === 'listOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'listOrdinal', listOrdinal: parsed };
+        }
+        if (by === 'tableOrdinal') {
+            const parsed = parseOrdinal(value);
+            if (parsed != null)
+                return { mode: 'tableOrdinal', tableOrdinal: parsed };
+        }
+        return failure('TARGET_UNSUPPORTED', 'Target object has unsupported {by,value} shape.', {
+            by,
+            valueType: typeof value,
+        });
+    }
+    const supportedKeys = [
+        'ref',
+        'nodeId',
+        'blockOrdinal',
+        'paragraphOrdinal',
+        'bodyParagraphOrdinal',
+        'headingOrdinal',
+        'listOrdinal',
+        'tableOrdinal',
+    ];
+    const presentKeys = supportedKeys.filter((key) => target[key] != null);
+    if (presentKeys.length !== 1) {
+        return failure('TARGET_UNSUPPORTED', 'Target object must include exactly one supported key: ref, nodeId, blockOrdinal, paragraphOrdinal, bodyParagraphOrdinal, headingOrdinal, listOrdinal, tableOrdinal.', { presentKeys });
+    }
+    const key = presentKeys[0];
+    if (key === 'ref') {
+        return parseWorkflowTargetRequest(target.ref);
+    }
+    if (key === 'nodeId' && typeof target.nodeId === 'string' && target.nodeId.length > 0) {
+        return { mode: 'nodeId', nodeId: target.nodeId };
+    }
+    if (key === 'blockOrdinal') {
+        const parsed = parseOrdinal(target.blockOrdinal);
+        if (parsed != null)
+            return { mode: 'blockOrdinal', blockOrdinal: parsed };
+    }
+    if (key === 'paragraphOrdinal') {
+        const parsed = parseOrdinal(target.paragraphOrdinal);
+        if (parsed != null)
+            return { mode: 'paragraphOrdinal', paragraphOrdinal: parsed };
+    }
+    if (key === 'bodyParagraphOrdinal') {
+        const parsed = parseOrdinal(target.bodyParagraphOrdinal);
+        if (parsed != null)
+            return { mode: 'bodyParagraphOrdinal', bodyParagraphOrdinal: parsed };
+    }
+    if (key === 'headingOrdinal') {
+        const parsed = parseOrdinal(target.headingOrdinal);
+        if (parsed != null)
+            return { mode: 'headingOrdinal', headingOrdinal: parsed };
+    }
+    if (key === 'listOrdinal') {
+        const parsed = parseOrdinal(target.listOrdinal);
+        if (parsed != null)
+            return { mode: 'listOrdinal', listOrdinal: parsed };
+    }
+    if (key === 'tableOrdinal') {
+        const parsed = parseOrdinal(target.tableOrdinal);
+        if (parsed != null)
+            return { mode: 'tableOrdinal', tableOrdinal: parsed };
+    }
+    return failure('TARGET_UNSUPPORTED', `Target ${key} value is invalid.`, {
+        key,
+        value: target[key],
+    });
+}
+function toResolvedTarget(mode, entity) {
+    if (entity.kind === 'block') {
+        return {
+            mode,
+            entityKind: entity.kind,
+            nodeId: entity.nodeId,
+            ref: entity.ref,
+            blockOrdinal: entity.ordinal,
+            paragraphOrdinal: entity.paragraphOrdinal,
+            bodyParagraphOrdinal: entity.bodyParagraphOrdinal,
+            headingOrdinal: entity.headingOrdinal,
+            tableOrdinal: entity.tableOrdinal,
+            entity,
+        };
+    }
+    if (entity.kind === 'listItem') {
+        return {
+            mode,
+            entityKind: entity.kind,
+            nodeId: entity.nodeId,
+            ref: entity.ref,
+            listOrdinal: entity.apiOrdinal,
+            entity,
+        };
+    }
+    return {
+        mode,
+        entityKind: entity.kind,
+        nodeId: entity.nodeId,
+        ref: entity.ref,
+        blockOrdinal: entity.blockOrdinal,
+        tableOrdinal: entity.tableOrdinal,
+        entity,
+    };
+}
+function resolveUnique(request, candidates, details) {
+    const mode = request.mode;
+    if (candidates.length === 0) {
+        return failure('TARGET_NOT_FOUND', `No workflow target matched ${mode}.`, details);
+    }
+    if (candidates.length > 1) {
+        return failure('TARGET_AMBIGUOUS', `Multiple workflow targets matched ${mode}.`, {
+            ...details,
+            candidateCount: candidates.length,
+            candidateKinds: candidates.map((candidate) => candidate.kind),
+            candidateNodeIds: candidates.map((candidate) => candidate.nodeId),
+        });
+    }
+    const matched = candidates[0];
+    if (matched == null) {
+        return failure('TARGET_NOT_FOUND', `No workflow target matched ${mode}.`, details);
+    }
+    return { ok: true, request, target: toResolvedTarget(mode, matched) };
+}
+export function resolveWorkflowTarget(index, request) {
+    if (request.mode === 'ref') {
+        const candidates = index.lookup.byRef.get(request.ref) ?? [];
+        if (candidates.length > 0) {
+            return resolveUnique(request, candidates, { ref: request.ref });
+        }
+        const nodeIdCandidates = index.lookup.byNodeId.get(request.ref) ?? [];
+        return resolveUnique(request, nodeIdCandidates, { ref: request.ref, nodeIdFallback: true });
+    }
+    if (request.mode === 'nodeId') {
+        const candidates = index.lookup.byNodeId.get(request.nodeId) ?? [];
+        return resolveUnique(request, candidates, { nodeId: request.nodeId });
+    }
+    if (request.mode === 'blockOrdinal') {
+        // Requests use the 1-based convention (parseOrdinal rejects < 1); the
+        // index keys on the doc-api block.ordinal, which is 0-based.
+        const block = index.lookup.byBlockOrdinal.get(request.blockOrdinal - 1);
+        return resolveUnique(request, block == null ? [] : [block], {
+            blockOrdinal: request.blockOrdinal,
+        });
+    }
+    if (request.mode === 'paragraphOrdinal') {
+        const block = index.lookup.byParagraphOrdinal.get(request.paragraphOrdinal);
+        return resolveUnique(request, block == null ? [] : [block], {
+            paragraphOrdinal: request.paragraphOrdinal,
+        });
+    }
+    if (request.mode === 'bodyParagraphOrdinal') {
+        const block = index.lookup.byBodyParagraphOrdinal.get(request.bodyParagraphOrdinal);
+        return resolveUnique(request, block == null ? [] : [block], {
+            bodyParagraphOrdinal: request.bodyParagraphOrdinal,
+        });
+    }
+    if (request.mode === 'headingOrdinal') {
+        const block = index.lookup.byHeadingOrdinal.get(request.headingOrdinal);
+        return resolveUnique(request, block == null ? [] : [block], {
+            headingOrdinal: request.headingOrdinal,
+        });
+    }
+    if (request.mode === 'listOrdinal') {
+        if (index.lookup.byListOrdinal.size === 0) {
+            return failure('TARGET_MODE_UNAVAILABLE', 'List ordinal resolution is unavailable: index has no API list ordinals.', {
+                listCount: index.lists.length,
+            });
+        }
+        const candidates = index.lookup.byListOrdinal.get(request.listOrdinal) ?? [];
+        return resolveUnique(request, candidates, { listOrdinal: request.listOrdinal });
+    }
+    if (index.lookup.byTableOrdinal.size === 0) {
+        return failure('TARGET_MODE_UNAVAILABLE', 'Table ordinal resolution is unavailable: index has no tables.', {
+            tableCount: index.tables.length,
+        });
+    }
+    const table = index.lookup.byTableOrdinal.get(request.tableOrdinal);
+    return resolveUnique(request, table == null ? [] : [table], { tableOrdinal: request.tableOrdinal });
+}
+export function resolveWorkflowTargetFromUnknown(index, rawTarget) {
+    if (rawTarget == null) {
+        return failure('TARGET_REQUIRED', 'No target value was provided.');
+    }
+    const parsed = parseWorkflowTargetRequest(rawTarget);
+    if (isResolveFailure(parsed)) {
+        return parsed;
+    }
+    return resolveWorkflowTarget(index, parsed);
+}

package/dist/action-primitives/session-cache.cjs

@@ -0,0 +1,43 @@
+'use strict';
+
+class WorkflowSessionCache {
+    states = new WeakMap();
+    nextId = 1;
+    getState(documentHandle) {
+        const cached = this.states.get(documentHandle);
+        if (cached != null) {
+            return cached;
+        }
+        const now = Date.now();
+        const created = {
+            documentKey: `workflow-doc-${this.nextId++}`,
+            createdAtMs: now,
+            updatedAtMs: now,
+            indexesByRevision: new Map(),
+        };
+        this.states.set(documentHandle, created);
+        return created;
+    }
+    getCachedIndex(documentHandle, revision) {
+        const state = this.getState(documentHandle);
+        if (revision == null) {
+            return state.latestIndex;
+        }
+        return state.indexesByRevision.get(revision);
+    }
+    setCachedIndex(documentHandle, index) {
+        const state = this.getState(documentHandle);
+        state.indexesByRevision.set(index.revision, index);
+        state.latestIndex = index;
+        state.updatedAtMs = Date.now();
+        return state;
+    }
+}
+function createWorkflowSessionCache() {
+    return new WorkflowSessionCache();
+}
+const workflowPocSessionCache = createWorkflowSessionCache();
+
+exports.WorkflowSessionCache = WorkflowSessionCache;
+exports.createWorkflowSessionCache = createWorkflowSessionCache;
+exports.workflowPocSessionCache = workflowPocSessionCache;

package/dist/action-primitives/session-cache.d.ts

@@ -0,0 +1,19 @@
+import type { BoundDocApi } from '../generated/client.js';
+import type { WorkflowDocIndex } from './doc-index.js';
+export type WorkflowSessionState = {
+    documentKey: string;
+    createdAtMs: number;
+    updatedAtMs: number;
+    latestIndex?: WorkflowDocIndex;
+    indexesByRevision: Map<string, WorkflowDocIndex>;
+};
+export declare class WorkflowSessionCache {
+    private readonly states;
+    private nextId;
+    getState(documentHandle: BoundDocApi): WorkflowSessionState;
+    getCachedIndex(documentHandle: BoundDocApi, revision?: string): WorkflowDocIndex | undefined;
+    setCachedIndex(documentHandle: BoundDocApi, index: WorkflowDocIndex): WorkflowSessionState;
+}
+export declare function createWorkflowSessionCache(): WorkflowSessionCache;
+export declare const workflowPocSessionCache: WorkflowSessionCache;
+//# sourceMappingURL=session-cache.d.ts.map

package/dist/action-primitives/session-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-cache.d.ts","sourceRoot":"","sources":["../../src/action-primitives/session-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAClD,CAAC;AAEF,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoD;IAC3E,OAAO,CAAC,MAAM,CAAK;IAEnB,QAAQ,CAAC,cAAc,EAAE,WAAW,GAAG,oBAAoB;IAiB3D,cAAc,CAAC,cAAc,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAQ5F,cAAc,CAAC,cAAc,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,GAAG,oBAAoB;CAO3F;AAED,wBAAgB,0BAA0B,IAAI,oBAAoB,CAEjE;AAED,eAAO,MAAM,uBAAuB,sBAA+B,CAAC"}

package/dist/action-primitives/session-cache.js

@@ -0,0 +1,37 @@
+export class WorkflowSessionCache {
+    states = new WeakMap();
+    nextId = 1;
+    getState(documentHandle) {
+        const cached = this.states.get(documentHandle);
+        if (cached != null) {
+            return cached;
+        }
+        const now = Date.now();
+        const created = {
+            documentKey: `workflow-doc-${this.nextId++}`,
+            createdAtMs: now,
+            updatedAtMs: now,
+            indexesByRevision: new Map(),
+        };
+        this.states.set(documentHandle, created);
+        return created;
+    }
+    getCachedIndex(documentHandle, revision) {
+        const state = this.getState(documentHandle);
+        if (revision == null) {
+            return state.latestIndex;
+        }
+        return state.indexesByRevision.get(revision);
+    }
+    setCachedIndex(documentHandle, index) {
+        const state = this.getState(documentHandle);
+        state.indexesByRevision.set(index.revision, index);
+        state.latestIndex = index;
+        state.updatedAtMs = Date.now();
+        return state;
+    }
+}
+export function createWorkflowSessionCache() {
+    return new WorkflowSessionCache();
+}
+export const workflowPocSessionCache = createWorkflowSessionCache();