@toolproof-core/lib 1.0.5 → 1.0.8

package/dist/utils/parallelizeSteps.js

@@ -0,0 +1,137 @@
+import { CONSTANTS } from '../artifacts/artifacts.js';
+export function getIndependentThreads(steps, strategyState) {
+    const getOwnerLabel = (ownerIndex) => {
+        const step = steps[ownerIndex];
+        return `steps[${ownerIndex}] stepKind=${step?.stepKind ?? 'unknown'}`;
+    };
+    // Map each jobStep.identity (including macro-nested job steps) to owning top-level step index.
+    const jobStepIdToOwner = new Map();
+    const ownerToJobStepIds = new Map();
+    const jobStepById = new Map();
+    const addJobStep = (jobStep, ownerIndex) => {
+        if (!jobStep?.identity)
+            return;
+        const existingOwner = jobStepIdToOwner.get(jobStep.identity);
+        if (existingOwner !== undefined) {
+            throw new Error(`Duplicate jobStep.identity '${jobStep.identity}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`);
+        }
+        jobStepIdToOwner.set(jobStep.identity, ownerIndex);
+        jobStepById.set(jobStep.identity, jobStep);
+        const bucket = ownerToJobStepIds.get(ownerIndex) ?? [];
+        bucket.push(jobStep.identity);
+        ownerToJobStepIds.set(ownerIndex, bucket);
+    };
+    steps.forEach((step, ownerIndex) => {
+        if (step.stepKind === CONSTANTS.Enums.StepKind.job) {
+            addJobStep(step, ownerIndex);
+            return;
+        }
+        if (step.stepKind === CONSTANTS.Enums.StepKind.for) {
+            const loop = step;
+            addJobStep(loop.case?.what, ownerIndex);
+            addJobStep(loop.case?.when, ownerIndex);
+            return;
+        }
+        if (step.stepKind === CONSTANTS.Enums.StepKind.while) {
+            const loop = step;
+            addJobStep(loop.case?.what, ownerIndex);
+            addJobStep(loop.case?.when, ownerIndex);
+            return;
+        }
+        if (step.stepKind === CONSTANTS.Enums.StepKind.branch) {
+            const branch = step;
+            for (const caseItem of branch.cases ?? []) {
+                addJobStep(caseItem?.what, ownerIndex);
+                addJobStep(caseItem?.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))
+            ownerAdj.set(ownerIndex, new Set());
+        if (!ownerDeps.has(ownerIndex))
+            ownerDeps.set(ownerIndex, new Set());
+    };
+    for (let i = 0; i < steps.length; i++) {
+        ensureOwner(i);
+    }
+    // Discover dependencies from strategyState.
+    for (const [jobStepId, ownerIndex] of jobStepIdToOwner) {
+        ensureOwner(ownerIndex);
+        const jobStep = jobStepById.get(jobStepId);
+        const inputBindings = jobStep?.roleBindings?.inputBindings ?? [];
+        const bucket = strategyState?.[jobStepId] ?? {};
+        for (const inputRoleHandle of inputBindings) {
+            const entry = bucket?.[inputRoleHandle];
+            if (!entry || entry.resourceShellKind !== 'inputPotential')
+                continue;
+            const creatorJobStepHandle = entry?.creationContext?.jobStepHandle;
+            if (!creatorJobStepHandle) {
+                throw new Error(`Unresolvable inputPotential in jobStep '${jobStepId}' (${getOwnerLabel(ownerIndex)}): missing creationContext.jobStepHandle for role '${inputRoleHandle}'`);
+            }
+            const producerOwner = jobStepIdToOwner.get(creatorJobStepHandle);
+            if (producerOwner === undefined) {
+                throw new Error(`Unresolvable inputPotential in jobStep '${jobStepId}' (${getOwnerLabel(ownerIndex)}): creator jobStepHandle '${creatorJobStepHandle}' 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 (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.
+    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) {
+                    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((compOwners) => {
+        const ownerSet = new Set(compOwners);
+        return steps.filter((_, i) => ownerSet.has(i));
+    })
+        .filter((group) => group.length > 0);
+}
+//# sourceMappingURL=parallelizeSteps.js.map

package/dist/utils/parallelizeSteps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallelizeSteps.js","sourceRoot":"","sources":["../../src/utils/parallelizeSteps.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAGtD,MAAM,UAAU,qBAAqB,CAAC,KAAiB,EAAE,aAAgC;IAGrF,MAAM,aAAa,GAAG,CAAC,UAAsB,EAAE,EAAE;QAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;QAC/B,OAAO,SAAS,UAAU,cAAe,IAAY,EAAE,QAAQ,IAAI,SAAS,EAAE,CAAC;IACnF,CAAC,CAAC;IAEF,+FAA+F;IAC/F,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAmC,CAAC;IACpE,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAqC,CAAC;IACvE,MAAM,WAAW,GAAG,IAAI,GAAG,EAAoC,CAAC;IAEhE,MAAM,UAAU,GAAG,CAAC,OAAgC,EAAE,UAAsB,EAAE,EAAE;QAC5E,IAAI,CAAC,OAAO,EAAE,QAAQ;YAAE,OAAO;QAE/B,MAAM,aAAa,GAAG,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC7D,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACX,+BAA+B,OAAO,CAAC,QAAQ,cAAc,aAAa,CAAC,UAAU,CAAC,QAAQ,aAAa,CAAC,aAAa,CAAC,EAAE,CAC/H,CAAC;QACN,CAAC;QAED,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACnD,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QACvD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC9B,iBAAiB,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE;QAC/B,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;YACjD,UAAU,CAAC,IAAmB,EAAE,UAAU,CAAC,CAAC;YAC5C,OAAO;QACX,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;YACjD,MAAM,IAAI,GAAG,IAAmB,CAAC;YACjC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;YACxC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;YACxC,OAAO;QACX,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnD,MAAM,IAAI,GAAG,IAAqB,CAAC;YACnC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;YACxC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;YACxC,OAAO;QACX,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACpD,MAAM,MAAM,GAAG,IAAsB,CAAC;YACtC,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;gBACxC,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;gBACvC,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;YAC3C,CAAC;YACD,OAAO;QACX,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,sEAAsE;IACtE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA+B,CAAC;IACxD,+FAA+F;IAC/F,MAAM,SAAS,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEzD,MAAM,WAAW,GAAG,CAAC,UAAsB,EAAE,EAAE;QAC3C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC;YAAE,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;IACzE,CAAC,CAAC;IAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,WAAW,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IAED,4CAA4C;IAC5C,KAAK,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,gBAAgB,EAAE,CAAC;QACrD,WAAW,CAAC,UAAU,CAAC,CAAC;QAExB,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,MAAM,aAAa,GAAG,OAAO,EAAE,YAAY,EAAE,aAAa,IAAI,EAAE,CAAC;QACjE,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC,SAAS,CAAC,IAAK,EAAU,CAAC;QAEzD,KAAK,MAAM,eAAe,IAAI,aAAa,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,eAA2C,CAAQ,CAAC;YAC3E,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,iBAAiB,KAAK,gBAAgB;gBAAE,SAAS;YAErE,MAAM,oBAAoB,GAAG,KAAK,EAAE,eAAe,EAAE,aAAgD,CAAC;YACtG,IAAI,CAAC,oBAAoB,EAAE,CAAC;gBACxB,MAAM,IAAI,KAAK,CACX,2CAA2C,SAAS,MAAM,aAAa,CAAC,UAAU,CAAC,sDAAsD,eAAe,GAAG,CAC9J,CAAC;YACN,CAAC;YAED,MAAM,aAAa,GAAG,gBAAgB,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;YACjE,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CACX,2CAA2C,SAAS,MAAM,aAAa,CAAC,UAAU,CAAC,6BAA6B,oBAAoB,+BAA+B,CACtK,CAAC;YACN,CAAC;YAED,WAAW,CAAC,aAAa,CAAC,CAAC;YAC3B,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAE,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YAC7C,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC7C,SAAS,CAAC,GAAG,CAAC,UAAU,CAAE,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAClD,CAAC;IACL,CAAC;IAED,oCAAoC;IACpC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAc,CAAC;IACtC,MAAM,UAAU,GAAmB,EAAE,CAAC;IAEtC,KAAK,IAAI,UAAU,GAAG,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC;QAC/D,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;YAAE,SAAS;QACtC,MAAM,SAAS,GAAiB,EAAE,CAAC;QACnC,MAAM,KAAK,GAAiB,CAAC,UAAU,CAAC,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACxB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;YAC5B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC9C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACzB,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBACtB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACzB,CAAC;YACL,CAAC;QACL,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;IAED,sFAAsF;IACtF,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAE3E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;QAC/C,aAAa,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QAEhE,KAAK,MAAM,aAAa,IAAI,aAAa,EAAE,CAAC;YACxC,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YAC1C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;gBAAE,SAAS;YAEvC,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAE,CAAC;YACjD,KAAK,MAAM,aAAa,IAAI,IAAI,EAAE,CAAC;gBAC/B,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;gBAChD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CACX,uCAAuC,aAAa,CAAC,aAAa,CAAC,qCAAqC,aAAa,CAAC,aAAa,CAAC,EAAE,CACzI,CAAC;gBACN,CAAC;gBACD,IAAI,WAAW,IAAI,WAAW,EAAE,CAAC;oBAC7B,MAAM,IAAI,KAAK,CACX,iCAAiC,aAAa,CAAC,aAAa,CAAC,eAAe,aAAa,CAAC,aAAa,CAAC,iDAAiD,CAC5J,CAAC;gBACN,CAAC;YACL,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,UAAU;SACZ,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE;QAChB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;QACrC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/utils/resolveResourceChain.d.ts

@@ -0,0 +1,23 @@
+import type { CreationContextJson, ResourceJson, ResourceMissingJson, ResourceOutputPotentialJson, StrategyStateJson } from '@toolproof-core/schema';
+import { CONSTANTS } from '../artifacts/artifacts.js';
+export type ResolveResult = {
+    status: typeof CONSTANTS.Enums.ResourceShellKind.materialized;
+    entry: ResourceJson;
+    path: CreationContextJson[];
+} | {
+    status: typeof CONSTANTS.Enums.ResourceShellKind.missing;
+    entry: ResourceMissingJson;
+    path: CreationContextJson[];
+} | {
+    status: typeof CONSTANTS.Enums.ResourceShellKind.outputPotential;
+    entry: ResourceOutputPotentialJson;
+    path: CreationContextJson[];
+} | {
+    status: 'unresolved';
+    reason: 'not-found' | 'cycle' | 'depth-exceeded';
+    path: CreationContextJson[];
+};
+export declare function resolveResourceChain(strategyState: StrategyStateJson, start: CreationContextJson, opts?: {
+    maxDepth?: number;
+}): ResolveResult;
+//# sourceMappingURL=resolveResourceChain.d.ts.map

package/dist/utils/resolveResourceChain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveResourceChain.d.ts","sourceRoot":"","sources":["../../src/utils/resolveResourceChain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EAEnB,2BAA2B,EAC3B,iBAAiB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEtD,MAAM,MAAM,aAAa,GACnB;IAAE,MAAM,EAAE,OAAO,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,YAAY,CAAC;IAAC,KAAK,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,mBAAmB,EAAE,CAAA;CAAE,GACnH;IAAE,MAAM,EAAE,OAAO,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,mBAAmB,EAAE,CAAA;CAAE,GACrH;IAAE,MAAM,EAAE,OAAO,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,eAAe,CAAC;IAAC,KAAK,EAAE,2BAA2B,CAAC;IAAC,IAAI,EAAE,mBAAmB,EAAE,CAAA;CAAE,GACrI;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,OAAO,GAAG,gBAAgB,CAAC;IAAC,IAAI,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC;AAE9G,wBAAgB,oBAAoB,CAChC,aAAa,EAAE,iBAAiB,EAChC,KAAK,EAAE,mBAAmB,EAC1B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,aAAa,CA8Cf"}

package/dist/utils/resolveResourceChain.js

@@ -0,0 +1,39 @@
+import { CONSTANTS } from '../artifacts/artifacts.js';
+export function resolveResourceChain(strategyState, start, opts) {
+    const maxDepth = opts?.maxDepth ?? 50;
+    const visited = new Set();
+    const path = [];
+    let current = start;
+    for (let depth = 0; depth <= maxDepth; depth++) {
+        path.push(current);
+        const visitKey = `${current.jobStepHandle}::${current.resourceRoleHandle}`;
+        if (visited.has(visitKey)) {
+            return { status: 'unresolved', reason: 'cycle', path };
+        }
+        visited.add(visitKey);
+        const bucket = strategyState[current.jobStepHandle];
+        if (!bucket)
+            return { status: 'unresolved', reason: 'not-found', path };
+        const entry = bucket[current.resourceRoleHandle];
+        if (!entry)
+            return { status: 'unresolved', reason: 'not-found', path };
+        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.materialized) {
+            return { status: CONSTANTS.Enums.ResourceShellKind.materialized, entry: entry, path };
+        }
+        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.missing) {
+            return { status: CONSTANTS.Enums.ResourceShellKind.missing, entry: entry, path };
+        }
+        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.outputPotential) {
+            return { status: CONSTANTS.Enums.ResourceShellKind.outputPotential, entry: entry, path };
+        }
+        // inputPotential: follow ref backwards
+        if (entry.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.inputPotential) {
+            current = entry.creationContext;
+            continue;
+        }
+        // Unknown case
+        return { status: 'unresolved', reason: 'not-found', path };
+    }
+    return { status: 'unresolved', reason: 'depth-exceeded', path };
+}
+//# sourceMappingURL=resolveResourceChain.js.map

package/dist/utils/resolveResourceChain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveResourceChain.js","sourceRoot":"","sources":["../../src/utils/resolveResourceChain.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAQtD,MAAM,UAAU,oBAAoB,CAChC,aAAgC,EAChC,KAA0B,EAC1B,IAA4B;IAE5B,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,IAAI,GAA0B,EAAE,CAAC;IACvC,IAAI,OAAO,GAAwB,KAAK,CAAC;IAEzC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;QAC7C,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnB,MAAM,QAAQ,GAAG,GAAG,OAAO,CAAC,aAAa,KAAK,OAAO,CAAC,kBAAkB,EAAE,CAAC;QAC3E,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3D,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEtB,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QACxE,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAM9C,CAAC;QACF,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QAEvE,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,YAAY,EAAE,CAAC;YAC7E,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,YAAY,EAAE,KAAK,EAAE,KAAqB,EAAE,IAAI,EAAE,CAAC;QAC1G,CAAC;QACD,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC;YACxE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,OAAO,EAAE,KAAK,EAAE,KAA4B,EAAE,IAAI,EAAE,CAAC;QAC5G,CAAC;QACD,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,eAAe,EAAE,CAAC;YAChF,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,eAAe,EAAE,KAAK,EAAE,KAAoC,EAAE,IAAI,EAAE,CAAC;QAC5H,CAAC;QAED,uCAAuC;QACvC,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,cAAc,EAAE,CAAC;YAC/E,OAAO,GAAI,KAAoC,CAAC,eAAe,CAAC;YAChE,SAAS;QACb,CAAC;QAED,eAAe;QACf,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC/D,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;AACpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolproof-core/lib",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "",
   "type": "module",
   "keywords": [],
@@ -15,17 +15,29 @@
       "types": "./dist/types/types.d.ts",
       "import": "./dist/types/types.js"
     },
-    "./extract-from": {
-      "types": "./dist/utils/extractFrom.d.ts",
-      "import": "./dist/utils/extractFrom.js"
+    "./extract-data": {
+      "types": "./dist/utils/extractData.d.ts",
+      "import": "./dist/utils/extractData.js"
     },
-    "./extract-from-resources-by-resource-type-handle": {
-      "types": "./dist/utils/extractFromResourcesByResourceTypeHandle.d.ts",
-      "import": "./dist/utils/extractFromResourcesByResourceTypeHandle.js"
+    "./create-resource": {
+      "types": "./dist/utils/createResource.d.ts",
+      "import": "./dist/utils/createResource.js"
     },
-    "./generate-from": {
-      "types": "./dist/utils/generateFrom.d.ts",
-      "import": "./dist/utils/generateFrom.js"
+    "./create-step": {
+      "types": "./dist/utils/createStep.d.ts",
+      "import": "./dist/utils/createStep.js"
+    },
+    "./create-runnable-strategy": {
+      "types": "./dist/utils/createRunnableStrategy.d.ts",
+      "import": "./dist/utils/createRunnableStrategy.js"
+    },
+    "./resolve-resource-chain": {
+      "types": "./dist/utils/resolveResourceChain.d.ts",
+      "import": "./dist/utils/resolveResourceChain.js"
+    },
+    "./bind-input-role-to-resource": {
+      "types": "./dist/utils/bindInputRoleToResource.d.ts",
+      "import": "./dist/utils/bindInputRoleToResource.js"
     },
     "./firebase-admin-init": {
       "types": "./dist/_lib/setup/firebaseAdminInit.d.ts",
@@ -44,7 +56,7 @@
     "@types/node": "^22.0.0"
   },
   "dependencies": {
-    "@toolproof-core/schema": "^1.0.11",
+    "@toolproof-core/schema": "^1.0.16",
     "firebase-admin": "^13.7.0"
   },
   "scripts": {

package/src/utils/{roleResourceBinding.ts → bindInputRoleToResource.ts}

@@ -6,7 +6,9 @@ import type {
     CreationContextJson,
     StrategyStateJson,
 } from '@toolproof-core/schema';
-import { resolveResourceChain } from './resourceChain.js';
+import { CONSTANTS } from '../artifacts/artifacts.js';
+import { resolveResourceChain } from './resolveResourceChain.js';
+
 
 export function bindInputResInStrategyState(
     strategyState: StrategyStateJson,
@@ -42,7 +44,7 @@ export function bindInputRefInStrategyState(
     const result = resolveResourceChain(strategyState, source);
     const bucket = strategyState[target.jobStepHandle] ?? {};
 
-    if (result.status === 'materialized') {
+    if (result.status === CONSTANTS.Enums.ResourceShellKind.materialized) {
         return {
             ...strategyState,
             [target.jobStepHandle]: {
@@ -52,12 +54,12 @@ export function bindInputRefInStrategyState(
         };
     }
 
-    if (result.status === 'missing') {
+    if (result.status === CONSTANTS.Enums.ResourceShellKind.missing) {
         const missing = result.entry;
         const reusedMissing: ResourceMissingJson = {
             identity: missing.identity,
             resourceTypeHandle: missing.resourceTypeHandle,
-            resourceShellKind: 'missing',
+            resourceShellKind: CONSTANTS.Enums.ResourceShellKind.missing,
         };
 
         return {
@@ -69,7 +71,7 @@ export function bindInputRefInStrategyState(
         };
     }
 
-    if (result.status === 'outputPotential') {
+    if (result.status === CONSTANTS.Enums.ResourceShellKind.outputPotential) {
         const potentialInput: ResourceInputPotentialJson = {
             identity: sourceEntry.identity,
             resourceTypeHandle: sourceEntry.resourceTypeHandle,
@@ -77,7 +79,7 @@ export function bindInputRefInStrategyState(
                 jobStepHandle: source.jobStepHandle,
                 resourceRoleHandle: source.resourceRoleHandle,
             },
-            resourceShellKind: 'inputPotential',
+            resourceShellKind: CONSTANTS.Enums.ResourceShellKind.inputPotential,
         };
 
         return {

package/src/utils/createResource.ts

@@ -0,0 +1,105 @@
+import type {
+    CreationContextJson,
+    ResourceIdentityJson,
+    ResourceInputPotentialJson,
+    ResourceJson,
+    ResourceMissingJson,
+    ResourceOutputPotentialJson,
+    ResourceTypeIdentityJson,
+} from '@toolproof-core/schema';
+import { CONSTANTS } from '../artifacts/artifacts.js';
+
+
+export function generatePath(resourceTypeHandle: ResourceTypeIdentityJson, identity: ResourceIdentityJson): string {
+    return `${resourceTypeHandle}/${identity}.json`;
+}
+
+export function createMaterializedFromOutputPotential(
+    outputPotential: ResourceOutputPotentialJson,
+    nucleus: unknown,
+    timestamp?: string
+): ResourceJson {
+    const { identity, resourceTypeHandle, creationContext } = outputPotential;
+
+    const path = generatePath(resourceTypeHandle, identity);
+
+    return {
+        identity,
+        resourceTypeHandle,
+        creationContext,
+        resourceShellKind: CONSTANTS.Enums.ResourceShellKind.materialized,
+        version: 1,
+        timestamp: timestamp ?? new Date().toISOString(), // Preserve original timestamp when copying
+        path,
+        nucleus,
+    };
+}
+
+export function createMaterializedFromInputPotential(
+    inputPotential: ResourceInputPotentialJson,
+    nucleus: unknown,
+    timestamp?: string
+): ResourceJson {
+    const { identity, resourceTypeHandle, creationContext } = inputPotential;
+
+    const path = generatePath(resourceTypeHandle, identity);
+
+    return {
+        identity,
+        resourceTypeHandle,
+        creationContext,
+        resourceShellKind: CONSTANTS.Enums.ResourceShellKind.materialized,
+        version: 1,
+        timestamp: timestamp ?? new Date().toISOString(),
+        path,
+        nucleus,
+    };
+}
+
+export function createMaterializedFromPotential(
+    potential: ResourceInputPotentialJson | ResourceOutputPotentialJson,
+    nucleus: unknown,
+    timestamp?: string
+): ResourceJson {
+    if (potential.resourceShellKind === CONSTANTS.Enums.ResourceShellKind.inputPotential) {
+        return createMaterializedFromInputPotential(potential, nucleus, timestamp);
+    }
+    return createMaterializedFromOutputPotential(potential, nucleus, timestamp);
+}
+
+export function createMissing(
+    identity: ResourceIdentityJson,
+    resourceTypeHandle: ResourceTypeIdentityJson
+): ResourceMissingJson {
+    return {
+        identity,
+        resourceTypeHandle,
+        resourceShellKind: CONSTANTS.Enums.ResourceShellKind.missing,
+    };
+}
+
+export function createInputPotential(
+    identity: ResourceIdentityJson,
+    resourceTypeHandle: ResourceTypeIdentityJson,
+    creationContext: CreationContextJson
+): ResourceInputPotentialJson {
+    return {
+        identity,
+        resourceTypeHandle,
+        creationContext,
+        resourceShellKind: CONSTANTS.Enums.ResourceShellKind.inputPotential,
+    };
+}
+
+export function createOutputPotential(
+    identity: ResourceIdentityJson,
+    resourceTypeHandle: ResourceTypeIdentityJson,
+    creationContext: CreationContextJson
+): ResourceOutputPotentialJson {
+    return {
+        identity,
+        resourceTypeHandle,
+        creationContext,
+        resourceShellKind: CONSTANTS.Enums.ResourceShellKind.outputPotential,
+    };
+}

package/src/utils/createRunnableStrategy.ts

@@ -0,0 +1,31 @@
+import type {
+    RawStrategyJson,
+    RunnableStrategyJson,
+    StrategyThreadDictJson
+} from '@toolproof-core/schema';
+import { CONSTANTS } from '../artifacts/artifacts.js';
+import { getNewIdentity } from '../firebase/firebaseAdminHelpers.js';
+import { getIndependentThreads } from './parallelizeSteps.js';
+
+export function createRunnableStrategy(rawStrategy: RawStrategyJson): RunnableStrategyJson {
+    const runnableStrategyIdentity = getNewIdentity(CONSTANTS.Names.RunnableStrategyIdentity);
+    const steps = rawStrategy.steps;
+    const strategyState = rawStrategy.strategyState;
+
+    const threadStepGroups = getIndependentThreads(steps, strategyState);
+    const strategyThreadDict: StrategyThreadDictJson = {};
+
+    for (const group of threadStepGroups) {
+        const threadIdentity = getNewIdentity(CONSTANTS.Names.StrategyThreadIdentity);
+        strategyThreadDict[threadIdentity] = group;
+    }
+
+    return {
+        identity: runnableStrategyIdentity,
+        runnableStrategyContext: {
+            status: CONSTANTS.Enums.RunnableStrategyStatus.pending,
+        },
+        strategyThreadDict,
+        strategyState,
+    };
+}

package/src/utils/createStep.ts

@@ -0,0 +1,111 @@
+import type {
+    BranchStepJson,
+    CaseJson,
+    ForStepJson,
+    JobJson,
+    JobStepJson,
+    ResourceRoleIdentityJson,
+    WhileStepJson,
+} from '@toolproof-core/schema';
+import { CONSTANTS } from '../artifacts/artifacts.js';
+import { getNewStepIdentity } from '../firebase/firebaseAdminHelpers.js';
+
+
+function assertNonEmpty<T>(arr: T[], msg: string): asserts arr is [T, ...T[]] {
+    if (arr.length === 0) throw new Error(msg);
+}
+
+
+export function createJobStepFromJob(job: JobJson): JobStepJson {
+    const inputBindings = Object.keys(job.roles.inputDict) as ResourceRoleIdentityJson[];
+    const outputBindings = Object.keys(job.roles.outputDict) as ResourceRoleIdentityJson[];
+
+    return {
+        identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.job),
+        stepKind: CONSTANTS.Enums.StepKind.job,
+        jobHandle: job.identity,
+        roleBindings: {
+            inputBindings,
+            outputBindings,
+        },
+    };
+}
+
+
+export function createLoopStepFromJobPair(
+    whatJob: JobJson,
+    whenJob: JobJson,
+    stepKind: typeof CONSTANTS.Enums.StepKind.for | typeof CONSTANTS.Enums.StepKind.while
+): ForStepJson | WhileStepJson {
+    const what = createJobStepFromJob(whatJob);
+    const when = createJobStepFromJob(whenJob);
+
+    if (stepKind === CONSTANTS.Enums.StepKind.for) {
+        return {
+            identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.for),
+            stepKind: CONSTANTS.Enums.StepKind.for,
+            case: { what, when },
+        };
+    }
+
+    return {
+        identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.while),
+        stepKind: CONSTANTS.Enums.StepKind.while,
+        case: { what, when },
+    };
+}
+
+
+export function createBranchStepFromJobPairs(
+    cases: Array<{ whatJob: JobJson; whenJob: JobJson }>
+): BranchStepJson {
+    const resolved = cases.map(({ whatJob, whenJob }) => {
+        const what = createJobStepFromJob(whatJob);
+        const when = createJobStepFromJob(whenJob);
+        return { what, when } satisfies CaseJson;
+    });
+
+    assertNonEmpty(resolved, 'createBranchStepFromJobPairs requires at least one case'); // ATTENTION_IMPURE
+
+    return {
+        identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.branch),
+        stepKind: CONSTANTS.Enums.StepKind.branch,
+        cases: resolved,
+    };
+}
+
+
+export function cloneForStep(forStep: ForStepJson): ForStepJson {
+    return {
+        identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.for),
+        stepKind: CONSTANTS.Enums.StepKind.for,
+        case: {
+            what: {
+                ...forStep.case.what,
+                identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.job),
+            },
+            when: {
+                ...forStep.case.when,
+                identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.job),
+            },
+        },
+    };
+}
+
+
+export function cloneWhileStep(whileStep: WhileStepJson): WhileStepJson {
+    return {
+        identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.while),
+        stepKind: CONSTANTS.Enums.StepKind.while,
+        case: {
+            what: {
+                ...whileStep.case.what,
+                identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.job),
+            },
+            when: {
+                ...whileStep.case.when,
+                identity: getNewStepIdentity(CONSTANTS.Enums.StepKind.job),
+            },
+        },
+    };
+}

package/src/utils/{extractFrom.ts → extractData.ts}

@@ -7,7 +7,9 @@ import type {
     StepJson,
     ResourceRoleIdentityJson,
     ResourceRoleJson,
-    ErrorJson
+    ResourceIdentityJson,
+    ResourceTypeIdentityJson,
+    ResourceJson,
 } from '@toolproof-core/schema';
 import { CONSTANTS } from '../artifacts/artifacts.js';
 
@@ -90,4 +92,54 @@ export function extractResourceRolesFromRawStrategy(rawStrategy: RawStrategyJson
     }
 
     return Array.from(map.values());
-}
+}
+
+
+export function extractResourceMapForResourceType<TResource extends ResourceJson = ResourceJson>(
+    resourcesByResourceTypeHandle: Partial<Record<ResourceTypeIdentityJson, TResource[]>>,
+    resourceTypeHandle: ResourceTypeIdentityJson
+): Map<ResourceIdentityJson, TResource> {
+    const resources = resourcesByResourceTypeHandle[resourceTypeHandle] ?? [];
+    const map = new Map<ResourceIdentityJson, TResource>();
+
+    for (const resource of resources) {
+        map.set(resource.identity, resource);
+    }
+
+    return map;
+}
+
+// ATTENTION: should only need standalone type as type parameter, then we could extract the nuclueus type and identity type
+export function extractNucleusMapForResourceType<
+    TKey extends string = string,
+    TNucleus extends { identity: string | number | boolean } = { identity: string | number | boolean },
+    TResource extends ResourceJson = ResourceJson
+>(
+    resourcesByResourceTypeHandle: Partial<Record<ResourceTypeIdentityJson, TResource[]>>,
+    resourceTypeHandle: ResourceTypeIdentityJson,
+): Map<TKey, TNucleus> {
+    const resourceMap = extractResourceMapForResourceType<TResource>(resourcesByResourceTypeHandle, resourceTypeHandle);
+    const out = new Map<TKey, TNucleus>();
+
+    for (const resource of resourceMap.values()) {
+        const data = (resource as any).nucleus as unknown;
+        if (data === null || data === undefined) {
+            continue;
+        }
+        if (typeof data !== 'object') {
+            continue;
+        }
+
+        const maybeIdentity = (data as any).identity as unknown;
+        if (maybeIdentity === null || maybeIdentity === undefined) {
+            continue;
+        }
+
+        const value = data as TNucleus;
+        const key = String(maybeIdentity) as TKey;
+
+        out.set(key, value);
+    }
+
+    return out;
+}