@toolproof-core/lib 1.0.32 → 1.0.34

package/src/utils/extractData.ts

@@ -1,21 +1,26 @@
 import type {
-    RawStrategy,
+    RoleName,
+    RoleValue,
     ToolId,
     Tool,
-    ToolStepId,
     ToolStep,
-    Step,
-    ResourceRoleId,
-    ResourceRole,
     ResourceId,
     ResourceTypeId,
     Resource,
 } from '@toolproof-core/schema';
 import { CONSTANTS } from '../artifacts/artifacts.js';
-
-
-export function extractToolIdsFromRawStrategy(rawStrategy: RawStrategy): ToolId[] {
-    const toolSteps = extractToolStepsFromRawStrategy(rawStrategy);
+import {
+    extractToolStepsFromStrategy,
+    getInputRoleEntries,
+    getOutputRoleEntries,
+    toToolRoleDescriptor,
+    type StrategyStepGraph,
+    type ToolRoleDescriptor,
+} from './roleSpec.js';
+
+
+export function extractToolIdsFromUnthreadedStrategy(unthreadedStrategy: StrategyStepGraph): ToolId[] {
+    const toolSteps = extractToolStepsFromUnthreadedStrategy(unthreadedStrategy);
     const ids = new Set<ToolId>();
     for (const jStep of toolSteps) {
         ids.add(jStep.toolId);
@@ -23,71 +28,24 @@ export function extractToolIdsFromRawStrategy(rawStrategy: RawStrategy): ToolId[
     return Array.from(ids);
 }
 
-export function extractToolStepsFromRawStrategy(rawStrategy: RawStrategy): ToolStep[] {
-    const toolSteps: ToolStep[] = [];
-    const seen = new Set<ToolStepId>();
-
-    const addToolStep = (toolStep: ToolStep) => {
-        if (seen.has(toolStep.id)) {
-            throw new Error(`Duplicate tool step id encountered: ${toolStep.id}`);
-        }
-        seen.add(toolStep.id);
-        toolSteps.push(toolStep);
-    };
-
-    const visitStep = (step: Step) => {
-        switch (step.stepKind) {
-            case CONSTANTS.Enums.StepKind.tool: {
-                addToolStep(step);
-                return;
-            }
-            case CONSTANTS.Enums.StepKind.branch: {
-                for (const conditional of step.cases) {
-                    addToolStep(conditional.when);
-                    addToolStep(conditional.what);
-                }
-                return;
-            }
-            case CONSTANTS.Enums.StepKind.while:
-            case CONSTANTS.Enums.StepKind.for: {
-                addToolStep(step.case.when);
-                addToolStep(step.case.what);
-                return;
-            }
-            default: {
-                const _exhaustive: never = step;
-                return _exhaustive;
-            }
-        }
-    };
-
-    for (const step of rawStrategy.steps) {
-        visitStep(step);
-    }
-
-    return toolSteps;
+export function extractToolStepsFromUnthreadedStrategy(unthreadedStrategy: StrategyStepGraph): ToolStep[] {
+    return extractToolStepsFromStrategy(unthreadedStrategy);
 }
 
 
-export function extractRoleMapFromRawStrategy(rawStrategy: RawStrategy, toolMap: Map<ToolId, Tool>): Map<ResourceRoleId, ResourceRole> {
-    const roleMap = new Map<ResourceRoleId, ResourceRole>();
-    const toolIds = extractToolIdsFromRawStrategy(rawStrategy);
+export function extractRoleMapFromUnthreadedStrategy(unthreadedStrategy: StrategyStepGraph, toolMap: Map<ToolId, Tool>): Map<RoleName, ToolRoleDescriptor> {
+    const roleMap = new Map<RoleName, ToolRoleDescriptor>();
+    const toolIds = extractToolIdsFromUnthreadedStrategy(unthreadedStrategy);
 
     for (const toolId of toolIds) {
         const tool = toolMap.get(toolId);
         if (!tool) continue;
 
-        for (const [rid, role] of Object.entries(tool.roleSpec.inputRoleValueById)) {
-            roleMap.set(rid as ResourceRoleId, {
-                id: rid as ResourceRoleId,
-                ...role,
-            });
+        for (const entry of getInputRoleEntries(tool)) {
+            roleMap.set(entry[0], toToolRoleDescriptor(entry));
         }
-        for (const [rid, role] of Object.entries(tool.roleSpec.outputRoleValueById)) {
-            roleMap.set(rid as ResourceRoleId, {
-                id: rid as ResourceRoleId,
-                ...role,
-            });
+        for (const entry of getOutputRoleEntries(tool)) {
+            roleMap.set(entry[0], toToolRoleDescriptor(entry));
         }
     }
 
@@ -96,11 +54,11 @@ export function extractRoleMapFromRawStrategy(rawStrategy: RawStrategy, toolMap:
 
 export function extractSingleNonErrorOutputTypeId(tool: Tool): ResourceTypeId | null {
     const errorRoleId = CONSTANTS.Cosmos.ROLE_ErrorOutput;
-    const outputEntries = Object.entries(tool.roleSpec.outputRoleValueById).filter(([roleId]) => roleId !== errorRoleId);
+    const outputEntries = getOutputRoleEntries(tool).filter(([roleName]) => roleName !== errorRoleId);
     if (!outputEntries || !outputEntries[0] || outputEntries.length !== 1) {
         throw new Error(`Tool ${tool.id} must have exactly one non-error output role to be branchable/loopable`);
     } // ATTENTION_PUREIFY
-    const outputRole = outputEntries[0][1];
+    const outputRole = outputEntries[0][1] as RoleValue;
     return outputRole.resourceTypeId;
 }
 

package/src/utils/parallelizeSteps.ts

@@ -1,14 +1,20 @@
 import type {
     BranchStep,
     ForStep,
-    ToolStepId,
     ToolStep,
-    ResourceRoleId,
     Step,
-    StrategyState,
     WhileStep,
 } from '@toolproof-core/schema';
 import { CONSTANTS } from '../artifacts/artifacts.js';
+import type { StrategyState } from './strategyState.js';
+
+type ToolStepId = string;
+type ToolStepWithId = ToolStep & { id: ToolStepId };
+
+function getToolStepId(toolStep: ToolStep | undefined): ToolStepId | undefined {
+    const maybeId = (toolStep as Partial<ToolStepWithId> | undefined)?.id;
+    return typeof maybeId === 'string' ? maybeId : undefined;
+}
 
 
 export function getIndependentThreads(steps: Step[], strategyState: StrategyState): Step[][] {
@@ -22,22 +28,23 @@ export function getIndependentThreads(steps: Step[], strategyState: StrategyStat
     // Map each toolStep.id (including macro-nested tool steps) to owning top-level step index.
     const toolStepIdToOwner = new Map<ToolStepId, OwnerIndex>();
     const ownerToToolStepIds = new Map<OwnerIndex, ToolStepId[]>();
-    const toolStepById = new Map<ToolStepId, ToolStep>();
+    const toolStepById = new Map<ToolStepId, ToolStepWithId>();
 
     const addToolStep = (toolStep: ToolStep | undefined, ownerIndex: OwnerIndex) => {
-        if (!toolStep?.id) return;
+        const toolStepId = getToolStepId(toolStep);
+        if (!toolStepId || !toolStep) return;
 
-        const existingOwner = toolStepIdToOwner.get(toolStep.id);
+        const existingOwner = toolStepIdToOwner.get(toolStepId);
         if (existingOwner !== undefined) {
             throw new Error(
-                `Duplicate toolStep.id '${toolStep.id}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`
+                `Duplicate toolStep.id '${toolStepId}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`
             );
         }
 
-        toolStepIdToOwner.set(toolStep.id, ownerIndex);
-        toolStepById.set(toolStep.id, toolStep);
+        toolStepIdToOwner.set(toolStepId, ownerIndex);
+        toolStepById.set(toolStepId, toolStep as ToolStepWithId);
         const bucket = ownerToToolStepIds.get(ownerIndex) ?? [];
-        bucket.push(toolStep.id);
+        bucket.push(toolStepId);
         ownerToToolStepIds.set(ownerIndex, bucket);
     };
 
@@ -94,20 +101,22 @@ export function getIndependentThreads(steps: Step[], strategyState: StrategyStat
         const bucket = strategyState?.[toolStepId] ?? ({} as any);
 
         for (const inputRoleId of inputBindings) {
-            const entry = bucket?.[inputRoleId as ResourceRoleId] as any;
-            if (!entry || entry.resourceShellKind !== 'internalInputPotential') continue;
+            const entry = bucket?.[inputRoleId] as any;
+            if (!entry || entry.strategyStateInputKind !== 'referenceInput') continue;
 
-            const creatorToolStepId = entry?.creationContext?.toolStepId as ToolStepId | undefined;
+            const creatorToolStepId = typeof entry?.toolStepPath === 'string'
+                ? entry.toolStepPath as ToolStepId
+                : undefined;
             if (!creatorToolStepId) {
                 throw new Error(
-                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): missing creationContext.toolStepId for role '${inputRoleId}'`
+                    `Unresolvable referenceInput in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): missing toolStepPath for role '${inputRoleId}'`
                 );
             }
 
             const producerOwner = toolStepIdToOwner.get(creatorToolStepId);
             if (producerOwner === undefined) {
                 throw new Error(
-                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): creator toolStepId '${creatorToolStepId}' not found in strategy steps`
+                    `Unresolvable referenceInput in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): creator toolStepPath '${creatorToolStepId}' not found in strategy steps`
                 );
             }
 

package/src/utils/resolveResourceChain.ts

@@ -1,18 +1,15 @@
 import type {
     CreationContext,
-    ExternalInputPotentialShell,
-    InternalInputPotentialShell,
-    OutputPotentialShell,
-    Resource,
-    ResourcePotential,
-    StrategyState,
+    ExternalInput,
+    ReferenceInput,
+    StrategyStateInputEntry,
+    ValueInput,
 } from '@toolproof-core/schema';
-import { CONSTANTS } from '../artifacts/artifacts.js';
+import { getStrategyStateEntry, type StrategyState } from './strategyState.js';
 
 export type ResolveResult =
-    | { status: typeof CONSTANTS.Enums.ResourceShellKind.materialized; entry: Resource; path: CreationContext[] }
-    | { status: typeof CONSTANTS.Enums.ResourceShellKind.externalInputPotential; entry: ExternalInputPotentialShell; path: CreationContext[] }
-    | { status: typeof CONSTANTS.Enums.ResourceShellKind.outputPotential; entry: OutputPotentialShell; path: CreationContext[] }
+    | { status: 'valueInput'; entry: ValueInput; path: CreationContext[] }
+    | { status: 'externalInput'; entry: ExternalInput; path: CreationContext[] }
     | { status: 'unresolved'; reason: 'not-found' | 'cycle' | 'depth-exceeded'; path: CreationContext[] };
 
 export function resolveResourceChain(
@@ -27,39 +24,28 @@ export function resolveResourceChain(
 
     for (let depth = 0; depth <= maxDepth; depth++) {
         path.push(current);
-        const visitKey = `${current.toolStepId}::${current.resourceRoleId}`;
+        const visitKey = `${current.toolStepPath}::${current.roleName}`;
         if (visited.has(visitKey)) {
             return { status: 'unresolved', reason: 'cycle', path };
         }
         visited.add(visitKey);
 
-        const bucket = strategyState[current.toolStepId];
-        if (!bucket) return { status: 'unresolved', reason: 'not-found', path };
-        const entry = bucket[current.resourceRoleId] as (
-            | Resource
-            | ResourcePotential
-            | undefined
-        );
+        const entry = getStrategyStateEntry(strategyState, current) as StrategyStateInputEntry | undefined;
         if (!entry) return { status: 'unresolved', reason: 'not-found', path };
 
-        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.materialized) {
-            return { status: CONSTANTS.Enums.ResourceShellKind.materialized, entry: entry as Resource, path };
+        if (entry.strategyStateInputKind === 'valueInput') {
+            return { status: 'valueInput', entry: entry, path };
         }
-        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.externalInputPotential) {
-            return { status: CONSTANTS.Enums.ResourceShellKind.externalInputPotential, entry: entry as ExternalInputPotentialShell, path };
-        }
-        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.outputPotential) {
-            return { status: CONSTANTS.Enums.ResourceShellKind.outputPotential, entry: entry as OutputPotentialShell, path };
+        if (entry.strategyStateInputKind === 'externalInput') {
+            return { status: 'externalInput', entry: entry, path };
         }
 
-        // internalInputPotential: follow ref backwards
-        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.internalInputPotential) {
-            current = (entry as InternalInputPotentialShell).creationContext;
-            continue;
-        }
+        current = {
+            toolStepPath: (entry as ReferenceInput).toolStepPath,
+            roleName: (entry as ReferenceInput).roleName,
+        };
+        continue;
 
-        // Unknown case
-        return { status: 'unresolved', reason: 'not-found', path };
     }
 
     return { status: 'unresolved', reason: 'depth-exceeded', path };

package/src/utils/roleSpec.ts

@@ -0,0 +1,84 @@
+import type {
+    RoleName,
+    RoleValue,
+    Step,
+    StepArrayArray,
+    Tool,
+    ToolStep,
+} from '@toolproof-core/schema';
+
+export type StrategyStepGraph =
+    | { steps: Step[] }
+    | { stepsByThreadIndex: StepArrayArray };
+
+export interface ToolRoleDescriptor extends RoleValue {
+    id: RoleName;
+    name: string;
+}
+
+export function getInputRoleEntries(tool: Tool): Array<[RoleName, RoleValue]> {
+    return Object.entries(tool.roleSpec.inputRoleValueByName) as Array<[RoleName, RoleValue]>;
+}
+
+export function getOutputRoleEntries(tool: Tool): Array<[RoleName, RoleValue]> {
+    return Object.entries(tool.roleSpec.outputRoleValueByName) as Array<[RoleName, RoleValue]>;
+}
+
+export function getInputRoleNames(tool: Tool): RoleName[] {
+    return getInputRoleEntries(tool).map(([roleName]) => roleName);
+}
+
+export function getOutputRoleNames(tool: Tool): RoleName[] {
+    return getOutputRoleEntries(tool).map(([roleName]) => roleName);
+}
+
+export function toToolRoleDescriptor([roleName, roleValue]: [RoleName, RoleValue]): ToolRoleDescriptor {
+    return {
+        id: roleName,
+        name: roleName,
+        ...roleValue,
+    };
+}
+
+export function extractToolStepsFromStrategy(strategy: StrategyStepGraph): ToolStep[] {
+    const toolSteps: ToolStep[] = [];
+
+    const visitStep = (step: Step) => {
+        switch (step.stepKind) {
+            case 'tool': {
+                toolSteps.push(step);
+                return;
+            }
+            case 'branch': {
+                for (const conditional of step.cases) {
+                    toolSteps.push(conditional.when, conditional.what);
+                }
+                return;
+            }
+            case 'while':
+            case 'for': {
+                toolSteps.push(step.case.when, step.case.what);
+                return;
+            }
+            default: {
+                const _exhaustive: never = step;
+                return _exhaustive;
+            }
+        }
+    };
+
+    if ('steps' in strategy) {
+        for (const step of strategy.steps) {
+            visitStep(step);
+        }
+        return toolSteps;
+    }
+
+    for (const threadSteps of strategy.stepsByThreadIndex) {
+        for (const step of threadSteps) {
+            visitStep(step);
+        }
+    }
+
+    return toolSteps;
+}

package/src/utils/strategyState.ts

@@ -0,0 +1,57 @@
+import type {
+    CreationContext,
+    Strategy,
+    StrategyStateInputEntry,
+    StrategyStateInputEntryByRoleName,
+} from '@toolproof-core/schema';
+
+export type StrategyState = Strategy['strategyState'];
+export type StrategyStateLike = Record<string, Record<string, unknown>>;
+
+export function getStrategyStateBucket(
+    strategyState: StrategyStateLike,
+    toolStepPath: CreationContext['toolStepPath'],
+): StrategyStateInputEntryByRoleName | undefined {
+    return strategyState[toolStepPath] as StrategyStateInputEntryByRoleName | undefined;
+}
+
+export function getStrategyStateEntry(
+    strategyState: StrategyStateLike,
+    context: CreationContext,
+): StrategyStateInputEntry | undefined {
+    return getStrategyStateBucket(strategyState, context.toolStepPath)?.[context.roleName];
+}
+
+export function setStrategyStateEntry<TStrategyState extends StrategyStateLike>(
+    strategyState: TStrategyState,
+    context: CreationContext,
+    entry: StrategyStateInputEntry,
+): TStrategyState {
+    const bucket = getStrategyStateBucket(strategyState, context.toolStepPath) ?? {};
+
+    return {
+        ...strategyState,
+        [context.toolStepPath]: {
+            ...bucket,
+            [context.roleName]: entry,
+        },
+    } as TStrategyState;
+}
+
+export function clearStrategyStateEntry<TStrategyState extends StrategyStateLike>(
+    strategyState: TStrategyState,
+    context: CreationContext,
+): TStrategyState {
+    const bucket = getStrategyStateBucket(strategyState, context.toolStepPath);
+    if (!bucket || !(context.roleName in bucket)) {
+        return strategyState;
+    }
+
+    const nextBucket = { ...bucket };
+    delete nextBucket[context.roleName];
+
+    return {
+        ...strategyState,
+        [context.toolStepPath]: nextBucket,
+    } as TStrategyState;
+}