@toolproof-core/lib 1.0.36 → 1.0.37

package/src/utils/stepParallelization.ts

@@ -0,0 +1,181 @@
+import type {
+	MutableBranchStep,
+	MutableForStep,
+	MutableStep,
+	MutableStrategyState,
+	MutableToolStep,
+	MutableToolStepKey,
+	MutableWhileStep,
+} from './mutableStrategyOverlay.js';
+import { CONSTANTS } from '../lookups/lookups.js';
+
+export function getIndependentThreads<
+	TKey extends string = MutableToolStepKey,
+	TStep extends MutableStep<TKey> = MutableStep<TKey>,
+>(
+	steps: TStep[],
+	strategyState: MutableStrategyState<TKey>,
+): TStep[][] {
+	type OwnerIndex = number;
+
+	const getOwnerLabel = (ownerIndex: OwnerIndex) => {
+		const step = steps[ownerIndex];
+		return `steps[${ownerIndex}] stepKind=${step?.stepKind ?? 'unknown'}`;
+	};
+
+	const toolStepKeyToOwner = new Map<TKey, OwnerIndex>();
+	const toolStepByKey = new Map<TKey, MutableToolStep<TKey>>();
+
+	const addToolStep = (
+		toolStep: MutableToolStep<TKey> | undefined,
+		ownerIndex: OwnerIndex,
+	) => {
+		if (!toolStep) return;
+
+		const existingOwner = toolStepKeyToOwner.get(toolStep.toolStepKey);
+		if (existingOwner !== undefined) {
+			throw new Error(
+				`Duplicate toolStepKey '${toolStep.toolStepKey}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`
+			);
+		}
+
+		toolStepKeyToOwner.set(toolStep.toolStepKey, ownerIndex);
+		toolStepByKey.set(toolStep.toolStepKey, toolStep);
+	};
+
+	steps.forEach((step, ownerIndex) => {
+		if (step.stepKind === CONSTANTS.Enums.StepKind.tool) {
+			addToolStep(step as MutableToolStep<TKey>, ownerIndex);
+			return;
+		}
+
+		if (step.stepKind === CONSTANTS.Enums.StepKind.for) {
+			const loop = step as MutableForStep<TKey>;
+			addToolStep(loop.case?.what, ownerIndex);
+			addToolStep(loop.case?.when, ownerIndex);
+			return;
+		}
+
+		if (step.stepKind === CONSTANTS.Enums.StepKind.while) {
+			const loop = step as MutableWhileStep<TKey>;
+			addToolStep(loop.case?.what, ownerIndex);
+			addToolStep(loop.case?.when, ownerIndex);
+			return;
+		}
+
+		if (step.stepKind === CONSTANTS.Enums.StepKind.branch) {
+			const branch = step as MutableBranchStep<TKey>;
+			for (const stepCase of branch.cases) {
+				addToolStep(stepCase?.what, ownerIndex);
+				addToolStep(stepCase?.when, ownerIndex);
+			}
+		}
+	});
+
+	const ownerAdj = new Map<OwnerIndex, Set<OwnerIndex>>();
+	const ownerDeps = new Map<OwnerIndex, Set<OwnerIndex>>();
+
+	const ensureOwner = (ownerIndex: OwnerIndex) => {
+		if (!ownerAdj.has(ownerIndex)) ownerAdj.set(ownerIndex, new Set());
+		if (!ownerDeps.has(ownerIndex)) ownerDeps.set(ownerIndex, new Set());
+	};
+
+	for (let index = 0; index < steps.length; index++) {
+		ensureOwner(index);
+	}
+
+	for (const [toolStepKey, ownerIndex] of toolStepKeyToOwner) {
+		ensureOwner(ownerIndex);
+
+		const toolStep = toolStepByKey.get(toolStepKey);
+		const inputBindings = toolStep?.roleBindingSpec?.inputBindings ?? [];
+		const bucket = strategyState[toolStepKey];
+
+		for (const inputRoleId of inputBindings) {
+			const entry = bucket?.[inputRoleId];
+			if (!entry || entry.strategyStateInputKind !== 'internalInputPotential') continue;
+
+			const producerToolStepKey = entry.toolStepRoleAddress?.toolStepKey;
+			if (typeof producerToolStepKey !== 'string') {
+				throw new Error(
+					`Unresolvable internalInputPotential in toolStep '${toolStepKey}' (${getOwnerLabel(ownerIndex)}): missing toolStepRoleAddress.toolStepKey for role '${inputRoleId}'`
+				);
+			}
+
+			const producerOwner = toolStepKeyToOwner.get(producerToolStepKey as TKey);
+			if (producerOwner === undefined) {
+				throw new Error(
+					`Unresolvable internalInputPotential in toolStep '${toolStepKey}' (${getOwnerLabel(ownerIndex)}): source toolStepKey '${producerToolStepKey}' not found in strategy steps`
+				);
+			}
+
+			ensureOwner(producerOwner);
+			ownerAdj.get(ownerIndex)?.add(producerOwner);
+			ownerAdj.get(producerOwner)?.add(ownerIndex);
+			ownerDeps.get(ownerIndex)?.add(producerOwner);
+		}
+	}
+
+	const visited = new Set<OwnerIndex>();
+	const components: OwnerIndex[][] = [];
+
+	for (let ownerIndex = 0; ownerIndex < steps.length; ownerIndex++) {
+		if (visited.has(ownerIndex)) continue;
+
+		const component: OwnerIndex[] = [];
+		const queue: OwnerIndex[] = [ownerIndex];
+		visited.add(ownerIndex);
+
+		while (queue.length > 0) {
+			const node = queue.shift();
+			if (node === undefined) break;
+			component.push(node);
+
+			for (const neighbor of ownerAdj.get(node) ?? []) {
+				if (visited.has(neighbor)) continue;
+				visited.add(neighbor);
+				queue.push(neighbor);
+			}
+		}
+
+		components.push(component);
+	}
+
+	for (const component of components) {
+		const componentOwners = new Set(component);
+		const ownersInOrder = steps.map((_, index) => index).filter((index) => componentOwners.has(index));
+		const position = new Map<OwnerIndex, number>();
+
+		ownersInOrder.forEach((owner, index) => position.set(owner, index));
+
+		for (const consumerOwner of ownersInOrder) {
+			const deps = ownerDeps.get(consumerOwner);
+			if (!deps || deps.size === 0) continue;
+
+			const consumerPos = position.get(consumerOwner);
+			if (consumerPos === undefined) continue;
+
+			for (const producerOwner of deps) {
+				const producerPos = position.get(producerOwner);
+				if (producerPos === undefined) {
+					throw new Error(
+						`Internal error: dependency producer ${getOwnerLabel(producerOwner)} missing from computed thread for ${getOwnerLabel(consumerOwner)}`
+					);
+				}
+
+				if (producerPos >= consumerPos) {
+					throw new Error(
+						`Invalid step order in thread: ${getOwnerLabel(consumerOwner)} depends on ${getOwnerLabel(producerOwner)}, but producer is not scheduled before consumer`
+					);
+				}
+			}
+		}
+	}
+
+	return components
+		.map((component) => {
+			const ownerSet = new Set(component);
+			return steps.filter((_step, index) => ownerSet.has(index));
+		})
+		.filter((group) => group.length > 0);
+}

package/src/utils/strategyAssembly.ts

@@ -0,0 +1,14 @@
+import type { Strategy } from '@toolproof-core/genesis';
+import type { MutableStrategy } from './mutableStrategyOverlay.js';
+import { toExecutionMutableStrategy } from './strategyThreading.js';
+import { mutableStrategyToStrategy } from './strategyCanonicalization.js';
+
+
+export function composeStrategyForExecution<TKey extends string>(
+    mutableStrategy: MutableStrategy<TKey>,
+): Strategy {
+    const executionStrategy =
+        toExecutionMutableStrategy(mutableStrategy);
+
+    return mutableStrategyToStrategy(executionStrategy);
+}

package/src/utils/strategyCanonicalization.ts

@@ -0,0 +1,294 @@
+import type {
+    BranchStep,
+    Case,
+    ExternalInputPotential,
+    ForStep,
+    InputResource,
+    InternalInputPotential,
+    RoleName,
+    Step,
+    Strategy,
+    StrategyStateInputEntry,
+    ToolStep,
+    ToolStepPath,
+    WhileStep,
+} from '@toolproof-core/genesis';
+import { CONSTANTS } from '../lookups/lookups.js';
+import type {
+    MutableBranchStep,
+    MutableCase,
+    MutableForStep,
+    MutableInternalInputPotential,
+    MutableStrategy,
+    MutableStep,
+    MutableStrategyStateInputEntry,
+    MutableToolStepKey,
+    MutableWhileStep,
+} from './mutableStrategyOverlay.js';
+import { generateIdentifier } from './identifierGeneration.js';
+
+function stripMutableCase(stepCase: MutableCase): Case {
+    const { when, what, ...rest } = stepCase;
+    const { toolStepKey: _whenToolStepKey, ...canonicalWhen } = when;
+    const { toolStepKey: _whatToolStepKey, ...canonicalWhat } = what;
+
+    return {
+        ...rest,
+        when: canonicalWhen,
+        what: canonicalWhat,
+    };
+}
+
+function buildExecutionPathMap(strategy: MutableStrategy): Map<MutableToolStepKey, ToolStepPath> {
+    const executionPathByKey = new Map<MutableToolStepKey, ToolStepPath>();
+
+    const registerStep = (step: MutableStep, pathPrefix: string) => {
+        switch (step.stepKind) {
+            case CONSTANTS.Enums.StepKind.tool:
+                executionPathByKey.set(step.toolStepKey, `${pathPrefix}/self` as ToolStepPath);
+                return;
+            case CONSTANTS.Enums.StepKind.branch:
+                step.cases.forEach((stepCase, caseIndex) => {
+                    executionPathByKey.set(stepCase.when.toolStepKey, `${pathPrefix}/cases/${caseIndex}/when` as ToolStepPath);
+                    executionPathByKey.set(stepCase.what.toolStepKey, `${pathPrefix}/cases/${caseIndex}/what` as ToolStepPath);
+                });
+                return;
+            case CONSTANTS.Enums.StepKind.while:
+            case CONSTANTS.Enums.StepKind.for:
+                executionPathByKey.set(step.case.when.toolStepKey, `${pathPrefix}/case/when` as ToolStepPath);
+                executionPathByKey.set(step.case.what.toolStepKey, `${pathPrefix}/case/what` as ToolStepPath);
+                return;
+            default:
+                throw new Error('Unsupported step kind while projecting strategy.');
+        }
+    };
+
+    strategy.stepsByThreadIndex.forEach((steps, threadIndex) => {
+        steps.forEach((step, stepIndex) => {
+            registerStep(step, `/threads/${threadIndex}/steps/${stepIndex}`);
+        });
+    });
+
+    return executionPathByKey;
+}
+
+function toCanonicalStrategyStateEntry(
+    entry: MutableStrategyStateInputEntry,
+    executionPathByKey: ReadonlyMap<MutableToolStepKey, ToolStepPath>,
+): StrategyStateInputEntry {
+    if (entry.strategyStateInputKind !== 'internalInputPotential') {
+        return entry as InputResource | ExternalInputPotential;
+    }
+
+    const sourceToolStepPath = executionPathByKey.get(entry.toolStepRoleAddress.toolStepKey);
+    if (!sourceToolStepPath) {
+        throw new Error(`Cannot project strategy state: no execution path found for toolStepKey '${entry.toolStepRoleAddress.toolStepKey}'.`);
+    }
+
+    return {
+        strategyStateInputKind: 'internalInputPotential',
+        toolStepRoleAddress: {
+            toolStepPath: sourceToolStepPath,
+            roleName: entry.toolStepRoleAddress.roleName,
+        },
+    } satisfies InternalInputPotential;
+}
+
+function toCanonicalStep(step: MutableStep): Step {
+    switch (step.stepKind) {
+        case CONSTANTS.Enums.StepKind.tool: {
+            const { toolStepKey: _toolStepKey, ...canonicalToolStep } = step;
+            return canonicalToolStep;
+        }
+        case CONSTANTS.Enums.StepKind.branch: {
+            const { macroStepKey: _macroStepKey, cases, ...rest } = step;
+            return {
+                ...rest,
+                cases: cases.map(stripMutableCase) as [Case, ...Case[]],
+            };
+        }
+        case CONSTANTS.Enums.StepKind.while:
+        case CONSTANTS.Enums.StepKind.for: {
+            const { macroStepKey: _macroStepKey, case: stepCase, ...rest } = step;
+            return {
+                ...rest,
+                case: stripMutableCase(stepCase),
+            };
+        }
+        default:
+            throw new Error('Unsupported step kind while projecting steps.');
+    }
+}
+
+function toMutableStrategyStateEntry(
+    entry: StrategyStateInputEntry,
+    executionKeyByPath: ReadonlyMap<ToolStepPath, MutableToolStepKey>,
+): MutableStrategyStateInputEntry {
+    if (entry.strategyStateInputKind !== 'internalInputPotential') {
+        return entry as InputResource | ExternalInputPotential;
+    }
+
+    const sourceToolStepKey = executionKeyByPath.get(entry.toolStepRoleAddress.toolStepPath);
+    if (!sourceToolStepKey) {
+        throw new Error(`Cannot deproject strategy state: no mutable key found for toolStepPath '${entry.toolStepRoleAddress.toolStepPath}'.`);
+    }
+
+    return {
+        strategyStateInputKind: 'internalInputPotential',
+        toolStepRoleAddress: {
+            toolStepKey: sourceToolStepKey,
+            roleName: entry.toolStepRoleAddress.roleName,
+        },
+    } satisfies MutableInternalInputPotential;
+}
+
+function toMutableToolStep(step: ToolStep) {
+    return {
+        ...step,
+        toolStepKey: generateIdentifier('ToolStepKey'),
+    };
+}
+
+function toMutableCase(stepCase: Case): MutableCase {
+    const { when, what, ...rest } = stepCase;
+
+    return {
+        ...rest,
+        when: toMutableToolStep(when),
+        what: toMutableToolStep(what),
+    };
+}
+
+function toMutableBranchStep(step: BranchStep): MutableBranchStep {
+    const { cases, ...rest } = step;
+
+    return {
+        ...rest,
+        macroStepKey: generateIdentifier('BranchStepKey'),
+        cases: cases.map(toMutableCase) as [MutableCase, ...MutableCase[]],
+    };
+}
+
+function toMutableWhileStep(step: WhileStep): MutableWhileStep {
+    const { case: stepCase, ...rest } = step;
+
+    return {
+        ...rest,
+        macroStepKey: generateIdentifier('WhileStepKey'),
+        case: toMutableCase(stepCase),
+    };
+}
+
+function toMutableForStep(step: ForStep): MutableForStep {
+    const { case: stepCase, ...rest } = step;
+
+    return {
+        ...rest,
+        macroStepKey: generateIdentifier('ForStepKey'),
+        case: toMutableCase(stepCase),
+    };
+}
+
+function toMutableStep(step: Step): MutableStep {
+    switch (step.stepKind) {
+        case CONSTANTS.Enums.StepKind.tool:
+            return toMutableToolStep(step);
+        case CONSTANTS.Enums.StepKind.branch:
+            return toMutableBranchStep(step);
+        case CONSTANTS.Enums.StepKind.while:
+            return toMutableWhileStep(step);
+        case CONSTANTS.Enums.StepKind.for:
+            return toMutableForStep(step);
+        default:
+            throw new Error('Unsupported step kind while deprojecting steps.');
+    }
+}
+
+function buildExecutionKeyMap(strategy: MutableStrategy): Map<ToolStepPath, MutableToolStepKey> {
+    const executionPathByKey = buildExecutionPathMap(strategy);
+    const executionKeyByPath = new Map<ToolStepPath, MutableToolStepKey>();
+
+    for (const [toolStepKey, toolStepPath] of executionPathByKey.entries()) {
+        executionKeyByPath.set(toolStepPath, toolStepKey);
+    }
+
+    return executionKeyByPath;
+}
+
+export function strategyToMutableStrategy(strategy: Strategy): MutableStrategy {
+    const stepsByThreadIndex = strategy.stepsByThreadIndex.map((steps) => steps.map(toMutableStep));
+
+    const seededMutableStrategy: MutableStrategy = {
+        ...strategy,
+        stepsByThreadIndex,
+        strategyState: {},
+    };
+
+    const executionKeyByPath = buildExecutionKeyMap(seededMutableStrategy);
+    const strategyState: MutableStrategy['strategyState'] = {};
+
+    for (const [toolStepPath, inputEntryByRoleName] of Object.entries(strategy.strategyState)) {
+        const toolStepKey = executionKeyByPath.get(toolStepPath as ToolStepPath);
+        if (!toolStepKey) {
+            throw new Error(`Cannot deproject strategy state: no mutable key found for toolStepPath '${toolStepPath}'.`);
+        }
+
+        strategyState[toolStepKey] = Object.fromEntries(
+            Object.entries(inputEntryByRoleName).map(([roleName, entry]) => {
+                if (entry === undefined) {
+                    throw new Error(
+                        `Cannot deproject strategy state: role '${roleName}' on toolStepPath '${toolStepPath}' is explicitly undefined.`
+                    );
+                }
+
+                return [
+                    roleName as RoleName,
+                    toMutableStrategyStateEntry(entry, executionKeyByPath),
+                ] as const;
+            })
+        );
+    }
+
+    return {
+        ...strategy,
+        stepsByThreadIndex,
+        strategyState,
+    };
+}
+
+export function mutableStrategyToStrategy(mutableStrategy: MutableStrategy): Strategy {
+    const executionPathByKey = buildExecutionPathMap(mutableStrategy);
+    const strategyState: Strategy['strategyState'] = {};
+
+    for (const [toolStepKey, inputEntryByRoleName] of Object.entries(mutableStrategy.strategyState)) {
+        if (!inputEntryByRoleName) {
+            continue;
+        }
+
+        const toolStepPath = executionPathByKey.get(toolStepKey);
+        if (!toolStepPath) {
+            throw new Error(`Cannot project strategy state: no execution path found for toolStepKey '${toolStepKey}'.`);
+        }
+
+        strategyState[toolStepPath] = Object.fromEntries(
+            Object.entries(inputEntryByRoleName).map(([roleName, entry]) => {
+                if (entry === undefined) {
+                    throw new Error(
+                        `Cannot project strategy state: role '${roleName}' on toolStepKey '${toolStepKey}' is explicitly undefined.`
+                    );
+                }
+
+                return [
+                    roleName,
+                    toCanonicalStrategyStateEntry(entry, executionPathByKey),
+                ] as const;
+            })
+        );
+    }
+
+    return {
+        ...mutableStrategy,
+        stepsByThreadIndex: mutableStrategy.stepsByThreadIndex.map((steps) => steps.map(toCanonicalStep)),
+        strategyState,
+    };
+}

package/src/utils/strategyExtraction.ts

@@ -0,0 +1,150 @@
+import type {
+    RoleName,
+    RoleSpec,
+    ToolHandle,
+    Tool,
+    ResourceTypeHandle,
+    RoleValue,
+} from '@toolproof-core/genesis';
+import type {
+    MutableStrategy,
+    MutableStep,
+    MutableToolStep
+} from './mutableStrategyOverlay.js';
+import { CONSTANTS } from '../lookups/lookups.js';
+
+export type RoleSpecEntry = [RoleName, RoleValue];
+
+type RoleSpecDirectionKeys = keyof Pick<
+    RoleSpec,
+    'inputRoleValueByName' | 'outputRoleValueByName'
+>;
+
+export type RoleSpecByDirection = {
+    [K in RoleSpecDirectionKeys]: Map<RoleName, RoleValue>;
+};
+
+export function getInputRoleSpecEntriesFromTool(tool: Tool): RoleSpecEntry[] {
+    return Object.entries(tool.roleSpec.inputRoleValueByName) as RoleSpecEntry[];
+}
+
+export function getOutputRoleSpecEntriesFromTool(tool: Tool): RoleSpecEntry[] {
+    return Object.entries(tool.roleSpec.outputRoleValueByName) as RoleSpecEntry[];
+}
+
+export function getInputRoleNamesFromTool(tool: Tool): RoleName[] {
+    return getInputRoleSpecEntriesFromTool(tool).map(([roleName]) => roleName);
+}
+
+export function getOutputRoleNamesFromTool(tool: Tool): RoleName[] {
+    return getOutputRoleSpecEntriesFromTool(tool).map(([roleName]) => roleName);
+}
+
+export function extractResourceTypeHandleFromRoleValue(
+    roleValue: RoleValue,
+): ResourceTypeHandle | null {
+    const typeRef = roleValue.typeRef;
+
+    if ('resourceTypeHandle' in typeRef) {
+        return typeRef.resourceTypeHandle;
+    }
+
+    return null;
+}
+
+export function extractToolStepsFromStrategy(strategy: MutableStrategy): MutableToolStep[] {
+    const toolSteps: MutableToolStep[] = [];
+
+    const visitStep = (step: MutableStep) => {
+        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;
+            }
+        }
+    };
+
+    for (const threadSteps of strategy.stepsByThreadIndex) {
+        for (const step of threadSteps) {
+            visitStep(step);
+        }
+    }
+
+    return toolSteps;
+}
+
+export function extractToolsFromStrategy(
+    strategy: MutableStrategy,
+    toolMap: Map<ToolHandle, Tool>,
+): Tool[] {
+    const toolSteps = extractToolStepsFromStrategy(strategy);
+    const toolHandles = new Set<ToolHandle>();
+    const tools: Tool[] = [];
+
+    for (const toolStep of toolSteps) {
+        toolHandles.add(toolStep.toolHandle);
+    }
+    for (const toolHandle of toolHandles) {
+        const tool = toolMap.get(toolHandle);
+        if (!tool) {
+            throw new Error(`Tool with handle '${toolHandle}' not found in toolMap.`);
+        }
+        tools.push(tool);
+    }
+
+    return tools;
+}
+
+function extractRoleSpecByDirectionFromTool(tool: Tool): RoleSpecByDirection {
+    return {
+        inputRoleValueByName: new Map(getInputRoleSpecEntriesFromTool(tool)),
+        outputRoleValueByName: new Map(getOutputRoleSpecEntriesFromTool(tool)),
+    };
+}
+
+export function extractRoleSpecByDirectionByToolHandleFromStrategy(
+    strategy: MutableStrategy,
+    toolMap: Map<ToolHandle, Tool>,
+): Map<ToolHandle, RoleSpecByDirection> {
+    const roleSpecByDirectionByToolHandle = new Map<ToolHandle, RoleSpecByDirection>();
+
+    for (const tool of extractToolsFromStrategy(strategy, toolMap)) {
+        roleSpecByDirectionByToolHandle.set(
+            tool.handle,
+            extractRoleSpecByDirectionFromTool(tool),
+        );
+    }
+
+    return roleSpecByDirectionByToolHandle;
+}
+
+export function extractSingleBranchableOutputResourceTypeHandle(
+    tool: Tool,
+): ResourceTypeHandle | null {
+    const outputRoleSpecEntries = getOutputRoleSpecEntriesFromTool(tool).filter(
+        ([roleName]) => roleName !== CONSTANTS.Cosmos.ErrorOutputRoleName,
+    );
+
+    if (!outputRoleSpecEntries[0] || outputRoleSpecEntries.length !== 1) {
+        throw new Error(
+            `Tool ${tool.handle} must have exactly one branchable output resource type to be branchable/loopable`,
+        );
+    }
+
+    return extractResourceTypeHandleFromRoleValue(outputRoleSpecEntries[0][1]);
+}

package/src/utils/strategyStateResolution.ts

@@ -0,0 +1,57 @@
+import type {
+	MutableInputResource,
+	MutableExternalInputPotential,
+	MutableInternalInputPotential,
+	MutableStrategyState,
+	MutableStrategyStateInputEntry,
+	MutableToolStepKey,
+	MutableToolStepRoleAddress,
+} from './mutableStrategyOverlay.js';
+import { getStrategyStateInputEntry } from './mutableStrategyOverlay.js';
+
+export type ResolveResult<TKey extends string = MutableToolStepKey> =
+	| { status: 'inputResource'; entry: MutableInputResource; path: MutableToolStepRoleAddress<TKey>[] }
+	| { status: 'externalInputPotential'; entry: MutableExternalInputPotential; path: MutableToolStepRoleAddress<TKey>[] }
+	| {
+		status: 'unresolved';
+		reason: 'not-found' | 'cycle' | 'depth-exceeded';
+		path: MutableToolStepRoleAddress<TKey>[];
+	};
+
+export function resolveStrategyStateChain<TKey extends string, TStrategyState extends MutableStrategyState<TKey>>(
+	strategyState: TStrategyState,
+	start: MutableToolStepRoleAddress<TKey>,
+	opts?: { maxDepth?: number },
+): ResolveResult<TKey> {
+	const maxDepth = opts?.maxDepth ?? 50;
+	const visited = new Set<string>();
+	const path: MutableToolStepRoleAddress<TKey>[] = [];
+	let current: MutableToolStepRoleAddress<TKey> = start;
+
+	for (let depth = 0; depth <= maxDepth; depth++) {
+		path.push(current);
+
+		const visitKey = `${current.toolStepKey}::${current.roleName}`;
+		if (visited.has(visitKey)) {
+			return { status: 'unresolved', reason: 'cycle', path };
+		}
+		visited.add(visitKey);
+
+		const entry = getStrategyStateInputEntry(strategyState, current) as MutableStrategyStateInputEntry<TKey> | undefined;
+		if (!entry) {
+			return { status: 'unresolved', reason: 'not-found', path };
+		}
+
+		if (entry.strategyStateInputKind === 'inputResource') {
+			return { status: 'inputResource', entry, path };
+		}
+
+		if (entry.strategyStateInputKind === 'externalInputPotential') {
+			return { status: 'externalInputPotential', entry, path };
+		}
+
+		current = (entry as MutableInternalInputPotential<TKey>).toolStepRoleAddress;
+	}
+
+	return { status: 'unresolved', reason: 'depth-exceeded', path };
+}