@toolproof-core/lib 1.0.3 → 1.0.5

package/src/shared.ts

@@ -0,0 +1,126 @@
+import type {
+    CreationContextJson,
+    JsonDataJson,
+    ResourceIdentityJson,
+    ResourceInputPotentialJson,
+    ResourceJson,
+    ResourceMissingJson,
+    ResourceOutputPotentialJson,
+    ResourceTypeIdentityJson,
+} from '@toolproof-core/schema';
+
+import { resolveResourceChain } from './utils/resourceChain.js';
+import {
+    bindInputRefInStrategyState,
+    bindInputResInStrategyState,
+    clearInputBindingInStrategyState,
+} from './utils/roleResourceBinding.js';
+import { createRunnableStrategy } from './utils/runnableStrategyCreation.js';
+import {
+    cloneForStep,
+    cloneWhileStep,
+    createBranchStepFromJobPairs,
+    createJobStepFromJob,
+    createLoopStepFromJobs,
+} from './utils/stepCreation.js';
+
+
+export const RESOURCE_CHAIN = {
+    resolveResourceChain,
+} as const;
+
+
+export const ROLE_RESOURCE_BINDINGS = {
+    bindInputResInStrategyState,
+    bindInputRefInStrategyState,
+    clearInputBindingInStrategyState,
+} as const;
+
+
+export const RUNNABLE_STRATEGY_CREATION = {
+    createRunnableStrategy,
+} as const;
+
+
+export const STEP_CREATION = {
+    createJobStepFromJob,
+    createLoopStepFromJobs,
+    createBranchStepFromJobPairs,
+    cloneForStep,
+    cloneWhileStep,
+} as const;
+
+
+function asMaterializedResource(
+    base: {
+        identity: ResourceIdentityJson;
+        resourceTypeHandle: ResourceTypeIdentityJson;
+        creationContext: CreationContextJson;
+    },
+    nucleus: JsonDataJson,
+    opts?: { path?: string; timestamp?: string }
+): ResourceJson {
+    return {
+        identity: base.identity,
+        resourceTypeHandle: base.resourceTypeHandle,
+        creationContext: base.creationContext,
+        resourceShellKind: 'materialized',
+        version: 1,
+        timestamp: opts?.timestamp ?? new Date().toISOString(),
+        path: opts?.path ?? '',
+        nucleus,
+    } as unknown as ResourceJson;
+}
+
+
+export const RESOURCE_CREATION = {
+    createMissingResource(identity: ResourceIdentityJson, resourceTypeHandle: ResourceTypeIdentityJson): ResourceMissingJson {
+        return {
+            identity,
+            resourceTypeHandle,
+            resourceShellKind: 'missing',
+        };
+    },
+
+    createOutputPotentialResource(
+        identity: ResourceIdentityJson,
+        resourceTypeHandle: ResourceTypeIdentityJson,
+        creationContext: CreationContextJson
+    ): ResourceOutputPotentialJson {
+        return {
+            identity,
+            resourceTypeHandle,
+            creationContext,
+            resourceShellKind: 'outputPotential',
+        };
+    },
+
+    createInputPotentialResource(
+        identity: ResourceIdentityJson,
+        resourceTypeHandle: ResourceTypeIdentityJson,
+        creationContext: CreationContextJson
+    ): ResourceInputPotentialJson {
+        return {
+            identity,
+            resourceTypeHandle,
+            creationContext,
+            resourceShellKind: 'inputPotential',
+        };
+    },
+
+    createMaterializedResourceFromPotential(
+        potential: ResourceOutputPotentialJson | ResourceInputPotentialJson,
+        nucleus: JsonDataJson,
+        opts?: { path?: string; timestamp?: string }
+    ): ResourceJson {
+        return asMaterializedResource(
+            {
+                identity: potential.identity,
+                resourceTypeHandle: potential.resourceTypeHandle,
+                creationContext: potential.creationContext,
+            },
+            nucleus,
+            opts
+        );
+    },
+} as const;

package/src/types/types.ts

@@ -1,25 +1,21 @@
-import type {
-	StepKindJson,
-	ResourceJson,
-	ResourceRoleIdentityJson,
-	ResourceRoleValueJson,
-	ResourceTypeIdentityJson,
-} from '@toolproof-core/schema';
-import { CONSTANTS } from '../artifacts/artifacts.js';
-import { MAPPINGS } from '../artifacts/artifacts.js';
-
-export type Bucket = typeof CONSTANTS.Persistence.Buckets.tp_resources;
-
-export type Collection = keyof typeof CONSTANTS.Persistence.Collections;
-
-export type SchemaLike = Record<string, unknown>;
-
-export type Role = { identity: ResourceRoleIdentityJson } & ResourceRoleValueJson;
-
-export type ResourceMap = Record<ResourceTypeIdentityJson, ResourceJson[]>;
-
-export type IdentityName = keyof typeof MAPPINGS.IdentityNameToIdentityPrefix;
-
-export type IdentityStringByIdentityName<K extends IdentityName> = `${(typeof MAPPINGS.IdentityNameToIdentityPrefix)[K]}${string}`;
-
+import type {
+	StepKindJson,
+	ResourceJson,
+	ResourceTypeIdentityJson,
+} from '@toolproof-core/schema';
+import { CONSTANTS } from '../artifacts/artifacts.js';
+import { MAPPINGS } from '../artifacts/artifacts.js';
+
+export type Bucket = typeof CONSTANTS.Persistence.Buckets.tp_resources;
+
+export type Collection = keyof typeof CONSTANTS.Persistence.Collections;
+
+export type SchemaLike = Record<string, unknown>;
+
+export type ResourcesByResourceTypeHandle = Record<ResourceTypeIdentityJson, ResourceJson[]>;
+
+export type IdentityName = keyof typeof MAPPINGS.IdentityNameToIdentityPrefix;
+
+export type IdentityStringByIdentityName<K extends IdentityName> = `${(typeof MAPPINGS.IdentityNameToIdentityPrefix)[K]}${string}`;
+
 export type StepIdentityStringByStepKind<K extends StepKindJson> = `${(typeof MAPPINGS.StepKindToStepIdentityPrefix)[K]}${string}`;

package/src/utils/extractFrom.ts

@@ -0,0 +1,93 @@
+import type {
+    RawStrategyJson,
+    JobIdentityJson,
+    JobJson,
+    JobStepIdentityJson,
+    JobStepJson,
+    StepJson,
+    ResourceRoleIdentityJson,
+    ResourceRoleJson,
+    ErrorJson
+} from '@toolproof-core/schema';
+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);
+    }
+    return Array.from(ids);
+}
+
+export function extractJobStepsFromRawStrategy(rawStrategy: RawStrategyJson): JobStepJson[] {
+    const jobSteps: JobStepJson[] = [];
+    const seen = new Set<JobStepIdentityJson>();
+
+    const addJobStep = (jobStep: JobStepJson) => {
+        if (seen.has(jobStep.identity)) {
+            throw new Error(`Duplicate job step identity encountered: ${jobStep.identity}`);
+        }
+        seen.add(jobStep.identity);
+        jobSteps.push(jobStep);
+    };
+
+    const visitStep = (step: StepJson) => {
+        switch (step.stepKind) {
+            case CONSTANTS.Enums.StepKind.job: {
+                addJobStep(step);
+                return;
+            }
+            case CONSTANTS.Enums.StepKind.branch: {
+                for (const conditional of step.cases) {
+                    addJobStep(conditional.when);
+                    addJobStep(conditional.what);
+                }
+                return;
+            }
+            case CONSTANTS.Enums.StepKind.while:
+            case CONSTANTS.Enums.StepKind.for: {
+                addJobStep(step.case.when);
+                addJobStep(step.case.what);
+                return;
+            }
+            default: {
+                const _exhaustive: never = step;
+                return _exhaustive;
+            }
+        }
+    };
+
+    for (const step of rawStrategy.steps) {
+        visitStep(step);
+    }
+
+    return jobSteps;
+}
+
+
+export function extractResourceRolesFromRawStrategy(rawStrategy: RawStrategyJson, jobMap: Map<JobIdentityJson, JobJson>): ResourceRoleJson[] {
+    const map = new Map<ResourceRoleIdentityJson, ResourceRoleJson>();
+    const jobHandles = extractJobHandlesFromRawStrategy(rawStrategy);
+
+    for (const jobHandle of jobHandles) {
+        const job = jobMap.get(jobHandle);
+        if (!job) continue;
+
+        for (const [rid, role] of Object.entries(job.roles.inputDict)) {
+            map.set(rid as ResourceRoleIdentityJson, {
+                identity: rid as ResourceRoleIdentityJson,
+                ...role,
+            });
+        }
+        for (const [rid, role] of Object.entries(job.roles.outputDict)) {
+            map.set(rid as ResourceRoleIdentityJson, {
+                identity: rid as ResourceRoleIdentityJson,
+                ...role,
+            });
+        }
+    }
+
+    return Array.from(map.values());
+}

package/src/utils/extractFromResourcesByResourceTypeHandle.ts

@@ -0,0 +1,55 @@
+import type {
+    ResourceIdentityJson,
+    ResourceTypeIdentityJson,
+    ResourceJson,
+} from '@toolproof-core/schema';
+
+
+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;
+}

package/src/utils/{creation.ts → generateFrom.ts}

@@ -1,27 +1,27 @@
-import type { ResourceIdentityJson, ResourceTypeIdentityJson, ResourceJson, ResourceOutputPotentialJson } from '@toolproof-core/schema';
-
-
-export function generatePath(resourceTypeHandle: ResourceTypeIdentityJson, identity: ResourceIdentityJson): string {
-    return `${resourceTypeHandle}/${identity}.json`;
-}
-
-export function fromOutputPotentialToMaterialized(
-    outputPotential: ResourceOutputPotentialJson,
-    nucleus: unknown,
-    timestamp?: string
-): ResourceJson {
-    const { identity, resourceTypeHandle, creationContext } = outputPotential;
-
-    const path = generatePath(resourceTypeHandle, identity);
-
-    return {
-        identity,
-        resourceTypeHandle,
-        creationContext,
-        resourceShellKind: 'materialized',
-        version: 1,
-        timestamp: timestamp ?? new Date().toISOString(), // Preserve original timestamp when copying
-        path,
-        nucleus,
-    };
+import type { ResourceIdentityJson, ResourceTypeIdentityJson, ResourceJson, ResourceOutputPotentialJson } from '@toolproof-core/schema';
+
+
+export function generatePath(resourceTypeHandle: ResourceTypeIdentityJson, identity: ResourceIdentityJson): string {
+    return `${resourceTypeHandle}/${identity}.json`;
+}
+
+export function generateMaterializedFromOutputPotential(
+    outputPotential: ResourceOutputPotentialJson,
+    nucleus: unknown,
+    timestamp?: string
+): ResourceJson {
+    const { identity, resourceTypeHandle, creationContext } = outputPotential;
+
+    const path = generatePath(resourceTypeHandle, identity);
+
+    return {
+        identity,
+        resourceTypeHandle,
+        creationContext,
+        resourceShellKind: 'materialized',
+        version: 1,
+        timestamp: timestamp ?? new Date().toISOString(), // Preserve original timestamp when copying
+        path,
+        nucleus,
+    };
 }

package/src/utils/parallelization.ts

@@ -0,0 +1,177 @@
+import type {
+    BranchStepJson,
+    ForStepJson,
+    JobStepIdentityJson,
+    JobStepJson,
+    ResourceRoleIdentityJson,
+    StepJson,
+    StrategyStateJson,
+    WhileStepJson,
+} from '@toolproof-core/schema';
+
+
+export function getIndependentThreads(steps: StepJson[], strategyState: StrategyStateJson): StepJson[][] {
+    type OwnerIndex = number;
+
+    const getOwnerLabel = (ownerIndex: OwnerIndex) => {
+        const step = steps[ownerIndex];
+        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>();
+
+    const addJobStep = (jobStep: JobStepJson | undefined, ownerIndex: 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 === 'job') {
+            addJobStep(step as JobStepJson, ownerIndex);
+            return;
+        }
+
+        if (step.stepKind === 'for') {
+            const loop = step as ForStepJson;
+            addJobStep(loop.case?.what, ownerIndex);
+            addJobStep(loop.case?.when, ownerIndex);
+            return;
+        }
+
+        if (step.stepKind === 'while') {
+            const loop = step as WhileStepJson;
+            addJobStep(loop.case?.what, ownerIndex);
+            addJobStep(loop.case?.when, ownerIndex);
+            return;
+        }
+
+        if (step.stepKind === 'branch') {
+            const branch = step as BranchStepJson;
+            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<OwnerIndex, Set<OwnerIndex>>();
+    // Directed dependencies used for strict ordering validation: owner -> producers it depends on.
+    const ownerDeps = new Map<OwnerIndex, Set<OwnerIndex>>();
+
+    const ensureOwner = (ownerIndex: 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] ?? ({} as any);
+
+        for (const inputRoleHandle of inputBindings) {
+            const entry = bucket?.[inputRoleHandle as ResourceRoleIdentityJson] as any;
+            if (!entry || entry.resourceShellKind !== 'inputPotential') continue;
+
+            const creatorJobStepHandle = entry?.creationContext?.jobStepHandle as JobStepIdentityJson | undefined;
+            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<OwnerIndex>();
+    const components: OwnerIndex[][] = [];
+
+    for (let ownerIndex = 0; ownerIndex < steps.length; ownerIndex++) {
+        if (visited.has(ownerIndex)) continue;
+        const component: OwnerIndex[] = [];
+        const queue: OwnerIndex[] = [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<OwnerIndex, number>();
+        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);
+}

package/src/utils/resourceChain.ts

@@ -0,0 +1,66 @@
+import type {
+    CreationContextJson,
+    ResourceJson,
+    ResourceMissingJson,
+    ResourceInputPotentialJson,
+    ResourceOutputPotentialJson,
+    StrategyStateJson,
+} from '@toolproof-core/schema';
+
+export type ResolveResult =
+    | { status: 'materialized'; entry: ResourceJson; path: CreationContextJson[] }
+    | { status: 'missing'; entry: ResourceMissingJson; path: CreationContextJson[] }
+    | { status: 'outputPotential'; entry: ResourceOutputPotentialJson; path: CreationContextJson[] }
+    | { status: 'unresolved'; reason: 'not-found' | 'cycle' | 'depth-exceeded'; path: CreationContextJson[] };
+
+export function resolveResourceChain(
+    strategyState: StrategyStateJson,
+    start: CreationContextJson,
+    opts?: { maxDepth?: number }
+): ResolveResult {
+    const maxDepth = opts?.maxDepth ?? 50;
+    const visited = new Set<string>();
+    const path: CreationContextJson[] = [];
+    let current: CreationContextJson = 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] as (
+            | ResourceJson
+            | ResourceMissingJson
+            | ResourceInputPotentialJson
+            | ResourceOutputPotentialJson
+            | undefined
+        );
+        if (!entry) return { status: 'unresolved', reason: 'not-found', path };
+
+        if (entry.resourceShellKind === 'materialized') {
+            return { status: 'materialized', entry: entry as ResourceJson, path };
+        }
+        if (entry.resourceShellKind === 'missing') {
+            return { status: 'missing', entry: entry as ResourceMissingJson, path };
+        }
+        if (entry.resourceShellKind === 'outputPotential') {
+            return { status: 'outputPotential', entry: entry as ResourceOutputPotentialJson, path };
+        }
+
+        // inputPotential: follow ref backwards
+        if (entry.resourceShellKind === 'inputPotential') {
+            current = (entry as ResourceInputPotentialJson).creationContext;
+            continue;
+        }
+
+        // Unknown case
+        return { status: 'unresolved', reason: 'not-found', path };
+    }
+
+    return { status: 'unresolved', reason: 'depth-exceeded', path };
+}