lib.workflow-composer

@lssm-tech/lib.workflow-composer

Website: https://contractspec.io

Workflow context, SLA monitoring and SDK error conversion are available through ./workflow/context, ./workflow/sla-monitor and ./workflow/workflow-sdk. ./operation-contracts/registry.workflow exposes the original frozen workflow operation partial. Historical ContractSpec imports forward to these exact implementations. Context accessors, timing defaults, event ordering and SDK error constructor injection are preserved. Private context partitions keep the original state identity and complete method bodies.

Workflow validation execution is available through ./workflow/validation, ./workflow/validation-workflow-devkit, and ./shared-entities/task-validators. These canonical leaves retain the complete original checks, error class, defaults, and nominal registry options. Operation options use the full RuntimeCore host registry; Form, Event, Capability, and Workflow registries retain their canonical class identities. Legacy validation imports forward to these exact implementations. This Source move remains conditional on the accepted RuntimeCore, Forms, and SurfaceRuntime supplier union and its remaining package return paths. All composition source imports now use canonical Core and OrchestrationSpec leaves or the local validator. The Composer dependency on Legacy is removed; the real AI provider selector and complete nominal registry dependencies remain.

Tenant-aware workflow composition helpers for ContractSpec.

What It Provides

• Layer: lib.
• Consumers: bundles.
• Related ContractSpec packages include @lssm-tech/lib.ai-providers, @lssm-tech/lib.contracts-spec, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.
• Related ContractSpec packages include @lssm-tech/lib.ai-providers, @lssm-tech/lib.contracts-spec, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.

Installation

npm install @lssm-tech/lib.workflow-composer

or

bun add @lssm-tech/lib.workflow-composer

Usage

Import the root entrypoint from @lssm-tech/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.
• src/composer.ts is part of the package's public or composition surface.
• src/index.ts is the root public barrel and package entrypoint.
• src/injector.ts is part of the package's public or composition surface.
• src/merger.ts is part of the package's public or composition surface.
• src/templates.ts is part of the package's public or composition surface.
• src/types.ts is shared public type definitions.

Public Entry Points

• Export . resolves through ./src/index.ts.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test --pass-with-no-tests
• bun run lint — bun lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.
• Add AI provider ranking system with ranking-driven model selection.
• Upgrade dependencies.

Notes

• Workflow composition must stay tenant-isolated — no cross-tenant data leakage.
• Depends on contracts-spec — keep aligned with contract definitions.

The additive ./workflow-registry entry owns the existing complete WorkflowRegistry class over Kernel SpecContractRegistry and canonical Orchestration WorkflowSpec. Historical ContractSpec exports forward to the same constructor; registration, lookup and defaults retain their original semantics. Other composition/provider dependencies remain declared by this package.

Canonical workflow execution is available from ./workflow/runner, ./workflow/state, ./workflow/dag-utils, ./workflow/expression, and ./workflow/adapters (including its three adapter leaves). These leaves own the complete original runner and its two error classes, state contracts and persistence implementations. Historical imports forward to the same classes. The runner retains full host DTOs and supplied callback authority, timer and ID defaults, retries, timeout behavior and event order. createFileStateStore (./workflow/adapters/file-adapter) keeps every state in one JSON file: writers hold a <file>.lock lockfile (one breaker at a time removes a stale lock), each write is a flushed temp file atomically renamed over the target, writes and lock-free reads retry Windows sharing violations until a deadline, and every read validates the document and fails closed with a FileStateStoreError (corrupt_state, invalid_state, io_contention, lock_timeout, ...). Other file-system errors, such as a missing directory or a lock file the directory refuses to create, propagate unchanged; outside Windows, EPERM and EACCES are never retried. A writer whose lock token write fails removes that lock before rethrowing. It needs the fs/promises builtin and looks it up on first use through process.getBuiltinModule (Node 20.16+, 22.3+ or Bun). It imports no builtin, statically or dynamically, so the neutral and browser outputs carry no node: specifier and web bundlers (webpack 5 included) build them; on a host without getBuiltinModule (a browser, an older Node) the first call fails with unsupported_host. No provider runtime or persistence dependency is added. Source qualification still requires the accepted host supplier union, unchanged original tests and Root adoption/affected-consumer checks. The original runner is now divided into private execution modules while retaining one public nominal class and all eight public async method bodies. Every runner and test module stays within 250 lines; generic helpers and fixtures stay within 100 lines. All 25 original test calls remain intact, registered in their original order through the existing test entrypoint. The synchronous DAG setup shares the original state and status-map identities. No await site, callback, timer default or policy choice is added or removed. Private modules are included in neutral build entries and the existing dist package closure; no additional public export or dependency is introduced. Promise settlement, compiler and affected-consumer qualification remain with Root’s bounded verification lane.

Canonical workflow operation contracts are available through the explicit ./operation-contracts family. Existing contracts-spec subpaths preserve the same contract objects and nominal registry types. These exports do not execute workflows, fetch benchmarks or run paid evaluations.