@toolproof-core/lib 1.0.33 → 1.0.36

package/src/utils/creation/resourceCreation.ts

@@ -1,121 +1,140 @@
-import type {
-    CreationContext,
-    ExternalInput,
-    ReferenceInput,
-    ResourceId,
-    Resource,
-    ResourceTypeId,
-    StrategyRunId,
-} from '@toolproof-core/schema';
-
-export interface OutputPotential {
-    id: ResourceId;
-    resourceTypeId: ResourceTypeId;
-    creationContext: CreationContext;
-    strategyRunId?: StrategyRunId;
-}
-
-export type InputPotential = ReferenceInput & {
-    id: ResourceId;
-    resourceTypeId: ResourceTypeId;
-    creationContext: CreationContext;
-    strategyRunId?: StrategyRunId;
-};
-
-export function generatePath(resourceTypeId: ResourceTypeId, id: ResourceId): string {
-    return `${resourceTypeId}/${id}.json`;
-}
-
-export function createMaterializedFromOutputPotential(
-    outputPotential: OutputPotential,
-    nucleus: unknown,
-    timestamp?: string,
-): Resource {
-    const { id, resourceTypeId, creationContext } = outputPotential;
-    const path = generatePath(resourceTypeId, id);
-
-    return {
-        id,
-        resourceTypeId,
-        provenance: {
-            resourceProvenanceKind: 'strategy',
-            strategyRunId: outputPotential.strategyRunId ?? ('STRATEGY_RUN-UNKNOWN' as StrategyRunId),
-            creationContext,
-        },
-        version: 1,
-        timestamp: timestamp ?? new Date().toISOString(),
-        path,
-        nucleus,
-    };
-}
-
-export function createMaterializedFromInputPotential(
-    inputPotential: InputPotential,
-    nucleus: unknown,
-    timestamp?: string,
-): Resource {
-    const { id, resourceTypeId, creationContext } = inputPotential;
-    const path = generatePath(resourceTypeId, id);
-
-    return {
-        id,
-        resourceTypeId,
-        provenance: {
-            resourceProvenanceKind: 'strategy',
-            strategyRunId: inputPotential.strategyRunId ?? ('STRATEGY_RUN-UNKNOWN' as StrategyRunId),
-            creationContext,
-        },
-        version: 1,
-        timestamp: timestamp ?? new Date().toISOString(),
-        path,
-        nucleus,
-    };
-}
-
-export function createMaterializedFromPotential(
-    potential: InputPotential | OutputPotential,
-    nucleus: unknown,
-    timestamp?: string,
-): Resource {
-    if ('strategyStateInputKind' in potential && potential.strategyStateInputKind === 'referenceInput') {
-        return createMaterializedFromInputPotential(potential, nucleus, timestamp);
-    }
-
-    return createMaterializedFromOutputPotential(potential, nucleus, timestamp);
-}
-
-export function createExternalInputPotential(
-    _id: ResourceId,
-    _resourceTypeId: ResourceTypeId,
-): ExternalInput {
-    return {
-        strategyStateInputKind: 'externalInput',
-    };
-}
-
-export function createInputPotential(
-    id: ResourceId,
-    resourceTypeId: ResourceTypeId,
-    creationContext: CreationContext,
-): InputPotential {
-    return {
-        id,
-        resourceTypeId,
-        strategyStateInputKind: 'referenceInput',
-        toolStepPath: creationContext.toolStepPath,
-        roleName: creationContext.roleName,
-        creationContext,
-    };
-}
-
-export function createOutputPotential(
-    id: ResourceId,
-    resourceTypeId: ResourceTypeId,
-    creationContext: CreationContext,
-): OutputPotential {
-    return {
-        id,
-        resourceTypeId,
-        creationContext,
-    };
-}
+import type {
+    ToolStepRoleAddress,
+    ExternalInputPotential,
+    InternalInputPotential,
+    ResourceId,
+    Resource,
+    ResourcePointer,
+    ResourceTypeHandle,
+    StrategyProvenance,
+    Provenance,
+    StrategyTraceHandle,
+} from '@toolproof-core/genesis';
+
+type RuntimeProvenance = Extract<Provenance, { provenanceKind: 'runtime' }>;
+
+export interface OutputPotential {
+    id: ResourceId;
+    resourceTypeHandle: ResourceTypeHandle;
+    toolStepRoleAddress?: ToolStepRoleAddress;
+    strategyTraceHandle?: StrategyTraceHandle;
+    provenanceKind?: Provenance['provenanceKind'];
+}
+
+export function createExternalInputPotential(): ExternalInputPotential {
+    return {
+        strategyStateInputKind: 'externalInputPotential',
+    };
+}
+
+export function createInternalInputPotential(
+    toolStepRoleAddress: ToolStepRoleAddress,
+): InternalInputPotential {
+    return {
+        strategyStateInputKind: 'internalInputPotential',
+        toolStepRoleAddress,
+    };
+}
+
+export function createStrategyProvenance(
+    strategyTraceHandle: StrategyTraceHandle,
+    toolStepRoleAddress: ToolStepRoleAddress,
+): StrategyProvenance {
+    return {
+        provenanceKind: 'strategy',
+        strategyTraceHandle,
+        toolStepRoleAddress,
+    };
+}
+
+export function createRuntimeProvenance(): RuntimeProvenance {
+    return {
+        provenanceKind: 'runtime',
+    };
+}
+
+export function createResourcePointer(
+    id: ResourceId,
+    resourceTypeHandle: ResourceTypeHandle,
+    provenance: Provenance,
+): ResourcePointer {
+    return {
+        id,
+        resourceTypeHandle,
+        provenance,
+    };
+}
+
+export function createResource(
+    resourcePointer: ResourcePointer,
+    projection: unknown,
+): Resource {
+    return {
+        ...resourcePointer,
+        projection,
+    };
+}
+
+export function createMaterializedFromOutputPotential(
+    outputPotential: OutputPotential,
+    projection: unknown,
+): Resource {
+    const provenance = outputPotential.provenanceKind === 'runtime'
+        ? createRuntimeProvenance()
+        : createStrategyProvenance(
+            requireStrategyTraceHandle(outputPotential.strategyTraceHandle),
+            requireToolStepRoleAddress(outputPotential.toolStepRoleAddress),
+        );
+
+    const resourcePointer = createResourcePointer(
+        outputPotential.id,
+        outputPotential.resourceTypeHandle,
+        provenance,
+    );
+
+    return createResource(resourcePointer, projection);
+}
+
+export function createMaterializedFromPotential(
+    outputPotential: OutputPotential,
+    projection: unknown,
+): Resource {
+    return createMaterializedFromOutputPotential(outputPotential, projection);
+}
+
+export function createOutputPotential(
+    id: ResourceId,
+    resourceTypeHandle: ResourceTypeHandle,
+    toolStepRoleAddress?: ToolStepRoleAddress,
+    strategyTraceHandle?: StrategyTraceHandle,
+    provenanceKind?: Provenance['provenanceKind'],
+): OutputPotential {
+    return {
+        id,
+        resourceTypeHandle,
+        ...(toolStepRoleAddress ? { toolStepRoleAddress } : {}),
+        ...(strategyTraceHandle ? { strategyTraceHandle } : {}),
+        ...(provenanceKind ? { provenanceKind } : {}),
+    };
+}
+
+function requireStrategyTraceHandle(
+    strategyTraceHandle: StrategyTraceHandle | undefined,
+): StrategyTraceHandle {
+    if (!strategyTraceHandle) {
+        throw new Error('strategyTraceHandle is required to materialize a strategy output potential');
+    }
+
+    return strategyTraceHandle;
+}
+
+function requireToolStepRoleAddress(
+    toolStepRoleAddress: ToolStepRoleAddress | undefined,
+): ToolStepRoleAddress {
+    if (!toolStepRoleAddress) {
+        throw new Error('toolStepRoleAddress is required to materialize a strategy output potential');
+    }
+
+    return toolStepRoleAddress;
+}
+

package/src/utils/creation/stepCreation.ts

@@ -5,39 +5,10 @@ import type {
     Tool,
     ToolStep,
     WhileStep,
-} from '@toolproof-core/schema';
-import { CONSTANTS } from '../../artifacts/artifacts.js';
+} from '@toolproof-core/genesis';
+import { CONSTANTS } from '../../lookups/lookups.js';
 import { getInputRoleNames, getOutputRoleNames } from '../roleSpec.js';
 
-type ToolStepId = string;
-type BranchStepId = string;
-type ForStepId = string;
-type WhileStepId = string;
-
-type ToolStepWithId = ToolStep & { id: ToolStepId };
-type BranchStepWithId = BranchStep & { id: BranchStepId };
-type ForStepWithId = ForStep & { id: ForStepId };
-type WhileStepWithId = WhileStep & { id: WhileStepId };
-
-export type LoopStepBuildIdentities =
-    | {
-        stepKind: typeof CONSTANTS.Enums.StepKind.for;
-        stepId: ForStepId;
-        whatId: ToolStepId;
-        whenId: ToolStepId;
-    }
-    | {
-        stepKind: typeof CONSTANTS.Enums.StepKind.while;
-        stepId: WhileStepId;
-        whatId: ToolStepId;
-        whenId: ToolStepId;
-    };
-
-export type BranchCaseBuildIdentities = {
-    whatId: ToolStepId;
-    whenId: ToolStepId;
-};
-
 function assertNonEmpty<T>(arr: T[], msg: string): asserts arr is [T, ...T[]] {
     if (arr.length === 0) {
         throw new Error(msg);
@@ -53,113 +24,72 @@ function getRoleBindingSpec(tool: Tool): ToolStep['roleBindingSpec'] {
 
 export function buildToolStepFromTool(
     tool: Tool,
-    id: ToolStepId,
-): ToolStepWithId {
+): ToolStep {
     return {
-        id,
         stepKind: CONSTANTS.Enums.StepKind.tool,
-        toolId: tool.id,
+        toolHandle: tool.handle,
         roleBindingSpec: getRoleBindingSpec(tool),
-    } as ToolStepWithId;
+    };
 }
 
 export function buildLoopStepFromToolPair(
     whatTool: Tool,
     whenTool: Tool,
-    identities: LoopStepBuildIdentities,
+    stepKind: typeof CONSTANTS.Enums.StepKind.for | typeof CONSTANTS.Enums.StepKind.while,
 ): ForStep | WhileStep {
-    const what = buildToolStepFromTool(whatTool, identities.whatId);
-    const when = buildToolStepFromTool(whenTool, identities.whenId);
+    const what = buildToolStepFromTool(whatTool);
+    const when = buildToolStepFromTool(whenTool);
 
-    if (identities.stepKind === CONSTANTS.Enums.StepKind.for) {
+    if (stepKind === CONSTANTS.Enums.StepKind.for) {
         return {
-            id: identities.stepId,
             stepKind: CONSTANTS.Enums.StepKind.for,
             case: { what, when },
-        } as ForStepWithId;
+        };
     }
 
     return {
-        id: identities.stepId,
         stepKind: CONSTANTS.Enums.StepKind.while,
         case: { what, when },
-    } as WhileStepWithId;
+    };
 }
 
 export function buildBranchStepFromToolPairs(
     cases: Array<{ whatTool: Tool; whenTool: Tool }>,
-    branchId: BranchStepId,
-    caseIdentities: BranchCaseBuildIdentities[],
-): BranchStepWithId {
-    if (cases.length !== caseIdentities.length) {
-        throw new Error('buildBranchStepFromToolPairs requires one id pair per case');
-    }
-
+): BranchStep {
     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 = buildToolStepFromTool(whatTool, identities.whatId);
-        const when = buildToolStepFromTool(whenTool, identities.whenId);
+        const what = buildToolStepFromTool(whatTool);
+        const when = buildToolStepFromTool(whenTool);
         return { what, when } satisfies Case;
     });
 
     assertNonEmpty(resolved, 'buildBranchStepFromToolPairs requires at least one case');
 
     return {
-        id: branchId,
         stepKind: CONSTANTS.Enums.StepKind.branch,
         cases: resolved,
-    } as BranchStepWithId;
+    };
 }
 
-export function cloneForStepWithIdentities(
+export function cloneForStep(
     forStep: ForStep,
-    identities: {
-        stepId: ForStepId;
-        whatId: ToolStepId;
-        whenId: ToolStepId;
-    },
-): ForStepWithId {
+): ForStep {
     return {
-        id: identities.stepId,
         stepKind: CONSTANTS.Enums.StepKind.for,
         case: {
-            what: {
-                ...forStep.case.what,
-                id: identities.whatId,
-            },
-            when: {
-                ...forStep.case.when,
-                id: identities.whenId,
-            },
+            what: { ...forStep.case.what },
+            when: { ...forStep.case.when },
         },
-    } as ForStepWithId;
+    };
 }
 
-export function cloneWhileStepWithIdentities(
+export function cloneWhileStep(
     whileStep: WhileStep,
-    identities: {
-        stepId: WhileStepId;
-        whatId: ToolStepId;
-        whenId: ToolStepId;
-    },
-): WhileStepWithId {
+): WhileStep {
     return {
-        id: identities.stepId,
         stepKind: CONSTANTS.Enums.StepKind.while,
         case: {
-            what: {
-                ...whileStep.case.what,
-                id: identities.whatId,
-            },
-            when: {
-                ...whileStep.case.when,
-                id: identities.whenId,
-            },
+            what: { ...whileStep.case.what },
+            when: { ...whileStep.case.when },
         },
-    } as WhileStepWithId;
+    };
 }

package/src/utils/creation/threadedStrategyCreation.ts

@@ -0,0 +1,42 @@
+import type {
+    Step,
+    StrategyHandle,
+} from '@toolproof-core/genesis';
+import { getIndependentThreads } from '../parallelizeSteps.js';
+import { CONSTANTS } from '../../lookups/lookups.js';
+
+export type ThreadableStrategy<TStrategyState = unknown> = {
+    handle: StrategyHandle;
+    strategyState: TStrategyState;
+} & (
+    | { steps: Step[] }
+    | { stepsByThreadIndex: Step[][] }
+);
+
+export type ThreadedStrategyLike<TStrategyState = unknown> = {
+    handle: StrategyHandle;
+    strategyKind: typeof CONSTANTS.Enums.StrategyKind.threaded;
+    stepsByThreadIndex: Step[][];
+    strategyState: TStrategyState;
+};
+
+export function getThreadedStrategyStepGroups<TStrategyState>(strategy: ThreadableStrategy<TStrategyState>): Step[][] {
+    if ('steps' in strategy) {
+        return getIndependentThreads(strategy.steps, strategy.strategyState as any);
+    }
+
+    return strategy.stepsByThreadIndex;
+}
+
+export function buildThreadedStrategy<TStrategyState>(
+    threadStepGroups: Step[][],
+    threadedStrategyHandle: StrategyHandle,
+    strategy: ThreadableStrategy<TStrategyState>,
+): ThreadedStrategyLike<TStrategyState> {
+    return {
+        handle: threadedStrategyHandle,
+        strategyKind: CONSTANTS.Enums.StrategyKind.threaded,
+        stepsByThreadIndex: threadStepGroups,
+        strategyState: strategy.strategyState,
+    };
+}

package/src/utils/extractData.ts

@@ -1,44 +1,54 @@
 import type {
     RoleName,
-    RoleValue,
-    Strategy,
-    ToolId,
+    ToolHandle,
     Tool,
     ToolStep,
     ResourceId,
-    ResourceTypeId,
+    ResourceTypeHandle,
     Resource,
-} from '@toolproof-core/schema';
-import { CONSTANTS } from '../artifacts/artifacts.js';
+} from '@toolproof-core/genesis';
 import {
     extractToolStepsFromStrategy,
     getInputRoleEntries,
     getOutputRoleEntries,
     toToolRoleDescriptor,
+    type StrategyStepGraph,
     type ToolRoleDescriptor,
 } from './roleSpec.js';
 
+const ERROR_OUTPUT_ROLE_NAME = 'ErrorOutput' as RoleName;
 
-export function extractToolIdsFromRawStrategy(rawStrategy: Strategy): ToolId[] {
-    const toolSteps = extractToolStepsFromRawStrategy(rawStrategy);
-    const ids = new Set<ToolId>();
+function extractResourceTypeHandleFromRoleValue(toolRoleValue: ToolRoleDescriptor): ResourceTypeHandle | null {
+    const typeRef = toolRoleValue.typeRef;
+
+    if ('resourceTypeHandle' in typeRef) {
+        return typeRef.resourceTypeHandle;
+    }
+
+    return null;
+}
+
+
+export function extractToolHandlesFromUnthreadedStrategy(unthreadedStrategy: StrategyStepGraph): ToolHandle[] {
+    const toolSteps = extractToolStepsFromUnthreadedStrategy(unthreadedStrategy);
+    const ids = new Set<ToolHandle>();
     for (const jStep of toolSteps) {
-        ids.add(jStep.toolId);
+        ids.add(jStep.toolHandle);
     }
     return Array.from(ids);
 }
 
-export function extractToolStepsFromRawStrategy(rawStrategy: Strategy): ToolStep[] {
-    return extractToolStepsFromStrategy(rawStrategy);
+export function extractToolStepsFromUnthreadedStrategy(unthreadedStrategy: StrategyStepGraph): ToolStep[] {
+    return extractToolStepsFromStrategy(unthreadedStrategy);
 }
 
 
-export function extractRoleMapFromRawStrategy(rawStrategy: Strategy, toolMap: Map<ToolId, Tool>): Map<RoleName, ToolRoleDescriptor> {
+export function extractRoleMapFromUnthreadedStrategy(unthreadedStrategy: StrategyStepGraph, toolMap: Map<ToolHandle, Tool>): Map<RoleName, ToolRoleDescriptor> {
     const roleMap = new Map<RoleName, ToolRoleDescriptor>();
-    const toolIds = extractToolIdsFromRawStrategy(rawStrategy);
+    const toolHandles = extractToolHandlesFromUnthreadedStrategy(unthreadedStrategy);
 
-    for (const toolId of toolIds) {
-        const tool = toolMap.get(toolId);
+    for (const toolHandle of toolHandles) {
+        const tool = toolMap.get(toolHandle);
         if (!tool) continue;
 
         for (const entry of getInputRoleEntries(tool)) {
@@ -52,23 +62,21 @@ export function extractRoleMapFromRawStrategy(rawStrategy: Strategy, toolMap: Ma
     return roleMap;
 }
 
-export function extractSingleNonErrorOutputTypeId(tool: Tool): ResourceTypeId | null {
-    const errorRoleId = CONSTANTS.Cosmos.ROLE_ErrorOutput;
-    const outputEntries = getOutputRoleEntries(tool).filter(([roleName]) => roleName !== errorRoleId);
+export function extractSingleNonErrorOutputTypeId(tool: Tool): ResourceTypeHandle | null {
+    const outputEntries = getOutputRoleEntries(tool).filter(([roleName]) => roleName !== ERROR_OUTPUT_ROLE_NAME);
     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`);
+        throw new Error(`Tool ${tool.handle} must have exactly one non-error output role to be branchable/loopable`);
     } // ATTENTION_PUREIFY
-    const outputRole = outputEntries[0][1] as RoleValue;
-    return outputRole.resourceTypeId;
+    return extractResourceTypeHandleFromRoleValue(toToolRoleDescriptor(outputEntries[0]));
 }
 
 
 
 export function extractResourceMapForType<TResource extends Resource = Resource>(
-    resourcesByType: Partial<Record<ResourceTypeId, TResource[]>>,
-    resourceTypeId: ResourceTypeId
+    resourcesByType: Partial<Record<ResourceTypeHandle, TResource[]>>,
+    resourceTypeHandle: ResourceTypeHandle
 ): Map<ResourceId, TResource> {
-    const resources = resourcesByType[resourceTypeId] ?? [];
+    const resources = resourcesByType[resourceTypeHandle] ?? [];
     const map = new Map<ResourceId, TResource>();
 
     for (const resource of resources) {
@@ -79,34 +87,34 @@ export function extractResourceMapForType<TResource extends Resource = Resource>
 }
 
 // Only use this for resource types whose nuclei are entity-like objects with their own intrinsic id.
-export function extractIdKeyedNucleusMapForType<
+export function extractIdKeyedValueMapForType<
     TKey extends string = string,
-    TNucleus extends { id: string | number | boolean } = { id: string | number | boolean },
+    TValue extends { id: string | number | boolean } = { id: string | number | boolean },
     TResource extends Resource = Resource
 >(
-    resourcesByType: Partial<Record<ResourceTypeId, TResource[]>>,
-    resourceTypeId: ResourceTypeId,
-): Map<TKey, TNucleus> {
-    const resourceMap = extractResourceMapForType<TResource>(resourcesByType, resourceTypeId);
-    const out = new Map<TKey, TNucleus>();
+    resourcesByType: Partial<Record<ResourceTypeHandle, TResource[]>>,
+    resourceTypeHandle: ResourceTypeHandle,
+): Map<TKey, TValue> {
+    const resourceMap = extractResourceMapForType<TResource>(resourcesByType, resourceTypeHandle);
+    const out = new Map<TKey, TValue>();
 
     for (const resource of resourceMap.values()) {
-        const data = (resource as any).nucleus as unknown;
+        const data = resource.projection as unknown;
         if (data === null || data === undefined) {
             throw new Error(
-                `Expected resource '${resource.id}' of type '${resourceTypeId}' to have a nucleus`
+                `Expected resource '${resource.id}' of type '${resourceTypeHandle}' to have a projection`
             );
         }
         if (typeof data !== 'object') {
             throw new Error(
-                `Expected resource '${resource.id}' of type '${resourceTypeId}' to have an object nucleus with id`
+                `Expected resource '${resource.id}' of type '${resourceTypeHandle}' to have an object projection with id`
             );
         }
 
         const maybeId = (data as any).id as unknown;
         if (maybeId === null || maybeId === undefined) {
             throw new Error(
-                `Expected resource '${resource.id}' of type '${resourceTypeId}' to have nucleus.id`
+                `Expected resource '${resource.id}' of type '${resourceTypeHandle}' to have projection.id`
             );
         }
         if (
@@ -115,11 +123,11 @@ export function extractIdKeyedNucleusMapForType<
             typeof maybeId !== 'boolean'
         ) {
             throw new Error(
-                `Expected resource '${resource.id}' of type '${resourceTypeId}' to have nucleus.id as string, number, or boolean`
+                `Expected resource '${resource.id}' of type '${resourceTypeHandle}' to have projection.id as string, number, or boolean`
             );
         }
 
-        const value = data as TNucleus;
+        const value = data as TValue;
         const key = String(maybeId) as TKey;
 
         out.set(key, value);