@toolproof-core/lib 1.0.28 → 1.0.30

package/src/integrations/firebase/firebaseAdminHelpers.ts

@@ -42,18 +42,18 @@ export function getNewStepId<K extends StepKindJson>(stepKind: K): StepIdStringB
 }
 
 export async function listResources(
-    resourceTypeHandles: ResourceTypeIdJson[],
+    resourceTypeIds: ResourceTypeIdJson[],
 ): Promise<ResourcesByType> {
     const bucketResources = storageAdmin.bucket(CONSTANTS.Persistence.Buckets.tp_resources);
     const bucketStrategies = storageAdmin.bucket(CONSTANTS.Persistence.Buckets.tp_strategies);
 
     async function fetchFilesUnder(
-        resourceTypeHandle: ResourceTypeIdJson,
+        resourceTypeId: ResourceTypeIdJson,
     ): Promise<Array<{ data: unknown; meta: any; name: string }>> {
-        const bucket = resourceTypeHandle === CONSTANTS.Cosmos.TYPE_RunnableStrategy
+        const bucket = resourceTypeId === CONSTANTS.Cosmos.TYPE_RunnableStrategy
             ? bucketStrategies
             : bucketResources;
-        const prefix = `${resourceTypeHandle}/`;
+        const prefix = `${resourceTypeId}/`;
         const [found] = await bucket.getFiles({ prefix });
         const files = found.filter((file) => {
             const name = file.name || '';
@@ -79,8 +79,8 @@ export async function listResources(
     }
 
     const entries = await Promise.all(
-        resourceTypeHandles.map(async (resourceTypeHandle) => {
-            const rows = await fetchFilesUnder(resourceTypeHandle);
+        resourceTypeIds.map(async (resourceTypeId) => {
+            const rows = await fetchFilesUnder(resourceTypeId);
             const items: ResourceJson[] = rows.map(({ data, meta, name }) => {
                 const flat = meta?.metadata ?? {};
                 const root: any = {};
@@ -147,8 +147,8 @@ export async function listResources(
                 }
 
                 const id = root.id;
-                const resourceRoleHandle = root.creationContext.resourceRoleHandle;
-                const toolStepHandle = root.creationContext.toolStepHandle;
+                const resourceRoleId = root.creationContext.resourceRoleId;
+                const toolStepId = root.creationContext.toolStepId;
                 const resourceShellKind = root.resourceShellKind;
                 const versionRaw = root.version;
                 const version = typeof versionRaw === 'number'
@@ -159,8 +159,8 @@ export async function listResources(
 
                 const missing = [
                     ['id', id],
-                    ['resourceRoleHandle', resourceRoleHandle],
-                    ['toolStepHandle', toolStepHandle],
+                    ['resourceRoleId', resourceRoleId],
+                    ['toolStepId', toolStepId],
                     ['resourceShellKind', resourceShellKind],
                     ['version', Number.isFinite(version) ? String(version) : ''],
                     ['timestamp', timestamp],
@@ -174,10 +174,10 @@ export async function listResources(
 
                 return {
                     id,
-                    resourceTypeHandle,
+                    resourceTypeId,
                     creationContext: {
-                        resourceRoleHandle,
-                        toolStepHandle,
+                        resourceRoleId,
+                        toolStepId,
                     },
                     resourceShellKind,
                     version,
@@ -187,7 +187,7 @@ export async function listResources(
                 } as unknown as ResourceJson;
             });
 
-            return [resourceTypeHandle, items] as const;
+            return [resourceTypeId, items] as const;
         }),
     );
 

package/src/utils/bindInputRoleToResource.ts

@@ -16,12 +16,12 @@ export function bindInputResInStrategyState(
     target: CreationContextJson,
     resource: ResourceJson
 ): StrategyStateJson {
-    const bucket = strategyState[target.toolStepHandle] ?? {};
+    const bucket = strategyState[target.toolStepId] ?? {};
     return {
         ...strategyState,
-        [target.toolStepHandle]: {
+        [target.toolStepId]: {
             ...bucket,
-            [target.resourceRoleHandle]: resource,
+            [target.resourceRoleId]: resource,
         },
     };
 }
@@ -31,24 +31,24 @@ export function bindInputRefInStrategyState(
     target: CreationContextJson,
     source: CreationContextJson
 ): StrategyStateJson {
-    const sourceEntry = strategyState?.[source.toolStepHandle]?.[source.resourceRoleHandle] as (
+    const sourceEntry = strategyState?.[source.toolStepId]?.[source.resourceRoleId] as (
         | ResourceJson
         | ResourcePotentialJson
         | undefined
     );
     if (!sourceEntry) {
-        throw new Error(`resourceEntry not found for source (${source.toolStepHandle}, ${source.resourceRoleHandle})`);
+        throw new Error(`resourceEntry not found for source (${source.toolStepId}, ${source.resourceRoleId})`);
     }
 
     const result = resolveResourceChain(strategyState, source);
-    const bucket = strategyState[target.toolStepHandle] ?? {};
+    const bucket = strategyState[target.toolStepId] ?? {};
 
     if (result.status === CONSTANTS.Enums.ResourceShellKind.materialized) {
         return {
             ...strategyState,
-            [target.toolStepHandle]: {
+            [target.toolStepId]: {
                 ...bucket,
-                [target.resourceRoleHandle]: result.entry,
+                [target.resourceRoleId]: result.entry,
             },
         };
     }
@@ -57,15 +57,15 @@ export function bindInputRefInStrategyState(
         const externalInput = result.entry;
         const reusedExternalInput: ExternalInputPotentialShellJson = {
             id: externalInput.id,
-            resourceTypeHandle: externalInput.resourceTypeHandle,
+            resourceTypeId: externalInput.resourceTypeId,
             resourceShellKind: CONSTANTS.Enums.ResourceShellKind.externalInputPotential,
         };
 
         return {
             ...strategyState,
-            [target.toolStepHandle]: {
+            [target.toolStepId]: {
                 ...bucket,
-                [target.resourceRoleHandle]: reusedExternalInput,
+                [target.resourceRoleId]: reusedExternalInput,
             },
         };
     }
@@ -73,19 +73,19 @@ export function bindInputRefInStrategyState(
     if (result.status === CONSTANTS.Enums.ResourceShellKind.outputPotential) {
         const potentialInput: InternalInputPotentialShellJson = {
             id: sourceEntry.id,
-            resourceTypeHandle: sourceEntry.resourceTypeHandle,
+            resourceTypeId: sourceEntry.resourceTypeId,
             creationContext: {
-                toolStepHandle: source.toolStepHandle,
-                resourceRoleHandle: source.resourceRoleHandle,
+                toolStepId: source.toolStepId,
+                resourceRoleId: source.resourceRoleId,
             },
             resourceShellKind: CONSTANTS.Enums.ResourceShellKind.internalInputPotential,
         };
 
         return {
             ...strategyState,
-            [target.toolStepHandle]: {
+            [target.toolStepId]: {
                 ...bucket,
-                [target.resourceRoleHandle]: potentialInput,
+                [target.resourceRoleId]: potentialInput,
             },
         };
     }
@@ -97,14 +97,14 @@ export function clearInputBindingInStrategyState(
     strategyState: StrategyStateJson,
     target: CreationContextJson
 ): StrategyStateJson {
-    const bucket = strategyState?.[target.toolStepHandle];
-    if (!bucket?.[target.resourceRoleHandle]) return strategyState;
+    const bucket = strategyState?.[target.toolStepId];
+    if (!bucket?.[target.resourceRoleId]) return strategyState;
 
     const nextBucket = { ...bucket } as Record<string, unknown>;
-    delete nextBucket[target.resourceRoleHandle];
+    delete nextBucket[target.resourceRoleId];
 
     return {
         ...strategyState,
-        [target.toolStepHandle]: nextBucket as any,
+        [target.toolStepId]: nextBucket as any,
     };
 }

package/src/utils/creation/resourceCreation.ts

@@ -9,8 +9,8 @@ import type {
 } from '@toolproof-core/schema';
 import { CONSTANTS } from '../../artifacts/artifacts.js';
 
-export function generatePath(resourceTypeHandle: ResourceTypeIdJson, id: ResourceIdJson): string {
-    return `${resourceTypeHandle}/${id}.json`;
+export function generatePath(resourceTypeId: ResourceTypeIdJson, id: ResourceIdJson): string {
+    return `${resourceTypeId}/${id}.json`;
 }
 
 export function createMaterializedFromOutputPotential(
@@ -18,12 +18,12 @@ export function createMaterializedFromOutputPotential(
     nucleus: unknown,
     timestamp?: string,
 ): ResourceJson {
-    const { id, resourceTypeHandle, creationContext } = outputPotential;
-    const path = generatePath(resourceTypeHandle, id);
+    const { id, resourceTypeId, creationContext } = outputPotential;
+    const path = generatePath(resourceTypeId, id);
 
     return {
         id,
-        resourceTypeHandle,
+        resourceTypeId,
         creationContext,
         resourceShellKind: CONSTANTS.Enums.ResourceShellKind.materialized,
         version: 1,
@@ -38,12 +38,12 @@ export function createMaterializedFromInputPotential(
     nucleus: unknown,
     timestamp?: string,
 ): ResourceJson {
-    const { id, resourceTypeHandle, creationContext } = inputPotential;
-    const path = generatePath(resourceTypeHandle, id);
+    const { id, resourceTypeId, creationContext } = inputPotential;
+    const path = generatePath(resourceTypeId, id);
 
     return {
         id,
-        resourceTypeHandle,
+        resourceTypeId,
         creationContext,
         resourceShellKind: CONSTANTS.Enums.ResourceShellKind.materialized,
         version: 1,
@@ -67,23 +67,23 @@ export function createMaterializedFromPotential(
 
 export function createExternalInputPotential(
     id: ResourceIdJson,
-    resourceTypeHandle: ResourceTypeIdJson,
+    resourceTypeId: ResourceTypeIdJson,
 ): ExternalInputPotentialShellJson {
     return {
         id,
-        resourceTypeHandle,
+        resourceTypeId,
         resourceShellKind: CONSTANTS.Enums.ResourceShellKind.externalInputPotential,
     };
 }
 
 export function createInputPotential(
     id: ResourceIdJson,
-    resourceTypeHandle: ResourceTypeIdJson,
+    resourceTypeId: ResourceTypeIdJson,
     creationContext: CreationContextJson,
 ): InternalInputPotentialShellJson {
     return {
         id,
-        resourceTypeHandle,
+        resourceTypeId,
         creationContext,
         resourceShellKind: CONSTANTS.Enums.ResourceShellKind.internalInputPotential,
     };
@@ -91,12 +91,12 @@ export function createInputPotential(
 
 export function createOutputPotential(
     id: ResourceIdJson,
-    resourceTypeHandle: ResourceTypeIdJson,
+    resourceTypeId: ResourceTypeIdJson,
     creationContext: CreationContextJson,
 ): OutputPotentialShellJson {
     return {
         id,
-        resourceTypeHandle,
+        resourceTypeId,
         creationContext,
         resourceShellKind: CONSTANTS.Enums.ResourceShellKind.outputPotential,
     };

package/src/utils/creation/stepCreation.ts

@@ -52,7 +52,7 @@ export function buildToolStepFromTool(
     return {
         id,
         stepKind: CONSTANTS.Enums.StepKind.tool,
-        toolHandle: tool.id,
+        toolId: tool.id,
         roleBindingSpec: getRoleBindingSpec(tool),
     };
 }

package/src/utils/extractData.ts

@@ -14,11 +14,11 @@ import type {
 import { CONSTANTS } from '../artifacts/artifacts.js';
 
 
-export function extractToolHandlesFromRawStrategy(rawStrategy: RawStrategyJson): ToolIdJson[] {
+export function extractToolIdsFromRawStrategy(rawStrategy: RawStrategyJson): ToolIdJson[] {
     const toolSteps = extractToolStepsFromRawStrategy(rawStrategy);
     const ids = new Set<ToolIdJson>();
     for (const jStep of toolSteps) {
-        ids.add(jStep.toolHandle);
+        ids.add(jStep.toolId);
     }
     return Array.from(ids);
 }
@@ -71,10 +71,10 @@ export function extractToolStepsFromRawStrategy(rawStrategy: RawStrategyJson): T
 
 export function extractRoleMapFromRawStrategy(rawStrategy: RawStrategyJson, toolMap: Map<ToolIdJson, ToolJson>): Map<ResourceRoleIdJson, ResourceRoleJson> {
     const roleMap = new Map<ResourceRoleIdJson, ResourceRoleJson>();
-    const toolHandles = extractToolHandlesFromRawStrategy(rawStrategy);
+    const toolIds = extractToolIdsFromRawStrategy(rawStrategy);
 
-    for (const toolHandle of toolHandles) {
-        const tool = toolMap.get(toolHandle);
+    for (const toolId of toolIds) {
+        const tool = toolMap.get(toolId);
         if (!tool) continue;
 
         for (const [rid, role] of Object.entries(tool.roleSpec.inputRoleValueById)) {
@@ -94,23 +94,23 @@ export function extractRoleMapFromRawStrategy(rawStrategy: RawStrategyJson, tool
     return roleMap;
 }
 
-export function extractSingleNonErrorOutputTypeHandle(tool: ToolJson): ResourceTypeIdJson | null {
+export function extractSingleNonErrorOutputTypeId(tool: ToolJson): ResourceTypeIdJson | null {
     const errorRoleId = CONSTANTS.Cosmos.ROLE_ErrorOutput;
     const outputEntries = Object.entries(tool.roleSpec.outputRoleValueById).filter(([roleId]) => roleId !== errorRoleId);
     if (!outputEntries || !outputEntries[0] || outputEntries.length !== 1) {
         throw new Error(`Tool ${tool.id} must have exactly one non-error output role to be branchable/loopable`);
     } // ATTENTION_PUREIFY
     const outputRole = outputEntries[0][1];
-    return outputRole.resourceTypeHandle;
+    return outputRole.resourceTypeId;
 }
 
 
 
 export function extractResourceMapForType<TResource extends ResourceJson = ResourceJson>(
     resourcesByType: Partial<Record<ResourceTypeIdJson, TResource[]>>,
-    resourceTypeHandle: ResourceTypeIdJson
+    resourceTypeId: ResourceTypeIdJson
 ): Map<ResourceIdJson, TResource> {
-    const resources = resourcesByType[resourceTypeHandle] ?? [];
+    const resources = resourcesByType[resourceTypeId] ?? [];
     const map = new Map<ResourceIdJson, TResource>();
 
     for (const resource of resources) {
@@ -127,28 +127,28 @@ export function extractIdKeyedNucleusMapForType<
     TResource extends ResourceJson = ResourceJson
 >(
     resourcesByType: Partial<Record<ResourceTypeIdJson, TResource[]>>,
-    resourceTypeHandle: ResourceTypeIdJson,
+    resourceTypeId: ResourceTypeIdJson,
 ): Map<TKey, TNucleus> {
-    const resourceMap = extractResourceMapForType<TResource>(resourcesByType, resourceTypeHandle);
+    const resourceMap = extractResourceMapForType<TResource>(resourcesByType, resourceTypeId);
     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) {
             throw new Error(
-                `Expected resource '${resource.id}' of type '${resourceTypeHandle}' to have a nucleus`
+                `Expected resource '${resource.id}' of type '${resourceTypeId}' to have a nucleus`
             );
         }
         if (typeof data !== 'object') {
             throw new Error(
-                `Expected resource '${resource.id}' of type '${resourceTypeHandle}' to have an object nucleus with id`
+                `Expected resource '${resource.id}' of type '${resourceTypeId}' to have an object nucleus with id`
             );
         }
 
         const maybeId = (data as any).id as unknown;
         if (maybeId === null || maybeId === undefined) {
             throw new Error(
-                `Expected resource '${resource.id}' of type '${resourceTypeHandle}' to have nucleus.id`
+                `Expected resource '${resource.id}' of type '${resourceTypeId}' to have nucleus.id`
             );
         }
         if (
@@ -157,7 +157,7 @@ export function extractIdKeyedNucleusMapForType<
             typeof maybeId !== 'boolean'
         ) {
             throw new Error(
-                `Expected resource '${resource.id}' of type '${resourceTypeHandle}' to have nucleus.id as string, number, or boolean`
+                `Expected resource '${resource.id}' of type '${resourceTypeId}' to have nucleus.id as string, number, or boolean`
             );
         }
 

package/src/utils/parallelizeSteps.ts

@@ -97,17 +97,17 @@ export function getIndependentThreads(steps: StepJson[], strategyState: Strategy
             const entry = bucket?.[inputRoleHandle as ResourceRoleIdJson] as any;
             if (!entry || entry.resourceShellKind !== 'internalInputPotential') continue;
 
-            const creatorToolStepHandle = entry?.creationContext?.toolStepHandle as ToolStepIdJson | undefined;
-            if (!creatorToolStepHandle) {
+            const creatorToolStepId = entry?.creationContext?.toolStepId as ToolStepIdJson | undefined;
+            if (!creatorToolStepId) {
                 throw new Error(
-                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): missing creationContext.toolStepHandle for role '${inputRoleHandle}'`
+                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): missing creationContext.toolStepId for role '${inputRoleHandle}'`
                 );
             }
 
-            const producerOwner = toolStepIdToOwner.get(creatorToolStepHandle);
+            const producerOwner = toolStepIdToOwner.get(creatorToolStepId);
             if (producerOwner === undefined) {
                 throw new Error(
-                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): creator toolStepHandle '${creatorToolStepHandle}' not found in strategy steps`
+                    `Unresolvable internalInputPotential in toolStep '${toolStepId}' (${getOwnerLabel(ownerIndex)}): creator toolStepId '${creatorToolStepId}' not found in strategy steps`
                 );
             }
 

package/src/utils/resolveResourceChain.ts

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