@toolproof-npm/shared 0.1.111 → 0.1.112

package/dist/_lib/utils/parallelization.d.ts

@@ -1,8 +1,2 @@
-import type { TerminalConst } from '../types.js';
-import type { ExecutionJson, StatefulStrategyJson, StrategyRunJson, StrategyRunStatusJson, StrategyStateJson } from '@toolproof-npm/schema';
-export type GetNewIdentity = (identifiable: TerminalConst) => string | Promise<string>;
-export declare function normalizeExecutionInputBindingMap(execution: ExecutionJson, strategyState: StrategyStateJson): ExecutionJson;
-export declare function statefulStrategyToStrategyRun(statefulStrategy: StatefulStrategyJson, opts?: {
-    getNewIdentity: GetNewIdentity;
-    status?: StrategyRunStatusJson;
-}): Promise<StrategyRunJson>;
+import type { StepJson, StrategyStateJson } from '@toolproof-npm/schema';
+export declare function getIndependentThreads(steps: StepJson[], strategyState: StrategyStateJson): StepJson[][];

package/dist/_lib/utils/parallelization.js

@@ -1,247 +1,139 @@
 import { CONSTANTS } from '../../constants.js';
-export function normalizeExecutionInputBindingMap(execution, strategyState) {
-    const inputBindingMap = execution.roleBindings?.inputBindingMap ?? {};
-    const outputBindingMap = execution.roleBindings?.outputBindingMap ?? {};
-    const bucket = strategyState?.[execution.identity];
-    if (!bucket) {
-        return execution;
-    }
-    let changed = false;
-    const nextInputBindingMap = { ...inputBindingMap };
-    for (const [roleRef, currentResourceId] of Object.entries(inputBindingMap)) {
-        const entryIdentity = bucket?.[roleRef]?.identity;
-        if (typeof entryIdentity === 'string' && entryIdentity.length > 0 && entryIdentity !== currentResourceId) {
-            nextInputBindingMap[roleRef] = entryIdentity;
-            changed = true;
+export function getIndependentThreads(steps, strategyState) {
+    const getOwnerLabel = (ownerIndex) => {
+        const step = steps[ownerIndex];
+        return `steps[${ownerIndex}] kind=${step?.kind ?? 'unknown'}`;
+    };
+    // Collect all executions (including macro-nested WorkSteps) and map them back to their
+    // owning top-level step index. We keep macro steps atomic at the outer step level.
+    const executionIdToOwner = new Map();
+    const ownerToExecutionIds = new Map();
+    const executionById = new Map();
+    const addExecution = (execution, ownerIndex) => {
+        if (!execution?.identity)
+            return;
+        const existingOwner = executionIdToOwner.get(execution.identity);
+        if (existingOwner !== undefined) {
+            throw new Error(`Duplicate execution.identity '${execution.identity}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`);
         }
-    }
-    if (!changed) {
-        return execution;
-    }
-    return {
-        ...execution,
-        roleBindings: {
-            inputBindingMap: nextInputBindingMap,
-            outputBindingMap,
-        },
+        executionIdToOwner.set(execution.identity, ownerIndex);
+        executionById.set(execution.identity, execution);
+        const bucket = ownerToExecutionIds.get(ownerIndex) ?? [];
+        bucket.push(execution.identity);
+        ownerToExecutionIds.set(ownerIndex, bucket);
     };
-}
-function normalizeStepRoleBindings(step, strategyState) {
-    if (step.kind === CONSTANTS.STEPS.work) {
-        const work = step;
-        if (!work.execution)
-            return step;
-        const nextExecution = normalizeExecutionInputBindingMap(work.execution, strategyState);
-        if (nextExecution === work.execution)
-            return step;
-        return {
-            ...work,
-            execution: nextExecution,
-        };
-    }
-    if (step.kind === CONSTANTS.STEPS.for) {
-        const loop = step;
-        const whatExecution = loop.case?.what?.execution;
-        const whenExecution = loop.case?.when?.execution;
-        const nextWhatExecution = whatExecution
-            ? normalizeExecutionInputBindingMap(whatExecution, strategyState)
-            : whatExecution;
-        const nextWhenExecution = whenExecution
-            ? normalizeExecutionInputBindingMap(whenExecution, strategyState)
-            : whenExecution;
-        if (nextWhatExecution === whatExecution && nextWhenExecution === whenExecution)
-            return step;
-        return {
-            ...loop,
-            case: {
-                ...loop.case,
-                what: loop.case?.what
-                    ? {
-                        ...loop.case.what,
-                        execution: nextWhatExecution,
-                    }
-                    : loop.case?.what,
-                when: loop.case?.when
-                    ? {
-                        ...loop.case.when,
-                        execution: nextWhenExecution,
-                    }
-                    : loop.case?.when,
-            },
-        };
-    }
-    if (step.kind === CONSTANTS.STEPS.while) {
-        const loop = step;
-        const whatExecution = loop.case?.what?.execution;
-        const whenExecution = loop.case?.when?.execution;
-        const nextWhatExecution = whatExecution
-            ? normalizeExecutionInputBindingMap(whatExecution, strategyState)
-            : whatExecution;
-        const nextWhenExecution = whenExecution
-            ? normalizeExecutionInputBindingMap(whenExecution, strategyState)
-            : whenExecution;
-        if (nextWhatExecution === whatExecution && nextWhenExecution === whenExecution)
-            return step;
-        return {
-            ...loop,
-            case: {
-                ...loop.case,
-                what: loop.case?.what
-                    ? {
-                        ...loop.case.what,
-                        execution: nextWhatExecution,
-                    }
-                    : loop.case?.what,
-                when: loop.case?.when
-                    ? {
-                        ...loop.case.when,
-                        execution: nextWhenExecution,
-                    }
-                    : loop.case?.when,
-            },
-        };
-    }
-    if (step.kind === CONSTANTS.STEPS.branch) {
-        const branch = step;
-        const cases = branch.cases ?? [];
-        let changed = false;
-        const nextCases = cases.map((caseItem) => {
-            const whatExecution = caseItem?.what?.execution;
-            const whenExecution = caseItem?.when?.execution;
-            const nextWhatExecution = whatExecution
-                ? normalizeExecutionInputBindingMap(whatExecution, strategyState)
-                : whatExecution;
-            const nextWhenExecution = whenExecution
-                ? normalizeExecutionInputBindingMap(whenExecution, strategyState)
-                : whenExecution;
-            if (nextWhatExecution !== whatExecution || nextWhenExecution !== whenExecution) {
-                changed = true;
+    steps.forEach((step, ownerIndex) => {
+        if (step.kind === CONSTANTS.STEPS.work) {
+            addExecution(step.execution, ownerIndex);
+            return;
+        }
+        if (step.kind === CONSTANTS.STEPS.for) {
+            const loop = step;
+            addExecution(loop.case?.what?.execution, ownerIndex);
+            addExecution(loop.case?.when?.execution, ownerIndex);
+            return;
+        }
+        if (step.kind === CONSTANTS.STEPS.while) {
+            const loop = step;
+            addExecution(loop.case?.what?.execution, ownerIndex);
+            addExecution(loop.case?.when?.execution, ownerIndex);
+            return;
+        }
+        if (step.kind === CONSTANTS.STEPS.branch) {
+            const branch = step;
+            for (const caseItem of branch.cases ?? []) {
+                addExecution(caseItem?.what?.execution, ownerIndex);
+                addExecution(caseItem?.when?.execution, ownerIndex);
             }
-            return {
-                ...caseItem,
-                what: caseItem?.what
-                    ? {
-                        ...caseItem.what,
-                        execution: nextWhatExecution,
-                    }
-                    : caseItem?.what,
-                when: caseItem?.when
-                    ? {
-                        ...caseItem.when,
-                        execution: nextWhenExecution,
-                    }
-                    : caseItem?.when,
-            };
-        });
-        if (!changed)
-            return step;
-        return {
-            ...branch,
-            cases: nextCases,
-        };
-    }
-    return step;
-}
-function normalizeStatefulStrategyInputBindingMaps(statefulStrategy) {
-    const steps = statefulStrategy.statelessStrategy?.steps;
-    if (!steps || steps.length === 0)
-        return statefulStrategy;
-    const strategyState = (statefulStrategy.strategyState ?? {});
-    let changed = false;
-    const nextSteps = steps.map((step) => {
-        const nextStep = normalizeStepRoleBindings(step, strategyState);
-        if (nextStep !== step)
-            changed = true;
-        return nextStep;
+            return;
+        }
     });
-    if (!changed)
-        return statefulStrategy;
-    return {
-        ...statefulStrategy,
-        statelessStrategy: {
-            ...statefulStrategy.statelessStrategy,
-            steps: nextSteps,
-        },
+    // 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))
+            ownerAdj.set(ownerIndex, new Set());
+        if (!ownerDeps.has(ownerIndex))
+            ownerDeps.set(ownerIndex, new Set());
     };
-}
-function getIndependentThreads(steps, strategyState) {
-    const getStepId = (s, i) => s?.execution?.identity || `step-${i}`;
-    const stepById = new Map(steps.map((s, i) => [getStepId(s, i), s]));
-    const adj = new Map(); // undirected graph for components
-    steps.forEach((step, i) => {
-        const id = getStepId(step, i);
-        if (!adj.has(id))
-            adj.set(id, []);
-        if (step.kind === CONSTANTS.STEPS.work && step.execution) {
-            const inputBindingMap = step.execution.roleBindings.inputBindingMap;
-            for (const inputRoleId of Object.keys(inputBindingMap)) {
-                const entry = strategyState?.[id]?.[inputRoleId];
-                if (entry?.kind === 'potential-input') {
-                    const creatorId = entry.creationContext?.executionRef;
-                    if (creatorId && stepById.has(creatorId)) {
-                        // Dependency exists
-                        adj.get(id).push(creatorId);
-                        if (!adj.has(creatorId))
-                            adj.set(creatorId, []);
-                        adj.get(creatorId).push(id);
-                    }
-                }
+    for (let i = 0; i < steps.length; i++) {
+        ensureOwner(i);
+    }
+    // Discover dependencies from strategyState. Note: strategyState is keyed by execution.identity.
+    for (const [executionId, ownerIndex] of executionIdToOwner) {
+        ensureOwner(ownerIndex);
+        const bucket = (strategyState?.[executionId] ?? {});
+        const execution = executionById.get(executionId);
+        const inputBindingMap = execution?.roleBindings?.inputBindingMap ?? {};
+        for (const inputRoleId of Object.keys(inputBindingMap)) {
+            const entry = bucket?.[inputRoleId];
+            if (entry?.kind !== 'potential-input')
+                continue;
+            const creatorExecutionRef = entry.creationContext?.executionRef;
+            if (!creatorExecutionRef) {
+                throw new Error(`Unresolvable potential-input in execution '${executionId}' (${getOwnerLabel(ownerIndex)}): missing creationContext.executionRef for role '${inputRoleId}'`);
             }
+            const producerOwner = executionIdToOwner.get(creatorExecutionRef);
+            if (producerOwner === undefined) {
+                throw new Error(`Unresolvable potential-input in execution '${executionId}' (${getOwnerLabel(ownerIndex)}): creator executionRef '${creatorExecutionRef}' not found in strategy steps`);
+            }
+            ensureOwner(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 (const [id] of adj) {
-        if (!visited.has(id)) {
-            const component = [];
-            const queue = [id];
-            visited.add(id);
-            while (queue.length > 0) {
-                const node = queue.shift();
-                component.push(node);
-                for (const neighbor of adj.get(node) || []) {
-                    if (!visited.has(neighbor)) {
-                        visited.add(neighbor);
-                        queue.push(neighbor);
-                    }
+    for (let ownerIndex = 0; ownerIndex < steps.length; ownerIndex++) {
+        if (visited.has(ownerIndex))
+            continue;
+        const component = [];
+        const queue = [ownerIndex];
+        visited.add(ownerIndex);
+        while (queue.length > 0) {
+            const node = queue.shift();
+            component.push(node);
+            for (const neighbor of ownerAdj.get(node) ?? []) {
+                if (!visited.has(neighbor)) {
+                    visited.add(neighbor);
+                    queue.push(neighbor);
+                }
+            }
+        }
+        components.push(component);
+    }
+    // Strict validation: within a thread, the linear order must not contain forward refs.
+    // The engine does not "wait" for dependencies; a consumer-before-producer will fail.
+    for (const comp of components) {
+        const compSet = new Set(comp);
+        const ownersInOrder = steps.map((_, i) => i).filter((i) => compSet.has(i));
+        const position = new Map();
+        ownersInOrder.forEach((owner, idx) => position.set(owner, idx));
+        for (const consumerOwner of ownersInOrder) {
+            const deps = ownerDeps.get(consumerOwner);
+            if (!deps || deps.size === 0)
+                continue;
+            const consumerPos = position.get(consumerOwner);
+            for (const producerOwner of deps) {
+                const producerPos = position.get(producerOwner);
+                if (producerPos === undefined) {
+                    // Should not happen since deps are within steps, but keep strict.
+                    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`);
                 }
             }
-            components.push(component);
         }
     }
     return components
-        .map((compIds) => {
-        return steps.filter((s, i) => {
-            const sId = getStepId(s, i);
-            return compIds.includes(sId);
-        });
+        .map((compOwners) => {
+        const ownerSet = new Set(compOwners);
+        return steps.filter((_, i) => ownerSet.has(i));
     })
         .filter((group) => group.length > 0);
 }
-export async function statefulStrategyToStrategyRun(statefulStrategy, opts) {
-    if (!opts?.getNewIdentity) {
-        throw new Error('statefulStrategyToStrategyRun: opts.getNewIdentity is required');
-    }
-    // Normalize roleBindings.inputBindingMap to reflect the identities present in strategyState.
-    // This is intentionally a pure transformation (no mutation of the provided statefulStrategy object graph).
-    const normalizedStatefulStrategy = normalizeStatefulStrategyInputBindingMaps(statefulStrategy);
-    const strategyRunIdentity = (await opts.getNewIdentity(CONSTANTS.TERMINALS.strategy_run));
-    const steps = normalizedStatefulStrategy.statelessStrategy?.steps ?? [];
-    const strategyState = (normalizedStatefulStrategy.strategyState ?? {});
-    // Algorithm to find what steps can run in parallel
-    const threadStepsGroups = getIndependentThreads(steps, strategyState);
-    const strategyThreadMap = {};
-    for (const group of threadStepsGroups) {
-        const threadIdentity = await opts.getNewIdentity(CONSTANTS.TERMINALS.strategy_thread);
-        strategyThreadMap[threadIdentity] = group;
-    }
-    return {
-        identity: strategyRunIdentity,
-        statefulStrategyRef: normalizedStatefulStrategy.identity,
-        strategyState: strategyState,
-        strategyRunContext: {
-            status: opts.status ?? 'running',
-        },
-        strategyThreadMap,
-    };
-}

package/dist/_lib/utils/strategyRunCreation.d.ts

@@ -1,5 +1,5 @@
-import type { TerminalConst } from '../types.js';
 import type { ExecutionJson, StatefulStrategyJson, StrategyRunJson, StrategyRunStatusJson, StrategyStateJson } from '@toolproof-npm/schema';
+import type { TerminalConst } from '../types.js';
 export type GetNewIdentity = (identifiable: TerminalConst) => string | Promise<string>;
 export declare function normalizeExecutionInputBindingMap(execution: ExecutionJson, strategyState: StrategyStateJson): ExecutionJson;
 export declare function createStrategyRun(statefulStrategy: StatefulStrategyJson, opts?: {

package/dist/_lib/utils/strategyRunCreation.js

@@ -1,4 +1,5 @@
 import { CONSTANTS } from '../../constants.js';
+import { getIndependentThreads } from './parallelization.js';
 export function normalizeExecutionInputBindingMap(execution, strategyState) {
     const inputBindingMap = execution.roleBindings?.inputBindingMap ?? {};
     const outputBindingMap = execution.roleBindings?.outputBindingMap ?? {};
@@ -164,60 +165,6 @@ function normalizeStatefulStrategyInputBindingMaps(statefulStrategy) {
         },
     };
 }
-function getIndependentThreads(steps, strategyState) {
-    const getStepId = (s, i) => s?.execution?.identity || `step-${i}`;
-    const stepById = new Map(steps.map((s, i) => [getStepId(s, i), s]));
-    const adj = new Map(); // undirected graph for components
-    steps.forEach((step, i) => {
-        const id = getStepId(step, i);
-        if (!adj.has(id))
-            adj.set(id, []);
-        if (step.kind === CONSTANTS.STEPS.work && step.execution) {
-            const inputBindingMap = step.execution.roleBindings.inputBindingMap;
-            for (const inputRoleId of Object.keys(inputBindingMap)) {
-                const entry = strategyState?.[id]?.[inputRoleId];
-                if (entry?.kind === 'potential-input') {
-                    const creatorId = entry.creationContext?.executionRef;
-                    if (creatorId && stepById.has(creatorId)) {
-                        // Dependency exists
-                        adj.get(id).push(creatorId);
-                        if (!adj.has(creatorId))
-                            adj.set(creatorId, []);
-                        adj.get(creatorId).push(id);
-                    }
-                }
-            }
-        }
-    });
-    const visited = new Set();
-    const components = [];
-    for (const [id] of adj) {
-        if (!visited.has(id)) {
-            const component = [];
-            const queue = [id];
-            visited.add(id);
-            while (queue.length > 0) {
-                const node = queue.shift();
-                component.push(node);
-                for (const neighbor of adj.get(node) || []) {
-                    if (!visited.has(neighbor)) {
-                        visited.add(neighbor);
-                        queue.push(neighbor);
-                    }
-                }
-            }
-            components.push(component);
-        }
-    }
-    return components
-        .map((compIds) => {
-        return steps.filter((s, i) => {
-            const sId = getStepId(s, i);
-            return compIds.includes(sId);
-        });
-    })
-        .filter((group) => group.length > 0);
-}
 export async function createStrategyRun(statefulStrategy, opts) {
     if (!opts?.getNewIdentity) {
         throw new Error('statefulStrategyToStrategyRun: opts.getNewIdentity is required');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolproof-npm/shared",
-  "version": "0.1.111",
+  "version": "0.1.112",
   "description": "Core library utilities for ToolProof",
   "keywords": [
     "toolproof",