@contractspec/lib.workflow-composer 3.0.0 → 3.1.1

package/README.md

@@ -2,45 +2,56 @@
 
 Website: https://contractspec.io/
 
+Compose base `WorkflowSpec` definitions with tenant-, role-, and device-scoped extensions.
 
-Compose base WorkflowSpecs with tenant-, role-, or device-specific extensions. The composer lets teams inject steps, hide portions of a workflow, and attach tenant-scoped metadata without duplicating base definitions.
+This package is designed for deterministic workflow personalization without duplicating core specs.
 
 ## Highlights
 
-- Type-safe `extendWorkflow` helper.
-- Registry for extension templates (tenant, role, device scopes).
-- Validation to ensure injected steps reference valid anchors.
-- Merge utilities to combine overlays coming from tenant + user.
-
-Refer to `docs/tech/personalization/workflow-composition.md` for more.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+- Deterministic extension merge ordering with stable tie-breaking.
+- Strict extension validation for anchors, transition endpoints, and duplicate injected step IDs.
+- Safe hidden-step handling with entry-step protections.
+- Metadata and annotations merge support on composed workflow outputs.
+- Post-composition validation using `validateWorkflowSpec` from `@contractspec/lib.contracts-spec/workflow`.
+
+## Usage
+
+```ts
+import { WorkflowComposer, approvalStepTemplate } from '@contractspec/lib.workflow-composer';
+
+const composer = new WorkflowComposer();
+
+composer.register({
+  workflow: 'billing.invoiceApproval',
+  tenantId: 'acme',
+  priority: 10,
+  metadata: {
+    tenant: 'acme',
+  },
+  annotations: {
+    source: 'tenant-extension',
+  },
+  customSteps: [
+    {
+      after: 'validate-invoice',
+      inject: approvalStepTemplate({
+        id: 'acme-legal-review',
+        label: 'Legal Review (ACME)',
+        description: 'Tenant-specific compliance step.',
+      }),
+      transitionTo: 'final-approval',
+    },
+  ],
+});
+
+const runtimeSpec = composer.compose({
+  base: BaseInvoiceWorkflow,
+  tenantId: 'acme',
+});
+```
+
+## Notes
+
+- Extensions are additive and validated before application.
+- Composition throws with explicit error codes/messages when extension constraints are violated.
+- Runtime behavior remains controlled by `@contractspec/lib.contracts-spec/workflow` runner and validation.

package/dist/browser/index.js

@@ -12,16 +12,63 @@ function approvalStepTemplate(options) {
     } : undefined
   };
 }
+// src/injector.ts
+import {
+  validateWorkflowSpec
+} from "@contractspec/lib.contracts-spec/workflow";
+
 // src/validator.ts
 function validateExtension(extension, base) {
   const issues = [];
-  const stepIds = new Set(base.definition.steps.map((step) => step.id));
+  const baseStepIds = new Set(base.definition.steps.map((step) => step.id));
+  if (!extension.workflow.trim()) {
+    issues.push({
+      code: "workflow.extension.workflow",
+      message: "workflow is required"
+    });
+  }
+  if (extension.workflow !== base.meta.key) {
+    issues.push({
+      code: "workflow.extension.workflow.mismatch",
+      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`
+      });
+    }
+  });
+  const availableAnchorSteps = new Set([...baseStepIds].filter((stepId) => !hiddenSteps.has(stepId)));
   extension.customSteps?.forEach((injection, idx) => {
-    if (!injection.inject.id) {
+    const injectionId = injection.inject.id?.trim();
+    if (!injectionId) {
       issues.push({
         code: "workflow.extension.step.id",
         message: `customSteps[${idx}] is missing an id`
       });
+      return;
+    }
+    if (injection.id && injection.id !== injectionId) {
+      issues.push({
+        code: "workflow.extension.step.id-mismatch",
+        message: `customSteps[${idx}] has mismatched id (id="${injection.id}", inject.id="${injectionId}")`
+      });
+    }
+    if (availableAnchorSteps.has(injectionId)) {
+      issues.push({
+        code: "workflow.extension.step.id.duplicate",
+        message: `customSteps[${idx}] injects duplicate step id "${injectionId}"`
+      });
+    }
+    if (injection.after && injection.before) {
+      issues.push({
+        code: "workflow.extension.step.anchor.multiple",
+        message: `customSteps[${idx}] cannot set both after and before`
+      });
     }
     if (!injection.after && !injection.before) {
       issues.push({
@@ -29,27 +76,39 @@ function validateExtension(extension, base) {
         message: `customSteps[${idx}] must set after or before`
       });
     }
-    if (injection.after && !stepIds.has(injection.after)) {
+    if (injection.after && !availableAnchorSteps.has(injection.after)) {
       issues.push({
         code: "workflow.extension.step.after",
         message: `customSteps[${idx}] references unknown step "${injection.after}"`
       });
     }
-    if (injection.before && !stepIds.has(injection.before)) {
+    if (injection.before && !availableAnchorSteps.has(injection.before)) {
       issues.push({
         code: "workflow.extension.step.before",
         message: `customSteps[${idx}] references unknown step "${injection.before}"`
       });
     }
-  });
-  extension.hiddenSteps?.forEach((stepId) => {
-    if (!stepIds.has(stepId)) {
+    if (injection.transitionFrom && !availableAnchorSteps.has(injection.transitionFrom)) {
       issues.push({
-        code: "workflow.extension.hidden-step",
-        message: `hidden step "${stepId}" does not exist`
+        code: "workflow.extension.step.transition-from",
+        message: `customSteps[${idx}] references unknown transitionFrom step "${injection.transitionFrom}"`
+      });
+    }
+    if (injection.transitionTo && !availableAnchorSteps.has(injection.transitionTo)) {
+      issues.push({
+        code: "workflow.extension.step.transition-to",
+        message: `customSteps[${idx}] references unknown transitionTo step "${injection.transitionTo}"`
       });
     }
+    availableAnchorSteps.add(injectionId);
   });
+  const entryStepId = base.definition.entryStepId ?? base.definition.steps[0]?.id;
+  if (entryStepId && hiddenSteps.has(entryStepId)) {
+    issues.push({
+      code: "workflow.extension.hidden-step.entry",
+      message: `hiddenSteps removes the 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}`);
@@ -78,10 +137,13 @@ function applyWorkflowExtension(base, extension) {
   });
   spec.definition.steps = steps;
   spec.definition.transitions = dedupeTransitions(transitions);
-  spec.meta = {
-    ...spec.meta,
-    version: spec.meta.version
-  };
+  spec.metadata = mergeRecords(spec.metadata, extension.metadata);
+  spec.annotations = mergeRecords(spec.annotations, extension.annotations);
+  const issues = validateWorkflowSpec(spec);
+  const blockingIssues = issues.filter((issue) => issue.level === "error");
+  if (blockingIssues.length > 0) {
+    throw new Error(`Invalid composed workflow ${spec.meta.key}.v${spec.meta.version}: ${blockingIssues.map((issue) => issue.message).join("; ")}`);
+  }
   return spec;
 }
 function insertStep(steps, injection) {
@@ -135,9 +197,41 @@ function dedupeTransitions(transitions) {
 function cloneWorkflowSpec(spec) {
   return JSON.parse(JSON.stringify(spec));
 }
+function mergeRecords(base, patch) {
+  if (!base && !patch) {
+    return;
+  }
+  return {
+    ...base ?? {},
+    ...patch ?? {}
+  };
+}
 // src/composer.ts
 import { satisfies } from "compare-versions";
 
+// src/merger.ts
+function mergeExtensions(extensions) {
+  return [...extensions].sort((a, b) => {
+    const priorityOrder = (a.priority ?? 0) - (b.priority ?? 0);
+    if (priorityOrder !== 0)
+      return priorityOrder;
+    const workflowOrder = a.workflow.localeCompare(b.workflow);
+    if (workflowOrder !== 0)
+      return workflowOrder;
+    const tenantOrder = (a.tenantId ?? "").localeCompare(b.tenantId ?? "");
+    if (tenantOrder !== 0)
+      return tenantOrder;
+    const roleOrder = (a.role ?? "").localeCompare(b.role ?? "");
+    if (roleOrder !== 0)
+      return roleOrder;
+    const deviceOrder = (a.device ?? "").localeCompare(b.device ?? "");
+    if (deviceOrder !== 0)
+      return deviceOrder;
+    return (a.baseVersion ?? "").localeCompare(b.baseVersion ?? "");
+  });
+}
+
+// src/composer.ts
 class WorkflowComposer {
   extensions = [];
   register(extension) {
@@ -145,11 +239,13 @@ class WorkflowComposer {
     return this;
   }
   registerMany(extensions) {
-    extensions.forEach((extension) => this.register(extension));
+    extensions.forEach((extension) => {
+      this.register(extension);
+    });
     return this;
   }
   compose(params) {
-    const applicable = this.extensions.filter((extension) => matches(params, extension)).sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+    const applicable = mergeExtensions(this.extensions.filter((extension) => matches(params, extension)));
     return applicable.reduce((acc, extension) => applyWorkflowExtension(acc, extension), params.base);
   }
 }
@@ -170,10 +266,6 @@ function matches(params, extension) {
   }
   return true;
 }
-// src/merger.ts
-function mergeExtensions(extensions) {
-  return extensions.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
-}
 export {
   validateExtension,
   mergeExtensions,

package/dist/composer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -13,16 +13,63 @@ function approvalStepTemplate(options) {
     } : undefined
   };
 }
+// src/injector.ts
+import {
+  validateWorkflowSpec
+} from "@contractspec/lib.contracts-spec/workflow";
+
 // src/validator.ts
 function validateExtension(extension, base) {
   const issues = [];
-  const stepIds = new Set(base.definition.steps.map((step) => step.id));
+  const baseStepIds = new Set(base.definition.steps.map((step) => step.id));
+  if (!extension.workflow.trim()) {
+    issues.push({
+      code: "workflow.extension.workflow",
+      message: "workflow is required"
+    });
+  }
+  if (extension.workflow !== base.meta.key) {
+    issues.push({
+      code: "workflow.extension.workflow.mismatch",
+      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`
+      });
+    }
+  });
+  const availableAnchorSteps = new Set([...baseStepIds].filter((stepId) => !hiddenSteps.has(stepId)));
   extension.customSteps?.forEach((injection, idx) => {
-    if (!injection.inject.id) {
+    const injectionId = injection.inject.id?.trim();
+    if (!injectionId) {
       issues.push({
         code: "workflow.extension.step.id",
         message: `customSteps[${idx}] is missing an id`
       });
+      return;
+    }
+    if (injection.id && injection.id !== injectionId) {
+      issues.push({
+        code: "workflow.extension.step.id-mismatch",
+        message: `customSteps[${idx}] has mismatched id (id="${injection.id}", inject.id="${injectionId}")`
+      });
+    }
+    if (availableAnchorSteps.has(injectionId)) {
+      issues.push({
+        code: "workflow.extension.step.id.duplicate",
+        message: `customSteps[${idx}] injects duplicate step id "${injectionId}"`
+      });
+    }
+    if (injection.after && injection.before) {
+      issues.push({
+        code: "workflow.extension.step.anchor.multiple",
+        message: `customSteps[${idx}] cannot set both after and before`
+      });
     }
     if (!injection.after && !injection.before) {
       issues.push({
@@ -30,27 +77,39 @@ function validateExtension(extension, base) {
         message: `customSteps[${idx}] must set after or before`
       });
     }
-    if (injection.after && !stepIds.has(injection.after)) {
+    if (injection.after && !availableAnchorSteps.has(injection.after)) {
       issues.push({
         code: "workflow.extension.step.after",
         message: `customSteps[${idx}] references unknown step "${injection.after}"`
       });
     }
-    if (injection.before && !stepIds.has(injection.before)) {
+    if (injection.before && !availableAnchorSteps.has(injection.before)) {
       issues.push({
         code: "workflow.extension.step.before",
         message: `customSteps[${idx}] references unknown step "${injection.before}"`
       });
     }
-  });
-  extension.hiddenSteps?.forEach((stepId) => {
-    if (!stepIds.has(stepId)) {
+    if (injection.transitionFrom && !availableAnchorSteps.has(injection.transitionFrom)) {
       issues.push({
-        code: "workflow.extension.hidden-step",
-        message: `hidden step "${stepId}" does not exist`
+        code: "workflow.extension.step.transition-from",
+        message: `customSteps[${idx}] references unknown transitionFrom step "${injection.transitionFrom}"`
+      });
+    }
+    if (injection.transitionTo && !availableAnchorSteps.has(injection.transitionTo)) {
+      issues.push({
+        code: "workflow.extension.step.transition-to",
+        message: `customSteps[${idx}] references unknown transitionTo step "${injection.transitionTo}"`
       });
     }
+    availableAnchorSteps.add(injectionId);
   });
+  const entryStepId = base.definition.entryStepId ?? base.definition.steps[0]?.id;
+  if (entryStepId && hiddenSteps.has(entryStepId)) {
+    issues.push({
+      code: "workflow.extension.hidden-step.entry",
+      message: `hiddenSteps removes the 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}`);
@@ -79,10 +138,13 @@ function applyWorkflowExtension(base, extension) {
   });
   spec.definition.steps = steps;
   spec.definition.transitions = dedupeTransitions(transitions);
-  spec.meta = {
-    ...spec.meta,
-    version: spec.meta.version
-  };
+  spec.metadata = mergeRecords(spec.metadata, extension.metadata);
+  spec.annotations = mergeRecords(spec.annotations, extension.annotations);
+  const issues = validateWorkflowSpec(spec);
+  const blockingIssues = issues.filter((issue) => issue.level === "error");
+  if (blockingIssues.length > 0) {
+    throw new Error(`Invalid composed workflow ${spec.meta.key}.v${spec.meta.version}: ${blockingIssues.map((issue) => issue.message).join("; ")}`);
+  }
   return spec;
 }
 function insertStep(steps, injection) {
@@ -136,9 +198,41 @@ function dedupeTransitions(transitions) {
 function cloneWorkflowSpec(spec) {
   return JSON.parse(JSON.stringify(spec));
 }
+function mergeRecords(base, patch) {
+  if (!base && !patch) {
+    return;
+  }
+  return {
+    ...base ?? {},
+    ...patch ?? {}
+  };
+}
 // src/composer.ts
 import { satisfies } from "compare-versions";
 
+// src/merger.ts
+function mergeExtensions(extensions) {
+  return [...extensions].sort((a, b) => {
+    const priorityOrder = (a.priority ?? 0) - (b.priority ?? 0);
+    if (priorityOrder !== 0)
+      return priorityOrder;
+    const workflowOrder = a.workflow.localeCompare(b.workflow);
+    if (workflowOrder !== 0)
+      return workflowOrder;
+    const tenantOrder = (a.tenantId ?? "").localeCompare(b.tenantId ?? "");
+    if (tenantOrder !== 0)
+      return tenantOrder;
+    const roleOrder = (a.role ?? "").localeCompare(b.role ?? "");
+    if (roleOrder !== 0)
+      return roleOrder;
+    const deviceOrder = (a.device ?? "").localeCompare(b.device ?? "");
+    if (deviceOrder !== 0)
+      return deviceOrder;
+    return (a.baseVersion ?? "").localeCompare(b.baseVersion ?? "");
+  });
+}
+
+// src/composer.ts
 class WorkflowComposer {
   extensions = [];
   register(extension) {
@@ -146,11 +240,13 @@ class WorkflowComposer {
     return this;
   }
   registerMany(extensions) {
-    extensions.forEach((extension) => this.register(extension));
+    extensions.forEach((extension) => {
+      this.register(extension);
+    });
     return this;
   }
   compose(params) {
-    const applicable = this.extensions.filter((extension) => matches(params, extension)).sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+    const applicable = mergeExtensions(this.extensions.filter((extension) => matches(params, extension)));
     return applicable.reduce((acc, extension) => applyWorkflowExtension(acc, extension), params.base);
   }
 }
@@ -171,10 +267,6 @@ function matches(params, extension) {
   }
   return true;
 }
-// src/merger.ts
-function mergeExtensions(extensions) {
-  return extensions.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
-}
 export {
   validateExtension,
   mergeExtensions,

package/dist/injector.d.ts

@@ -1,3 +1,3 @@
-import type { WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
+import { type WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
 import type { WorkflowExtension } from './types';
 export declare function applyWorkflowExtension(base: WorkflowSpec, extension: WorkflowExtension): WorkflowSpec;

package/dist/node/index.js

@@ -12,16 +12,63 @@ function approvalStepTemplate(options) {
     } : undefined
   };
 }
+// src/injector.ts
+import {
+  validateWorkflowSpec
+} from "@contractspec/lib.contracts-spec/workflow";
+
 // src/validator.ts
 function validateExtension(extension, base) {
   const issues = [];
-  const stepIds = new Set(base.definition.steps.map((step) => step.id));
+  const baseStepIds = new Set(base.definition.steps.map((step) => step.id));
+  if (!extension.workflow.trim()) {
+    issues.push({
+      code: "workflow.extension.workflow",
+      message: "workflow is required"
+    });
+  }
+  if (extension.workflow !== base.meta.key) {
+    issues.push({
+      code: "workflow.extension.workflow.mismatch",
+      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`
+      });
+    }
+  });
+  const availableAnchorSteps = new Set([...baseStepIds].filter((stepId) => !hiddenSteps.has(stepId)));
   extension.customSteps?.forEach((injection, idx) => {
-    if (!injection.inject.id) {
+    const injectionId = injection.inject.id?.trim();
+    if (!injectionId) {
       issues.push({
         code: "workflow.extension.step.id",
         message: `customSteps[${idx}] is missing an id`
       });
+      return;
+    }
+    if (injection.id && injection.id !== injectionId) {
+      issues.push({
+        code: "workflow.extension.step.id-mismatch",
+        message: `customSteps[${idx}] has mismatched id (id="${injection.id}", inject.id="${injectionId}")`
+      });
+    }
+    if (availableAnchorSteps.has(injectionId)) {
+      issues.push({
+        code: "workflow.extension.step.id.duplicate",
+        message: `customSteps[${idx}] injects duplicate step id "${injectionId}"`
+      });
+    }
+    if (injection.after && injection.before) {
+      issues.push({
+        code: "workflow.extension.step.anchor.multiple",
+        message: `customSteps[${idx}] cannot set both after and before`
+      });
     }
     if (!injection.after && !injection.before) {
       issues.push({
@@ -29,27 +76,39 @@ function validateExtension(extension, base) {
         message: `customSteps[${idx}] must set after or before`
       });
     }
-    if (injection.after && !stepIds.has(injection.after)) {
+    if (injection.after && !availableAnchorSteps.has(injection.after)) {
       issues.push({
         code: "workflow.extension.step.after",
         message: `customSteps[${idx}] references unknown step "${injection.after}"`
       });
     }
-    if (injection.before && !stepIds.has(injection.before)) {
+    if (injection.before && !availableAnchorSteps.has(injection.before)) {
       issues.push({
         code: "workflow.extension.step.before",
         message: `customSteps[${idx}] references unknown step "${injection.before}"`
       });
     }
-  });
-  extension.hiddenSteps?.forEach((stepId) => {
-    if (!stepIds.has(stepId)) {
+    if (injection.transitionFrom && !availableAnchorSteps.has(injection.transitionFrom)) {
       issues.push({
-        code: "workflow.extension.hidden-step",
-        message: `hidden step "${stepId}" does not exist`
+        code: "workflow.extension.step.transition-from",
+        message: `customSteps[${idx}] references unknown transitionFrom step "${injection.transitionFrom}"`
+      });
+    }
+    if (injection.transitionTo && !availableAnchorSteps.has(injection.transitionTo)) {
+      issues.push({
+        code: "workflow.extension.step.transition-to",
+        message: `customSteps[${idx}] references unknown transitionTo step "${injection.transitionTo}"`
       });
     }
+    availableAnchorSteps.add(injectionId);
   });
+  const entryStepId = base.definition.entryStepId ?? base.definition.steps[0]?.id;
+  if (entryStepId && hiddenSteps.has(entryStepId)) {
+    issues.push({
+      code: "workflow.extension.hidden-step.entry",
+      message: `hiddenSteps removes the 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}`);
@@ -78,10 +137,13 @@ function applyWorkflowExtension(base, extension) {
   });
   spec.definition.steps = steps;
   spec.definition.transitions = dedupeTransitions(transitions);
-  spec.meta = {
-    ...spec.meta,
-    version: spec.meta.version
-  };
+  spec.metadata = mergeRecords(spec.metadata, extension.metadata);
+  spec.annotations = mergeRecords(spec.annotations, extension.annotations);
+  const issues = validateWorkflowSpec(spec);
+  const blockingIssues = issues.filter((issue) => issue.level === "error");
+  if (blockingIssues.length > 0) {
+    throw new Error(`Invalid composed workflow ${spec.meta.key}.v${spec.meta.version}: ${blockingIssues.map((issue) => issue.message).join("; ")}`);
+  }
   return spec;
 }
 function insertStep(steps, injection) {
@@ -135,9 +197,41 @@ function dedupeTransitions(transitions) {
 function cloneWorkflowSpec(spec) {
   return JSON.parse(JSON.stringify(spec));
 }
+function mergeRecords(base, patch) {
+  if (!base && !patch) {
+    return;
+  }
+  return {
+    ...base ?? {},
+    ...patch ?? {}
+  };
+}
 // src/composer.ts
 import { satisfies } from "compare-versions";
 
+// src/merger.ts
+function mergeExtensions(extensions) {
+  return [...extensions].sort((a, b) => {
+    const priorityOrder = (a.priority ?? 0) - (b.priority ?? 0);
+    if (priorityOrder !== 0)
+      return priorityOrder;
+    const workflowOrder = a.workflow.localeCompare(b.workflow);
+    if (workflowOrder !== 0)
+      return workflowOrder;
+    const tenantOrder = (a.tenantId ?? "").localeCompare(b.tenantId ?? "");
+    if (tenantOrder !== 0)
+      return tenantOrder;
+    const roleOrder = (a.role ?? "").localeCompare(b.role ?? "");
+    if (roleOrder !== 0)
+      return roleOrder;
+    const deviceOrder = (a.device ?? "").localeCompare(b.device ?? "");
+    if (deviceOrder !== 0)
+      return deviceOrder;
+    return (a.baseVersion ?? "").localeCompare(b.baseVersion ?? "");
+  });
+}
+
+// src/composer.ts
 class WorkflowComposer {
   extensions = [];
   register(extension) {
@@ -145,11 +239,13 @@ class WorkflowComposer {
     return this;
   }
   registerMany(extensions) {
-    extensions.forEach((extension) => this.register(extension));
+    extensions.forEach((extension) => {
+      this.register(extension);
+    });
     return this;
   }
   compose(params) {
-    const applicable = this.extensions.filter((extension) => matches(params, extension)).sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+    const applicable = mergeExtensions(this.extensions.filter((extension) => matches(params, extension)));
     return applicable.reduce((acc, extension) => applyWorkflowExtension(acc, extension), params.base);
   }
 }
@@ -170,10 +266,6 @@ function matches(params, extension) {
   }
   return true;
 }
-// src/merger.ts
-function mergeExtensions(extensions) {
-  return extensions.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
-}
 export {
   validateExtension,
   mergeExtensions,

package/dist/types.d.ts

@@ -1,4 +1,18 @@
-import type { Step, WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
+import type { Step, StepModelHints, WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
+import type { ModelSelector } from '@contractspec/lib.ai-providers/selector-types';
+/**
+ * Context provided to operation executors during workflow step execution.
+ * Includes an optional ranking-driven model selector for AI-powered steps.
+ */
+export interface OperationExecutorContext {
+    tenantId?: string;
+    role?: string;
+    /** Ranking-driven model selector; executors should use this when selecting AI models. */
+    modelSelector?: ModelSelector;
+    /** Model hints from the current step, if any. */
+    stepModelHints?: StepModelHints;
+    metadata?: Record<string, unknown>;
+}
 export interface WorkflowExtensionScope {
     tenantId?: string;
     role?: string;

package/package.json

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