@asaidimu/runtime 1.0.3 → 1.0.5

package/README.md

@@ -1,3 +1,389 @@
-# `@asaidimu/utils-runtime`
+# `@asaidimu/runtime`
 
-This package provides runtime utilities.
+A workflow runtime for executing pipelines built on `@asaidimu/utils-pipeline`. Routes bus events to workflow triggers, manages run lifecycle (invoke, pause, resume, abort), and provides execution-mode concurrency control.
+
+## Installation
+
+```bash
+npm install @asaidimu/runtime
+```
+
+## Quick Start
+
+```ts
+import { WorkflowRuntime } from "@asaidimu/runtime";
+import { createEventBus } from "@core/events";
+import { StoreRegistry } from "@core/store";
+
+const bus = createEventBus();
+const storeRegistry = new StoreRegistry();
+
+const runtime = new WorkflowRuntime({ bus, storeRegistry });
+
+await runtime.register(myWorkflow, {
+  mode: { type: "transient", concurrency: 10 },
+  onPrepare: async (ctx) => {
+    /* set up state */
+  },
+  onComplete: async (result) => {
+    /* handle completion */
+  },
+});
+```
+
+## API
+
+### `WorkflowRuntime`
+
+#### Constructor
+
+```ts
+new WorkflowRuntime(options: WorkflowRuntimeOptions)
+```
+
+| Option          | Type                                  | Description                                                                                                                                                                                    |
+| --------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bus`           | `EventBus`                            | Event bus for dispatching and subscribing to workflow events                                                                                                                                   |
+| `storeRegistry` | `StoreRegistry`                       | Registry for creating workflow state stores                                                                                                                                                    |
+| `timelineStore` | `TimelineStore`                       | Optional store for recording execution timelines. When set, all log messages emitted by pipeline steps via `pcxt.logger` are automatically captured as timeline events with source `"logger"`. |
+| `services`      | `ServiceDefinition[]`                 | Optional global singleton services injected into all pipeline runs                                                                                                                             |
+| `env`           | `Record<string, string \| undefined>` | Optional global environment variables (defaults to `process.env`). Per-workflow overrides can be set on the `Workflow` definition.                                                             |
+
+#### `static createTestTimelineStore(database?)`
+
+Creates a `TimelineStore` backed by IndexedDB, useful in test harnesses.
+
+```ts
+const timelineStore =
+  await WorkflowRuntime.createTestTimelineStore("my-test-db");
+```
+
+#### `register(workflow, options)`
+
+Registers a workflow with the runtime. Wires up triggers to bus events and execution-mode enforcement. If the workflow declares `services`, a scoped child container is created so those services are visible only to runs of that workflow. If the workflow declares `env`, those variables override the global env layer for runs of this workflow.
+
+```ts
+runtime.register(workflow, {
+  mode: { type: "transient", concurrency: 10, capacity: 100 },
+  onPrepare: async (ctx) => { ... },
+  onComplete: async (result) => { ... },
+  onResume: async (ctx) => { ... },
+  onCleanup: async () => { ... },
+  onDispatch: (result) => { ... },
+});
+```
+
+**Hook order on completion:**
+
+1. `onComplete(result)` — fires immediately when the run finishes
+2. Internal bookkeeping (`settle`, `onRunEnded`, `registry.prune`)
+3. `onCleanup()` — fires after internal cleanup is done
+
+This ordering ensures the UI is notified before any cleanup runs, and `onCleanup` runs after internal state is settled (safe to deregister the workflow).
+
+#### `deregister(workflowId)`
+
+Removes a workflow, releases all bus subscriptions, and disposes the workflow's scoped service container.
+
+#### `hasWorkflow(workflowId)`
+
+Returns `true` if the workflow is registered.
+
+#### `listWorkflows()`
+
+Returns an array of registered workflow IDs.
+
+#### `invoke(workflowId, triggerId, event)`
+
+Directly executes a pipeline, bypassing the bus and execution context. Returns a promise that resolves when the run completes or pauses.
+
+```ts
+const result = await runtime.invoke("my-workflow", "my-trigger", event);
+
+if (result.ok) {
+  if (result.value.status === "paused") {
+    const runId = result.metadata!.runId;
+    // Resume later via runtime.resume(runId, patch)
+  }
+}
+```
+
+#### `resume(runId, patch?)`
+
+Resumes a paused run with an optional state patch. Handles:
+
+- Pause-window expiry (reconstructs context from checkpoint)
+- Watch drain — if the resumed run re-pauses, checks for buffered events
+- Service injection for reconstructed contexts
+
+#### `signal(runId, patch)`
+
+Writes a state patch directly into a running run's context.
+
+#### `abort(runId)`
+
+Aborts a running or paused run.
+
+#### `registry(workflowId)`
+
+Returns the `PipelineRegistry` for a workflow, or `undefined`.
+
+#### `watch(workflowId, runId)`
+
+Returns `RunInfo` for a specific run, or `undefined`.
+
+#### `listAllRuns()`
+
+Returns an array of all runs across all registered workflows.
+
+#### `stop()`
+
+Gracefully stops the runtime. Deregisters all workflows and unsubscribes from abort/signal events.
+
+## Execution Modes
+
+| Mode             | Description                                                                |
+| ---------------- | -------------------------------------------------------------------------- |
+| `transient`      | Concurrency-limited. Drops when queue hits capacity.                       |
+| `serialized`     | FIFO queue, one run at a time. Uses `Serializer`.                          |
+| `singleton_loop` | At most one active run. On busy: `drop`, `signal`, or `replace`.           |
+| `exclusive`      | At most one active run. On busy: `reject` or `queue_single` (latest-wins). |
+
+## Pause / Resume
+
+Pipelines can pause at a stage boundary. The runtime:
+
+1. Buffers matching events **before** the pause (pre-pause window) and **between** resume cycles (inter-resume buffer).
+2. On pause, immediately drains any buffered events via `resume()`.
+3. If the queue is empty, the run "parks" — the next matching bus event triggers resume automatically.
+
+The `PauseService` is available to steps as `services.__pause_service__` and provides `register()`, `cancel()`, and condition-based event matching with AND semantics across operators: `==`, `!=`, `>`, `>=`, `<`, `<=`, `exists`.
+
+## Services
+
+### Global services
+
+Services available to every pipeline run can be injected at construction. They are registered as singletons on the runtime's internal `ArtifactContainer`.
+
+```ts
+new WorkflowRuntime({
+  bus,
+  storeRegistry,
+  services: [
+    {
+      id: "my-api",
+      factory: () => new ApiClient(), // context is available but unused
+    },
+    {
+      id: "my-context",
+      factory: (ctx) => new RequestContext(ctx.runId),
+      // ctx has state(), use(), select(), onCleanup(), etc.
+    },
+  ],
+});
+```
+
+The `factory` receives a full `ArtifactFactoryContext` allowing service factories to use `ctx.use()`, `ctx.select()`, and other artifact container features for dependency injection.
+
+`ServiceDefinition` has no `scope` field — global services are always `"singleton"`.
+
+### Workflow-level services
+
+Workflows can declare their own services with three scope options:
+
+| Scope         | Lifetime                                  | Container                            | Artifact scope |
+| ------------- | ----------------------------------------- | ------------------------------------ | -------------- |
+| `"workflow"`  | As long as the workflow is registered     | Scoped child of the global container | `"singleton"`  |
+| `"run"`       | For the duration of a single pipeline run | Run's context container (per-run)    | `"singleton"`  |
+| `"transient"` | Per-resolution (new instance each time)   | Run's context container (per-run)    | `"transient"`  |
+
+**`"workflow"`** (default) services are registered in a scoped child container, isolating them to runs of that workflow. They **cannot** access run state via `select()` because their factory runs against the scoped container's store.
+
+**`"run"`** and **`"transient"`** services are registered directly on each run's context container. Their factories resolve against the **run's state store**, so they can use `deps.select()` to read pipeline state and react to state changes.
+
+```ts
+const workflow = {
+  id: "my-workflow",
+  label: "My Workflow",
+  triggers: { ... },
+  pipelines: { ... },
+  services: [
+    // workflow-scoped: shared across all runs, no run state access
+    { id: "config", scope: "workflow", factory: () => loadConfig() },
+
+    // run-scoped: singleton per run, can access run state
+    {
+      id: "userProfile",
+      scope: "run",
+      factory: async (ctx) => {
+        const userId = await ctx.use((deps) =>
+          deps.select((s: any) => s.userId),
+        );
+        return fetchProfile(userId);
+      },
+    },
+
+    // transient: new instance per resolution, can access run state
+    { id: "requestId", scope: "transient", factory: () => crypto.randomUUID() },
+  ],
+};
+```
+
+### Reserved service IDs
+
+The following service IDs are reserved and cannot be redefined:
+
+| ID                  | Description                                                  |
+| ------------------- | ------------------------------------------------------------ |
+| `__pause_service__` | Built-in `PauseService` for pause/resume workflows           |
+| `__env__`           | Built-in environment variable service for layered env access |
+
+Attempting to redefine either throws a `SystemError` with code `DUPLICATE_KEY`.
+
+---
+
+### Environment variables (`__env__`)
+
+The runtime provides a built-in `__env__` service for reading environment variables. It supports two layers:
+
+- **Global** — set via `WorkflowRuntimeOptions.env` (falls back to `process.env`)
+- **Per-workflow** — set via `Workflow.env`, overrides the global layer for that workflow
+
+```ts
+const runtime = new WorkflowRuntime({
+  bus,
+  storeRegistry,
+  env: { DATABASE_URL: "postgres://..." }, // global default
+});
+
+const workflow = {
+  id: "my-workflow",
+  env: { DATABASE_URL: "postgres://override..." }, // per-workflow override
+  // ...
+};
+```
+
+Steps access env vars via `deps.require("__env__")` and call `.get()`:
+
+```ts
+action: async (ctx) => {
+  const env = await ctx.use((deps) => deps.require("__env__"));
+  const dbUrl = env.get("DATABASE_URL"); // workflow env wins, then global
+};
+```
+
+Resolution order:
+
+1. Per-workflow env layer (if set on `Workflow.env`)
+2. Global env layer (`WorkflowRuntimeOptions.env` or `process.env`)
+3. `undefined`
+
+#### `EnvService` API
+
+```ts
+interface EnvService {
+  get(key: string): string | undefined;
+}
+```
+
+Only `.get()` is exposed — plain property access (`env.KEY`) is not supported. The service is read-only.
+
+### Do's and Don'ts of Services
+
+#### Do
+
+- **Do** use `"run"`-scoped services when the factory needs to read pipeline state via `select()` — they resolve against the run's state store.
+- **Do** use `"workflow"`-scoped services for shared configuration, API clients, or connections that are identical across all runs of a workflow.
+- **Do** use `__env__` for reading configuration — it correctly resolves per-workflow overrides over the global defaults.
+- **Do** keep service factories pure where possible — prefer injecting state via `select()` over side-effectful construction.
+- **Do** use `ctx.onCleanup()` inside factories to release resources (close sockets, free handles) when the run ends.
+
+#### Don't
+
+- **Don't** attempt to register a service with ID `__pause_service__` or `__env__` — both are reserved and throw `DUPLICATE_KEY`.
+- **Don't** use `"workflow"`-scoped services for per-run state — they are singletons shared across all runs and cannot access run-specific state via `select()`.
+- **Don't** cache per-run data in `"workflow"`-scoped or global singletons — it will leak across runs.
+- **Don't** mutate the env service or treat it as a plain object — always use `.get("KEY")`.
+- **Don't** assume `process.env` is available — the runtime may be configured with an explicit `env` object that does not include it.
+
+### Service resolution
+
+Steps resolve services via `ctx.use()`:
+
+```ts
+action: async (ctx) => {
+  const svc = await ctx.use((deps) => deps.require("my-api"));
+};
+```
+
+The `ctx.use()` callback receives a `UseDependencyContext` with `resolve()`, `require()`, and `select()`.
+
+## Container Architecture
+
+The runtime uses an `ArtifactContainer` (from `@core/artifacts`) as its internal service container:
+
+```
+Global service container (ArtifactContainer)
+  ├── Global singleton services
+  ├── __pause_service__ (built-in PauseService)
+  ├── __env__ (unscoped fallback — rarely hit)
+  └── Scoped containers per workflow
+       ├── Workflow-scoped services ("workflow" scope)
+       └── Run context extends with scoped __env__ (global + per-workflow layers)
+```
+
+When a pipeline run starts, the run's context container is **extended** with:
+
+1. The workflow's scoped container (for `"workflow"`-scoped services)
+2. The global service container (for global services and `__pause_service__`)
+3. `"run"`-scoped and `"transient"` services are registered directly on the run's container, so their factories resolve against the run's state store.
+
+On `deregister()`, the workflow's scoped container is disposed, cleaning up all workflow-level artifacts.
+
+### Container capabilities
+
+The underlying `ArtifactContainer` provides:
+
+| Feature              | Description                                                                                                                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `register(template)` | Register an artifact with scope (`singleton` / `transient`), lazy/eager loading, timeouts, retries, param key, and serialization opt-in                                                |
+| `resolve(key)`       | Resolve an artifact, falling back through parent containers                                                                                                                            |
+| `require(key)`       | Like `resolve` but returns the instance directly, throws on error                                                                                                                      |
+| `peek(key)`          | Synchronous non-resolving lookup                                                                                                                                                       |
+| `invalidate(key)`    | Invalidate a cached artifact, optionally force rebuild                                                                                                                                 |
+| `extend(parent)`     | Add a parent container for fallback resolution                                                                                                                                         |
+| `scope(name)`        | Create a namespaced `ScopedContainer`                                                                                                                                                  |
+| `watch(key)`         | Create an observer that fires on change                                                                                                                                                |
+| `on(event)`          | Subscribe to lifecycle events (`build:start`, `build:complete`, `build:error`, `artifact:invalidated`, `artifact:disposed`, `artifact:registered`, `stream:emit`, `container:dispose`) |
+| `export()`           | Serialize singleton artifacts for persistence                                                                                                                                          |
+| `from(bundle)`       | Static factory: create container from store + optional bundle + templates                                                                                                              |
+| `debugInfo()`        | Snapshot of all artifacts' status, dependencies, and dependents                                                                                                                        |
+
+## Internal Architecture
+
+```
+Bus events → dispatch index → ExecutionContext.accept() → spawnRun()
+                                                              │
+                     ┌────────────────────────────────────────┤
+                     │                                        │
+               pipeline runs                              returns runId
+                     │                                        │
+             ┌───────┴───────┐                          ExecutionContext
+             │               │                          updates inFlight
+          paused         completed                      / activeRunId
+             │               │
+     drainWatchQueue     onComplete() → UI notified
+             │               │
+        resume()         bookkeeping
+             │               │
+     ┌───────┴───────┐   onCleanup()
+     │               │
+   re-paused      completed → onComplete()
+```
+
+## Testing
+
+```bash
+npm test
+npm run test:watch
+```

package/index.d.cts

@@ -1030,7 +1030,7 @@ interface ArtifactObserver<TRegistry, K extends keyof TRegistry> {
  * @template TArtifact The resolved type of the artifact instance.
  * @template TRegistry The type mapping of all artifacts in the container.
  */
-interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends Record<string, any> = Record<string, any>, TExtra extends Record<string, any> = {}> {
+interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends Record<string, any> = Record<string, any>, TExtra extends Record<string, any> = {}, K extends Record<string, unknown> = Record<string, unknown>> {
   /** The unique key identifying this artifact within the registry. */
   key: keyof TRegistry;
   /** The factory function responsible for creating the artifact's instance. */
@@ -1064,7 +1064,7 @@ interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends R
    */
   debounce?: number;
   /** If defined, the artifact is parameterized. Receives the user‑supplied params and returns a unique string key. */
-  paramKey?: (params: Record<string, unknown>) => string;
+  paramKey?: (params: K) => string;
   virtual?: true;
   /**
    * If `true`, the artifact's instance can be serialized and included in
@@ -1351,6 +1351,19 @@ declare class ArtifactRegistry<TRegistry extends Record<string, any> = Record<st
  * Levels are ordered by increasing severity: trace, debug, info, warn, error.
  */
 type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/**
+ * Defines a destination where system logs are outputted or processed.
+ * Custom sinks (e.g., File, Logstash, Sentry) must implement this interface.
+ */
+interface LogSink {
+  /**
+   * Dispatches a structured log entry to the underlying destination.
+   *
+   * @param record - The complete log object containing metadata and payload.
+   * @returns A void or Promise that resolves when the log has been safely handed off.
+   */
+  write(record: SystemLog): void | Promise<void>;
+}
 /**
  * Structure representing a fully contextualized system log entry ready for sinking.
  */
@@ -1367,7 +1380,8 @@ interface SystemLog {
   timestamp: number;
 }
 /**
- * Primary logger interface providing level-specific log dispatching and context-chaining.
+ * Primary logger interface providing level-specific log dispatching, context-chaining,
+ * and dynamic sink management.
  */
 interface SystemLogger {
   /** Logs high-volume, extremely fine-grained diagnostic details. */
@@ -1394,6 +1408,22 @@ interface SystemLogger {
    * @param context - The metadata to append to all subsequent logs emitted by the child logger.
    */
   child(context: object): SystemLogger;
+  /**
+   * Adds a new sink to this logger instance.
+   * The sink will receive all logs emitted by this logger and its descendants (unless
+   * a descendant removes it). This operation does not affect the parent logger.
+   *
+   * @param sink - The LogSink to add.
+   */
+  addSink(sink: LogSink): void;
+  /**
+   * Removes a previously added sink from this logger instance.
+   * Returns `true` if the sink was found and removed, otherwise `false`.
+   * This operation does not affect the parent logger.
+   *
+   * @param sink - The LogSink to remove.
+   */
+  removeSink(sink: LogSink): boolean;
 }
 //#endregion
 //#region src/artifacts/observer.d.ts
@@ -1467,7 +1497,14 @@ declare class ArtifactObserverManager<TRegistry extends Record<string, any>, TSt
 }
 //#endregion
 //#region src/artifacts/manager.d.ts
-declare class ArtifactManager<TRegistry extends Record<string, any>, TState extends object> {
+/** Minimal interface for parent-chain resolution operations. */
+interface ParentChainManager {
+  build(key: string, parentPath?: Array<any>, templateKey?: string): Promise<KeyedResolvedArtifact<any, any>>;
+  invalidate(key: string, replace?: boolean, fatal?: boolean): Promise<void>;
+  has(key: string): boolean;
+  getCached(key: string): CachedArtifact<any, any> | undefined;
+}
+declare class ArtifactManager<TRegistry extends Record<string, any>, TState extends object> implements ParentChainManager {
   private readonly registry;
   private readonly cache;
   private readonly graph;
@@ -1476,10 +1513,14 @@ declare class ArtifactManager<TRegistry extends Record<string, any>, TState exte
   private readonly logger;
   private readonly events?;
   /** Parent containers used as fallback during resolution */
-  readonly parentContainers: ArtifactManager<any, any>[];
+  readonly parentContainers: ParentChainManager[];
   constructor(registry: ArtifactRegistry<TRegistry, TState>, cache: ArtifactCache<TRegistry>, graph: ArtifactDependencyGraph, store: Pick<DataStore<TState>, "watch" | "get" | "set">, observer: ArtifactObserverManager<TRegistry, TState>, logger: SystemLogger, events?: EventBus<ArtifactLifecycleEventMap> | undefined);
-  addParent(parent: ArtifactManager<any, any>): void;
-  removeParent(parent: ArtifactManager<any, any>): void;
+  addParent(parent: ParentChainManager): void;
+  removeParent(parent: ParentChainManager): void;
+  /** @inheritdoc */
+  has(key: string): boolean;
+  /** @inheritdoc */
+  getCached(key: string): CachedArtifact<any, any> | undefined;
   build(key: string, parentPath?: Array<keyof TRegistry>, templateKey?: string): Promise<KeyedResolvedArtifact<TRegistry, any>>;
   private buildFromParent;
   private executeBuild;
@@ -1501,7 +1542,51 @@ declare class ArtifactManager<TRegistry extends Record<string, any>, TState exte
   computeParamKey<K extends keyof TRegistry>(key: K, params: Record<string, unknown>): string;
 }
 //#endregion
+//#region src/artifacts/scoped-container.d.ts
+declare class ScopedContainer<TRegistry extends Record<string, any> = Record<string, any>, TState extends object = any> implements ContainerLike {
+  private readonly container;
+  readonly name: string;
+  private readonly prefix;
+  private readonly keys;
+  private disposed;
+  private readonly scopedManager;
+  constructor(container: ArtifactContainer<TRegistry, TState>, name: string);
+  /**
+   * Returns a scope-aware parent-chain manager that mangles keys with the
+   * scope prefix. When used via extend(), the child's parentContainers will
+   * only see scoped artifacts — not the underlying container's global ones.
+   */
+  get manager(): ParentChainManager;
+  /** Expose the parent container's event bus so this scope can act as an extend parent. */
+  get events(): EventBus<ArtifactLifecycleEventMap>;
+  private ensureNotDisposed;
+  private mangle;
+  register<K extends keyof TRegistry>(params: ArtifactTemplate<TState, TRegistry[K], TRegistry>): () => void;
+  dispose(): Promise<void>;
+  resolve<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<KeyedResolvedArtifact<TRegistry, K>>;
+  require<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<TRegistry[K]>;
+  has<K extends keyof TRegistry>(key: K): boolean;
+  peek<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): TRegistry[K] | undefined;
+  invalidate<K extends keyof TRegistry>(key: K, options?: {
+    replace?: boolean;
+    params?: Record<string, unknown>;
+  }): Promise<void>;
+  unregister<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<void>;
+  watch<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>, ttl?: number): ArtifactObserver<TRegistry, K>;
+  notifyObservers(key: string): void;
+  hasWatchers(key: string): boolean;
+}
+//#endregion
 //#region src/artifacts/container.d.ts
+/** Minimum interface required for something to act as a parent via extend(). */
+interface ContainerLike {
+  readonly manager: ParentChainManager;
+  readonly events: EventBus<ArtifactLifecycleEventMap>;
+  has(key: any): boolean;
+  peek(key: any, params?: Record<string, unknown>): any;
+  resolve(key: any, params?: Record<string, unknown>): Promise<any>;
+  watch(key: any, params?: Record<string, unknown>, ttl?: number): ArtifactObserver<any, any>;
+}
 declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<string, any>, TState extends object = any> {
   private readonly registry;
   private readonly cache;
@@ -1512,9 +1597,11 @@ declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<s
   private readonly store;
   readonly events: EventBus<ArtifactLifecycleEventMap>;
   /** Parent containers used as fallback during resolution */
-  readonly parents: ArtifactContainer<any, any>[];
+  readonly parents: ContainerLike[];
   /** Cleanup functions for parent event subscriptions */
   private parentCleanups;
+  /** Track used scope names to enforce uniqueness */
+  readonly scopeNames: Set<string>;
   constructor(store: Pick<DataStore<TState>, "watch" | "get" | "set" | "subset">, options?: {
     logger?: SystemLogger;
   });
@@ -1535,14 +1622,28 @@ declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<s
   once<TEventName extends keyof ArtifactLifecycleEventMap>(eventName: TEventName, callback: (payload: ArtifactLifecycleEventMap[TEventName]) => void): () => void;
   once(eventName: "*", callback: (payload: ArtifactLifecycleEventMap[keyof ArtifactLifecycleEventMap], event: keyof ArtifactLifecycleEventMap) => void): () => void;
   /**
-   * Extends this container with a parent container. When resolution of a key
-   * fails locally, each parent is tried in order. Returned artifacts are cached
-   * as lightweight proxies with the instance from the parent. Invalidation
-   * propagates from parent to child transparently.
+   * Extends this container with a parent container or scoped container.
+   * When resolution of a key fails locally, each parent is tried in order.
+   * Invalidation propagates from parent to child transparently.
+   *
+   * When the parent is an `ArtifactContainer`, read-only methods (`has`,
+   * `peek`, `watch`) also delegate to it. For `ScopedContainer` parents,
+   * only invalidation propagation and manager wiring are established.
    *
    * @returns A function to un-extend the parent.
    */
-  extend(parent: ArtifactContainer<any, any>): () => void;
+  extend(parent: ContainerLike): () => void;
+  /**
+   * Creates a scoped view of this container. Artifacts registered on the
+   * scoped container get their keys prefixed with `"<name>::"`, making them
+   * invisible to other scopes but discoverable from this container.
+   *
+   * Scope names must be unique per container — a duplicate name throws.
+   *
+   * Dependencies resolved inside a scoped artifact's factory (via `use()`) try
+   * the scoped key first, then fall back to the unscoped (global) key.
+   */
+  scope(name: string): ScopedContainer<TRegistry, TState>;
   notifyObservers(key: string): void;
   hasWatchers(key: string): boolean;
   dispose(): Promise<void>;
@@ -2240,6 +2341,18 @@ interface TimelineStoreEvents<S = any> {
   };
 }
 //#endregion
+//#region src/pipeline/pollyfill.d.ts
+type NodeSetImmediate = typeof globalThis extends {
+  setImmediate: infer T;
+} ? T : never;
+type NodeClearImmediate = typeof globalThis extends {
+  clearImmediate: infer T;
+} ? T : never;
+declare global {
+  function setImmediate(callback: (...args: any[]) => void, ...args: any[]): NodeSetImmediate extends never ? number : ReturnType<any>;
+  function clearImmediate(id: NodeClearImmediate extends never ? number : Parameters<any>[0]): void;
+}
+//#endregion
 //#region node_modules/.bun/@asaidimu+query@1.1.2/node_modules/@asaidimu/query/index.d.ts
 /**
  * Query-related type definitions.
@@ -13523,6 +13636,17 @@ declare class TimelineStore<S = any> implements ITimelineEventSource<S> {
   private allDocs;
 }
 //#endregion
+//#region src/runtime/types/service.d.ts
+type ServiceDefinition<T> = {
+  id: string;
+  factory: ArtifactFactory<any, any, T>;
+};
+type WorkflowServiceDefinition<T = unknown> = {
+  id: string;
+  scope?: "workflow" | "run" | "transient";
+  factory: ArtifactFactory<any, any, T>;
+};
+//#endregion
 //#region src/runtime/types/workflow.d.ts
 type WorkflowState<T extends Record<string, any> = Record<string, any>> = T;
 interface WorkflowEvent<Payload = unknown> {
@@ -13541,24 +13665,10 @@ interface Workflow<T extends Record<string, any> = Record<string, any>> {
   label: string;
   triggers: Record<string, WorkflowTrigger>;
   pipelines: Record<string, RoutingPipelineDefinition<WorkflowState<T>>>;
+  services?: WorkflowServiceDefinition[];
+  env?: Record<string, string | undefined>;
 }
 //#endregion
-//#region src/runtime/types/service.d.ts
-interface RunServiceContext {
-  runId: string;
-  workflowId: string;
-  triggerId: string;
-}
-type ServiceDefinition<T> = {
-  id: string;
-  scope: "singleton";
-  factory: () => T | Promise<T>;
-} | {
-  id: string;
-  scope: "transient";
-  factory: (ctx: RunServiceContext) => T | Promise<T>;
-};
-//#endregion
 //#region src/runtime/types/runtime.d.ts
 declare const ABORT_EVENT: "__abort__";
 declare const SIGNAL_EVENT: "__signal__";
@@ -13596,9 +13706,11 @@ type InvokeResult = Result<PipelineRunResult<WorkflowState>, SystemError, {
 }>;
 interface WorkflowRuntimeOptions {
   bus: EventBus<Record<string, any>>;
+  logger?: SystemLogger;
   storeRegistry: StoreRegistry<WorkflowState>;
   timelineStore?: TimelineStore<WorkflowState>;
   services?: ServiceDefinition<unknown>[];
+  env?: Record<string, string | undefined>;
 }
 interface RegisterOptions {
   mode: WorkflowExecutionMode;
@@ -13616,10 +13728,10 @@ declare class WorkflowRuntime {
   private readonly timelineStore;
   /** Built-in watch service. Always present. */
   private readonly pauseService;
-  /** User-defined run-scoped service definitions, instantiated per run. */
-  private readonly runServiceDefinitions;
   /** Global container holding all registered services accessible by steps. */
   private readonly serviceContainer;
+  /** Store backing the global container — used to update reactive env state. */
+  private readonly serviceStore;
   private readonly workflows;
   private readonly index;
   private readonly subscriptions;
@@ -13628,6 +13740,7 @@ declare class WorkflowRuntime {
    * Populated when a run pauses. Cleared when run ends or is aborted.
    */
   private readonly pausedRuns;
+  private readonly logger;
   private readonly abortUnsubscribe;
   private readonly signalUnsubscribe;
   constructor(options: WorkflowRuntimeOptions);
@@ -13638,14 +13751,28 @@ declare class WorkflowRuntime {
   listWorkflows(): string[];
   stop(): Promise<void>;
   registry(workflowId: string): PipelineRegistry<WorkflowState> | undefined;
-  watch(workflowId: string, runId: string): RunInfo<WorkflowState> | undefined;
-  listAllRuns(): Array<RunInfo<WorkflowState> & {
+  info(workflowId: string, runId: string): RunInfo<WorkflowState> | undefined;
+  list(): Array<RunInfo<WorkflowState> & {
     workflowId: string;
   }>;
   invoke(workflowId: string, triggerId: string, event: WorkflowEvent): Promise<InvokeResult>;
   resume(runId: string, patch?: DeepPartial<WorkflowState>): Promise<InvokeResult>;
   signal(runId: string, patch: DeepPartial<WorkflowState>): Promise<void>;
   private dispatch;
+  /**
+   * Creates a TimelineRecorder for the given workflow, resolving the
+   * per-workflow sanitizer from the global service container.
+   *
+   * Returns `undefined` when no timelineStore is configured.
+   */
+  private createRecorder;
+  /**
+   * Attaches a TimelineRecorder (when one is provided) to the run context,
+   * invokes the callback, and detaches it in a finally block.
+   *
+   * When no recorder is provided the callback runs without recording.
+   */
+  private withRecorder;
   private executePipeline;
   private spawnRun;
   private drainWatchQueue;
@@ -13653,10 +13780,28 @@ declare class WorkflowRuntime {
   private buildExecutionContext;
   private acquireBusSubscription;
   private releaseBusSubscription;
+  /**
+   * Extends `ctx.container` with the workflow's scoped container (if any) and
+   * the global service container, then:
+   *   - Eagerly resolves the parameterized __scoped_env_service__ for this
+   *     workflow and registers the captured EnvService as __env__ (frozen for
+   *     the run).
+   *   - Shadows __env_service__ and __scoped_env_service__ so steps cannot
+   *     access them via container extension bubbling.
+   *   - Registers per‑run and transient workflow services on the run's
+   *     container so their factories resolve against the run's state store.
+   */
+  private extendContextContainer;
   private getOrCreateFactory;
   private generateRunId;
 }
 //#endregion
+//#region src/runtime/types/env.d.ts
+interface EnvService {
+  get(key: string): string | undefined;
+  list(): Record<string, string | undefined>;
+}
+//#endregion
 //#region src/runtime/types/pause.d.ts
 type PauseOperator = ">=" | "<=" | "==" | "!=" | ">" | "<" | "exists";
 interface PauseCondition {
@@ -13670,4 +13815,4 @@ interface PauseDescriptor {
   patch?: DeepPartial<WorkflowState>;
 }
 //#endregion
-export { ABORT_EVENT, type DispatchResult, type InvokeResult, type PauseCondition, type PauseDescriptor, type PauseOperator, type RegisterOptions, SIGNAL_EVENT, type ServiceDefinition, type Workflow, type WorkflowEvent, type WorkflowExecutionMode, WorkflowRuntime, type WorkflowRuntimeOptions, type WorkflowState, type WorkflowTrigger };
+export { ABORT_EVENT, type DispatchResult, type EnvService, type InvokeResult, type PauseCondition, type PauseDescriptor, type PauseOperator, type RegisterOptions, SIGNAL_EVENT, type ServiceDefinition, type Workflow, type WorkflowEvent, type WorkflowExecutionMode, WorkflowRuntime, type WorkflowRuntimeOptions, type WorkflowServiceDefinition, type WorkflowState, type WorkflowTrigger };

package/index.d.ts

@@ -1,8 +1,21 @@
+import { ArtifactContainer, ArtifactFactory } from "@asaidimu/utils-artifacts";
 import { Result, SystemError } from "@asaidimu/utils-error";
+import { SystemLogger } from "@asaidimu/utils-logger";
 import { PipelineFactory, PipelineRegistry, PipelineRunResult, RoutingPipelineDefinition, RunContext, RunInfo, TimelineStore } from "@asaidimu/utils-pipeline";
 import { DeepPartial, StoreRegistry } from "@asaidimu/utils-store";
 import { EventBus } from "@asaidimu/utils-events";
 
+//#region src/runtime/types/service.d.ts
+type ServiceDefinition<T> = {
+  id: string;
+  factory: ArtifactFactory<any, any, T>;
+};
+type WorkflowServiceDefinition<T = unknown> = {
+  id: string;
+  scope?: "workflow" | "run" | "transient";
+  factory: ArtifactFactory<any, any, T>;
+};
+//#endregion
 //#region src/runtime/types/workflow.d.ts
 type WorkflowState<T extends Record<string, any> = Record<string, any>> = T;
 interface WorkflowEvent<Payload = unknown> {
@@ -21,24 +34,10 @@ interface Workflow<T extends Record<string, any> = Record<string, any>> {
   label: string;
   triggers: Record<string, WorkflowTrigger>;
   pipelines: Record<string, RoutingPipelineDefinition<WorkflowState<T>>>;
+  services?: WorkflowServiceDefinition[];
+  env?: Record<string, string | undefined>;
 }
 //#endregion
-//#region src/runtime/types/service.d.ts
-interface RunServiceContext {
-  runId: string;
-  workflowId: string;
-  triggerId: string;
-}
-type ServiceDefinition<T> = {
-  id: string;
-  scope: "singleton";
-  factory: () => T | Promise<T>;
-} | {
-  id: string;
-  scope: "transient";
-  factory: (ctx: RunServiceContext) => T | Promise<T>;
-};
-//#endregion
 //#region src/runtime/types/runtime.d.ts
 declare const ABORT_EVENT: "__abort__";
 declare const SIGNAL_EVENT: "__signal__";
@@ -76,9 +75,11 @@ type InvokeResult = Result<PipelineRunResult<WorkflowState>, SystemError, {
 }>;
 interface WorkflowRuntimeOptions {
   bus: EventBus<Record<string, any>>;
+  logger?: SystemLogger;
   storeRegistry: StoreRegistry<WorkflowState>;
   timelineStore?: TimelineStore<WorkflowState>;
   services?: ServiceDefinition<unknown>[];
+  env?: Record<string, string | undefined>;
 }
 interface RegisterOptions {
   mode: WorkflowExecutionMode;
@@ -96,10 +97,10 @@ declare class WorkflowRuntime {
   private readonly timelineStore;
   /** Built-in watch service. Always present. */
   private readonly pauseService;
-  /** User-defined run-scoped service definitions, instantiated per run. */
-  private readonly runServiceDefinitions;
   /** Global container holding all registered services accessible by steps. */
   private readonly serviceContainer;
+  /** Store backing the global container — used to update reactive env state. */
+  private readonly serviceStore;
   private readonly workflows;
   private readonly index;
   private readonly subscriptions;
@@ -108,6 +109,7 @@ declare class WorkflowRuntime {
    * Populated when a run pauses. Cleared when run ends or is aborted.
    */
   private readonly pausedRuns;
+  private readonly logger;
   private readonly abortUnsubscribe;
   private readonly signalUnsubscribe;
   constructor(options: WorkflowRuntimeOptions);
@@ -118,14 +120,28 @@ declare class WorkflowRuntime {
   listWorkflows(): string[];
   stop(): Promise<void>;
   registry(workflowId: string): PipelineRegistry<WorkflowState> | undefined;
-  watch(workflowId: string, runId: string): RunInfo<WorkflowState> | undefined;
-  listAllRuns(): Array<RunInfo<WorkflowState> & {
+  info(workflowId: string, runId: string): RunInfo<WorkflowState> | undefined;
+  list(): Array<RunInfo<WorkflowState> & {
     workflowId: string;
   }>;
   invoke(workflowId: string, triggerId: string, event: WorkflowEvent): Promise<InvokeResult>;
   resume(runId: string, patch?: DeepPartial<WorkflowState>): Promise<InvokeResult>;
   signal(runId: string, patch: DeepPartial<WorkflowState>): Promise<void>;
   private dispatch;
+  /**
+   * Creates a TimelineRecorder for the given workflow, resolving the
+   * per-workflow sanitizer from the global service container.
+   *
+   * Returns `undefined` when no timelineStore is configured.
+   */
+  private createRecorder;
+  /**
+   * Attaches a TimelineRecorder (when one is provided) to the run context,
+   * invokes the callback, and detaches it in a finally block.
+   *
+   * When no recorder is provided the callback runs without recording.
+   */
+  private withRecorder;
   private executePipeline;
   private spawnRun;
   private drainWatchQueue;
@@ -133,10 +149,28 @@ declare class WorkflowRuntime {
   private buildExecutionContext;
   private acquireBusSubscription;
   private releaseBusSubscription;
+  /**
+   * Extends `ctx.container` with the workflow's scoped container (if any) and
+   * the global service container, then:
+   *   - Eagerly resolves the parameterized __scoped_env_service__ for this
+   *     workflow and registers the captured EnvService as __env__ (frozen for
+   *     the run).
+   *   - Shadows __env_service__ and __scoped_env_service__ so steps cannot
+   *     access them via container extension bubbling.
+   *   - Registers per‑run and transient workflow services on the run's
+   *     container so their factories resolve against the run's state store.
+   */
+  private extendContextContainer;
   private getOrCreateFactory;
   private generateRunId;
 }
 //#endregion
+//#region src/runtime/types/env.d.ts
+interface EnvService {
+  get(key: string): string | undefined;
+  list(): Record<string, string | undefined>;
+}
+//#endregion
 //#region src/runtime/types/pause.d.ts
 type PauseOperator = ">=" | "<=" | "==" | "!=" | ">" | "<" | "exists";
 interface PauseCondition {
@@ -150,4 +184,4 @@ interface PauseDescriptor {
   patch?: DeepPartial<WorkflowState>;
 }
 //#endregion
-export { ABORT_EVENT, type DispatchResult, type InvokeResult, type PauseCondition, type PauseDescriptor, type PauseOperator, type RegisterOptions, SIGNAL_EVENT, type ServiceDefinition, type Workflow, type WorkflowEvent, type WorkflowExecutionMode, WorkflowRuntime, type WorkflowRuntimeOptions, type WorkflowState, type WorkflowTrigger };
+export { ABORT_EVENT, type DispatchResult, type EnvService, type InvokeResult, type PauseCondition, type PauseDescriptor, type PauseOperator, type RegisterOptions, SIGNAL_EVENT, type ServiceDefinition, type Workflow, type WorkflowEvent, type WorkflowExecutionMode, WorkflowRuntime, type WorkflowRuntimeOptions, type WorkflowServiceDefinition, type WorkflowState, type WorkflowTrigger };

package/index.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@asaidimu/utils-artifacts"),t=require("@asaidimu/utils-database"),n=require("@asaidimu/utils-error"),r=require("@asaidimu/utils-pipeline"),i=require("@asaidimu/utils-store"),a=require("@asaidimu/utils-sync");const o=`__abort__`,s=`__signal__`;var c=class{workflowId;concurrency;capacity;inFlight=0;queueSize=0;closed=!1;constructor(e,t,n){this.workflowId=e,this.concurrency=t,this.capacity=n}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`queue_full`};if(this.inFlight<this.concurrency)return this.inFlight++,this.run(e,t,n),{status:`accepted`};if(this.queueSize>=this.capacity)return{status:`rejected`,reason:`queue_full`};this.queueSize++;let r=this.queueSize;return await new Promise(e=>{let t=()=>{if(this.closed){e();return}this.inFlight<this.concurrency?(this.inFlight++,this.queueSize--,e()):setTimeout(t,0)};setTimeout(t,0)}),this.closed?{status:`rejected`,reason:`queue_full`}:(this.run(e,t,n),{status:`queued`,position:r})}settle(e){}close(){this.closed=!0}async run(e,t,n){try{await n(e,t)}finally{this.inFlight--}}},l=class{workflowId;capacity;serializer;queueDepth=0;closed=!1;constructor(e,t){this.workflowId=e,this.capacity=t,this.serializer=new a.Serializer({capacity:t,yieldMode:`macrotask`})}async accept(e,t,n){if(this.closed||this.queueDepth>=this.capacity)return{status:`rejected`,reason:`queue_full`};let r=this.queueDepth;return this.queueDepth++,await this.serializer.do(async()=>{try{await n(e,t)}finally{this.queueDepth--}}),r===0?{status:`accepted`}:{status:`queued`,position:r}}settle(e){}close(){this.closed=!0,this.serializer.close()}},u=class{workflowId;onActive;replacementGracePeriod;deliverSignal;state=`idle`;activeRunId;settleResolve;closed=!1;constructor(e,t,n,r){this.workflowId=e,this.onActive=t,this.replacementGracePeriod=n,this.deliverSignal=r}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`singleton_active`};if(this.state===`idle`){this.state=`starting`;let r=await n(e,t);return r||(this.state=`idle`,this.activeRunId=void 0),{status:`accepted`,runId:r}}if(this.state===`terminating`)return{status:`rejected`,reason:`terminating`};switch(this.onActive){case`drop`:return{status:`rejected`,reason:`singleton_active`};case`signal`:{let e=this.activeRunId??``;return e?this.deliverSignal(e,t):console.warn(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": signal requested but activeRunId unknown (state="${this.state}"). Event "${t.type}" dropped.`),{status:`signalled`,runId:e}}case`replace`:return this.handleReplace(e,t,n)}}settle(e){(this.state===`starting`||e===this.activeRunId)&&(this.activeRunId=e,this.state=`running`),this.state===`terminating`&&e===this.activeRunId&&this.settleResolve?.()}close(){this.closed=!0,this.settleResolve?.()}async handleReplace(e,t,n){if(this.state=`terminating`,this.activeRunId&&console.info(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": replacing run "${this.activeRunId}" with new event "${t.type}".`),await Promise.race([new Promise(e=>{this.settleResolve=e}),new Promise(e=>setTimeout(e,this.replacementGracePeriod))]),this.settleResolve=void 0,this.closed)return this.state=`idle`,{status:`rejected`,reason:`singleton_active`};this.state=`starting`,this.activeRunId=void 0;let r=await n(e,t);return r||(this.state=`idle`),{status:`accepted`,runId:r}}},d=class{workflowId;onActive;activeRunId;pending;closed=!1;constructor(e,t){this.workflowId=e,this.onActive=t}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`exclusive_active`};if(!this.activeRunId){let r=await n(e,t);return r&&(this.activeRunId=r),{status:`accepted`,runId:r}}return this.onActive===`reject`?{status:`rejected`,reason:`exclusive_active`}:(this.pending={triggerId:e,event:t,spawn:n},{status:`queued`,position:1})}settle(e){if(e===this.activeRunId&&(this.activeRunId=void 0,this.pending&&!this.closed)){let{triggerId:e,event:t,spawn:n}=this.pending;this.pending=void 0,n(e,t).then(e=>{e&&(this.activeRunId=e)})}}close(){this.closed=!0,this.pending=void 0}},f=class{registrations=new Map;byEventType=new Map;busSubscriptions=new Map;bus;resumeCallback;constructor(e){this.bus=e.bus,this.resumeCallback=e.resume}register(e,t){let n=this.registrations.get(e);n||(n=new Map,this.registrations.set(e,n));let r={runId:e,descriptor:t,queue:[],parked:!1};n.set(t.eventType,r);let i=this.byEventType.get(t.eventType);i||(i=new Set,this.byEventType.set(t.eventType,i)),i.add(e),this.acquireBusSubscription(t.eventType)}cancel(e,t){let n=this.registrations.get(e);n&&(n.delete(t),n.size===0&&this.registrations.delete(e),this.removeFromReverseIndex(e,t),this.releaseBusSubscription(t))}onRunPaused(e){let t=this.registrations.get(e);if(!t)return null;for(let e of t.values())if(e.queue.length>0)return e.queue.shift();for(let e of t.values())e.parked=!0;return null}onRunEnded(e){let t=this.registrations.get(e);if(t){for(let[n]of t)this.removeFromReverseIndex(e,n),this.releaseBusSubscription(n);this.registrations.delete(e)}}onEvent(e,t){let n=this.byEventType.get(e);if(!(!n||n.size===0))for(let r of n){let n=this.registrations.get(r);if(!n)continue;let i=n.get(e);if(!i||!this.evaluate(i.descriptor.conditions,t))continue;let a=this.resolve(i.descriptor,t);i.parked?(i.parked=!1,this.resumeCallback(r,a.patch)):i.queue.push(a)}}evaluate(e,t){for(let n of e){let e=this.getField(t,n.field);if(n.op===`exists`){if(e==null)return!1;continue}if(e==null)return!1;try{switch(n.op){case`==`:if(e!=n.value)return!1;break;case`!=`:if(e==n.value)return!1;break;case`>`:if(!(e>n.value))return!1;break;case`>=`:if(!(e>=n.value))return!1;break;case`<`:if(!(e<n.value))return!1;break;case`<=`:if(!(e<=n.value))return!1;break;default:return!1}}catch{return!1}}return!0}resolve(e,t){return{eventPayload:t,patch:{...e.patch??{},__watch_event__:t}}}getField(e,t){let n=t.split(`.`),r=e;for(let e of n){if(r==null||typeof r!=`object`&&!Array.isArray(r))return;let t=Number(e);r=!isNaN(t)&&Array.isArray(r)?r[t]:r[e]}return r}acquireBusSubscription(e){if(this.busSubscriptions.has(e))return;let t=this.bus.subscribe(e,t=>{this.onEvent(e,t)});this.busSubscriptions.set(e,t)}releaseBusSubscription(e){let t=this.byEventType.get(e);if(t&&t.size>0)return;let n=this.busSubscriptions.get(e);if(n){try{n()}catch{}this.busSubscriptions.delete(e)}}removeFromReverseIndex(e,t){let n=this.byEventType.get(t);n&&(n.delete(e),n.size===0&&this.byEventType.delete(t))}},p=class{bus;storeRegistry;timelineStore;pauseService;runServiceDefinitions=[];serviceContainer;workflows=new Map;index=new Map;subscriptions=new Map;pausedRuns=new Map;abortUnsubscribe;signalUnsubscribe;constructor(t){this.bus=t.bus,this.storeRegistry=t.storeRegistry,this.timelineStore=t.timelineStore,this.pauseService=new f({bus:this.bus,resume:async(e,t)=>{this.resume(e,t)}}),this.serviceContainer=new e.ArtifactContainer(new i.ReactiveDataStore({}));for(let e of t.services??[]){if(e.id===`__pause_service__`)throw new n.SystemError({code:n.ErrorCodes.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Service id "__pause_service__" is reserved for the built-in PauseService and cannot be redefined.`});e.scope===`singleton`?this.serviceContainer.register({key:e.id,factory:()=>e.factory(),scope:`singleton`}):this.runServiceDefinitions.push(e)}this.serviceContainer.register({key:`__pause_service__`,factory:()=>this.pauseService,scope:`singleton`}),this.abortUnsubscribe=this.bus.subscribe(o,e=>{this.abortRun(e.run)}),this.signalUnsubscribe=this.bus.subscribe(s,e=>{this.signal(e.runId,e.patch)})}static async createTestTimelineStore(e=`test-timeline-database`){return new r.TimelineStore(await(0,t.DatabaseConnection)({database:e,validate:!0,predicates:{},enableTelemetry:!0},t.createIndexedDbStore))}async register(e,t){if(this.workflows.has(e.id))throw new n.SystemError({code:n.ErrorCodes.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Workflow "${e.id}" is already registered. Call deregister("${e.id}") before registering again.`});let i=r.PipelineRegistry.get(`workflow:${e.id}`,{onExpired:(t,n)=>{console.info(`[WorkflowRuntime] Run "${t}" pause-window expired for workflow "${e.id}". Checkpoint: ${n.pipelineId}.`)},onExportFailed:(t,n)=>{console.error(`[WorkflowRuntime] Deferred export failed for run "${t}" in workflow "${e.id}":`,n)}}),a=async e=>{let n=e.ok?e.value.runId:e.error?.runId;n&&(s.executionContext.settle(n),this.pauseService.onRunEnded(n),this.pausedRuns.delete(n)),i.prune();try{await t.onComplete(e)}finally{await t.onCleanup?.()}},o=this.buildExecutionContext(e.id,t.mode),s;s={workflow:e,mode:t.mode,executionContext:o,factories:new Map,registry:i,hooks:{onPrepare:t.onPrepare,onComplete:a,onResume:t.onResume,onDispatch:t.onDispatch,onCleanup:t.onCleanup}},this.workflows.set(e.id,s);for(let[t,n]of Object.entries(e.triggers)){let r={workflowId:e.id,triggerId:t,trigger:n},i=this.index.get(n.event);i||(i=new Set,this.index.set(n.event,i)),i.add(r),await this.acquireBusSubscription(n.event)}}deregister(e){let t=this.workflows.get(e);if(t){for(let n of Object.values(t.workflow.triggers)){let t=this.index.get(n.event);if(t){for(let n of t)n.workflowId===e&&t.delete(n);t.size===0&&this.index.delete(n.event)}this.releaseBusSubscription(n.event)}t.executionContext.close(),r.PipelineRegistry.destroy(`workflow:${e}`),t.factories.clear(),this.workflows.delete(e)}}hasWorkflow(e){return this.workflows.has(e)}listWorkflows(){return Array.from(this.workflows.keys())}async stop(){for(let e of Array.from(this.workflows.keys()))this.deregister(e);try{this.abortUnsubscribe()}catch{}try{this.signalUnsubscribe()}catch{}}registry(e){return this.workflows.get(e)?.registry}watch(e,t){return this.workflows.get(e)?.registry.get(t)}listAllRuns(){let e=[];for(let[t,n]of this.workflows)for(let r of n.registry.list())e.push({...r,workflowId:t});return e}async invoke(e,t,r){let i=this.workflows.get(e);if(!i)throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: workflow "${e}" is not registered.`});if(!i.workflow.pipelines[t])throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: no pipeline definition for workflow "${e}" trigger "${t}".`});let a=this.generateRunId(e,t),o=await this.executePipeline(i,t,a,r);return o.ok&&o.value.status===`paused`?(this.pausedRuns.set(a,{workflowId:e,triggerId:t}),await this.drainWatchQueue(a)):await i.hooks.onComplete(o),o.ok?n.Result.ok(o.value,{runId:a,triggerId:t}):n.Result.fail(o.error,{runId:a,triggerId:t})}async resume(e,t={}){let r=this.pausedRuns.get(e);if(!r)throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] resume() failed: run "${e}" is not in the paused runs registry. It may have already completed, been aborted, or the runId is incorrect.`});let{workflowId:a,triggerId:o}=r,s=this.workflows.get(a);if(!s)throw new n.SystemError({code:n.ErrorCodes.RESOURCE_RELEASED.code,message:`[WorkflowRuntime] resume() failed: workflow "${a}" is no longer registered. The workflow may have been deregistered while the run was paused.`});let c=this.getOrCreateFactory(s,o),l=s.registry.hold(e),u;try{let t=await c.resume(e);if(!t.ok)throw t.error;u=t.value}catch(t){throw new n.SystemError({code:n.ErrorCodes.INTERNAL_ERROR.code,message:`[WorkflowRuntime] resume() failed to reconstruct context for run "${e}"`,cause:t})}l||u.container.extend(this.serviceContainer),Object.keys(t).length>0&&u.write(t),u.write({__watch__:i.DELETE_SYMBOL}),await s.hooks.onResume?.(u);let d=await u.run();if(d.ok&&d.value.status===`paused`)await this.drainWatchQueue(e);else{let t=this.workflows.get(a);if(t)try{await t.hooks.onComplete(d)}catch(t){console.error(`[WorkflowRuntime] onComplete hook threw during resume for run "${e}":`,t)}}return d.ok?n.Result.ok(d.value,{runId:e,triggerId:o}):n.Result.fail(d.error,{runId:e,triggerId:o})}async signal(e,t){for(let n of this.workflows.values()){let r=n.registry.get(e);if(r?.context){r.context.write(t);return}}}dispatch(e,t){let n=this.index.get(e);if(!n||n.size===0)return;let r={type:e,payload:t,timestamp:Date.now()};for(let e of n){let t=!0;if(e.trigger.predicate)try{t=e.trigger.predicate(r)}catch(n){console.error(`[WorkflowRuntime] Predicate threw for workflow "${e.workflowId}" trigger "${e.triggerId}":`,n),t=!1}if(!t){this.workflows.get(e.workflowId)?.hooks.onDispatch?.({status:`rejected`,reason:`filtered`});continue}let n=this.workflows.get(e.workflowId);n&&n.executionContext.accept(e.triggerId,r,(e,t)=>this.spawnRun(n,e,t)).then(e=>{n.hooks.onDispatch?.(e)}).catch(t=>{console.error(`[WorkflowRuntime] ExecutionContext.accept() threw for workflow "${e.workflowId}":`,t)})}}async executePipeline(e,t,i,a){let o=this.timelineStore?new r.TimelineRecorder(this.timelineStore,{}):void 0,s=this.getOrCreateFactory(e,t),c;try{c=await s.prepare(void 0,i),o&&await o.attach(c),await c.store.set({__trigger_event__:a})}catch(e){o&&await o.detach().catch(()=>{});let t=e instanceof n.SystemError?e:new n.SystemError({code:`PIPELINE_PREPARE_FAILED`,message:e instanceof Error?e.message:String(e)});return n.Result.fail(t)}c.container.extend(this.serviceContainer),await e.hooks.onPrepare(c);let l=await c.run();return o&&await o.detach().catch(()=>{}),l}async spawnRun(e,t,n){let r=this.generateRunId(e.workflow.id,t);return this.executePipeline(e,t,r,n).then(async n=>{if(n.ok&&n.value.status===`paused`){this.pausedRuns.set(r,{workflowId:e.workflow.id,triggerId:t}),await this.drainWatchQueue(r);return}try{await e.hooks.onComplete(n)}catch(e){console.error(`[WorkflowRuntime] onComplete hook threw for run "${r}":`,e)}}).catch(e=>{console.error(`[WorkflowRuntime] Pipeline execution failed for run "${r}":`,e)}),r}async drainWatchQueue(e){let t=this.pauseService.onRunPaused(e);if(t!==null)try{await this.resume(e,t.patch)}catch(t){console.error(`[WorkflowRuntime] drainWatchQueue: resume() failed for run "${e}":`,t),this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}}async abortRun(e){for(let t of this.workflows.values()){let n=t.registry.get(e);if(n?.context){try{n.context.abort()}catch(t){console.error(`[WorkflowRuntime] Error aborting run "${e}":`,t)}break}}this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}buildExecutionContext(e,t){switch(t.type){case`transient`:return new c(e,t.concurrency??10,t.capacity??1e3);case`serialized`:return new l(e,t.capacity??1e3);case`singleton_loop`:return new u(e,t.onActive??`drop`,t.replacementGracePeriod??5e3,(e,t)=>this.signal(e,{__singleton_event__:t}));case`exclusive`:return new d(e,t.onActive??`reject`)}}async acquireBusSubscription(e){let t=this.subscriptions.get(e);t||(t=new a.SharedResource(()=>this.bus.subscribe(e,t=>{this.dispatch(e,t)}),t=>{try{t?.(),this.subscriptions.delete(e)}catch{}},{gracePeriod:`sync`}),this.subscriptions.set(e,t)),await t.acquire()}releaseBusSubscription(e){this.subscriptions.get(e)?.release()}getOrCreateFactory(e,t){let i=e.factories.get(t);if(i)return i;let a=e.workflow.pipelines[t];if(!a)throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] No pipeline definition found for workflow "${e.workflow.id}" trigger "${t}". Ensure workflow.pipelines["${t}"] is populated by the compiler.`});let o=new r.PipelineFactory(a,{storeFactory:async e=>this.storeRegistry.get(e),registry:e.registry});return e.factories.set(t,o),o}generateRunId(e,t){return`${e}:${t}:${Date.now()}:${Math.random().toString(36).slice(2)}`}};exports.ABORT_EVENT=o,exports.SIGNAL_EVENT=s,exports.WorkflowRuntime=p;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@asaidimu/utils-artifacts"),t=require("@asaidimu/utils-database"),n=require("@asaidimu/utils-error"),r=require("@asaidimu/utils-logger"),i=require("@asaidimu/utils-pipeline"),a=require("@asaidimu/utils-sanitize"),o=require("@asaidimu/utils-store"),s=require("@asaidimu/utils-sync");const c=`__abort__`,l=`__signal__`;var u=class{envs=new Map;use(e,t){return this.envs.set(e,t),this}get(e){return this.envs.get(`global`)?.[e]}list(){return{...this.envs.get(`global`)}}scope(e){let t=this.envs.get(e),n=this.envs.get(`global`);return{get:e=>{if(t&&e in t)return t[e];if(n&&e in n)return n[e]},list:()=>{let e={...n};if(t)for(let n of Object.keys(t))e[n]=t[n];return e}}}},d=class{workflowId;concurrency;capacity;logger;inFlight=0;queueSize=0;closed=!1;constructor(e,t,n,r){this.workflowId=e,this.concurrency=t,this.capacity=n,this.logger=r}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`queue_full`};if(this.inFlight<this.concurrency)return this.inFlight++,this.run(e,t,n),{status:`accepted`};if(this.queueSize>=this.capacity)return{status:`rejected`,reason:`queue_full`};this.queueSize++;let r=this.queueSize;return await new Promise(e=>{let t=()=>{if(this.closed){e();return}this.inFlight<this.concurrency?(this.inFlight++,this.queueSize--,e()):setTimeout(t,0)};setTimeout(t,0)}),this.closed?{status:`rejected`,reason:`queue_full`}:(this.run(e,t,n),{status:`queued`,position:r})}settle(e){}close(){this.closed=!0}async run(e,t,n){try{await n(e,t)}finally{this.inFlight--}}},f=class{workflowId;capacity;logger;serializer;queueDepth=0;closed=!1;constructor(e,t,n){this.workflowId=e,this.capacity=t,this.logger=n,this.serializer=new s.Serializer({capacity:t,yieldMode:`macrotask`})}async accept(e,t,n){if(this.closed||this.queueDepth>=this.capacity)return{status:`rejected`,reason:`queue_full`};let r=this.queueDepth;return this.queueDepth++,await this.serializer.do(async()=>{try{await n(e,t)}finally{this.queueDepth--}}),r===0?{status:`accepted`}:{status:`queued`,position:r}}settle(e){}close(){this.closed=!0,this.serializer.close()}},p=class{workflowId;onActive;replacementGracePeriod;deliverSignal;logger;state=`idle`;activeRunId;settleResolve;closed=!1;constructor(e,t,n,r,i){this.workflowId=e,this.onActive=t,this.replacementGracePeriod=n,this.deliverSignal=r,this.logger=i}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`singleton_active`};if(this.state===`idle`){this.state=`starting`;let r=await n(e,t);return r||(this.state=`idle`,this.activeRunId=void 0),{status:`accepted`,runId:r}}if(this.state===`terminating`)return{status:`rejected`,reason:`terminating`};switch(this.onActive){case`drop`:return{status:`rejected`,reason:`singleton_active`};case`signal`:{let e=this.activeRunId??``;return e?this.deliverSignal(e,t):this.logger.warn(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": signal requested but activeRunId unknown (state="${this.state}"). Event "${t.type}" dropped.`),{status:`signalled`,runId:e}}case`replace`:return this.handleReplace(e,t,n)}}settle(e){(this.state===`starting`||e===this.activeRunId)&&(this.activeRunId=e,this.state=`running`),this.state===`terminating`&&e===this.activeRunId&&this.settleResolve?.()}close(){this.closed=!0,this.settleResolve?.()}async handleReplace(e,t,n){if(this.state=`terminating`,this.activeRunId&&this.logger.info(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": replacing run "${this.activeRunId}" with new event "${t.type}".`),await Promise.race([new Promise(e=>{this.settleResolve=e}),new Promise(e=>setTimeout(e,this.replacementGracePeriod))]),this.settleResolve=void 0,this.closed)return this.state=`idle`,{status:`rejected`,reason:`singleton_active`};this.state=`starting`,this.activeRunId=void 0;let r=await n(e,t);return r||(this.state=`idle`),{status:`accepted`,runId:r}}},m=class{workflowId;onActive;logger;activeRunId;pending;closed=!1;constructor(e,t,n){this.workflowId=e,this.onActive=t,this.logger=n}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`exclusive_active`};if(!this.activeRunId){let r=await n(e,t);return r&&(this.activeRunId=r),{status:`accepted`,runId:r}}return this.onActive===`reject`?{status:`rejected`,reason:`exclusive_active`}:(this.pending={triggerId:e,event:t,spawn:n},{status:`queued`,position:1})}settle(e){if(e===this.activeRunId&&(this.activeRunId=void 0,this.pending&&!this.closed)){let{triggerId:e,event:t,spawn:n}=this.pending;this.pending=void 0,n(e,t).then(e=>{e&&(this.activeRunId=e)})}}close(){this.closed=!0,this.pending=void 0}},h=class{registrations=new Map;byEventType=new Map;busSubscriptions=new Map;bus;resumeCallback;constructor(e){this.bus=e.bus,this.resumeCallback=e.resume}register(e,t){let n=this.registrations.get(e);n||(n=new Map,this.registrations.set(e,n));let r={runId:e,descriptor:t,queue:[],parked:!1};n.set(t.eventType,r);let i=this.byEventType.get(t.eventType);i||(i=new Set,this.byEventType.set(t.eventType,i)),i.add(e),this.acquireBusSubscription(t.eventType)}cancel(e,t){let n=this.registrations.get(e);n&&(n.delete(t),n.size===0&&this.registrations.delete(e),this.removeFromReverseIndex(e,t),this.releaseBusSubscription(t))}onRunPaused(e){let t=this.registrations.get(e);if(!t)return null;for(let e of t.values())if(e.queue.length>0)return e.queue.shift();for(let e of t.values())e.parked=!0;return null}onRunEnded(e){let t=this.registrations.get(e);if(t){for(let[n]of t)this.removeFromReverseIndex(e,n),this.releaseBusSubscription(n);this.registrations.delete(e)}}onEvent(e,t){let n=this.byEventType.get(e);if(!(!n||n.size===0))for(let r of n){let n=this.registrations.get(r);if(!n)continue;let i=n.get(e);if(!i||!this.evaluate(i.descriptor.conditions,t))continue;let a=this.resolve(i.descriptor,t);i.parked?(i.parked=!1,this.resumeCallback(r,a.patch)):i.queue.push(a)}}evaluate(e,t){for(let n of e){let e=this.getField(t,n.field);if(n.op===`exists`){if(e==null)return!1;continue}if(e==null)return!1;try{switch(n.op){case`==`:if(e!=n.value)return!1;break;case`!=`:if(e==n.value)return!1;break;case`>`:if(!(e>n.value))return!1;break;case`>=`:if(!(e>=n.value))return!1;break;case`<`:if(!(e<n.value))return!1;break;case`<=`:if(!(e<=n.value))return!1;break;default:return!1}}catch{return!1}}return!0}resolve(e,t){return{eventPayload:t,patch:{...e.patch??{},__watch_event__:t}}}getField(e,t){let n=t.split(`.`),r=e;for(let e of n){if(r==null||typeof r!=`object`&&!Array.isArray(r))return;let t=Number(e);r=!isNaN(t)&&Array.isArray(r)?r[t]:r[e]}return r}acquireBusSubscription(e){if(this.busSubscriptions.has(e))return;let t=this.bus.subscribe(e,t=>{this.onEvent(e,t)});this.busSubscriptions.set(e,t)}releaseBusSubscription(e){let t=this.byEventType.get(e);if(t&&t.size>0)return;let n=this.busSubscriptions.get(e);if(n){try{n()}catch{}this.busSubscriptions.delete(e)}}removeFromReverseIndex(e,t){let n=this.byEventType.get(t);n&&(n.delete(e),n.size===0&&this.byEventType.delete(t))}},g=class{bus;storeRegistry;timelineStore;pauseService;serviceContainer;serviceStore;workflows=new Map;index=new Map;subscriptions=new Map;pausedRuns=new Map;logger;abortUnsubscribe;signalUnsubscribe;constructor(t){this.bus=t.bus,this.storeRegistry=t.storeRegistry,this.timelineStore=t.timelineStore,this.logger=t.logger?t.logger:new r.Logger([],{scope:`workflow-runtime`}),this.pauseService=new h({bus:this.bus,resume:async(e,t)=>{this.resume(e,t)}}),this.serviceStore=new o.ReactiveDataStore({env:{global:t.env??{}}}),this.serviceContainer=new e.ArtifactContainer(this.serviceStore);for(let e of t.services??[]){if(e.id===`__pause_service__`)throw new n.SystemError({code:n.ErrorCodes.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Service id "__pause_service__" is reserved for the built-in PauseService and cannot be redefined.`});if(e.id===`__env__`)throw new n.SystemError({code:n.ErrorCodes.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Service id "__env__" is reserved for the built-in environment-variable service and cannot be redefined.`});this.serviceContainer.register({key:e.id,factory:e.factory,scope:`singleton`})}this.serviceContainer.register({key:`__pause_service__`,factory:()=>this.pauseService,scope:`singleton`}),this.serviceContainer.register({key:`__env_service__`,factory:async({use:e})=>{let t=await e(e=>e.select(e=>e.env)),n=new u;for(let[e,r]of Object.entries(t??{}))n.use(e,r);return n},scope:`singleton`}),this.serviceContainer.register({key:`__scoped_env_service__`,paramKey:e=>`env:${e.workflowId}`,factory:async({use:e,params:t})=>(await e(e=>e.require(`__env_service__`))).scope(t.workflowId),scope:`singleton`}),this.serviceContainer.register({key:`__sanitizer__`,paramKey:e=>`sanitizer:${e.workflowId}`,factory:async({use:e,params:t})=>{let n=(await e(e=>e.require(`__scoped_env_service__`,{workflowId:t.workflowId}))).list(),r=(0,a.newSecureDefaultConfig)();return r.patterns=[...r.patterns,...(0,a.commonEnvPatterns)([],n)],new a.DocumentSanitizer(r,t.workflowId)},scope:`singleton`}),this.abortUnsubscribe=this.bus.subscribe(c,e=>{this.abortRun(e.run)}),this.signalUnsubscribe=this.bus.subscribe(l,e=>{this.signal(e.runId,e.patch)})}static async createTestTimelineStore(e=`test-timeline-database`){return new i.TimelineStore(await(0,t.DatabaseConnection)({database:e,validate:!0,predicates:{},enableTelemetry:!0},t.createIndexedDbStore))}async register(e,t){if(this.workflows.has(e.id))throw new n.SystemError({code:n.ErrorCodes.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Workflow "${e.id}" is already registered. Call deregister("${e.id}") before registering again.`});let r=i.PipelineRegistry.get(`workflow:${e.id}`,{onExpired:(t,n)=>{this.logger.info(`[WorkflowRuntime] Run "${t}" pause-window expired for workflow "${e.id}". Checkpoint: ${n.pipelineId}.`)},onExportFailed:(t,n)=>{this.logger.error(`[WorkflowRuntime] Deferred export failed for run "${t}" in workflow "${e.id}":`,n)}}),a=async e=>{let n=e.ok?e.value.runId:e.error?.runId;try{await t.onComplete(e)}finally{n&&(s.executionContext.settle(n),this.pauseService.onRunEnded(n),this.pausedRuns.delete(n)),r.prune(),await t.onCleanup?.()}},o=this.buildExecutionContext(e.id,t.mode),s;s={workflow:e,mode:t.mode,executionContext:o,factories:new Map,registry:r,hooks:{onPrepare:t.onPrepare,onComplete:a,onResume:t.onResume,onDispatch:t.onDispatch,onCleanup:t.onCleanup}},this.workflows.set(e.id,s),this.serviceStore.set(t=>({env:{...t.env??{},[e.id]:e.env??{}}}));let c=this.serviceContainer.scope(e.id);if(e.services&&e.services.length>0)for(let t of e.services)t.scope===`run`||t.scope===`transient`||c.register({key:t.id,factory:t.factory,scope:`singleton`});s.container=c;for(let[t,n]of Object.entries(e.triggers)){let r={workflowId:e.id,triggerId:t,trigger:n},i=this.index.get(n.event);i||(i=new Set,this.index.set(n.event,i)),i.add(r),await this.acquireBusSubscription(n.event)}}deregister(e){let t=this.workflows.get(e);if(t){for(let n of Object.values(t.workflow.triggers)){let t=this.index.get(n.event);if(t){for(let n of t)n.workflowId===e&&t.delete(n);t.size===0&&this.index.delete(n.event)}this.releaseBusSubscription(n.event)}for(let t of[`__scoped_env_service__`,`__sanitizer__`])try{this.serviceContainer.unregister(t,{workflowId:e})}catch{}this.serviceStore.set(t=>({env:{...t.env??{},[e]:o.DELETE_SYMBOL}})),t.container?.dispose(),t.executionContext.close(),i.PipelineRegistry.destroy(`workflow:${e}`),t.factories.clear(),this.workflows.delete(e)}}hasWorkflow(e){return this.workflows.has(e)}listWorkflows(){return Array.from(this.workflows.keys())}async stop(){for(let e of Array.from(this.workflows.keys()))this.deregister(e);try{this.abortUnsubscribe()}catch{}try{this.signalUnsubscribe()}catch{}}registry(e){return this.workflows.get(e)?.registry}info(e,t){return this.workflows.get(e)?.registry.get(t)}list(){let e=[];for(let[t,n]of this.workflows)for(let r of n.registry.list())e.push({...r,workflowId:t});return e}async invoke(e,t,r){let i=this.workflows.get(e);if(!i)throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: workflow "${e}" is not registered.`});if(!i.workflow.pipelines[t])throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: no pipeline definition for workflow "${e}" trigger "${t}".`});let a=this.generateRunId(e,t),o=await this.executePipeline(i,t,a,r);return o.ok&&o.value.status===`paused`?(this.pausedRuns.set(a,{workflowId:e,triggerId:t}),await this.drainWatchQueue(a)):await i.hooks.onComplete(o),o.ok?n.Result.ok(o.value,{runId:a,triggerId:t}):n.Result.fail(o.error,{runId:a,triggerId:t})}async resume(e,t={}){let r=this.pausedRuns.get(e);if(!r)throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] resume() failed: run "${e}" is not in the paused runs registry. It may have already completed, been aborted, or the runId is incorrect.`});let{workflowId:i,triggerId:a}=r,s=this.workflows.get(i);if(!s)throw new n.SystemError({code:n.ErrorCodes.RESOURCE_RELEASED.code,message:`[WorkflowRuntime] resume() failed: workflow "${i}" is no longer registered. The workflow may have been deregistered while the run was paused.`});let c=this.getOrCreateFactory(s,a),l=s.registry.hold(e),u=await this.createRecorder(s),d=u?[u.asLogSink()]:void 0,f;try{let t=await c.resume(e,{sinks:d});if(!t.ok)throw t.error;f=t.value}catch(t){throw new n.SystemError({code:n.ErrorCodes.INTERNAL_ERROR.code,message:`[WorkflowRuntime] resume() failed to reconstruct context for run "${e}"`,cause:t})}l||this.extendContextContainer(f,s),Object.keys(t).length>0&&f.write(t),f.write({__watch__:o.DELETE_SYMBOL});let p=await this.withRecorder(f,async()=>(await s.hooks.onResume?.(f),await f.run()),u);if(p.ok&&p.value.status===`paused`)await this.drainWatchQueue(e);else{let t=this.workflows.get(i);if(t)try{await t.hooks.onComplete(p)}catch(t){this.logger.error(`[WorkflowRuntime] onComplete hook threw during resume for run "${e}":`,t)}}return p.ok?n.Result.ok(p.value,{runId:e,triggerId:a}):n.Result.fail(p.error,{runId:e,triggerId:a})}async signal(e,t){for(let n of this.workflows.values()){let r=n.registry.get(e);if(r?.context){r.context.write(t);return}}}dispatch(e,t){let n=this.index.get(e);if(!n||n.size===0)return;let r={type:e,payload:t,timestamp:Date.now()};for(let e of n){let t=!0;if(e.trigger.predicate)try{t=e.trigger.predicate(r)}catch(n){this.logger.error(`[WorkflowRuntime] Predicate threw for workflow "${e.workflowId}" trigger "${e.triggerId}":`,n),t=!1}if(!t){this.workflows.get(e.workflowId)?.hooks.onDispatch?.({status:`rejected`,reason:`filtered`});continue}let n=this.workflows.get(e.workflowId);n&&n.executionContext.accept(e.triggerId,r,(e,t)=>this.spawnRun(n,e,t)).then(e=>{n.hooks.onDispatch?.(e)}).catch(t=>{this.logger.error(`[WorkflowRuntime] ExecutionContext.accept() threw for workflow "${e.workflowId}":`,t)})}}async createRecorder(e){if(!this.timelineStore)return;let t;try{t=await this.serviceContainer.require(`__sanitizer__`,{workflowId:e.workflow.id})}catch{}return new i.TimelineRecorder(this.timelineStore,{sanitizer:t})}async withRecorder(e,t,n){if(!n)return t();await n.attach(e),await(0,i.yieldToEventLoop)();try{return await t()}finally{await n.detach().catch(()=>{})}}async executePipeline(e,t,r,i){let a=this.getOrCreateFactory(e,t),o=await this.createRecorder(e),s=o?[o.asLogSink()]:void 0,c;try{c=await a.prepare(void 0,r,{sinks:s}),await c.store.set({__trigger_event__:i})}catch(e){let t=e instanceof n.SystemError?e:new n.SystemError({code:`PIPELINE_PREPARE_FAILED`,message:e instanceof Error?e.message:String(e)});return n.Result.fail(t)}return this.extendContextContainer(c,e),this.withRecorder(c,async()=>(await e.hooks.onPrepare(c),await c.run()),o)}async spawnRun(e,t,n){let r=this.generateRunId(e.workflow.id,t);return this.executePipeline(e,t,r,n).then(async n=>{if(n.ok&&n.value.status===`paused`){this.pausedRuns.set(r,{workflowId:e.workflow.id,triggerId:t}),await this.drainWatchQueue(r);return}try{await e.hooks.onComplete(n)}catch(e){this.logger.error(`[WorkflowRuntime] onComplete hook threw for run "${r}":`,e)}}).catch(e=>{this.logger.error(`[WorkflowRuntime] Pipeline execution failed for run "${r}":`,e)}),r}async drainWatchQueue(e){let t=this.pauseService.onRunPaused(e);if(t!==null)try{await this.resume(e,t.patch)}catch(t){this.logger.error(`[WorkflowRuntime] drainWatchQueue: resume() failed for run "${e}":`,t),this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}}async abortRun(e){for(let t of this.workflows.values()){let n=t.registry.get(e);if(n?.context){try{n.context.abort()}catch(t){this.logger.error(`[WorkflowRuntime] Error aborting run "${e}":`,t)}break}}this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}buildExecutionContext(e,t){let n=this.logger.child({scope:`${t.type}:execution-context`});switch(t.type){case`transient`:return new d(e,t.concurrency??10,t.capacity??1e3,n);case`serialized`:return new f(e,t.capacity??1e3,n);case`singleton_loop`:return new p(e,t.onActive??`drop`,t.replacementGracePeriod??5e3,(e,t)=>this.signal(e,{__singleton_event__:t}),n);case`exclusive`:return new m(e,t.onActive??`reject`,n)}}async acquireBusSubscription(e){let t=this.subscriptions.get(e);t||(t=new s.SharedResource(()=>this.bus.subscribe(e,t=>{this.dispatch(e,t)}),t=>{try{t?.(),this.subscriptions.delete(e)}catch{}},{gracePeriod:`sync`}),this.subscriptions.set(e,t)),await t.acquire()}releaseBusSubscription(e){this.subscriptions.get(e)?.release()}async extendContextContainer(e,t){t.container&&e.container.extend(t.container),e.container.extend(this.serviceContainer);let r=await this.serviceContainer.require(`__scoped_env_service__`,{workflowId:t.workflow.id});e.container.register({key:`__env__`,factory:()=>r,scope:`singleton`});for(let t of[`__env_service__`,`__scoped_env_service__`])e.container.register({key:t,factory:()=>{throw new n.SystemError({code:n.ErrorCodes.UNAUTHENTICATED.code,message:`"${t}" is an internal artifact and cannot be accessed from pipeline steps.`})},scope:`singleton`,lazy:!1});if(t.workflow.services)for(let n of t.workflow.services){if(n.scope===`workflow`||n.scope===void 0)continue;let t=n.scope===`run`?`singleton`:`transient`;e.container.register({key:n.id,factory:n.factory,scope:t})}}getOrCreateFactory(e,t){let r=e.factories.get(t);if(r)return r;let a=e.workflow.pipelines[t];if(!a)throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] No pipeline definition found for workflow "${e.workflow.id}" trigger "${t}". Ensure workflow.pipelines["${t}"] is populated by the compiler.`});let o=new i.PipelineFactory(a,{storeFactory:async e=>this.storeRegistry.get(e),registry:e.registry});return e.factories.set(t,o),o}generateRunId(e,t){return`${e}:${t}:${Date.now()}:${Math.random().toString(36).slice(2)}`}};exports.ABORT_EVENT=c,exports.SIGNAL_EVENT=l,exports.WorkflowRuntime=g;

package/index.mjs

@@ -1 +1 @@
-import{ArtifactContainer as e}from"@asaidimu/utils-artifacts";import{DatabaseConnection as t,createIndexedDbStore as n}from"@asaidimu/utils-database";import{ErrorCodes as r,Result as i,SystemError as a}from"@asaidimu/utils-error";import{PipelineFactory as o,PipelineRegistry as s,TimelineRecorder as c,TimelineStore as l}from"@asaidimu/utils-pipeline";import{DELETE_SYMBOL as u,ReactiveDataStore as d}from"@asaidimu/utils-store";import{Serializer as f,SharedResource as p}from"@asaidimu/utils-sync";const m=`__abort__`,h=`__signal__`;var g=class{workflowId;concurrency;capacity;inFlight=0;queueSize=0;closed=!1;constructor(e,t,n){this.workflowId=e,this.concurrency=t,this.capacity=n}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`queue_full`};if(this.inFlight<this.concurrency)return this.inFlight++,this.run(e,t,n),{status:`accepted`};if(this.queueSize>=this.capacity)return{status:`rejected`,reason:`queue_full`};this.queueSize++;let r=this.queueSize;return await new Promise(e=>{let t=()=>{if(this.closed){e();return}this.inFlight<this.concurrency?(this.inFlight++,this.queueSize--,e()):setTimeout(t,0)};setTimeout(t,0)}),this.closed?{status:`rejected`,reason:`queue_full`}:(this.run(e,t,n),{status:`queued`,position:r})}settle(e){}close(){this.closed=!0}async run(e,t,n){try{await n(e,t)}finally{this.inFlight--}}},_=class{workflowId;capacity;serializer;queueDepth=0;closed=!1;constructor(e,t){this.workflowId=e,this.capacity=t,this.serializer=new f({capacity:t,yieldMode:`macrotask`})}async accept(e,t,n){if(this.closed||this.queueDepth>=this.capacity)return{status:`rejected`,reason:`queue_full`};let r=this.queueDepth;return this.queueDepth++,await this.serializer.do(async()=>{try{await n(e,t)}finally{this.queueDepth--}}),r===0?{status:`accepted`}:{status:`queued`,position:r}}settle(e){}close(){this.closed=!0,this.serializer.close()}},v=class{workflowId;onActive;replacementGracePeriod;deliverSignal;state=`idle`;activeRunId;settleResolve;closed=!1;constructor(e,t,n,r){this.workflowId=e,this.onActive=t,this.replacementGracePeriod=n,this.deliverSignal=r}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`singleton_active`};if(this.state===`idle`){this.state=`starting`;let r=await n(e,t);return r||(this.state=`idle`,this.activeRunId=void 0),{status:`accepted`,runId:r}}if(this.state===`terminating`)return{status:`rejected`,reason:`terminating`};switch(this.onActive){case`drop`:return{status:`rejected`,reason:`singleton_active`};case`signal`:{let e=this.activeRunId??``;return e?this.deliverSignal(e,t):console.warn(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": signal requested but activeRunId unknown (state="${this.state}"). Event "${t.type}" dropped.`),{status:`signalled`,runId:e}}case`replace`:return this.handleReplace(e,t,n)}}settle(e){(this.state===`starting`||e===this.activeRunId)&&(this.activeRunId=e,this.state=`running`),this.state===`terminating`&&e===this.activeRunId&&this.settleResolve?.()}close(){this.closed=!0,this.settleResolve?.()}async handleReplace(e,t,n){if(this.state=`terminating`,this.activeRunId&&console.info(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": replacing run "${this.activeRunId}" with new event "${t.type}".`),await Promise.race([new Promise(e=>{this.settleResolve=e}),new Promise(e=>setTimeout(e,this.replacementGracePeriod))]),this.settleResolve=void 0,this.closed)return this.state=`idle`,{status:`rejected`,reason:`singleton_active`};this.state=`starting`,this.activeRunId=void 0;let r=await n(e,t);return r||(this.state=`idle`),{status:`accepted`,runId:r}}},y=class{workflowId;onActive;activeRunId;pending;closed=!1;constructor(e,t){this.workflowId=e,this.onActive=t}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`exclusive_active`};if(!this.activeRunId){let r=await n(e,t);return r&&(this.activeRunId=r),{status:`accepted`,runId:r}}return this.onActive===`reject`?{status:`rejected`,reason:`exclusive_active`}:(this.pending={triggerId:e,event:t,spawn:n},{status:`queued`,position:1})}settle(e){if(e===this.activeRunId&&(this.activeRunId=void 0,this.pending&&!this.closed)){let{triggerId:e,event:t,spawn:n}=this.pending;this.pending=void 0,n(e,t).then(e=>{e&&(this.activeRunId=e)})}}close(){this.closed=!0,this.pending=void 0}},b=class{registrations=new Map;byEventType=new Map;busSubscriptions=new Map;bus;resumeCallback;constructor(e){this.bus=e.bus,this.resumeCallback=e.resume}register(e,t){let n=this.registrations.get(e);n||(n=new Map,this.registrations.set(e,n));let r={runId:e,descriptor:t,queue:[],parked:!1};n.set(t.eventType,r);let i=this.byEventType.get(t.eventType);i||(i=new Set,this.byEventType.set(t.eventType,i)),i.add(e),this.acquireBusSubscription(t.eventType)}cancel(e,t){let n=this.registrations.get(e);n&&(n.delete(t),n.size===0&&this.registrations.delete(e),this.removeFromReverseIndex(e,t),this.releaseBusSubscription(t))}onRunPaused(e){let t=this.registrations.get(e);if(!t)return null;for(let e of t.values())if(e.queue.length>0)return e.queue.shift();for(let e of t.values())e.parked=!0;return null}onRunEnded(e){let t=this.registrations.get(e);if(t){for(let[n]of t)this.removeFromReverseIndex(e,n),this.releaseBusSubscription(n);this.registrations.delete(e)}}onEvent(e,t){let n=this.byEventType.get(e);if(!(!n||n.size===0))for(let r of n){let n=this.registrations.get(r);if(!n)continue;let i=n.get(e);if(!i||!this.evaluate(i.descriptor.conditions,t))continue;let a=this.resolve(i.descriptor,t);i.parked?(i.parked=!1,this.resumeCallback(r,a.patch)):i.queue.push(a)}}evaluate(e,t){for(let n of e){let e=this.getField(t,n.field);if(n.op===`exists`){if(e==null)return!1;continue}if(e==null)return!1;try{switch(n.op){case`==`:if(e!=n.value)return!1;break;case`!=`:if(e==n.value)return!1;break;case`>`:if(!(e>n.value))return!1;break;case`>=`:if(!(e>=n.value))return!1;break;case`<`:if(!(e<n.value))return!1;break;case`<=`:if(!(e<=n.value))return!1;break;default:return!1}}catch{return!1}}return!0}resolve(e,t){return{eventPayload:t,patch:{...e.patch??{},__watch_event__:t}}}getField(e,t){let n=t.split(`.`),r=e;for(let e of n){if(r==null||typeof r!=`object`&&!Array.isArray(r))return;let t=Number(e);r=!isNaN(t)&&Array.isArray(r)?r[t]:r[e]}return r}acquireBusSubscription(e){if(this.busSubscriptions.has(e))return;let t=this.bus.subscribe(e,t=>{this.onEvent(e,t)});this.busSubscriptions.set(e,t)}releaseBusSubscription(e){let t=this.byEventType.get(e);if(t&&t.size>0)return;let n=this.busSubscriptions.get(e);if(n){try{n()}catch{}this.busSubscriptions.delete(e)}}removeFromReverseIndex(e,t){let n=this.byEventType.get(t);n&&(n.delete(e),n.size===0&&this.byEventType.delete(t))}},x=class{bus;storeRegistry;timelineStore;pauseService;runServiceDefinitions=[];serviceContainer;workflows=new Map;index=new Map;subscriptions=new Map;pausedRuns=new Map;abortUnsubscribe;signalUnsubscribe;constructor(t){this.bus=t.bus,this.storeRegistry=t.storeRegistry,this.timelineStore=t.timelineStore,this.pauseService=new b({bus:this.bus,resume:async(e,t)=>{this.resume(e,t)}}),this.serviceContainer=new e(new d({}));for(let e of t.services??[]){if(e.id===`__pause_service__`)throw new a({code:r.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Service id "__pause_service__" is reserved for the built-in PauseService and cannot be redefined.`});e.scope===`singleton`?this.serviceContainer.register({key:e.id,factory:()=>e.factory(),scope:`singleton`}):this.runServiceDefinitions.push(e)}this.serviceContainer.register({key:`__pause_service__`,factory:()=>this.pauseService,scope:`singleton`}),this.abortUnsubscribe=this.bus.subscribe(m,e=>{this.abortRun(e.run)}),this.signalUnsubscribe=this.bus.subscribe(h,e=>{this.signal(e.runId,e.patch)})}static async createTestTimelineStore(e=`test-timeline-database`){return new l(await t({database:e,validate:!0,predicates:{},enableTelemetry:!0},n))}async register(e,t){if(this.workflows.has(e.id))throw new a({code:r.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Workflow "${e.id}" is already registered. Call deregister("${e.id}") before registering again.`});let n=s.get(`workflow:${e.id}`,{onExpired:(t,n)=>{console.info(`[WorkflowRuntime] Run "${t}" pause-window expired for workflow "${e.id}". Checkpoint: ${n.pipelineId}.`)},onExportFailed:(t,n)=>{console.error(`[WorkflowRuntime] Deferred export failed for run "${t}" in workflow "${e.id}":`,n)}}),i=async e=>{let r=e.ok?e.value.runId:e.error?.runId;r&&(c.executionContext.settle(r),this.pauseService.onRunEnded(r),this.pausedRuns.delete(r)),n.prune();try{await t.onComplete(e)}finally{await t.onCleanup?.()}},o=this.buildExecutionContext(e.id,t.mode),c;c={workflow:e,mode:t.mode,executionContext:o,factories:new Map,registry:n,hooks:{onPrepare:t.onPrepare,onComplete:i,onResume:t.onResume,onDispatch:t.onDispatch,onCleanup:t.onCleanup}},this.workflows.set(e.id,c);for(let[t,n]of Object.entries(e.triggers)){let r={workflowId:e.id,triggerId:t,trigger:n},i=this.index.get(n.event);i||(i=new Set,this.index.set(n.event,i)),i.add(r),await this.acquireBusSubscription(n.event)}}deregister(e){let t=this.workflows.get(e);if(t){for(let n of Object.values(t.workflow.triggers)){let t=this.index.get(n.event);if(t){for(let n of t)n.workflowId===e&&t.delete(n);t.size===0&&this.index.delete(n.event)}this.releaseBusSubscription(n.event)}t.executionContext.close(),s.destroy(`workflow:${e}`),t.factories.clear(),this.workflows.delete(e)}}hasWorkflow(e){return this.workflows.has(e)}listWorkflows(){return Array.from(this.workflows.keys())}async stop(){for(let e of Array.from(this.workflows.keys()))this.deregister(e);try{this.abortUnsubscribe()}catch{}try{this.signalUnsubscribe()}catch{}}registry(e){return this.workflows.get(e)?.registry}watch(e,t){return this.workflows.get(e)?.registry.get(t)}listAllRuns(){let e=[];for(let[t,n]of this.workflows)for(let r of n.registry.list())e.push({...r,workflowId:t});return e}async invoke(e,t,n){let o=this.workflows.get(e);if(!o)throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: workflow "${e}" is not registered.`});if(!o.workflow.pipelines[t])throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: no pipeline definition for workflow "${e}" trigger "${t}".`});let s=this.generateRunId(e,t),c=await this.executePipeline(o,t,s,n);return c.ok&&c.value.status===`paused`?(this.pausedRuns.set(s,{workflowId:e,triggerId:t}),await this.drainWatchQueue(s)):await o.hooks.onComplete(c),c.ok?i.ok(c.value,{runId:s,triggerId:t}):i.fail(c.error,{runId:s,triggerId:t})}async resume(e,t={}){let n=this.pausedRuns.get(e);if(!n)throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] resume() failed: run "${e}" is not in the paused runs registry. It may have already completed, been aborted, or the runId is incorrect.`});let{workflowId:o,triggerId:s}=n,c=this.workflows.get(o);if(!c)throw new a({code:r.RESOURCE_RELEASED.code,message:`[WorkflowRuntime] resume() failed: workflow "${o}" is no longer registered. The workflow may have been deregistered while the run was paused.`});let l=this.getOrCreateFactory(c,s),d=c.registry.hold(e),f;try{let t=await l.resume(e);if(!t.ok)throw t.error;f=t.value}catch(t){throw new a({code:r.INTERNAL_ERROR.code,message:`[WorkflowRuntime] resume() failed to reconstruct context for run "${e}"`,cause:t})}d||f.container.extend(this.serviceContainer),Object.keys(t).length>0&&f.write(t),f.write({__watch__:u}),await c.hooks.onResume?.(f);let p=await f.run();if(p.ok&&p.value.status===`paused`)await this.drainWatchQueue(e);else{let t=this.workflows.get(o);if(t)try{await t.hooks.onComplete(p)}catch(t){console.error(`[WorkflowRuntime] onComplete hook threw during resume for run "${e}":`,t)}}return p.ok?i.ok(p.value,{runId:e,triggerId:s}):i.fail(p.error,{runId:e,triggerId:s})}async signal(e,t){for(let n of this.workflows.values()){let r=n.registry.get(e);if(r?.context){r.context.write(t);return}}}dispatch(e,t){let n=this.index.get(e);if(!n||n.size===0)return;let r={type:e,payload:t,timestamp:Date.now()};for(let e of n){let t=!0;if(e.trigger.predicate)try{t=e.trigger.predicate(r)}catch(n){console.error(`[WorkflowRuntime] Predicate threw for workflow "${e.workflowId}" trigger "${e.triggerId}":`,n),t=!1}if(!t){this.workflows.get(e.workflowId)?.hooks.onDispatch?.({status:`rejected`,reason:`filtered`});continue}let n=this.workflows.get(e.workflowId);n&&n.executionContext.accept(e.triggerId,r,(e,t)=>this.spawnRun(n,e,t)).then(e=>{n.hooks.onDispatch?.(e)}).catch(t=>{console.error(`[WorkflowRuntime] ExecutionContext.accept() threw for workflow "${e.workflowId}":`,t)})}}async executePipeline(e,t,n,r){let o=this.timelineStore?new c(this.timelineStore,{}):void 0,s=this.getOrCreateFactory(e,t),l;try{l=await s.prepare(void 0,n),o&&await o.attach(l),await l.store.set({__trigger_event__:r})}catch(e){o&&await o.detach().catch(()=>{});let t=e instanceof a?e:new a({code:`PIPELINE_PREPARE_FAILED`,message:e instanceof Error?e.message:String(e)});return i.fail(t)}l.container.extend(this.serviceContainer),await e.hooks.onPrepare(l);let u=await l.run();return o&&await o.detach().catch(()=>{}),u}async spawnRun(e,t,n){let r=this.generateRunId(e.workflow.id,t);return this.executePipeline(e,t,r,n).then(async n=>{if(n.ok&&n.value.status===`paused`){this.pausedRuns.set(r,{workflowId:e.workflow.id,triggerId:t}),await this.drainWatchQueue(r);return}try{await e.hooks.onComplete(n)}catch(e){console.error(`[WorkflowRuntime] onComplete hook threw for run "${r}":`,e)}}).catch(e=>{console.error(`[WorkflowRuntime] Pipeline execution failed for run "${r}":`,e)}),r}async drainWatchQueue(e){let t=this.pauseService.onRunPaused(e);if(t!==null)try{await this.resume(e,t.patch)}catch(t){console.error(`[WorkflowRuntime] drainWatchQueue: resume() failed for run "${e}":`,t),this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}}async abortRun(e){for(let t of this.workflows.values()){let n=t.registry.get(e);if(n?.context){try{n.context.abort()}catch(t){console.error(`[WorkflowRuntime] Error aborting run "${e}":`,t)}break}}this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}buildExecutionContext(e,t){switch(t.type){case`transient`:return new g(e,t.concurrency??10,t.capacity??1e3);case`serialized`:return new _(e,t.capacity??1e3);case`singleton_loop`:return new v(e,t.onActive??`drop`,t.replacementGracePeriod??5e3,(e,t)=>this.signal(e,{__singleton_event__:t}));case`exclusive`:return new y(e,t.onActive??`reject`)}}async acquireBusSubscription(e){let t=this.subscriptions.get(e);t||(t=new p(()=>this.bus.subscribe(e,t=>{this.dispatch(e,t)}),t=>{try{t?.(),this.subscriptions.delete(e)}catch{}},{gracePeriod:`sync`}),this.subscriptions.set(e,t)),await t.acquire()}releaseBusSubscription(e){this.subscriptions.get(e)?.release()}getOrCreateFactory(e,t){let n=e.factories.get(t);if(n)return n;let i=e.workflow.pipelines[t];if(!i)throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] No pipeline definition found for workflow "${e.workflow.id}" trigger "${t}". Ensure workflow.pipelines["${t}"] is populated by the compiler.`});let s=new o(i,{storeFactory:async e=>this.storeRegistry.get(e),registry:e.registry});return e.factories.set(t,s),s}generateRunId(e,t){return`${e}:${t}:${Date.now()}:${Math.random().toString(36).slice(2)}`}};export{m as ABORT_EVENT,h as SIGNAL_EVENT,x as WorkflowRuntime};
+import{ArtifactContainer as e}from"@asaidimu/utils-artifacts";import{DatabaseConnection as t,createIndexedDbStore as n}from"@asaidimu/utils-database";import{ErrorCodes as r,Result as i,SystemError as a}from"@asaidimu/utils-error";import{Logger as o}from"@asaidimu/utils-logger";import{PipelineFactory as s,PipelineRegistry as c,TimelineRecorder as l,TimelineStore as u,yieldToEventLoop as d}from"@asaidimu/utils-pipeline";import{DocumentSanitizer as f,commonEnvPatterns as p,newSecureDefaultConfig as m}from"@asaidimu/utils-sanitize";import{DELETE_SYMBOL as h,ReactiveDataStore as g}from"@asaidimu/utils-store";import{Serializer as _,SharedResource as v}from"@asaidimu/utils-sync";const y=`__abort__`,b=`__signal__`;var x=class{envs=new Map;use(e,t){return this.envs.set(e,t),this}get(e){return this.envs.get(`global`)?.[e]}list(){return{...this.envs.get(`global`)}}scope(e){let t=this.envs.get(e),n=this.envs.get(`global`);return{get:e=>{if(t&&e in t)return t[e];if(n&&e in n)return n[e]},list:()=>{let e={...n};if(t)for(let n of Object.keys(t))e[n]=t[n];return e}}}},S=class{workflowId;concurrency;capacity;logger;inFlight=0;queueSize=0;closed=!1;constructor(e,t,n,r){this.workflowId=e,this.concurrency=t,this.capacity=n,this.logger=r}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`queue_full`};if(this.inFlight<this.concurrency)return this.inFlight++,this.run(e,t,n),{status:`accepted`};if(this.queueSize>=this.capacity)return{status:`rejected`,reason:`queue_full`};this.queueSize++;let r=this.queueSize;return await new Promise(e=>{let t=()=>{if(this.closed){e();return}this.inFlight<this.concurrency?(this.inFlight++,this.queueSize--,e()):setTimeout(t,0)};setTimeout(t,0)}),this.closed?{status:`rejected`,reason:`queue_full`}:(this.run(e,t,n),{status:`queued`,position:r})}settle(e){}close(){this.closed=!0}async run(e,t,n){try{await n(e,t)}finally{this.inFlight--}}},C=class{workflowId;capacity;logger;serializer;queueDepth=0;closed=!1;constructor(e,t,n){this.workflowId=e,this.capacity=t,this.logger=n,this.serializer=new _({capacity:t,yieldMode:`macrotask`})}async accept(e,t,n){if(this.closed||this.queueDepth>=this.capacity)return{status:`rejected`,reason:`queue_full`};let r=this.queueDepth;return this.queueDepth++,await this.serializer.do(async()=>{try{await n(e,t)}finally{this.queueDepth--}}),r===0?{status:`accepted`}:{status:`queued`,position:r}}settle(e){}close(){this.closed=!0,this.serializer.close()}},w=class{workflowId;onActive;replacementGracePeriod;deliverSignal;logger;state=`idle`;activeRunId;settleResolve;closed=!1;constructor(e,t,n,r,i){this.workflowId=e,this.onActive=t,this.replacementGracePeriod=n,this.deliverSignal=r,this.logger=i}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`singleton_active`};if(this.state===`idle`){this.state=`starting`;let r=await n(e,t);return r||(this.state=`idle`,this.activeRunId=void 0),{status:`accepted`,runId:r}}if(this.state===`terminating`)return{status:`rejected`,reason:`terminating`};switch(this.onActive){case`drop`:return{status:`rejected`,reason:`singleton_active`};case`signal`:{let e=this.activeRunId??``;return e?this.deliverSignal(e,t):this.logger.warn(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": signal requested but activeRunId unknown (state="${this.state}"). Event "${t.type}" dropped.`),{status:`signalled`,runId:e}}case`replace`:return this.handleReplace(e,t,n)}}settle(e){(this.state===`starting`||e===this.activeRunId)&&(this.activeRunId=e,this.state=`running`),this.state===`terminating`&&e===this.activeRunId&&this.settleResolve?.()}close(){this.closed=!0,this.settleResolve?.()}async handleReplace(e,t,n){if(this.state=`terminating`,this.activeRunId&&this.logger.info(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": replacing run "${this.activeRunId}" with new event "${t.type}".`),await Promise.race([new Promise(e=>{this.settleResolve=e}),new Promise(e=>setTimeout(e,this.replacementGracePeriod))]),this.settleResolve=void 0,this.closed)return this.state=`idle`,{status:`rejected`,reason:`singleton_active`};this.state=`starting`,this.activeRunId=void 0;let r=await n(e,t);return r||(this.state=`idle`),{status:`accepted`,runId:r}}},T=class{workflowId;onActive;logger;activeRunId;pending;closed=!1;constructor(e,t,n){this.workflowId=e,this.onActive=t,this.logger=n}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`exclusive_active`};if(!this.activeRunId){let r=await n(e,t);return r&&(this.activeRunId=r),{status:`accepted`,runId:r}}return this.onActive===`reject`?{status:`rejected`,reason:`exclusive_active`}:(this.pending={triggerId:e,event:t,spawn:n},{status:`queued`,position:1})}settle(e){if(e===this.activeRunId&&(this.activeRunId=void 0,this.pending&&!this.closed)){let{triggerId:e,event:t,spawn:n}=this.pending;this.pending=void 0,n(e,t).then(e=>{e&&(this.activeRunId=e)})}}close(){this.closed=!0,this.pending=void 0}},E=class{registrations=new Map;byEventType=new Map;busSubscriptions=new Map;bus;resumeCallback;constructor(e){this.bus=e.bus,this.resumeCallback=e.resume}register(e,t){let n=this.registrations.get(e);n||(n=new Map,this.registrations.set(e,n));let r={runId:e,descriptor:t,queue:[],parked:!1};n.set(t.eventType,r);let i=this.byEventType.get(t.eventType);i||(i=new Set,this.byEventType.set(t.eventType,i)),i.add(e),this.acquireBusSubscription(t.eventType)}cancel(e,t){let n=this.registrations.get(e);n&&(n.delete(t),n.size===0&&this.registrations.delete(e),this.removeFromReverseIndex(e,t),this.releaseBusSubscription(t))}onRunPaused(e){let t=this.registrations.get(e);if(!t)return null;for(let e of t.values())if(e.queue.length>0)return e.queue.shift();for(let e of t.values())e.parked=!0;return null}onRunEnded(e){let t=this.registrations.get(e);if(t){for(let[n]of t)this.removeFromReverseIndex(e,n),this.releaseBusSubscription(n);this.registrations.delete(e)}}onEvent(e,t){let n=this.byEventType.get(e);if(!(!n||n.size===0))for(let r of n){let n=this.registrations.get(r);if(!n)continue;let i=n.get(e);if(!i||!this.evaluate(i.descriptor.conditions,t))continue;let a=this.resolve(i.descriptor,t);i.parked?(i.parked=!1,this.resumeCallback(r,a.patch)):i.queue.push(a)}}evaluate(e,t){for(let n of e){let e=this.getField(t,n.field);if(n.op===`exists`){if(e==null)return!1;continue}if(e==null)return!1;try{switch(n.op){case`==`:if(e!=n.value)return!1;break;case`!=`:if(e==n.value)return!1;break;case`>`:if(!(e>n.value))return!1;break;case`>=`:if(!(e>=n.value))return!1;break;case`<`:if(!(e<n.value))return!1;break;case`<=`:if(!(e<=n.value))return!1;break;default:return!1}}catch{return!1}}return!0}resolve(e,t){return{eventPayload:t,patch:{...e.patch??{},__watch_event__:t}}}getField(e,t){let n=t.split(`.`),r=e;for(let e of n){if(r==null||typeof r!=`object`&&!Array.isArray(r))return;let t=Number(e);r=!isNaN(t)&&Array.isArray(r)?r[t]:r[e]}return r}acquireBusSubscription(e){if(this.busSubscriptions.has(e))return;let t=this.bus.subscribe(e,t=>{this.onEvent(e,t)});this.busSubscriptions.set(e,t)}releaseBusSubscription(e){let t=this.byEventType.get(e);if(t&&t.size>0)return;let n=this.busSubscriptions.get(e);if(n){try{n()}catch{}this.busSubscriptions.delete(e)}}removeFromReverseIndex(e,t){let n=this.byEventType.get(t);n&&(n.delete(e),n.size===0&&this.byEventType.delete(t))}},D=class{bus;storeRegistry;timelineStore;pauseService;serviceContainer;serviceStore;workflows=new Map;index=new Map;subscriptions=new Map;pausedRuns=new Map;logger;abortUnsubscribe;signalUnsubscribe;constructor(t){this.bus=t.bus,this.storeRegistry=t.storeRegistry,this.timelineStore=t.timelineStore,this.logger=t.logger?t.logger:new o([],{scope:`workflow-runtime`}),this.pauseService=new E({bus:this.bus,resume:async(e,t)=>{this.resume(e,t)}}),this.serviceStore=new g({env:{global:t.env??{}}}),this.serviceContainer=new e(this.serviceStore);for(let e of t.services??[]){if(e.id===`__pause_service__`)throw new a({code:r.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Service id "__pause_service__" is reserved for the built-in PauseService and cannot be redefined.`});if(e.id===`__env__`)throw new a({code:r.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Service id "__env__" is reserved for the built-in environment-variable service and cannot be redefined.`});this.serviceContainer.register({key:e.id,factory:e.factory,scope:`singleton`})}this.serviceContainer.register({key:`__pause_service__`,factory:()=>this.pauseService,scope:`singleton`}),this.serviceContainer.register({key:`__env_service__`,factory:async({use:e})=>{let t=await e(e=>e.select(e=>e.env)),n=new x;for(let[e,r]of Object.entries(t??{}))n.use(e,r);return n},scope:`singleton`}),this.serviceContainer.register({key:`__scoped_env_service__`,paramKey:e=>`env:${e.workflowId}`,factory:async({use:e,params:t})=>(await e(e=>e.require(`__env_service__`))).scope(t.workflowId),scope:`singleton`}),this.serviceContainer.register({key:`__sanitizer__`,paramKey:e=>`sanitizer:${e.workflowId}`,factory:async({use:e,params:t})=>{let n=(await e(e=>e.require(`__scoped_env_service__`,{workflowId:t.workflowId}))).list(),r=m();return r.patterns=[...r.patterns,...p([],n)],new f(r,t.workflowId)},scope:`singleton`}),this.abortUnsubscribe=this.bus.subscribe(y,e=>{this.abortRun(e.run)}),this.signalUnsubscribe=this.bus.subscribe(b,e=>{this.signal(e.runId,e.patch)})}static async createTestTimelineStore(e=`test-timeline-database`){return new u(await t({database:e,validate:!0,predicates:{},enableTelemetry:!0},n))}async register(e,t){if(this.workflows.has(e.id))throw new a({code:r.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Workflow "${e.id}" is already registered. Call deregister("${e.id}") before registering again.`});let n=c.get(`workflow:${e.id}`,{onExpired:(t,n)=>{this.logger.info(`[WorkflowRuntime] Run "${t}" pause-window expired for workflow "${e.id}". Checkpoint: ${n.pipelineId}.`)},onExportFailed:(t,n)=>{this.logger.error(`[WorkflowRuntime] Deferred export failed for run "${t}" in workflow "${e.id}":`,n)}}),i=async e=>{let r=e.ok?e.value.runId:e.error?.runId;try{await t.onComplete(e)}finally{r&&(s.executionContext.settle(r),this.pauseService.onRunEnded(r),this.pausedRuns.delete(r)),n.prune(),await t.onCleanup?.()}},o=this.buildExecutionContext(e.id,t.mode),s;s={workflow:e,mode:t.mode,executionContext:o,factories:new Map,registry:n,hooks:{onPrepare:t.onPrepare,onComplete:i,onResume:t.onResume,onDispatch:t.onDispatch,onCleanup:t.onCleanup}},this.workflows.set(e.id,s),this.serviceStore.set(t=>({env:{...t.env??{},[e.id]:e.env??{}}}));let l=this.serviceContainer.scope(e.id);if(e.services&&e.services.length>0)for(let t of e.services)t.scope===`run`||t.scope===`transient`||l.register({key:t.id,factory:t.factory,scope:`singleton`});s.container=l;for(let[t,n]of Object.entries(e.triggers)){let r={workflowId:e.id,triggerId:t,trigger:n},i=this.index.get(n.event);i||(i=new Set,this.index.set(n.event,i)),i.add(r),await this.acquireBusSubscription(n.event)}}deregister(e){let t=this.workflows.get(e);if(t){for(let n of Object.values(t.workflow.triggers)){let t=this.index.get(n.event);if(t){for(let n of t)n.workflowId===e&&t.delete(n);t.size===0&&this.index.delete(n.event)}this.releaseBusSubscription(n.event)}for(let t of[`__scoped_env_service__`,`__sanitizer__`])try{this.serviceContainer.unregister(t,{workflowId:e})}catch{}this.serviceStore.set(t=>({env:{...t.env??{},[e]:h}})),t.container?.dispose(),t.executionContext.close(),c.destroy(`workflow:${e}`),t.factories.clear(),this.workflows.delete(e)}}hasWorkflow(e){return this.workflows.has(e)}listWorkflows(){return Array.from(this.workflows.keys())}async stop(){for(let e of Array.from(this.workflows.keys()))this.deregister(e);try{this.abortUnsubscribe()}catch{}try{this.signalUnsubscribe()}catch{}}registry(e){return this.workflows.get(e)?.registry}info(e,t){return this.workflows.get(e)?.registry.get(t)}list(){let e=[];for(let[t,n]of this.workflows)for(let r of n.registry.list())e.push({...r,workflowId:t});return e}async invoke(e,t,n){let o=this.workflows.get(e);if(!o)throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: workflow "${e}" is not registered.`});if(!o.workflow.pipelines[t])throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: no pipeline definition for workflow "${e}" trigger "${t}".`});let s=this.generateRunId(e,t),c=await this.executePipeline(o,t,s,n);return c.ok&&c.value.status===`paused`?(this.pausedRuns.set(s,{workflowId:e,triggerId:t}),await this.drainWatchQueue(s)):await o.hooks.onComplete(c),c.ok?i.ok(c.value,{runId:s,triggerId:t}):i.fail(c.error,{runId:s,triggerId:t})}async resume(e,t={}){let n=this.pausedRuns.get(e);if(!n)throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] resume() failed: run "${e}" is not in the paused runs registry. It may have already completed, been aborted, or the runId is incorrect.`});let{workflowId:o,triggerId:s}=n,c=this.workflows.get(o);if(!c)throw new a({code:r.RESOURCE_RELEASED.code,message:`[WorkflowRuntime] resume() failed: workflow "${o}" is no longer registered. The workflow may have been deregistered while the run was paused.`});let l=this.getOrCreateFactory(c,s),u=c.registry.hold(e),d=await this.createRecorder(c),f=d?[d.asLogSink()]:void 0,p;try{let t=await l.resume(e,{sinks:f});if(!t.ok)throw t.error;p=t.value}catch(t){throw new a({code:r.INTERNAL_ERROR.code,message:`[WorkflowRuntime] resume() failed to reconstruct context for run "${e}"`,cause:t})}u||this.extendContextContainer(p,c),Object.keys(t).length>0&&p.write(t),p.write({__watch__:h});let m=await this.withRecorder(p,async()=>(await c.hooks.onResume?.(p),await p.run()),d);if(m.ok&&m.value.status===`paused`)await this.drainWatchQueue(e);else{let t=this.workflows.get(o);if(t)try{await t.hooks.onComplete(m)}catch(t){this.logger.error(`[WorkflowRuntime] onComplete hook threw during resume for run "${e}":`,t)}}return m.ok?i.ok(m.value,{runId:e,triggerId:s}):i.fail(m.error,{runId:e,triggerId:s})}async signal(e,t){for(let n of this.workflows.values()){let r=n.registry.get(e);if(r?.context){r.context.write(t);return}}}dispatch(e,t){let n=this.index.get(e);if(!n||n.size===0)return;let r={type:e,payload:t,timestamp:Date.now()};for(let e of n){let t=!0;if(e.trigger.predicate)try{t=e.trigger.predicate(r)}catch(n){this.logger.error(`[WorkflowRuntime] Predicate threw for workflow "${e.workflowId}" trigger "${e.triggerId}":`,n),t=!1}if(!t){this.workflows.get(e.workflowId)?.hooks.onDispatch?.({status:`rejected`,reason:`filtered`});continue}let n=this.workflows.get(e.workflowId);n&&n.executionContext.accept(e.triggerId,r,(e,t)=>this.spawnRun(n,e,t)).then(e=>{n.hooks.onDispatch?.(e)}).catch(t=>{this.logger.error(`[WorkflowRuntime] ExecutionContext.accept() threw for workflow "${e.workflowId}":`,t)})}}async createRecorder(e){if(!this.timelineStore)return;let t;try{t=await this.serviceContainer.require(`__sanitizer__`,{workflowId:e.workflow.id})}catch{}return new l(this.timelineStore,{sanitizer:t})}async withRecorder(e,t,n){if(!n)return t();await n.attach(e),await d();try{return await t()}finally{await n.detach().catch(()=>{})}}async executePipeline(e,t,n,r){let o=this.getOrCreateFactory(e,t),s=await this.createRecorder(e),c=s?[s.asLogSink()]:void 0,l;try{l=await o.prepare(void 0,n,{sinks:c}),await l.store.set({__trigger_event__:r})}catch(e){let t=e instanceof a?e:new a({code:`PIPELINE_PREPARE_FAILED`,message:e instanceof Error?e.message:String(e)});return i.fail(t)}return this.extendContextContainer(l,e),this.withRecorder(l,async()=>(await e.hooks.onPrepare(l),await l.run()),s)}async spawnRun(e,t,n){let r=this.generateRunId(e.workflow.id,t);return this.executePipeline(e,t,r,n).then(async n=>{if(n.ok&&n.value.status===`paused`){this.pausedRuns.set(r,{workflowId:e.workflow.id,triggerId:t}),await this.drainWatchQueue(r);return}try{await e.hooks.onComplete(n)}catch(e){this.logger.error(`[WorkflowRuntime] onComplete hook threw for run "${r}":`,e)}}).catch(e=>{this.logger.error(`[WorkflowRuntime] Pipeline execution failed for run "${r}":`,e)}),r}async drainWatchQueue(e){let t=this.pauseService.onRunPaused(e);if(t!==null)try{await this.resume(e,t.patch)}catch(t){this.logger.error(`[WorkflowRuntime] drainWatchQueue: resume() failed for run "${e}":`,t),this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}}async abortRun(e){for(let t of this.workflows.values()){let n=t.registry.get(e);if(n?.context){try{n.context.abort()}catch(t){this.logger.error(`[WorkflowRuntime] Error aborting run "${e}":`,t)}break}}this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}buildExecutionContext(e,t){let n=this.logger.child({scope:`${t.type}:execution-context`});switch(t.type){case`transient`:return new S(e,t.concurrency??10,t.capacity??1e3,n);case`serialized`:return new C(e,t.capacity??1e3,n);case`singleton_loop`:return new w(e,t.onActive??`drop`,t.replacementGracePeriod??5e3,(e,t)=>this.signal(e,{__singleton_event__:t}),n);case`exclusive`:return new T(e,t.onActive??`reject`,n)}}async acquireBusSubscription(e){let t=this.subscriptions.get(e);t||(t=new v(()=>this.bus.subscribe(e,t=>{this.dispatch(e,t)}),t=>{try{t?.(),this.subscriptions.delete(e)}catch{}},{gracePeriod:`sync`}),this.subscriptions.set(e,t)),await t.acquire()}releaseBusSubscription(e){this.subscriptions.get(e)?.release()}async extendContextContainer(e,t){t.container&&e.container.extend(t.container),e.container.extend(this.serviceContainer);let n=await this.serviceContainer.require(`__scoped_env_service__`,{workflowId:t.workflow.id});e.container.register({key:`__env__`,factory:()=>n,scope:`singleton`});for(let t of[`__env_service__`,`__scoped_env_service__`])e.container.register({key:t,factory:()=>{throw new a({code:r.UNAUTHENTICATED.code,message:`"${t}" is an internal artifact and cannot be accessed from pipeline steps.`})},scope:`singleton`,lazy:!1});if(t.workflow.services)for(let n of t.workflow.services){if(n.scope===`workflow`||n.scope===void 0)continue;let t=n.scope===`run`?`singleton`:`transient`;e.container.register({key:n.id,factory:n.factory,scope:t})}}getOrCreateFactory(e,t){let n=e.factories.get(t);if(n)return n;let i=e.workflow.pipelines[t];if(!i)throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] No pipeline definition found for workflow "${e.workflow.id}" trigger "${t}". Ensure workflow.pipelines["${t}"] is populated by the compiler.`});let o=new s(i,{storeFactory:async e=>this.storeRegistry.get(e),registry:e.registry});return e.factories.set(t,o),o}generateRunId(e,t){return`${e}:${t}:${Date.now()}:${Math.random().toString(36).slice(2)}`}};export{y as ABORT_EVENT,b as SIGNAL_EVENT,D as WorkflowRuntime};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/runtime",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A runtime for workflows built on \"@asaidimu/utils-pipeline\".",
   "main": "index.js",
   "module": "index.mjs",
@@ -35,13 +35,15 @@
     }
   },
   "dependencies": {
-    "@asaidimu/utils-store": "^10.2.12",
+    "@asaidimu/utils-store": "^10.2.13",
     "@asaidimu/utils-database": "^3.1.15",
     "@asaidimu/utils-sync": "^2.3.6",
-    "@asaidimu/utils-pipeline": "^1.3.12",
-    "@asaidimu/utils-artifacts": "^8.2.19",
+    "@asaidimu/utils-pipeline": "^1.3.14",
+    "@asaidimu/utils-artifacts": "^8.2.20",
     "@asaidimu/utils-error": "^1.0.0",
-    "@asaidimu/utils-events": "^1.2.7"
+    "@asaidimu/utils-events": "^1.2.7",
+    "@asaidimu/utils-sanitize": "^1.0.6",
+    "@asaidimu/utils-logger": "^1.0.9"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",