@toolproof-core/lib 1.0.34 → 1.0.37

package/dist/utils/mutableStrategyOverlay.js

@@ -0,0 +1,115 @@
+import { extractResourceTypeHandleFromRoleValue } from './strategyExtraction.js';
+export function getAuthoringSteps(strategy) {
+    return strategy.stepsByThreadIndex[0] ?? [];
+}
+export function setAuthoringSteps(strategy, steps) {
+    const nextStepsByThreadIndex = [...strategy.stepsByThreadIndex];
+    nextStepsByThreadIndex[0] = steps;
+    return {
+        ...strategy,
+        stepsByThreadIndex: nextStepsByThreadIndex,
+    };
+}
+export function getStrategyStateInputEntryByRoleName(strategyState, toolStepKey) {
+    return strategyState[toolStepKey];
+}
+export function getStrategyStateInputEntry(strategyState, toolStepRoleAddress) {
+    const inputEntryByRoleName = getStrategyStateInputEntryByRoleName(strategyState, toolStepRoleAddress.toolStepKey);
+    return inputEntryByRoleName?.[toolStepRoleAddress.roleName];
+}
+export function setStrategyStateInputEntry(strategyState, toolStepRoleAddress, entry) {
+    const inputEntryByRoleName = getStrategyStateInputEntryByRoleName(strategyState, toolStepRoleAddress.toolStepKey) ?? {};
+    return {
+        ...strategyState,
+        [toolStepRoleAddress.toolStepKey]: {
+            ...inputEntryByRoleName,
+            [toolStepRoleAddress.roleName]: entry,
+        },
+    };
+}
+export function clearInputBinding(strategyState, toolStepRoleAddress) {
+    const inputEntryByRoleName = getStrategyStateInputEntryByRoleName(strategyState, toolStepRoleAddress.toolStepKey);
+    if (!inputEntryByRoleName || !(toolStepRoleAddress.roleName in inputEntryByRoleName)) {
+        return strategyState;
+    }
+    const nextInputEntryByRoleName = { ...inputEntryByRoleName };
+    delete nextInputEntryByRoleName[toolStepRoleAddress.roleName];
+    if (Object.keys(nextInputEntryByRoleName).length === 0) {
+        const nextStrategyState = { ...strategyState };
+        delete nextStrategyState[toolStepRoleAddress.toolStepKey];
+        return nextStrategyState;
+    }
+    return {
+        ...strategyState,
+        [toolStepRoleAddress.toolStepKey]: nextInputEntryByRoleName,
+    };
+}
+export function bindInputResource(strategyState, target, resource) {
+    const mutableInputResource = {
+        ...resource,
+        strategyStateInputKind: 'inputResource',
+    };
+    return setStrategyStateInputEntry(strategyState, target, mutableInputResource);
+}
+function getInputRoleValue(tool, roleName) {
+    return tool.roleSpec.inputRoleValueByName[roleName];
+}
+function getOutputRoleValue(tool, roleName) {
+    return tool.roleSpec.outputRoleValueByName[roleName];
+}
+export function bindInternalInputPotential(strategyState, targetAddress, sourceAddress, context) {
+    const sourceToolStep = context.toolStepByKey.get(sourceAddress.toolStepKey) ?? null;
+    if (!sourceToolStep) {
+        throw new Error(`Source tool step not found for '${sourceAddress.toolStepKey}'.`);
+    }
+    const targetToolStep = context.toolStepByKey.get(targetAddress.toolStepKey) ?? null;
+    if (!targetToolStep) {
+        throw new Error(`Target tool step not found for '${targetAddress.toolStepKey}'.`);
+    }
+    const sourceTool = context.toolMap.get(sourceToolStep.toolHandle) ?? null;
+    if (!sourceTool) {
+        throw new Error(`Source tool not found for '${sourceToolStep.toolHandle}'.`);
+    }
+    const targetTool = context.toolMap.get(targetToolStep.toolHandle) ?? null;
+    if (!targetTool) {
+        throw new Error(`Target tool not found for '${targetToolStep.toolHandle}'.`);
+    }
+    const targetInputRole = getInputRoleValue(targetTool, targetAddress.roleName);
+    if (!targetInputRole) {
+        throw new Error(`Target input role not found for (${targetAddress.toolStepKey}, ${targetAddress.roleName}).`);
+    }
+    const sourceOutputRole = getOutputRoleValue(sourceTool, sourceAddress.roleName);
+    const sourceInputRole = getInputRoleValue(sourceTool, sourceAddress.roleName);
+    const sourceInputEntryByRoleName = strategyState[sourceAddress.toolStepKey];
+    const sourceInputEntry = sourceInputEntryByRoleName?.[sourceAddress.roleName];
+    const sourceRoleType = sourceOutputRole
+        ? extractResourceTypeHandleFromRoleValue(sourceOutputRole)
+        : sourceInputRole
+            ? extractResourceTypeHandleFromRoleValue(sourceInputRole)
+            : null;
+    const targetRoleType = extractResourceTypeHandleFromRoleValue(targetInputRole);
+    if (!sourceOutputRole && sourceInputRole) {
+        if (!sourceInputEntry) {
+            throw new Error(`Source input role is not bound for (${sourceAddress.toolStepKey}, ${sourceAddress.roleName}).`); // ATTENTION: not an ontological invariant, but it might help catch some mistakes early on.
+        }
+    }
+    if (!sourceOutputRole && !sourceInputRole) {
+        throw new Error(`Source role not found for (${sourceAddress.toolStepKey}, ${sourceAddress.roleName}).`);
+    }
+    if (!sourceRoleType || !targetRoleType || sourceRoleType !== targetRoleType) {
+        throw new Error(`Reference type mismatch between source (${sourceAddress.toolStepKey}, ${sourceAddress.roleName}) and target (${targetAddress.toolStepKey}, ${targetAddress.roleName}).`);
+    }
+    return setStrategyStateInputEntry(strategyState, targetAddress, {
+        strategyStateInputKind: 'internalInputPotential',
+        toolStepRoleAddress: {
+            toolStepKey: sourceAddress.toolStepKey,
+            roleName: sourceAddress.roleName,
+        },
+    });
+}
+export function bindExternalInputPotential(strategyState, target) {
+    const mutableExternalInputPotential = {
+        strategyStateInputKind: 'externalInputPotential',
+    };
+    return setStrategyStateInputEntry(strategyState, target, mutableExternalInputPotential);
+}

package/dist/utils/resourceCreation.d.ts

@@ -0,0 +1,11 @@
+import type { ToolStepRoleAddress, ResourceId, Resource, ResourceTypeHandle, StrategyTraceHandle } from '@toolproof-core/genesis';
+export type ResourceCreationDescriptor = {
+    id: ResourceId;
+    resourceTypeHandle: ResourceTypeHandle;
+} | {
+    id: ResourceId;
+    resourceTypeHandle: ResourceTypeHandle;
+    toolStepRoleAddress: ToolStepRoleAddress;
+    strategyTraceHandle: StrategyTraceHandle;
+};
+export declare function createResourceFromDescriptor(descriptor: ResourceCreationDescriptor, projection: unknown): Resource;

package/dist/utils/resourceCreation.js

@@ -0,0 +1,32 @@
+import { CONSTANTS } from '../lookups/lookups.js';
+function createStrategyProvenance(strategyTraceHandle, toolStepRoleAddress) {
+    return {
+        provenanceKind: CONSTANTS.Enums.ProvenanceKind.strategy,
+        strategyTraceHandle,
+        toolStepRoleAddress,
+    };
+}
+function createRuntimeProvenance() {
+    return {
+        provenanceKind: CONSTANTS.Enums.ProvenanceKind.runtime,
+    };
+}
+function createResourcePointer(id, resourceTypeHandle, provenance) {
+    return {
+        id,
+        resourceTypeHandle,
+        provenance,
+    };
+}
+function createResource(resourcePointer, projection) {
+    return {
+        ...resourcePointer,
+        projection,
+    };
+}
+export function createResourceFromDescriptor(descriptor, projection) {
+    const provenance = 'toolStepRoleAddress' in descriptor
+        ? createStrategyProvenance(descriptor.strategyTraceHandle, descriptor.toolStepRoleAddress)
+        : createRuntimeProvenance();
+    return createResource(createResourcePointer(descriptor.id, descriptor.resourceTypeHandle, provenance), projection);
+}

package/dist/utils/stepCreation.d.ts

@@ -0,0 +1,9 @@
+import type { Tool } from '@toolproof-core/genesis';
+import type { MutableToolStep, MutableCase, MutableWhileStep, MutableForStep, MutableBranchStep } from './mutableStrategyOverlay.js';
+import { CONSTANTS } from '../lookups/lookups.js';
+export declare function createToolStepFromTool(tool: Tool): MutableToolStep;
+export declare function createCaseFromToolStepPair(what: MutableToolStep, when: MutableToolStep): MutableCase;
+export declare function createLoopStepFromCase(stepCase: MutableCase, stepKind: typeof CONSTANTS.Enums.StepKind.for | typeof CONSTANTS.Enums.StepKind.while): MutableForStep | MutableWhileStep;
+export declare function createBranchStepFromCases(cases: MutableCase[]): MutableBranchStep;
+export declare function cloneForStep(forStep: MutableForStep): MutableForStep;
+export declare function cloneWhileStep(whileStep: MutableWhileStep): MutableWhileStep;

package/dist/utils/stepCreation.js

@@ -0,0 +1,79 @@
+import { CONSTANTS } from '../lookups/lookups.js';
+import { getInputRoleNamesFromTool, getOutputRoleNamesFromTool } from './strategyExtraction.js';
+import { generateIdentifier } from './identifierGeneration.js';
+function assertNonEmpty(arr, msg) {
+    if (arr.length === 0) {
+        throw new Error(msg);
+    }
+}
+function getRoleBindingSpec(tool) {
+    return {
+        inputBindings: getInputRoleNamesFromTool(tool),
+        outputBindings: getOutputRoleNamesFromTool(tool),
+    };
+}
+export function createToolStepFromTool(tool) {
+    return {
+        toolStepKey: generateIdentifier('ToolStepKey'),
+        stepKind: CONSTANTS.Enums.StepKind.tool,
+        toolHandle: tool.handle,
+        roleBindingSpec: getRoleBindingSpec(tool),
+    };
+}
+export function createCaseFromToolStepPair(what, when) {
+    return { what, when };
+}
+export function createLoopStepFromCase(stepCase, stepKind) {
+    if (stepKind === CONSTANTS.Enums.StepKind.for) {
+        return {
+            macroStepKey: generateIdentifier('ForStepKey'),
+            stepKind: CONSTANTS.Enums.StepKind.for,
+            case: stepCase,
+        };
+    }
+    return {
+        macroStepKey: generateIdentifier('WhileStepKey'),
+        stepKind: CONSTANTS.Enums.StepKind.while,
+        case: stepCase,
+    };
+}
+export function createBranchStepFromCases(cases) {
+    assertNonEmpty(cases, 'createBranchStepFromCases requires at least one case');
+    return {
+        macroStepKey: generateIdentifier('BranchStepKey'),
+        stepKind: CONSTANTS.Enums.StepKind.branch,
+        cases,
+    };
+}
+export function cloneForStep(forStep) {
+    return {
+        macroStepKey: generateIdentifier('ForStepKey'),
+        stepKind: CONSTANTS.Enums.StepKind.for,
+        case: {
+            what: {
+                ...forStep.case.what,
+                toolStepKey: generateIdentifier('ToolStepKey'),
+            },
+            when: {
+                ...forStep.case.when,
+                toolStepKey: generateIdentifier('ToolStepKey'),
+            },
+        },
+    };
+}
+export function cloneWhileStep(whileStep) {
+    return {
+        macroStepKey: generateIdentifier('WhileStepKey'),
+        stepKind: CONSTANTS.Enums.StepKind.while,
+        case: {
+            what: {
+                ...whileStep.case.what,
+                toolStepKey: generateIdentifier('ToolStepKey'),
+            },
+            when: {
+                ...whileStep.case.when,
+                toolStepKey: generateIdentifier('ToolStepKey'),
+            },
+        },
+    };
+}

package/dist/utils/stepParallelization.d.ts

@@ -0,0 +1,2 @@
+import type { MutableStep, MutableStrategyState, MutableToolStepKey } from './mutableStrategyOverlay.js';
+export declare function getIndependentThreads<TKey extends string = MutableToolStepKey, TStep extends MutableStep<TKey> = MutableStep<TKey>>(steps: TStep[], strategyState: MutableStrategyState<TKey>): TStep[][];

package/dist/utils/{parallelizeSteps.js → stepParallelization.js}

@@ -1,30 +1,20 @@
-import { CONSTANTS } from '../artifacts/artifacts.js';
-function getToolStepId(toolStep) {
-    const maybeId = toolStep?.id;
-    return typeof maybeId === 'string' ? maybeId : undefined;
-}
+import { CONSTANTS } from '../lookups/lookups.js';
 export function getIndependentThreads(steps, strategyState) {
     const getOwnerLabel = (ownerIndex) => {
         const step = steps[ownerIndex];
         return `steps[${ownerIndex}] stepKind=${step?.stepKind ?? 'unknown'}`;
     };
-    // Map each toolStep.id (including macro-nested tool steps) to owning top-level step index.
-    const toolStepIdToOwner = new Map();
-    const ownerToToolStepIds = new Map();
-    const toolStepById = new Map();
+    const toolStepKeyToOwner = new Map();
+    const toolStepByKey = new Map();
     const addToolStep = (toolStep, ownerIndex) => {
-        const toolStepId = getToolStepId(toolStep);
-        if (!toolStepId || !toolStep)
+        if (!toolStep)
             return;
-        const existingOwner = toolStepIdToOwner.get(toolStepId);
+        const existingOwner = toolStepKeyToOwner.get(toolStep.toolStepKey);
         if (existingOwner !== undefined) {
-            throw new Error(`Duplicate toolStep.id '${toolStepId}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`);
+            throw new Error(`Duplicate toolStepKey '${toolStep.toolStepKey}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`);
         }
-        toolStepIdToOwner.set(toolStepId, ownerIndex);
-        toolStepById.set(toolStepId, toolStep);
-        const bucket = ownerToToolStepIds.get(ownerIndex) ?? [];
-        bucket.push(toolStepId);
-        ownerToToolStepIds.set(ownerIndex, bucket);
+        toolStepKeyToOwner.set(toolStep.toolStepKey, ownerIndex);
+        toolStepByKey.set(toolStep.toolStepKey, toolStep);
     };
     steps.forEach((step, ownerIndex) => {
         if (step.stepKind === CONSTANTS.Enums.StepKind.tool) {
@@ -45,16 +35,13 @@ export function getIndependentThreads(steps, strategyState) {
         }
         if (step.stepKind === CONSTANTS.Enums.StepKind.branch) {
             const branch = step;
-            for (const caseItem of branch.cases ?? []) {
-                addToolStep(caseItem?.what, ownerIndex);
-                addToolStep(caseItem?.when, ownerIndex);
+            for (const stepCase of branch.cases) {
+                addToolStep(stepCase?.what, ownerIndex);
+                addToolStep(stepCase?.when, ownerIndex);
             }
-            return;
         }
     });
-    // Undirected adjacency used for connected components (thread groups).
     const ownerAdj = new Map();
-    // Directed dependencies used for strict ordering validation: owner -> producers it depends on.
     const ownerDeps = new Map();
     const ensureOwner = (ownerIndex) => {
         if (!ownerAdj.has(ownerIndex))
@@ -62,36 +49,32 @@ export function getIndependentThreads(steps, strategyState) {
         if (!ownerDeps.has(ownerIndex))
             ownerDeps.set(ownerIndex, new Set());
     };
-    for (let i = 0; i < steps.length; i++) {
-        ensureOwner(i);
+    for (let index = 0; index < steps.length; index++) {
+        ensureOwner(index);
     }
-    // Discover dependencies from strategyState.
-    for (const [toolStepId, ownerIndex] of toolStepIdToOwner) {
+    for (const [toolStepKey, ownerIndex] of toolStepKeyToOwner) {
         ensureOwner(ownerIndex);
-        const toolStep = toolStepById.get(toolStepId);
+        const toolStep = toolStepByKey.get(toolStepKey);
         const inputBindings = toolStep?.roleBindingSpec?.inputBindings ?? [];
-        const bucket = strategyState?.[toolStepId] ?? {};
+        const bucket = strategyState[toolStepKey];
         for (const inputRoleId of inputBindings) {
             const entry = bucket?.[inputRoleId];
-            if (!entry || entry.strategyStateInputKind !== 'referenceInput')
+            if (!entry || entry.strategyStateInputKind !== 'internalInputPotential')
                 continue;
-            const creatorToolStepId = typeof entry?.toolStepPath === 'string'
-                ? entry.toolStepPath
-                : undefined;
-            if (!creatorToolStepId) {
-                throw new Error(`Unresolvable referenceInput in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): missing toolStepPath for role '${inputRoleId}'`);
+            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 = toolStepIdToOwner.get(creatorToolStepId);
+            const producerOwner = toolStepKeyToOwner.get(producerToolStepKey);
             if (producerOwner === undefined) {
-                throw new Error(`Unresolvable referenceInput in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): creator toolStepPath '${creatorToolStepId}' not found in strategy steps`);
+                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);
+            ownerAdj.get(ownerIndex)?.add(producerOwner);
+            ownerAdj.get(producerOwner)?.add(ownerIndex);
+            ownerDeps.get(ownerIndex)?.add(producerOwner);
         }
     }
-    // Connected components over owners.
     const visited = new Set();
     const components = [];
     for (let ownerIndex = 0; ownerIndex < steps.length; ownerIndex++) {
@@ -102,27 +85,30 @@ export function getIndependentThreads(steps, strategyState) {
         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)) {
-                    visited.add(neighbor);
-                    queue.push(neighbor);
-                }
+                if (visited.has(neighbor))
+                    continue;
+                visited.add(neighbor);
+                queue.push(neighbor);
             }
         }
         components.push(component);
     }
-    // Strict validation: within a thread, the linear order must not contain forward refs.
-    for (const comp of components) {
-        const compSet = new Set(comp);
-        const ownersInOrder = steps.map((_, i) => i).filter((i) => compSet.has(i));
+    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();
-        ownersInOrder.forEach((owner, idx) => position.set(owner, idx));
+        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) {
@@ -135,10 +121,9 @@ export function getIndependentThreads(steps, strategyState) {
         }
     }
     return components
-        .map((compOwners) => {
-        const ownerSet = new Set(compOwners);
-        return steps.filter((_, i) => ownerSet.has(i));
+        .map((component) => {
+        const ownerSet = new Set(component);
+        return steps.filter((_step, index) => ownerSet.has(index));
     })
         .filter((group) => group.length > 0);
 }
-//# sourceMappingURL=parallelizeSteps.js.map

package/dist/utils/strategyAssembly.d.ts

@@ -0,0 +1,3 @@
+import type { Strategy } from '@toolproof-core/genesis';
+import type { MutableStrategy } from './mutableStrategyOverlay.js';
+export declare function composeStrategyForExecution<TKey extends string>(mutableStrategy: MutableStrategy<TKey>): Strategy;

package/dist/utils/strategyAssembly.js

@@ -0,0 +1,6 @@
+import { toExecutionMutableStrategy } from './strategyThreading.js';
+import { mutableStrategyToStrategy } from './strategyCanonicalization.js';
+export function composeStrategyForExecution(mutableStrategy) {
+    const executionStrategy = toExecutionMutableStrategy(mutableStrategy);
+    return mutableStrategyToStrategy(executionStrategy);
+}

package/dist/utils/strategyCanonicalization.d.ts

@@ -0,0 +1,4 @@
+import type { Strategy } from '@toolproof-core/genesis';
+import type { MutableStrategy } from './mutableStrategyOverlay.js';
+export declare function strategyToMutableStrategy(strategy: Strategy): MutableStrategy;
+export declare function mutableStrategyToStrategy(mutableStrategy: MutableStrategy): Strategy;

package/dist/utils/strategyCanonicalization.js

@@ -0,0 +1,215 @@
+import { CONSTANTS } from '../lookups/lookups.js';
+import { generateIdentifier } from './identifierGeneration.js';
+function stripMutableCase(stepCase) {
+    const { when, what, ...rest } = stepCase;
+    const { toolStepKey: _whenToolStepKey, ...canonicalWhen } = when;
+    const { toolStepKey: _whatToolStepKey, ...canonicalWhat } = what;
+    return {
+        ...rest,
+        when: canonicalWhen,
+        what: canonicalWhat,
+    };
+}
+function buildExecutionPathMap(strategy) {
+    const executionPathByKey = new Map();
+    const registerStep = (step, pathPrefix) => {
+        switch (step.stepKind) {
+            case CONSTANTS.Enums.StepKind.tool:
+                executionPathByKey.set(step.toolStepKey, `${pathPrefix}/self`);
+                return;
+            case CONSTANTS.Enums.StepKind.branch:
+                step.cases.forEach((stepCase, caseIndex) => {
+                    executionPathByKey.set(stepCase.when.toolStepKey, `${pathPrefix}/cases/${caseIndex}/when`);
+                    executionPathByKey.set(stepCase.what.toolStepKey, `${pathPrefix}/cases/${caseIndex}/what`);
+                });
+                return;
+            case CONSTANTS.Enums.StepKind.while:
+            case CONSTANTS.Enums.StepKind.for:
+                executionPathByKey.set(step.case.when.toolStepKey, `${pathPrefix}/case/when`);
+                executionPathByKey.set(step.case.what.toolStepKey, `${pathPrefix}/case/what`);
+                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, executionPathByKey) {
+    if (entry.strategyStateInputKind !== 'internalInputPotential') {
+        return entry;
+    }
+    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,
+        },
+    };
+}
+function toCanonicalStep(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),
+            };
+        }
+        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, executionKeyByPath) {
+    if (entry.strategyStateInputKind !== 'internalInputPotential') {
+        return entry;
+    }
+    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,
+        },
+    };
+}
+function toMutableToolStep(step) {
+    return {
+        ...step,
+        toolStepKey: generateIdentifier('ToolStepKey'),
+    };
+}
+function toMutableCase(stepCase) {
+    const { when, what, ...rest } = stepCase;
+    return {
+        ...rest,
+        when: toMutableToolStep(when),
+        what: toMutableToolStep(what),
+    };
+}
+function toMutableBranchStep(step) {
+    const { cases, ...rest } = step;
+    return {
+        ...rest,
+        macroStepKey: generateIdentifier('BranchStepKey'),
+        cases: cases.map(toMutableCase),
+    };
+}
+function toMutableWhileStep(step) {
+    const { case: stepCase, ...rest } = step;
+    return {
+        ...rest,
+        macroStepKey: generateIdentifier('WhileStepKey'),
+        case: toMutableCase(stepCase),
+    };
+}
+function toMutableForStep(step) {
+    const { case: stepCase, ...rest } = step;
+    return {
+        ...rest,
+        macroStepKey: generateIdentifier('ForStepKey'),
+        case: toMutableCase(stepCase),
+    };
+}
+function toMutableStep(step) {
+    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) {
+    const executionPathByKey = buildExecutionPathMap(strategy);
+    const executionKeyByPath = new Map();
+    for (const [toolStepKey, toolStepPath] of executionPathByKey.entries()) {
+        executionKeyByPath.set(toolStepPath, toolStepKey);
+    }
+    return executionKeyByPath;
+}
+export function strategyToMutableStrategy(strategy) {
+    const stepsByThreadIndex = strategy.stepsByThreadIndex.map((steps) => steps.map(toMutableStep));
+    const seededMutableStrategy = {
+        ...strategy,
+        stepsByThreadIndex,
+        strategyState: {},
+    };
+    const executionKeyByPath = buildExecutionKeyMap(seededMutableStrategy);
+    const strategyState = {};
+    for (const [toolStepPath, inputEntryByRoleName] of Object.entries(strategy.strategyState)) {
+        const toolStepKey = executionKeyByPath.get(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,
+                toMutableStrategyStateEntry(entry, executionKeyByPath),
+            ];
+        }));
+    }
+    return {
+        ...strategy,
+        stepsByThreadIndex,
+        strategyState,
+    };
+}
+export function mutableStrategyToStrategy(mutableStrategy) {
+    const executionPathByKey = buildExecutionPathMap(mutableStrategy);
+    const 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),
+            ];
+        }));
+    }
+    return {
+        ...mutableStrategy,
+        stepsByThreadIndex: mutableStrategy.stepsByThreadIndex.map((steps) => steps.map(toCanonicalStep)),
+        strategyState,
+    };
+}

package/dist/utils/strategyExtraction.d.ts

@@ -0,0 +1,17 @@
+import type { RoleName, RoleSpec, ToolHandle, Tool, ResourceTypeHandle, RoleValue } from '@toolproof-core/genesis';
+import type { MutableStrategy, MutableToolStep } from './mutableStrategyOverlay.js';
+export type RoleSpecEntry = [RoleName, RoleValue];
+type RoleSpecDirectionKeys = keyof Pick<RoleSpec, 'inputRoleValueByName' | 'outputRoleValueByName'>;
+export type RoleSpecByDirection = {
+    [K in RoleSpecDirectionKeys]: Map<RoleName, RoleValue>;
+};
+export declare function getInputRoleSpecEntriesFromTool(tool: Tool): RoleSpecEntry[];
+export declare function getOutputRoleSpecEntriesFromTool(tool: Tool): RoleSpecEntry[];
+export declare function getInputRoleNamesFromTool(tool: Tool): RoleName[];
+export declare function getOutputRoleNamesFromTool(tool: Tool): RoleName[];
+export declare function extractResourceTypeHandleFromRoleValue(roleValue: RoleValue): ResourceTypeHandle | null;
+export declare function extractToolStepsFromStrategy(strategy: MutableStrategy): MutableToolStep[];
+export declare function extractToolsFromStrategy(strategy: MutableStrategy, toolMap: Map<ToolHandle, Tool>): Tool[];
+export declare function extractRoleSpecByDirectionByToolHandleFromStrategy(strategy: MutableStrategy, toolMap: Map<ToolHandle, Tool>): Map<ToolHandle, RoleSpecByDirection>;
+export declare function extractSingleBranchableOutputResourceTypeHandle(tool: Tool): ResourceTypeHandle | null;
+export {};