@toolproof-npm/shared 0.1.112 → 0.1.114

package/dist/_lib/types.d.ts

@@ -2,7 +2,7 @@ import type { ResourceJson, ResourceRoleIdentityJson, ResourceRoleValueJson, Res
 import { CONSTANTS } from '../constants.js';
 export type BucketConst = typeof CONSTANTS.STORAGE.BUCKETS.tp_resources;
 export type CollectionConst = keyof typeof CONSTANTS.STORAGE.COLLECTIONS;
-export type TerminalConst = keyof typeof CONSTANTS.TERMINALS;
+export type IDENTITY_PREFIX = keyof typeof CONSTANTS.IDENTITY_PREFIXES;
 export type StepConst = keyof typeof CONSTANTS.STEPS;
 export type Role = {
     identity: ResourceRoleIdentityJson;

package/dist/_lib/utils/stepCreation.js

@@ -1,26 +1,30 @@
 import { CONSTANTS } from '@toolproof-npm/shared/constants';
-import { getNewIdentity } from '@toolproof-npm/shared/server';
+import { getNewIdentity, getNewStepIdentity, getExecutionRefFromWorkStepIdentity } from '@toolproof-npm/shared/server';
+function assertNonEmpty(arr, msg) {
+    if (arr.length === 0)
+        throw new Error(msg);
+}
 const mintNewRoleBindingMap = async (existingMap) => {
     const newMap = {};
     await Promise.all(Object.keys(existingMap).map(async (resourceRoleRef) => {
-        const resourceId = await getNewIdentity(CONSTANTS.TERMINALS.resource);
+        const resourceId = await getNewIdentity(CONSTANTS.IDENTITY_PREFIXES.resource);
         newMap[resourceRoleRef] = resourceId;
     }));
     return newMap;
 };
 // DOC: Helper function to construct an Execution object from a job
 const createExecutionFromJob = async (job, executionRef) => {
-    const execIdentity = executionRef ?? await getNewIdentity(CONSTANTS.TERMINALS.execution);
+    const execIdentity = executionRef ?? await getNewIdentity(CONSTANTS.IDENTITY_PREFIXES.execution);
     const inputBindingMap = {};
     const inputs = job.roles.inputMap;
     await Promise.all(Object.keys(inputs).map(async (resourceRoleRef) => {
-        const resourceId = await getNewIdentity(CONSTANTS.TERMINALS.resource);
+        const resourceId = await getNewIdentity(CONSTANTS.IDENTITY_PREFIXES.resource);
         inputBindingMap[resourceRoleRef] = resourceId;
     }));
     const outputBindingMap = {};
     const outputs = job.roles.outputMap;
     await Promise.all(Object.keys(outputs).map(async (resourceRoleRef) => {
-        const resourceId = await getNewIdentity(CONSTANTS.TERMINALS.resource);
+        const resourceId = await getNewIdentity(CONSTANTS.IDENTITY_PREFIXES.resource);
         outputBindingMap[resourceRoleRef] = resourceId;
     }));
     return {
@@ -34,8 +38,8 @@ const createExecutionFromJob = async (job, executionRef) => {
 };
 // DOC: Helper function to construct a WorkStep object from an jobMetaJson (does not append to statelessStrategy.steps)
 export const createWorkStepFromJob = async (job) => {
-    const workStepIdentity = await getNewIdentity(CONSTANTS.STEPS.work);
-    const executionRef = workStepIdentity.replace(CONSTANTS.STEPS.work.toUpperCase(), 'execution'.toUpperCase()); // ATTENTION: use function
+    const workStepIdentity = await getNewStepIdentity(CONSTANTS.STEPS.work);
+    const executionRef = getExecutionRefFromWorkStepIdentity(workStepIdentity);
     const execution = await createExecutionFromJob(job, executionRef);
     const newWorkStep = {
         identity: workStepIdentity,
@@ -52,8 +56,8 @@ export const createLoopStepFromJob = async (whatJob, whenJob, kind) => {
     const whenWorkStep = await createWorkStepFromJob(whenJob);
     // Generate loop step identity based on kind
     const stepIdentity = (kind === 'for'
-        ? await getNewIdentity(CONSTANTS.STEPS.for)
-        : await getNewIdentity(CONSTANTS.STEPS.while));
+        ? await getNewStepIdentity(CONSTANTS.STEPS.for)
+        : await getNewStepIdentity(CONSTANTS.STEPS.while));
     // Assemble the loop step
     return {
         identity: stepIdentity,
@@ -67,7 +71,7 @@ export const createLoopStepFromJob = async (whatJob, whenJob, kind) => {
 // DOC: Helper function to construct a BranchStep from an array of job pairs
 export const createBranchStepFromJobPairs = async (cases) => {
     // Generate branch step identity
-    const branchStepIdentity = await getNewIdentity(CONSTANTS.STEPS.branch);
+    const branchStepIdentity = await getNewStepIdentity(CONSTANTS.STEPS.branch);
     // Create WorkSteps for each case (what and when pair)
     const casesWithWorkSteps = await Promise.all(cases.map(async ({ whatJob, whenJob }) => {
         const whatWorkStep = await createWorkStepFromJob(whatJob);
@@ -77,21 +81,25 @@ export const createBranchStepFromJobPairs = async (cases) => {
             when: whenWorkStep
         };
     }));
+    assertNonEmpty(casesWithWorkSteps, 'createBranchStepFromJobPairs requires at least one case');
+    const casesTuple = casesWithWorkSteps;
     // Assemble the branch step
+    const canonicalWhatExecutionRef = casesWithWorkSteps?.[0]?.what?.execution?.identity;
     return {
         identity: branchStepIdentity,
         kind: CONSTANTS.STEPS.branch,
-        cases: casesWithWorkSteps
+        cases: casesTuple,
+        canonicalWhatExecutionRef: canonicalWhatExecutionRef ? String(canonicalWhatExecutionRef) : undefined
     };
 };
 // DOC: Helper function to clone a ForStep with new identities for steps and executions, preserving job references and bindings
 export const cloneForStep = async (forStep) => {
     // Generate new ForStep identity
-    const newForStepIdentity = await getNewIdentity(CONSTANTS.STEPS.for);
+    const newForStepIdentity = await getNewStepIdentity(CONSTANTS.STEPS.for);
     // Clone the "what" WorkStep
     const originalWhatWorkStep = forStep.case.what;
-    const newWhatWorkStepIdentity = await getNewIdentity(CONSTANTS.STEPS.work);
-    const newWhatExecutionIdentity = newWhatWorkStepIdentity.replace(CONSTANTS.STEPS.work.toUpperCase(), 'execution'.toUpperCase());
+    const newWhatWorkStepIdentity = await getNewStepIdentity(CONSTANTS.STEPS.work);
+    const newWhatExecutionIdentity = getExecutionRefFromWorkStepIdentity(newWhatWorkStepIdentity);
     const newWhatExecution = {
         identity: newWhatExecutionIdentity,
         jobRef: originalWhatWorkStep.execution.jobRef,
@@ -107,8 +115,8 @@ export const cloneForStep = async (forStep) => {
     };
     // Clone the "when" WorkStep
     const originalWhenWorkStep = forStep.case.when;
-    const newWhenWorkStepIdentity = await getNewIdentity(CONSTANTS.STEPS.work);
-    const newWhenExecutionIdentity = newWhenWorkStepIdentity.replace(CONSTANTS.STEPS.work.toUpperCase(), 'execution'.toUpperCase());
+    const newWhenWorkStepIdentity = await getNewStepIdentity(CONSTANTS.STEPS.work);
+    const newWhenExecutionIdentity = getExecutionRefFromWorkStepIdentity(newWhenWorkStepIdentity);
     const newWhenExecution = {
         identity: newWhenExecutionIdentity,
         jobRef: originalWhenWorkStep.execution.jobRef,
@@ -135,11 +143,11 @@ export const cloneForStep = async (forStep) => {
 // DOC: Helper function to clone a WhileStep with new identities for steps and executions, preserving job references and bindings
 export const cloneWhileStep = async (whileStep) => {
     // Generate new WhileStep identity
-    const newWhileStepIdentity = await getNewIdentity(CONSTANTS.STEPS.while);
+    const newWhileStepIdentity = await getNewStepIdentity(CONSTANTS.STEPS.while);
     // Clone the "what" WorkStep
     const originalWhatWorkStep = whileStep.case.what;
-    const newWhatWorkStepIdentity = await getNewIdentity(CONSTANTS.STEPS.work);
-    const newWhatExecutionIdentity = newWhatWorkStepIdentity.replace(CONSTANTS.STEPS.work.toUpperCase(), 'execution'.toUpperCase());
+    const newWhatWorkStepIdentity = await getNewStepIdentity(CONSTANTS.STEPS.work);
+    const newWhatExecutionIdentity = getExecutionRefFromWorkStepIdentity(newWhatWorkStepIdentity);
     const newWhatExecution = {
         identity: newWhatExecutionIdentity,
         jobRef: originalWhatWorkStep.execution.jobRef,
@@ -155,8 +163,8 @@ export const cloneWhileStep = async (whileStep) => {
     };
     // Clone the "when" WorkStep
     const originalWhenWorkStep = whileStep.case.when;
-    const newWhenWorkStepIdentity = await getNewIdentity(CONSTANTS.STEPS.work);
-    const newWhenExecutionIdentity = newWhenWorkStepIdentity.replace(CONSTANTS.STEPS.work.toUpperCase(), 'execution'.toUpperCase());
+    const newWhenWorkStepIdentity = await getNewStepIdentity(CONSTANTS.STEPS.work);
+    const newWhenExecutionIdentity = getExecutionRefFromWorkStepIdentity(newWhenWorkStepIdentity);
     const newWhenExecution = {
         identity: newWhenExecutionIdentity,
         jobRef: originalWhenWorkStep.execution.jobRef,
@@ -183,10 +191,20 @@ export const cloneWhileStep = async (whileStep) => {
 // DOC: Helper function to clone a BranchStep with a new identity, optionally overriding its cases.
 // Note: We intentionally do NOT clone executions/steps here because BranchStep (Option A) does not repeat cases.
 export const cloneBranchStep = async (branchStep, casesOverride) => {
-    const newBranchStepIdentity = await getNewIdentity(CONSTANTS.STEPS.branch);
+    const newBranchStepIdentity = await getNewStepIdentity(CONSTANTS.STEPS.branch);
+    const cases = casesOverride ?? branchStep.cases;
+    const priorCanonical = branchStep.canonicalWhatExecutionRef;
+    const canonicalStillExists = priorCanonical
+        ? (cases ?? []).some((c) => String(c?.what?.execution?.identity ?? '') === String(priorCanonical))
+        : false;
+    const fallbackCanonical = (cases ?? [])?.[0]?.what?.execution?.identity;
+    const canonicalWhatExecutionRef = canonicalStillExists
+        ? priorCanonical
+        : (fallbackCanonical ? String(fallbackCanonical) : undefined);
     return {
         identity: newBranchStepIdentity,
         kind: CONSTANTS.STEPS.branch,
-        cases: casesOverride ?? branchStep.cases,
+        cases,
+        canonicalWhatExecutionRef,
     };
 };

package/dist/_lib/utils/strategyRunCreation.d.ts

@@ -1,6 +1,6 @@
 import type { ExecutionJson, StatefulStrategyJson, StrategyRunJson, StrategyRunStatusJson, StrategyStateJson } from '@toolproof-npm/schema';
-import type { TerminalConst } from '../types.js';
-export type GetNewIdentity = (identifiable: TerminalConst) => string | Promise<string>;
+import type { IDENTITY_PREFIX } from '../types.js';
+export type GetNewIdentity = (identifiable: IDENTITY_PREFIX) => string | Promise<string>;
 export declare function normalizeExecutionInputBindingMap(execution: ExecutionJson, strategyState: StrategyStateJson): ExecutionJson;
 export declare function createStrategyRun(statefulStrategy: StatefulStrategyJson, opts?: {
     getNewIdentity: GetNewIdentity;

package/dist/_lib/utils/strategyRunCreation.js

@@ -172,14 +172,14 @@ export async function createStrategyRun(statefulStrategy, opts) {
     // Normalize roleBindings.inputBindingMap to reflect the identities present in strategyState.
     // This is intentionally a pure transformation (no mutation of the provided statefulStrategy object graph).
     const normalizedStatefulStrategy = normalizeStatefulStrategyInputBindingMaps(statefulStrategy);
-    const strategyRunIdentity = (await opts.getNewIdentity(CONSTANTS.TERMINALS.strategy_run));
+    const strategyRunIdentity = (await opts.getNewIdentity(CONSTANTS.IDENTITY_PREFIXES.strategy_run));
     const steps = normalizedStatefulStrategy.statelessStrategy?.steps ?? [];
     const strategyState = (normalizedStatefulStrategy.strategyState ?? {});
     // Algorithm to find what steps can run in parallel
     const threadStepsGroups = getIndependentThreads(steps, strategyState);
     const strategyThreadMap = {};
     for (const group of threadStepsGroups) {
-        const threadIdentity = await opts.getNewIdentity(CONSTANTS.TERMINALS.strategy_thread);
+        const threadIdentity = await opts.getNewIdentity(CONSTANTS.IDENTITY_PREFIXES.strategy_thread);
         strategyThreadMap[threadIdentity] = group;
     }
     return {

package/dist/constants.d.ts

@@ -15,7 +15,7 @@ export declare const CONSTANTS: {
             readonly members: "members";
         };
     };
-    readonly TERMINALS: {
+    readonly IDENTITY_PREFIXES: {
         readonly format: "format";
         readonly type: "type";
         readonly role: "role";
@@ -33,6 +33,18 @@ export declare const CONSTANTS: {
         readonly while: "while";
         readonly for: "for";
     };
+    readonly STEP_IDENTITY_PREFIXES: {
+        readonly workstep: "workstep";
+        readonly branchstep: "branchstep";
+        readonly forstep: "forstep";
+        readonly whilestep: "whilestep";
+    };
+    readonly STEP_IDENTITY_PREFIX_BY_KIND: {
+        readonly work: "workstep";
+        readonly branch: "branchstep";
+        readonly for: "forstep";
+        readonly while: "whilestep";
+    };
     readonly ENGINE: {
         readonly GraphRunStrategy: "GraphRunStrategy";
     };

package/dist/constants.js

@@ -15,7 +15,7 @@ export const CONSTANTS = {
             members: 'members',
         },
     },
-    TERMINALS: {
+    IDENTITY_PREFIXES: {
         format: 'format',
         type: 'type',
         role: 'role',
@@ -33,6 +33,18 @@ export const CONSTANTS = {
         while: 'while',
         for: 'for',
     },
+    STEP_IDENTITY_PREFIXES: {
+        workstep: 'workstep',
+        branchstep: 'branchstep',
+        forstep: 'forstep',
+        whilestep: 'whilestep',
+    },
+    STEP_IDENTITY_PREFIX_BY_KIND: {
+        work: 'workstep',
+        branch: 'branchstep',
+        for: 'forstep',
+        while: 'whilestep',
+    },
     ENGINE: {
         GraphRunStrategy: 'GraphRunStrategy',
     },

package/dist/firebaseAdminHelpers.d.ts

@@ -1,5 +1,17 @@
-import type { ResourceTypeIdentityJson } from '@toolproof-npm/schema';
-import type { StepConst, ResourceMap, TerminalConst } from './_lib/types.js';
-export declare function getNewIdentity(identifiable: TerminalConst | StepConst): string;
+import type { BranchStepIdentityJson, ExecutionIdentityJson, ForStepIdentityJson, IdentityByPrefix, ResourceTypeIdentityJson, WhileStepIdentityJson, WorkStepIdentityJson } from '@toolproof-npm/schema';
+import type { ResourceMap, IDENTITY_PREFIX } from './_lib/types.js';
+import { CONSTANTS } from './constants.js';
+type StripTrailingS<S extends string> = S extends `${infer Rest}S` ? Rest : S;
+type IdentityPrefixFor<T extends string> = StripTrailingS<Uppercase<T>>;
+export type StepKind = keyof typeof CONSTANTS.STEPS;
+export type StepIdentityPrefix = (typeof CONSTANTS.STEP_IDENTITY_PREFIX_BY_KIND)[StepKind];
+type StepIdentityForPrefix<P extends StepIdentityPrefix> = P extends 'workstep' ? WorkStepIdentityJson : P extends 'branchstep' ? BranchStepIdentityJson : P extends 'forstep' ? ForStepIdentityJson : P extends 'whilestep' ? WhileStepIdentityJson : never;
+type AnyIdentityPrefix = IDENTITY_PREFIX | StepIdentityPrefix;
+export type NewIdentity<T extends AnyIdentityPrefix = AnyIdentityPrefix> = T extends keyof IdentityByPrefix ? IdentityByPrefix[T] : T extends StepIdentityPrefix ? StepIdentityForPrefix<T> : `${IdentityPrefixFor<T>}-${string}`;
+export declare function getNewIdentity<T extends AnyIdentityPrefix>(identifiable: T): NewIdentity<T>;
+export declare function getNewStepIdentityPrefix<K extends StepKind>(kind: K): (typeof CONSTANTS.STEP_IDENTITY_PREFIX_BY_KIND)[K];
+export declare function getNewStepIdentity<K extends StepKind>(kind: K): Promise<StepIdentityForPrefix<(typeof CONSTANTS.STEP_IDENTITY_PREFIX_BY_KIND)[K]>>;
+export declare function getExecutionRefFromWorkStepIdentity(workStepIdentity: WorkStepIdentityJson): ExecutionIdentityJson;
 export declare function listResources(// ATTENTION: must clean up
 resourceTypeRefs: ResourceTypeIdentityJson[]): Promise<ResourceMap>;
+export {};

package/dist/firebaseAdminHelpers.js

@@ -5,7 +5,17 @@ export function getNewIdentity(identifiable) {
     const normalized = base.endsWith('S') ? base.slice(0, -1) : base;
     const prefix = normalized + '-';
     const docRef = dbAdmin.collection(CONSTANTS.STORAGE.COLLECTIONS.resources).doc(identifiable).collection(CONSTANTS.STORAGE.COLLECTIONS.members).doc();
-    return prefix + docRef.id;
+    return (prefix + docRef.id);
+}
+export function getNewStepIdentityPrefix(kind) {
+    return CONSTANTS.STEP_IDENTITY_PREFIX_BY_KIND[kind];
+}
+export async function getNewStepIdentity(kind) {
+    const prefix = getNewStepIdentityPrefix(kind);
+    return getNewIdentity(prefix);
+}
+export function getExecutionRefFromWorkStepIdentity(workStepIdentity) {
+    return workStepIdentity.replace('WORKSTEP', 'EXECUTION');
 }
 export async function listResources(// ATTENTION: must clean up
 resourceTypeRefs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolproof-npm/shared",
-  "version": "0.1.112",
+  "version": "0.1.114",
   "description": "Core library utilities for ToolProof",
   "keywords": [
     "toolproof",
@@ -56,7 +56,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@toolproof-npm/schema": "^0.1.75",
+    "@toolproof-npm/schema": "^0.1.77",
     "firebase-admin": "^13.6.0"
   },
   "scripts": {