@toolproof-core/lib 1.0.24 → 1.0.26

package/src/utils/creation/stepCreation.ts

@@ -4,9 +4,9 @@ import type {
     CaseJson,
     ForStepIdentityJson,
     ForStepJson,
-    JobJson,
-    JobStepIdentityJson,
-    JobStepJson,
+    ToolJson,
+    ToolStepIdentityJson,
+    ToolStepJson,
     ResourceRoleIdentityJson,
     WhileStepIdentityJson,
     WhileStepJson,
@@ -17,19 +17,19 @@ export type LoopStepBuildIdentities =
     | {
         stepKind: typeof CONSTANTS.Enums.StepKind.for;
         stepIdentity: ForStepIdentityJson;
-        whatIdentity: JobStepIdentityJson;
-        whenIdentity: JobStepIdentityJson;
+        whatIdentity: ToolStepIdentityJson;
+        whenIdentity: ToolStepIdentityJson;
     }
     | {
         stepKind: typeof CONSTANTS.Enums.StepKind.while;
         stepIdentity: WhileStepIdentityJson;
-        whatIdentity: JobStepIdentityJson;
-        whenIdentity: JobStepIdentityJson;
+        whatIdentity: ToolStepIdentityJson;
+        whenIdentity: ToolStepIdentityJson;
     };
 
 export type BranchCaseBuildIdentities = {
-    whatIdentity: JobStepIdentityJson;
-    whenIdentity: JobStepIdentityJson;
+    whatIdentity: ToolStepIdentityJson;
+    whenIdentity: ToolStepIdentityJson;
 };
 
 function assertNonEmpty<T>(arr: T[], msg: string): asserts arr is [T, ...T[]] {
@@ -38,32 +38,32 @@ function assertNonEmpty<T>(arr: T[], msg: string): asserts arr is [T, ...T[]] {
     }
 }
 
-function getRoleBindingSpec(job: JobJson): JobStepJson['roleBindingSpec'] {
+function getRoleBindingSpec(tool: ToolJson): ToolStepJson['roleBindingSpec'] {
     return {
-        inputBindings: Object.keys(job.roleSpec.inputRoleValueByIdentity) as ResourceRoleIdentityJson[],
-        outputBindings: Object.keys(job.roleSpec.outputRoleValueByIdentity) as ResourceRoleIdentityJson[],
+        inputBindings: Object.keys(tool.roleSpec.inputRoleValueByIdentity) as ResourceRoleIdentityJson[],
+        outputBindings: Object.keys(tool.roleSpec.outputRoleValueByIdentity) as ResourceRoleIdentityJson[],
     };
 }
 
-export function buildJobStepFromJob(
-    job: JobJson,
-    identity: JobStepIdentityJson,
-): JobStepJson {
+export function buildToolStepFromTool(
+    tool: ToolJson,
+    identity: ToolStepIdentityJson,
+): ToolStepJson {
     return {
         identity,
-        stepKind: CONSTANTS.Enums.StepKind.job,
-        jobHandle: job.identity,
-        roleBindingSpec: getRoleBindingSpec(job),
+        stepKind: CONSTANTS.Enums.StepKind.tool,
+        toolHandle: tool.identity,
+        roleBindingSpec: getRoleBindingSpec(tool),
     };
 }
 
-export function buildLoopStepFromJobPair(
-    whatJob: JobJson,
-    whenJob: JobJson,
+export function buildLoopStepFromToolPair(
+    whatTool: ToolJson,
+    whenTool: ToolJson,
     identities: LoopStepBuildIdentities,
 ): ForStepJson | WhileStepJson {
-    const what = buildJobStepFromJob(whatJob, identities.whatIdentity);
-    const when = buildJobStepFromJob(whenJob, identities.whenIdentity);
+    const what = buildToolStepFromTool(whatTool, identities.whatIdentity);
+    const when = buildToolStepFromTool(whenTool, identities.whenIdentity);
 
     if (identities.stepKind === CONSTANTS.Enums.StepKind.for) {
         return {
@@ -80,28 +80,28 @@ export function buildLoopStepFromJobPair(
     };
 }
 
-export function buildBranchStepFromJobPairs(
-    cases: Array<{ whatJob: JobJson; whenJob: JobJson }>,
+export function buildBranchStepFromToolPairs(
+    cases: Array<{ whatTool: ToolJson; whenTool: ToolJson }>,
     branchIdentity: BranchStepIdentityJson,
     caseIdentities: BranchCaseBuildIdentities[],
 ): BranchStepJson {
     if (cases.length !== caseIdentities.length) {
-        throw new Error('buildBranchStepFromJobPairs requires one identity pair per case');
+        throw new Error('buildBranchStepFromToolPairs requires one identity pair per case');
     }
 
-    const resolved = cases.map(({ whatJob, whenJob }, index) => {
+    const resolved = cases.map(({ whatTool, whenTool }, index) => {
         const identities = caseIdentities[index];
 
         if (!identities) {
             throw new Error(`Missing case identities for case index ${index}`);
         }
 
-        const what = buildJobStepFromJob(whatJob, identities.whatIdentity);
-        const when = buildJobStepFromJob(whenJob, identities.whenIdentity);
+        const what = buildToolStepFromTool(whatTool, identities.whatIdentity);
+        const when = buildToolStepFromTool(whenTool, identities.whenIdentity);
         return { what, when } satisfies CaseJson;
     });
 
-    assertNonEmpty(resolved, 'buildBranchStepFromJobPairs requires at least one case');
+    assertNonEmpty(resolved, 'buildBranchStepFromToolPairs requires at least one case');
 
     return {
         identity: branchIdentity,
@@ -114,8 +114,8 @@ export function cloneForStepWithIdentities(
     forStep: ForStepJson,
     identities: {
         stepIdentity: ForStepIdentityJson;
-        whatIdentity: JobStepIdentityJson;
-        whenIdentity: JobStepIdentityJson;
+        whatIdentity: ToolStepIdentityJson;
+        whenIdentity: ToolStepIdentityJson;
     },
 ): ForStepJson {
     return {
@@ -138,8 +138,8 @@ export function cloneWhileStepWithIdentities(
     whileStep: WhileStepJson,
     identities: {
         stepIdentity: WhileStepIdentityJson;
-        whatIdentity: JobStepIdentityJson;
-        whenIdentity: JobStepIdentityJson;
+        whatIdentity: ToolStepIdentityJson;
+        whenIdentity: ToolStepIdentityJson;
     },
 ): WhileStepJson {
     return {

package/src/utils/extractData.ts

@@ -1,9 +1,9 @@
 import type {
     RawStrategyJson,
-    JobIdentityJson,
-    JobJson,
-    JobStepIdentityJson,
-    JobStepJson,
+    ToolIdentityJson,
+    ToolJson,
+    ToolStepIdentityJson,
+    ToolStepJson,
     StepJson,
     ResourceRoleIdentityJson,
     ResourceRoleJson,
@@ -14,44 +14,44 @@ import type {
 import { CONSTANTS } from '../artifacts/artifacts.js';
 
 
-export function extractJobHandlesFromRawStrategy(rawStrategy: RawStrategyJson): JobIdentityJson[] {
-    const jobSteps = extractJobStepsFromRawStrategy(rawStrategy);
-    const ids = new Set<JobIdentityJson>();
-    for (const jStep of jobSteps) {
-        ids.add(jStep.jobHandle);
+export function extractToolHandlesFromRawStrategy(rawStrategy: RawStrategyJson): ToolIdentityJson[] {
+    const toolSteps = extractToolStepsFromRawStrategy(rawStrategy);
+    const ids = new Set<ToolIdentityJson>();
+    for (const jStep of toolSteps) {
+        ids.add(jStep.toolHandle);
     }
     return Array.from(ids);
 }
 
-export function extractJobStepsFromRawStrategy(rawStrategy: RawStrategyJson): JobStepJson[] {
-    const jobSteps: JobStepJson[] = [];
-    const seen = new Set<JobStepIdentityJson>();
+export function extractToolStepsFromRawStrategy(rawStrategy: RawStrategyJson): ToolStepJson[] {
+    const toolSteps: ToolStepJson[] = [];
+    const seen = new Set<ToolStepIdentityJson>();
 
-    const addJobStep = (jobStep: JobStepJson) => {
-        if (seen.has(jobStep.identity)) {
-            throw new Error(`Duplicate job step identity encountered: ${jobStep.identity}`);
+    const addToolStep = (toolStep: ToolStepJson) => {
+        if (seen.has(toolStep.identity)) {
+            throw new Error(`Duplicate tool step identity encountered: ${toolStep.identity}`);
         }
-        seen.add(jobStep.identity);
-        jobSteps.push(jobStep);
+        seen.add(toolStep.identity);
+        toolSteps.push(toolStep);
     };
 
     const visitStep = (step: StepJson) => {
         switch (step.stepKind) {
-            case CONSTANTS.Enums.StepKind.job: {
-                addJobStep(step);
+            case CONSTANTS.Enums.StepKind.tool: {
+                addToolStep(step);
                 return;
             }
             case CONSTANTS.Enums.StepKind.branch: {
                 for (const conditional of step.cases) {
-                    addJobStep(conditional.when);
-                    addJobStep(conditional.what);
+                    addToolStep(conditional.when);
+                    addToolStep(conditional.what);
                 }
                 return;
             }
             case CONSTANTS.Enums.StepKind.while:
             case CONSTANTS.Enums.StepKind.for: {
-                addJobStep(step.case.when);
-                addJobStep(step.case.what);
+                addToolStep(step.case.when);
+                addToolStep(step.case.what);
                 return;
             }
             default: {
@@ -65,25 +65,25 @@ export function extractJobStepsFromRawStrategy(rawStrategy: RawStrategyJson): Jo
         visitStep(step);
     }
 
-    return jobSteps;
+    return toolSteps;
 }
 
 
-export function extractRoleMapFromRawStrategy(rawStrategy: RawStrategyJson, jobMap: Map<JobIdentityJson, JobJson>): Map<ResourceRoleIdentityJson, ResourceRoleJson> {
+export function extractRoleMapFromRawStrategy(rawStrategy: RawStrategyJson, toolMap: Map<ToolIdentityJson, ToolJson>): Map<ResourceRoleIdentityJson, ResourceRoleJson> {
     const roleMap = new Map<ResourceRoleIdentityJson, ResourceRoleJson>();
-    const jobHandles = extractJobHandlesFromRawStrategy(rawStrategy);
+    const toolHandles = extractToolHandlesFromRawStrategy(rawStrategy);
 
-    for (const jobHandle of jobHandles) {
-        const job = jobMap.get(jobHandle);
-        if (!job) continue;
+    for (const toolHandle of toolHandles) {
+        const tool = toolMap.get(toolHandle);
+        if (!tool) continue;
 
-        for (const [rid, role] of Object.entries(job.roleSpec.inputRoleValueByIdentity)) {
+        for (const [rid, role] of Object.entries(tool.roleSpec.inputRoleValueByIdentity)) {
             roleMap.set(rid as ResourceRoleIdentityJson, {
                 identity: rid as ResourceRoleIdentityJson,
                 ...role,
             });
         }
-        for (const [rid, role] of Object.entries(job.roleSpec.outputRoleValueByIdentity)) {
+        for (const [rid, role] of Object.entries(tool.roleSpec.outputRoleValueByIdentity)) {
             roleMap.set(rid as ResourceRoleIdentityJson, {
                 identity: rid as ResourceRoleIdentityJson,
                 ...role,
@@ -94,11 +94,11 @@ export function extractRoleMapFromRawStrategy(rawStrategy: RawStrategyJson, jobM
     return roleMap;
 }
 
-export function extractSingleNonErrorOutputTypeHandle(job: JobJson): ResourceTypeIdentityJson | null {
+export function extractSingleNonErrorOutputTypeHandle(tool: ToolJson): ResourceTypeIdentityJson | null {
     const errorRoleId = CONSTANTS.Cosmos.ROLE_ErrorOutput;
-    const outputEntries = Object.entries(job.roleSpec.outputRoleValueByIdentity).filter(([roleId]) => roleId !== errorRoleId);
+    const outputEntries = Object.entries(tool.roleSpec.outputRoleValueByIdentity).filter(([roleId]) => roleId !== errorRoleId);
     if (!outputEntries || !outputEntries[0] || outputEntries.length !== 1) {
-        throw new Error(`Job ${job.identity} must have exactly one non-error output role to be branchable/loopable`);
+        throw new Error(`Tool ${tool.identity} must have exactly one non-error output role to be branchable/loopable`);
     } // ATTENTION_PUREIFY
     const outputRole = outputEntries[0][1];
     return outputRole.resourceTypeHandle;
@@ -120,8 +120,8 @@ export function extractResourceMapForType<TResource extends ResourceJson = Resou
     return map;
 }
 
-// ATTENTION: should only need standalone type as type parameter, then we could extract the nuclueus type and identity type
-export function extractNucleusMapForType<
+// Only use this for resource types whose nuclei are entity-like objects with their own intrinsic identity.
+export function extractIdentityKeyedNucleusMapForType<
     TKey extends string = string,
     TNucleus extends { identity: string | number | boolean } = { identity: string | number | boolean },
     TResource extends ResourceJson = ResourceJson
@@ -135,15 +135,30 @@ export function extractNucleusMapForType<
     for (const resource of resourceMap.values()) {
         const data = (resource as any).nucleus as unknown;
         if (data === null || data === undefined) {
-            continue;
+            throw new Error(
+                `Expected resource '${resource.identity}' of type '${resourceTypeHandle}' to have a nucleus`
+            );
         }
         if (typeof data !== 'object') {
-            continue;
+            throw new Error(
+                `Expected resource '${resource.identity}' of type '${resourceTypeHandle}' to have an object nucleus with identity`
+            );
         }
 
         const maybeIdentity = (data as any).identity as unknown;
         if (maybeIdentity === null || maybeIdentity === undefined) {
-            continue;
+            throw new Error(
+                `Expected resource '${resource.identity}' of type '${resourceTypeHandle}' to have nucleus.identity`
+            );
+        }
+        if (
+            typeof maybeIdentity !== 'string' &&
+            typeof maybeIdentity !== 'number' &&
+            typeof maybeIdentity !== 'boolean'
+        ) {
+            throw new Error(
+                `Expected resource '${resource.identity}' of type '${resourceTypeHandle}' to have nucleus.identity as string, number, or boolean`
+            );
         }
 
         const value = data as TNucleus;

package/src/utils/parallelizeSteps.ts

@@ -1,8 +1,8 @@
 import type {
     BranchStepJson,
     ForStepJson,
-    JobStepIdentityJson,
-    JobStepJson,
+    ToolStepIdentityJson,
+    ToolStepJson,
     ResourceRoleIdentityJson,
     StepJson,
     StrategyStateJson,
@@ -19,53 +19,53 @@ export function getIndependentThreads(steps: StepJson[], strategyState: Strategy
         return `steps[${ownerIndex}] stepKind=${(step as any)?.stepKind ?? 'unknown'}`;
     };
 
-    // Map each jobStep.identity (including macro-nested job steps) to owning top-level step index.
-    const jobStepIdToOwner = new Map<JobStepIdentityJson, OwnerIndex>();
-    const ownerToJobStepIds = new Map<OwnerIndex, JobStepIdentityJson[]>();
-    const jobStepById = new Map<JobStepIdentityJson, JobStepJson>();
+    // Map each toolStep.identity (including macro-nested tool steps) to owning top-level step index.
+    const toolStepIdToOwner = new Map<ToolStepIdentityJson, OwnerIndex>();
+    const ownerToToolStepIds = new Map<OwnerIndex, ToolStepIdentityJson[]>();
+    const toolStepById = new Map<ToolStepIdentityJson, ToolStepJson>();
 
-    const addJobStep = (jobStep: JobStepJson | undefined, ownerIndex: OwnerIndex) => {
-        if (!jobStep?.identity) return;
+    const addToolStep = (toolStep: ToolStepJson | undefined, ownerIndex: OwnerIndex) => {
+        if (!toolStep?.identity) return;
 
-        const existingOwner = jobStepIdToOwner.get(jobStep.identity);
+        const existingOwner = toolStepIdToOwner.get(toolStep.identity);
         if (existingOwner !== undefined) {
             throw new Error(
-                `Duplicate jobStep.identity '${jobStep.identity}' found in ${getOwnerLabel(ownerIndex)} and ${getOwnerLabel(existingOwner)}`
+                `Duplicate toolStep.identity '${toolStep.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);
+        toolStepIdToOwner.set(toolStep.identity, ownerIndex);
+        toolStepById.set(toolStep.identity, toolStep);
+        const bucket = ownerToToolStepIds.get(ownerIndex) ?? [];
+        bucket.push(toolStep.identity);
+        ownerToToolStepIds.set(ownerIndex, bucket);
     };
 
     steps.forEach((step, ownerIndex) => {
-        if (step.stepKind === CONSTANTS.Enums.StepKind.job) {
-            addJobStep(step as JobStepJson, ownerIndex);
+        if (step.stepKind === CONSTANTS.Enums.StepKind.tool) {
+            addToolStep(step as ToolStepJson, ownerIndex);
             return;
         }
 
         if (step.stepKind === CONSTANTS.Enums.StepKind.for) {
             const loop = step as ForStepJson;
-            addJobStep(loop.case?.what, ownerIndex);
-            addJobStep(loop.case?.when, ownerIndex);
+            addToolStep(loop.case?.what, ownerIndex);
+            addToolStep(loop.case?.when, ownerIndex);
             return;
         }
 
         if (step.stepKind === CONSTANTS.Enums.StepKind.while) {
             const loop = step as WhileStepJson;
-            addJobStep(loop.case?.what, ownerIndex);
-            addJobStep(loop.case?.when, ownerIndex);
+            addToolStep(loop.case?.what, ownerIndex);
+            addToolStep(loop.case?.when, ownerIndex);
             return;
         }
 
         if (step.stepKind === CONSTANTS.Enums.StepKind.branch) {
             const branch = step as BranchStepJson;
             for (const caseItem of branch.cases ?? []) {
-                addJobStep(caseItem?.what, ownerIndex);
-                addJobStep(caseItem?.when, ownerIndex);
+                addToolStep(caseItem?.what, ownerIndex);
+                addToolStep(caseItem?.when, ownerIndex);
             }
             return;
         }
@@ -86,28 +86,28 @@ export function getIndependentThreads(steps: StepJson[], strategyState: Strategy
     }
 
     // Discover dependencies from strategyState.
-    for (const [jobStepId, ownerIndex] of jobStepIdToOwner) {
+    for (const [toolStepId, ownerIndex] of toolStepIdToOwner) {
         ensureOwner(ownerIndex);
 
-        const jobStep = jobStepById.get(jobStepId);
-        const inputBindings = jobStep?.roleBindingSpec?.inputBindings ?? [];
-        const bucket = strategyState?.[jobStepId] ?? ({} as any);
+        const toolStep = toolStepById.get(toolStepId);
+        const inputBindings = toolStep?.roleBindingSpec?.inputBindings ?? [];
+        const bucket = strategyState?.[toolStepId] ?? ({} as any);
 
         for (const inputRoleHandle of inputBindings) {
             const entry = bucket?.[inputRoleHandle as ResourceRoleIdentityJson] as any;
             if (!entry || entry.resourceShellKind !== 'internalInputPotential') continue;
 
-            const creatorJobStepHandle = entry?.creationContext?.jobStepHandle as JobStepIdentityJson | undefined;
-            if (!creatorJobStepHandle) {
+            const creatorToolStepHandle = entry?.creationContext?.toolStepHandle as ToolStepIdentityJson | undefined;
+            if (!creatorToolStepHandle) {
                 throw new Error(
-                    `Unresolvable internalInputPotential in jobStep '${jobStepId}' (${getOwnerLabel(ownerIndex)}): missing creationContext.jobStepHandle for role '${inputRoleHandle}'`
+                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): missing creationContext.toolStepHandle for role '${inputRoleHandle}'`
                 );
             }
 
-            const producerOwner = jobStepIdToOwner.get(creatorJobStepHandle);
+            const producerOwner = toolStepIdToOwner.get(creatorToolStepHandle);
             if (producerOwner === undefined) {
                 throw new Error(
-                    `Unresolvable internalInputPotential in jobStep '${jobStepId}' (${getOwnerLabel(ownerIndex)}): creator jobStepHandle '${creatorJobStepHandle}' not found in strategy steps`
+                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): creator toolStepHandle '${creatorToolStepHandle}' not found in strategy steps`
                 );
             }
 

package/src/utils/resolveResourceChain.ts

@@ -27,13 +27,13 @@ export function resolveResourceChain(
 
     for (let depth = 0; depth <= maxDepth; depth++) {
         path.push(current);
-        const visitKey = `${current.jobStepHandle}::${current.resourceRoleHandle}`;
+        const visitKey = `${current.toolStepHandle}::${current.resourceRoleHandle}`;
         if (visited.has(visitKey)) {
             return { status: 'unresolved', reason: 'cycle', path };
         }
         visited.add(visitKey);
 
-        const bucket = strategyState[current.jobStepHandle];
+        const bucket = strategyState[current.toolStepHandle];
         if (!bucket) return { status: 'unresolved', reason: 'not-found', path };
         const entry = bucket[current.resourceRoleHandle] as (
             | ResourceJson