@contractspec/lib.workflow-composer 3.7.10 → 3.7.12

package/README.md

@@ -23,6 +23,13 @@ or
 
 Import the root entrypoint from `@contractspec/lib.workflow-composer`, or choose a documented subpath when you only need one part of the package surface.
 
+Workflow composition is deterministic by default:
+
+- Extensions are applied in stable priority order.
+- Duplicate injected step ids and invalid anchor combinations are rejected.
+- Hidden-step overlays are validated so they cannot orphan the remaining graph.
+- Extension `metadata` and `annotations` are merged into the composed workflow output.
+
 ## Architecture
 
 - `src/composer.test.ts` is part of the package's public or composition surface.

package/dist/browser/index.js

@@ -10,6 +10,9 @@ import {
 function validateExtension(extension, base) {
   const issues = [];
   const baseStepIds = new Set(base.definition.steps.map((step) => step.id));
+  const hiddenSteps = new Set(extension.hiddenSteps ?? []);
+  const visibleStepIds = new Set(baseStepIds);
+  const visibleTransitions = base.definition.transitions.filter((transition) => visibleStepIds.has(transition.from) && visibleStepIds.has(transition.to)).map((transition) => ({ ...transition }));
   if (!extension.workflow.trim()) {
     issues.push({
       code: "workflow.extension.workflow",
@@ -22,15 +25,17 @@ function validateExtension(extension, base) {
       message: `extension targets "${extension.workflow}" but base workflow is "${base.meta.key}"`
     });
   }
-  const hiddenSteps = new Set(extension.hiddenSteps ?? []);
   hiddenSteps.forEach((stepId) => {
     if (!baseStepIds.has(stepId)) {
       issues.push({
         code: "workflow.extension.hidden-step",
         message: `hidden step "${stepId}" does not exist`
       });
+      return;
     }
+    visibleStepIds.delete(stepId);
   });
+  removeHiddenTransitions(visibleTransitions, hiddenSteps);
   const availableAnchorSteps = new Set([...baseStepIds].filter((stepId) => !hiddenSteps.has(stepId)));
   extension.customSteps?.forEach((injection, idx) => {
     const injectionId = injection.inject.id?.trim();
@@ -90,6 +95,21 @@ function validateExtension(extension, base) {
       });
     }
     availableAnchorSteps.add(injectionId);
+    visibleStepIds.add(injectionId);
+    if (injection.transitionFrom) {
+      visibleTransitions.push({
+        from: injection.transitionFrom,
+        to: injectionId,
+        condition: injection.when
+      });
+    }
+    if (injection.transitionTo) {
+      visibleTransitions.push({
+        from: injectionId,
+        to: injection.transitionTo,
+        condition: injection.when
+      });
+    }
   });
   const entryStepId = base.definition.entryStepId ?? base.definition.steps[0]?.id;
   if (entryStepId && hiddenSteps.has(entryStepId)) {
@@ -98,11 +118,54 @@ function validateExtension(extension, base) {
       message: `hiddenSteps removes the entry step "${entryStepId}"`
     });
   }
+  if (entryStepId && !hiddenSteps.has(entryStepId)) {
+    const reachable = collectReachableSteps(entryStepId, visibleTransitions);
+    for (const stepId of visibleStepIds) {
+      if (!reachable.has(stepId)) {
+        issues.push({
+          code: "workflow.extension.hidden-step.orphan",
+          message: `extension leaves step "${stepId}" unreachable from entry step "${entryStepId}"`
+        });
+      }
+    }
+  }
   if (issues.length) {
     const reason = issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
     throw new Error(`Invalid workflow extension for ${extension.workflow}: ${reason}`);
   }
 }
+function removeHiddenTransitions(transitions, hiddenSteps) {
+  for (let index = transitions.length - 1;index >= 0; index -= 1) {
+    const transition = transitions[index];
+    if (!transition) {
+      continue;
+    }
+    if (hiddenSteps.has(transition.from) || hiddenSteps.has(transition.to)) {
+      transitions.splice(index, 1);
+    }
+  }
+}
+function collectReachableSteps(entryStepId, transitions) {
+  const adjacency = new Map;
+  for (const transition of transitions) {
+    const next = adjacency.get(transition.from) ?? [];
+    next.push(transition.to);
+    adjacency.set(transition.from, next);
+  }
+  const reachable = new Set;
+  const queue = [entryStepId];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || reachable.has(current)) {
+      continue;
+    }
+    reachable.add(current);
+    for (const next of adjacency.get(current) ?? []) {
+      queue.push(next);
+    }
+  }
+  return reachable;
+}
 
 // src/injector.ts
 function applyWorkflowExtension(base, extension) {

package/dist/index.js

@@ -11,6 +11,9 @@ import {
 function validateExtension(extension, base) {
   const issues = [];
   const baseStepIds = new Set(base.definition.steps.map((step) => step.id));
+  const hiddenSteps = new Set(extension.hiddenSteps ?? []);
+  const visibleStepIds = new Set(baseStepIds);
+  const visibleTransitions = base.definition.transitions.filter((transition) => visibleStepIds.has(transition.from) && visibleStepIds.has(transition.to)).map((transition) => ({ ...transition }));
   if (!extension.workflow.trim()) {
     issues.push({
       code: "workflow.extension.workflow",
@@ -23,15 +26,17 @@ function validateExtension(extension, base) {
       message: `extension targets "${extension.workflow}" but base workflow is "${base.meta.key}"`
     });
   }
-  const hiddenSteps = new Set(extension.hiddenSteps ?? []);
   hiddenSteps.forEach((stepId) => {
     if (!baseStepIds.has(stepId)) {
       issues.push({
         code: "workflow.extension.hidden-step",
         message: `hidden step "${stepId}" does not exist`
       });
+      return;
     }
+    visibleStepIds.delete(stepId);
   });
+  removeHiddenTransitions(visibleTransitions, hiddenSteps);
   const availableAnchorSteps = new Set([...baseStepIds].filter((stepId) => !hiddenSteps.has(stepId)));
   extension.customSteps?.forEach((injection, idx) => {
     const injectionId = injection.inject.id?.trim();
@@ -91,6 +96,21 @@ function validateExtension(extension, base) {
       });
     }
     availableAnchorSteps.add(injectionId);
+    visibleStepIds.add(injectionId);
+    if (injection.transitionFrom) {
+      visibleTransitions.push({
+        from: injection.transitionFrom,
+        to: injectionId,
+        condition: injection.when
+      });
+    }
+    if (injection.transitionTo) {
+      visibleTransitions.push({
+        from: injectionId,
+        to: injection.transitionTo,
+        condition: injection.when
+      });
+    }
   });
   const entryStepId = base.definition.entryStepId ?? base.definition.steps[0]?.id;
   if (entryStepId && hiddenSteps.has(entryStepId)) {
@@ -99,11 +119,54 @@ function validateExtension(extension, base) {
       message: `hiddenSteps removes the entry step "${entryStepId}"`
     });
   }
+  if (entryStepId && !hiddenSteps.has(entryStepId)) {
+    const reachable = collectReachableSteps(entryStepId, visibleTransitions);
+    for (const stepId of visibleStepIds) {
+      if (!reachable.has(stepId)) {
+        issues.push({
+          code: "workflow.extension.hidden-step.orphan",
+          message: `extension leaves step "${stepId}" unreachable from entry step "${entryStepId}"`
+        });
+      }
+    }
+  }
   if (issues.length) {
     const reason = issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
     throw new Error(`Invalid workflow extension for ${extension.workflow}: ${reason}`);
   }
 }
+function removeHiddenTransitions(transitions, hiddenSteps) {
+  for (let index = transitions.length - 1;index >= 0; index -= 1) {
+    const transition = transitions[index];
+    if (!transition) {
+      continue;
+    }
+    if (hiddenSteps.has(transition.from) || hiddenSteps.has(transition.to)) {
+      transitions.splice(index, 1);
+    }
+  }
+}
+function collectReachableSteps(entryStepId, transitions) {
+  const adjacency = new Map;
+  for (const transition of transitions) {
+    const next = adjacency.get(transition.from) ?? [];
+    next.push(transition.to);
+    adjacency.set(transition.from, next);
+  }
+  const reachable = new Set;
+  const queue = [entryStepId];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || reachable.has(current)) {
+      continue;
+    }
+    reachable.add(current);
+    for (const next of adjacency.get(current) ?? []) {
+      queue.push(next);
+    }
+  }
+  return reachable;
+}
 
 // src/injector.ts
 function applyWorkflowExtension(base, extension) {

package/dist/node/index.js

@@ -10,6 +10,9 @@ import {
 function validateExtension(extension, base) {
   const issues = [];
   const baseStepIds = new Set(base.definition.steps.map((step) => step.id));
+  const hiddenSteps = new Set(extension.hiddenSteps ?? []);
+  const visibleStepIds = new Set(baseStepIds);
+  const visibleTransitions = base.definition.transitions.filter((transition) => visibleStepIds.has(transition.from) && visibleStepIds.has(transition.to)).map((transition) => ({ ...transition }));
   if (!extension.workflow.trim()) {
     issues.push({
       code: "workflow.extension.workflow",
@@ -22,15 +25,17 @@ function validateExtension(extension, base) {
       message: `extension targets "${extension.workflow}" but base workflow is "${base.meta.key}"`
     });
   }
-  const hiddenSteps = new Set(extension.hiddenSteps ?? []);
   hiddenSteps.forEach((stepId) => {
     if (!baseStepIds.has(stepId)) {
       issues.push({
         code: "workflow.extension.hidden-step",
         message: `hidden step "${stepId}" does not exist`
       });
+      return;
     }
+    visibleStepIds.delete(stepId);
   });
+  removeHiddenTransitions(visibleTransitions, hiddenSteps);
   const availableAnchorSteps = new Set([...baseStepIds].filter((stepId) => !hiddenSteps.has(stepId)));
   extension.customSteps?.forEach((injection, idx) => {
     const injectionId = injection.inject.id?.trim();
@@ -90,6 +95,21 @@ function validateExtension(extension, base) {
       });
     }
     availableAnchorSteps.add(injectionId);
+    visibleStepIds.add(injectionId);
+    if (injection.transitionFrom) {
+      visibleTransitions.push({
+        from: injection.transitionFrom,
+        to: injectionId,
+        condition: injection.when
+      });
+    }
+    if (injection.transitionTo) {
+      visibleTransitions.push({
+        from: injectionId,
+        to: injection.transitionTo,
+        condition: injection.when
+      });
+    }
   });
   const entryStepId = base.definition.entryStepId ?? base.definition.steps[0]?.id;
   if (entryStepId && hiddenSteps.has(entryStepId)) {
@@ -98,11 +118,54 @@ function validateExtension(extension, base) {
       message: `hiddenSteps removes the entry step "${entryStepId}"`
     });
   }
+  if (entryStepId && !hiddenSteps.has(entryStepId)) {
+    const reachable = collectReachableSteps(entryStepId, visibleTransitions);
+    for (const stepId of visibleStepIds) {
+      if (!reachable.has(stepId)) {
+        issues.push({
+          code: "workflow.extension.hidden-step.orphan",
+          message: `extension leaves step "${stepId}" unreachable from entry step "${entryStepId}"`
+        });
+      }
+    }
+  }
   if (issues.length) {
     const reason = issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
     throw new Error(`Invalid workflow extension for ${extension.workflow}: ${reason}`);
   }
 }
+function removeHiddenTransitions(transitions, hiddenSteps) {
+  for (let index = transitions.length - 1;index >= 0; index -= 1) {
+    const transition = transitions[index];
+    if (!transition) {
+      continue;
+    }
+    if (hiddenSteps.has(transition.from) || hiddenSteps.has(transition.to)) {
+      transitions.splice(index, 1);
+    }
+  }
+}
+function collectReachableSteps(entryStepId, transitions) {
+  const adjacency = new Map;
+  for (const transition of transitions) {
+    const next = adjacency.get(transition.from) ?? [];
+    next.push(transition.to);
+    adjacency.set(transition.from, next);
+  }
+  const reachable = new Set;
+  const queue = [entryStepId];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || reachable.has(current)) {
+      continue;
+    }
+    reachable.add(current);
+    for (const next of adjacency.get(current) ?? []) {
+      queue.push(next);
+    }
+  }
+  return reachable;
+}
 
 // src/injector.ts
 function applyWorkflowExtension(base, extension) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.workflow-composer",
-  "version": "3.7.10",
+  "version": "3.7.12",
   "description": "Tenant-aware workflow composition helpers for ContractSpec.",
   "keywords": [
     "contractspec",
@@ -31,14 +31,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.contracts-spec": "4.1.2",
-    "@contractspec/lib.ai-providers": "3.7.8",
+    "@contractspec/lib.contracts-spec": "5.0.0",
+    "@contractspec/lib.ai-providers": "3.7.9",
     "compare-versions": "^6.1.1"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.8",
+    "@contractspec/tool.typescript": "3.7.9",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.8"
+    "@contractspec/tool.bun": "3.7.9"
   },
   "exports": {
     ".": {