@adonis-agora/durable 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @adonis-agora/durable
 
+## 0.8.0
+
+### Minor Changes
+
+- [`86819e0`](https://github.com/DavideCarvalho/adonis-durable/commit/86819e08666a307046e8845a7d9b9ed3685d7c53) - BaseWorkflow is the sole authoring form; `services/main`; dashboard login; signal/child/subscriber fixes
+
+  **BREAKING — the `@Workflow` decorator is removed.** Author workflows with a
+  `BaseWorkflow` subclass plus `static workflow = { name, version }`:
+
+  ```ts
+  // before
+  @Workflow({ name: "charge", version: "1" })
+  class ChargeWorkflow {
+    async run(ctx: WorkflowCtx, input: Input) {}
+  }
+
+  // after
+  export default class ChargeWorkflow extends BaseWorkflow {
+    static workflow = { name: "charge", version: "1" };
+    async run(ctx: WorkflowCtx, input: Input) {}
+  }
+  ```
+
+  `workflowMeta()` now reads only the `static workflow` config; normalization is
+  unchanged (version defaults to `'1'`). One authoring form means one thing to
+  document, one thing to discover, and no decorator/metadata runtime.
+
+  **Features**
+
+  - `BaseWorkflow` with context-aware static `start`/`dispatch`. Call
+    `ChargeWorkflow.start(input)` and it does the right thing by context: outside a
+    workflow it enqueues on the engine and blocks until the run reaches a terminal
+    state; inside one it starts a linked child and suspends the parent. `.dispatch`
+    is the fire-and-forget twin, returning `{ runId }` without waiting.
+  - `@adonis-agora/durable/services/main` — an idiomatic singleton import, so app
+    code reaches the engine the way it reaches any other Adonis service.
+  - Control-flow signal marker plus `isWorkflowControlFlowSignal`, so a workflow
+    can tell a control-flow signal apart from a domain one.
+  - Buffered events are now reliable: an event delivered before its waiter exists is
+    no longer lost.
+  - Dashboard built-in login screen via `dashboardAuth`.
+
+  **Fixes**
+
+  - Closed a lost-wake race in the signal waiter, and added the
+    `removeSignalWaiter` SPI so a waiter can be torn down deterministically.
+  - A child that fails to _start_ now surfaces the failure to the parent instead of
+    stranding it. The parent used to wait forever on a child that never existed:
+    the start was fire-and-forget, so nothing ever notified the parent. The child
+    start is now deferred and its rejection is reported to the parent as a failed
+    child result.
+  - The Redis control plane now heals a silently-dead subscriber connection. A
+    subscriber whose socket died without an error event stopped delivering messages
+    while still looking healthy, and every wake-up routed through it was lost. A
+    ping watchdog now detects the dead connection and forces a reconnect.
+  - `BaseWorkflow.start` waits for terminal (matching the linked-child path), the
+    steps hook is configurable, and the dashboard token comparison is
+    constant-time.
+
+  **eslint-plugin** — `no-nondeterminism` identifies a workflow's `run` body by the
+  new authoring form (a `BaseWorkflow` subclass, or any class with a
+  `static workflow` config) instead of the removed `@Workflow` decorator. Without
+  this the rule would silently stop guarding every workflow in a 0.8 codebase.
+
 ## 0.6.1
 
 ### Patch Changes

package/README.md

@@ -53,7 +53,7 @@ export default defineConfig({
 `node ace configure` registers an AdonisJS **Assembler `init` hook** that generates
 a typed barrel of `app/workflows/` at build/dev time — exactly how core generates
 the controllers/events/listeners barrels. The provider imports the generated
-`.adonisjs/durable/workflows.ts` at boot and registers every `@Workflow` class,
+`.adonisjs/durable/workflows.ts` at boot and registers every `BaseWorkflow` class,
 instead of scanning the directory with `readdir` at runtime. The file watcher
 regenerates the barrel whenever a workflow file changes.
 

package/dist/commands/main.d.ts

@@ -6,8 +6,9 @@ import DurableWork from './work.js';
 /**
  * The commands barrel for `@adonis-agora/durable`. Registered in an app's `adonisrc` via
  * `rcFile.addCommand('@adonis-agora/durable/commands')` (done by this package's `configure`). The ace
- * kernel imports this module and treats it as a commands loader: a {@link ListLoader} over the three
- * durable commands provides their metadata and constructors.
+ * kernel imports this module and treats it as a commands loader: a {@link ListLoader} over the four
+ * durable commands (`durable:work`, `durable:runs`, `durable:retry`, `make:workflow`) provides their
+ * metadata and constructors.
  */
 declare const loader: ListLoader<typeof MakeWorkflow | typeof DurableRetry | typeof DurableRuns | typeof DurableWork>;
 export declare const getMetaData: () => Promise<import("@adonisjs/core/types/ace").CommandMetaData[]>;

package/dist/commands/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAC9C,OAAO,YAAY,MAAM,YAAY,CAAC;AACtC,OAAO,WAAW,MAAM,WAAW,CAAC;AACpC,OAAO,WAAW,MAAM,WAAW,CAAC;AAEpC;;;;;GAKG;AACH,QAAA,MAAM,MAAM,iGAAyE,CAAC;AAEtF,eAAO,MAAM,WAAW,qEAAkC,CAAC;AAC3D,eAAO,MAAM,UAAU,uKAAiC,CAAC;AAEzD,eAAe,MAAM,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAC9C,OAAO,YAAY,MAAM,YAAY,CAAC;AACtC,OAAO,WAAW,MAAM,WAAW,CAAC;AACpC,OAAO,WAAW,MAAM,WAAW,CAAC;AAEpC;;;;;;GAMG;AACH,QAAA,MAAM,MAAM,iGAAyE,CAAC;AAEtF,eAAO,MAAM,WAAW,qEAAkC,CAAC;AAC3D,eAAO,MAAM,UAAU,uKAAiC,CAAC;AAEzD,eAAe,MAAM,CAAC"}

package/dist/commands/main.js

@@ -6,8 +6,9 @@ import DurableWork from './work.js';
 /**
  * The commands barrel for `@adonis-agora/durable`. Registered in an app's `adonisrc` via
  * `rcFile.addCommand('@adonis-agora/durable/commands')` (done by this package's `configure`). The ace
- * kernel imports this module and treats it as a commands loader: a {@link ListLoader} over the three
- * durable commands provides their metadata and constructors.
+ * kernel imports this module and treats it as a commands loader: a {@link ListLoader} over the four
+ * durable commands (`durable:work`, `durable:runs`, `durable:retry`, `make:workflow`) provides their
+ * metadata and constructors.
  */
 const loader = new ListLoader([DurableWork, DurableRuns, DurableRetry, MakeWorkflow]);
 export const getMetaData = loader.getMetaData.bind(loader);

package/dist/commands/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAC9C,OAAO,YAAY,MAAM,YAAY,CAAC;AACtC,OAAO,WAAW,MAAM,WAAW,CAAC;AACpC,OAAO,WAAW,MAAM,WAAW,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;AAEtF,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAe,MAAM,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,YAAY,MAAM,oBAAoB,CAAC;AAC9C,OAAO,YAAY,MAAM,YAAY,CAAC;AACtC,OAAO,WAAW,MAAM,WAAW,CAAC;AACpC,OAAO,WAAW,MAAM,WAAW,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;AAEtF,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAe,MAAM,CAAC"}

package/dist/commands/make_workflow.d.ts

@@ -2,9 +2,10 @@ import { BaseCommand } from '@adonisjs/core/ace';
 import type { CommandOptions } from '@adonisjs/core/types/ace';
 /**
  * `node ace make:workflow <name>` — scaffold a durable workflow class under `app/workflows/`, the
- * parallel to `@adonisjs/queue`'s `make:job` (which scaffolds `app/jobs/`). The generated class is
- * `@Workflow`-decorated with a `run(ctx, input)` method and is auto-registered on the engine at boot
- * by the durable provider — no manual `engine.register(...)`.
+ * parallel to `@adonisjs/queue`'s `make:job` (which scaffolds `app/jobs/`). The generated class
+ * extends `BaseWorkflow` (the blessed authoring form) with a `static workflow = { name, version }`
+ * identity and a `run(ctx, input)` method, and is auto-registered on the engine at boot by the
+ * durable provider — no manual `engine.register(...)`.
  */
 export default class MakeWorkflow extends BaseCommand {
     static commandName: string;

package/dist/commands/make_workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_workflow.d.ts","sourceRoot":"","sources":["../../commands/make_workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAQ,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,WAAW;IACnD,OAAgB,WAAW,SAAmB;IAC9C,OAAgB,WAAW,SAAyC;IACpE,OAAgB,OAAO,EAAE,cAAc,CAA+B;IAG9D,IAAI,EAAE,MAAM,CAAC;IAEN,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAOpC"}
+{"version":3,"file":"make_workflow.d.ts","sourceRoot":"","sources":["../../commands/make_workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAQ,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,WAAW;IACnD,OAAgB,WAAW,SAAmB;IAC9C,OAAgB,WAAW,SAAyC;IACpE,OAAgB,OAAO,EAAE,cAAc,CAA+B;IAG9D,IAAI,EAAE,MAAM,CAAC;IAEN,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAOpC"}

package/dist/commands/make_workflow.js

@@ -8,9 +8,10 @@ import { BaseCommand, args } from '@adonisjs/core/ace';
 import { stubsRoot } from '../stubs/main.js';
 /**
  * `node ace make:workflow <name>` — scaffold a durable workflow class under `app/workflows/`, the
- * parallel to `@adonisjs/queue`'s `make:job` (which scaffolds `app/jobs/`). The generated class is
- * `@Workflow`-decorated with a `run(ctx, input)` method and is auto-registered on the engine at boot
- * by the durable provider — no manual `engine.register(...)`.
+ * parallel to `@adonisjs/queue`'s `make:job` (which scaffolds `app/jobs/`). The generated class
+ * extends `BaseWorkflow` (the blessed authoring form) with a `static workflow = { name, version }`
+ * identity and a `run(ctx, input)` method, and is auto-registered on the engine at boot by the
+ * durable provider — no manual `engine.register(...)`.
  */
 export default class MakeWorkflow extends BaseCommand {
     static commandName = 'make:workflow';

package/dist/commands/make_workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"make_workflow.js","sourceRoot":"","sources":["../../commands/make_workflow.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,WAAW;IACnD,MAAM,CAAU,WAAW,GAAG,eAAe,CAAC;IAC9C,MAAM,CAAU,WAAW,GAAG,qCAAqC,CAAC;IACpE,MAAM,CAAU,OAAO,GAAmB,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAK7D,KAAK,CAAC,GAAG;QAChB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC7C,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,yBAAyB,EAAE;YACjE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;YACxB,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;SACpD,CAAC,CAAC;IACL,CAAC;;AARO;IADP,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,sBAAsB,EAAE,CAAC;0CAChC"}
+{"version":3,"file":"make_workflow.js","sourceRoot":"","sources":["../../commands/make_workflow.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,WAAW;IACnD,MAAM,CAAU,WAAW,GAAG,eAAe,CAAC;IAC9C,MAAM,CAAU,WAAW,GAAG,qCAAqC,CAAC;IACpE,MAAM,CAAU,OAAO,GAAmB,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAK7D,KAAK,CAAC,GAAG;QAChB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC7C,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,yBAAyB,EAAE;YACjE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;YACxB,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;SACpD,CAAC,CAAC;IACL,CAAC;;AARO;IADP,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,sBAAsB,EAAE,CAAC;0CAChC"}

package/dist/configure.d.ts

@@ -3,12 +3,13 @@ import type Configure from '@adonisjs/core/commands/configure';
  * `node ace configure @adonis-agora/durable` — auto-wires the package:
  *
  * 1. registers the core service provider in `adonisrc.ts`;
- * 2. registers the ace commands barrel (`durable:work`, `durable:runs`,
- *    `durable:retry`);
+ * 2. registers the ace commands barrel (four commands: `durable:work`,
+ *    `durable:runs`, `durable:retry`, `make:workflow`);
  * 3. registers the optional dashboard provider;
- * 4. registers the Assembler `init` hook that generates the typed `app/workflows`
- *    barrel at build/dev time (the provider imports it instead of scanning at
- *    runtime; it falls back to the runtime scan when the barrel is absent);
+ * 4. registers the Assembler `init` hooks that generate the typed `app/workflows`
+ *    and `app/steps` barrels at build/dev time (the provider imports them instead
+ *    of scanning at runtime; each falls back to the runtime scan when its barrel
+ *    is absent);
  * 5. publishes `config/durable.ts` + `config/durable_dashboard.ts`;
  * 6. publishes the Lucid migrations for the optional `lucid` store and `db`
  *    transport drivers (run `node ace migration:run`, and delete the transport

package/dist/configure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mCAAmC,CAAC;AAG/D;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,SAAS,iBAmBjD"}
+{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mCAAmC,CAAC;AAG/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,SAAS,iBAqBjD"}

package/dist/configure.js

@@ -3,12 +3,13 @@ import { stubsRoot } from './stubs/main.js';
  * `node ace configure @adonis-agora/durable` — auto-wires the package:
  *
  * 1. registers the core service provider in `adonisrc.ts`;
- * 2. registers the ace commands barrel (`durable:work`, `durable:runs`,
- *    `durable:retry`);
+ * 2. registers the ace commands barrel (four commands: `durable:work`,
+ *    `durable:runs`, `durable:retry`, `make:workflow`);
  * 3. registers the optional dashboard provider;
- * 4. registers the Assembler `init` hook that generates the typed `app/workflows`
- *    barrel at build/dev time (the provider imports it instead of scanning at
- *    runtime; it falls back to the runtime scan when the barrel is absent);
+ * 4. registers the Assembler `init` hooks that generate the typed `app/workflows`
+ *    and `app/steps` barrels at build/dev time (the provider imports them instead
+ *    of scanning at runtime; each falls back to the runtime scan when its barrel
+ *    is absent);
  * 5. publishes `config/durable.ts` + `config/durable_dashboard.ts`;
  * 6. publishes the Lucid migrations for the optional `lucid` store and `db`
  *    transport drivers (run `node ace migration:run`, and delete the transport
@@ -20,8 +21,10 @@ export async function configure(command) {
         rcFile.addProvider('@adonis-agora/durable/durable_provider');
         rcFile.addProvider('@adonis-agora/durable/dashboard_provider');
         rcFile.addCommand('@adonis-agora/durable/commands');
-        // Generate the typed app/workflows barrel at build/dev time (replaces the runtime readdir scan).
+        // Generate the typed app/workflows + app/steps barrels at build/dev time (each replaces its
+        // runtime readdir scan; the provider falls back to the scan when a barrel is absent).
         rcFile.addAssemblerHook('init', '@adonis-agora/durable/hooks/workflows');
+        rcFile.addAssemblerHook('init', '@adonis-agora/durable/hooks/steps');
     });
     await codemods.makeUsingStub(stubsRoot, 'config/durable.stub', {});
     await codemods.makeUsingStub(stubsRoot, 'config/durable_dashboard.stub', {});

package/dist/configure.js.map

@@ -1 +1 @@
-{"version":3,"file":"configure.js","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAEhD,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,WAAW,CAAC,wCAAwC,CAAC,CAAC;QAC7D,MAAM,CAAC,WAAW,CAAC,0CAA0C,CAAC,CAAC;QAC/D,MAAM,CAAC,UAAU,CAAC,gCAAgC,CAAC,CAAC;QACpD,iGAAiG;QACjG,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,uCAAuC,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,qBAAqB,EAAE,EAAE,CAAC,CAAC;IACnE,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,+BAA+B,EAAE,EAAE,CAAC,CAAC;IAC7E,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,gDAAgD,EAAE,EAAE,CAAC,CAAC;IAC9F,MAAM,QAAQ,CAAC,aAAa,CAC1B,SAAS,EACT,0DAA0D,EAC1D,EAAE,CACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAEhD,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,WAAW,CAAC,wCAAwC,CAAC,CAAC;QAC7D,MAAM,CAAC,WAAW,CAAC,0CAA0C,CAAC,CAAC;QAC/D,MAAM,CAAC,UAAU,CAAC,gCAAgC,CAAC,CAAC;QACpD,4FAA4F;QAC5F,sFAAsF;QACtF,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,uCAAuC,CAAC,CAAC;QACzE,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,mCAAmC,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,qBAAqB,EAAE,EAAE,CAAC,CAAC;IACnE,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,+BAA+B,EAAE,EAAE,CAAC,CAAC;IAC7E,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,gDAAgD,EAAE,EAAE,CAAC,CAAC;IAC9F,MAAM,QAAQ,CAAC,aAAa,CAC1B,SAAS,EACT,0DAA0D,EAC1D,EAAE,CACH,CAAC;AACJ,CAAC"}

package/dist/providers/dashboard_provider.d.ts

@@ -16,12 +16,43 @@ import type { ApplicationService } from '@adonisjs/core/types';
 export default class DashboardProvider {
     protected app: ApplicationService;
     constructor(app: ApplicationService);
+    /** Warn once so a throwing `login` hook doesn't spam the logs on every failed attempt. */
+    private warnedOnHookThrow;
     boot(): Promise<void>;
     private registerRoutes;
     /**
-     * Run the configured guard. On denial, replies `403` and returns `false` so
-     * the route handler short-circuits.
+     * Mount the built-in `dashboardAuth` endpoints under `basePath`. All three are public (no guard):
+     * they create/destroy the session the {@link enforce} guard checks for.
+     *
+     * - `GET  <base>/login`  → the server-rendered login page (never varies per request beyond the
+     *    developer-controlled `basePath`; `returnTo`/`error` are read client-side from the query).
+     * - `POST <base>/login`  → verifies credentials via the host `login` hook and mints the cookie.
+     *    Called by the login page's own `fetch` (JSON body). Uniform `401` on ANY failure — unknown
+     *    user, wrong password, or a throwing hook — so there is no user-enumeration.
+     * - `GET  <base>/logout` → clears the cookie and redirects back to the login page. A plain `GET`
+     *    (idempotent, only ever destroys the caller's own session) so a simple `<a href>` works.
      */
-    private guard;
+    private registerAuthRoutes;
+    /**
+     * Run the guards for a dashboard resource. Composes the existing `authorize` hook (bearer
+     * token/custom) with the optional `dashboardAuth` session guard — BOTH must pass:
+     *
+     * 1. `authorize` fails → `403` (unchanged behavior).
+     * 2. `dashboardAuth` configured AND no valid session → for a `page` request, redirect `302` to
+     *    the login page carrying a sanitized `returnTo`; for an `api` request, a plain `401`.
+     *
+     * When `dashboardAuth` is unconfigured only step 1 runs, so behavior is byte-for-byte unchanged.
+     * Returns `false` (and has already written the response) when the request must short-circuit.
+     */
+    private enforce;
+    /** Read the raw (unencoded) session cookie value, or `undefined` when absent. */
+    private readSessionCookie;
+    /**
+     * Write the signed session as an unsigned (`plainCookie`, `encode: false`) cookie — the value
+     * carries its own HMAC signature, so AdonisJS's cookie signing would be redundant double-wrapping.
+     * `HttpOnly` + `SameSite=Lax` (blocks cross-site POSTs carrying the cookie — CSRF coverage) +
+     * `Secure` on https. `Path=/` so it reaches both the UI and API mounts regardless of prefix.
+     */
+    private writeSessionCookie;
 }
 //# sourceMappingURL=dashboard_provider.d.ts.map

package/dist/providers/dashboard_provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard_provider.d.ts","sourceRoot":"","sources":["../../providers/dashboard_provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAmB/D;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAiB;IACxB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAEvC,IAAI;IASV,OAAO,CAAC,cAAc;IA+CtB;;;OAGG;YACW,KAAK;CAQpB"}
+{"version":3,"file":"dashboard_provider.d.ts","sourceRoot":"","sources":["../../providers/dashboard_provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA0B/D;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAiB;IACxB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,0FAA0F;IAC1F,OAAO,CAAC,iBAAiB,CAAS;IAE5B,IAAI;IASV,OAAO,CAAC,cAAc;IAwDtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,kBAAkB;IAgD1B;;;;;;;;;;OAUG;YACW,OAAO;IA0BrB,iFAAiF;IACjF,OAAO,CAAC,iBAAiB;IAKzB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;CAU3B"}

package/dist/providers/dashboard_provider.js

@@ -1,7 +1,9 @@
 import router from '@adonisjs/core/services/router';
+import { SESSION_COOKIE_NAME, performLogin, readSession, } from '../src/dashboard/auth.js';
 import { resolveConfig, } from '../src/dashboard/define_config.js';
 import { cancelRun, getRun, health, listRuns, retryRun, } from '../src/dashboard/handlers.js';
 import { renderDashboard } from '../src/dashboard/html.js';
+import { renderLoginPage } from '../src/dashboard/login_page.js';
 import { WorkflowEngine } from '../src/index.js';
 /**
  * Mounts the durable dashboard into an AdonisJS app: a JSON API over the
@@ -22,6 +24,8 @@ export default class DashboardProvider {
     constructor(app) {
         this.app = app;
     }
+    /** Warn once so a throwing `login` hook doesn't spam the logs on every failed attempt. */
+    warnedOnHookThrow = false;
     async boot() {
         const config = resolveConfig(this.app.config.get('durable_dashboard', {}));
         if (!config.enabled)
@@ -37,10 +41,18 @@ export default class DashboardProvider {
             const engine = await this.app.container.make(WorkflowEngine);
             return { engine };
         };
+        // Built-in `dashboardAuth` login screen (opt-in). Registered ONLY when configured, so omitting
+        // `dashboardAuth` leaves route registration byte-for-byte as it was. These endpoints are public
+        // (behind NEITHER guard): they MINT the session the guard checks for, and the login page must
+        // stay reachable while unauthenticated — including in production, where the default `authorize`
+        // hook would otherwise deny it.
+        if (config.dashboardAuth) {
+            this.registerAuthRoutes(config, config.dashboardAuth);
+        }
         // The HTML page.
         router
             .get(config.path === '' ? '/' : config.path, async (ctx) => {
-            if (!(await this.guard(config, ctx)))
+            if (!(await this.enforce(config, ctx, 'page')))
                 return;
             ctx.response.header('content-type', 'text/html; charset=utf-8');
             return ctx.response.send(renderDashboard(apiBase));
@@ -49,7 +61,7 @@ export default class DashboardProvider {
         // JSON API.
         const json = (handler) => {
             return async (ctx) => {
-                if (!(await this.guard(config, ctx)))
+                if (!(await this.enforce(config, ctx, 'api')))
                     return;
                 try {
                     const result = await handler(await deps(), toApiRequest(ctx));
@@ -71,16 +83,108 @@ export default class DashboardProvider {
             .as('durable_dashboard.health');
     }
     /**
-     * Run the configured guard. On denial, replies `403` and returns `false` so
-     * the route handler short-circuits.
+     * Mount the built-in `dashboardAuth` endpoints under `basePath`. All three are public (no guard):
+     * they create/destroy the session the {@link enforce} guard checks for.
+     *
+     * - `GET  <base>/login`  → the server-rendered login page (never varies per request beyond the
+     *    developer-controlled `basePath`; `returnTo`/`error` are read client-side from the query).
+     * - `POST <base>/login`  → verifies credentials via the host `login` hook and mints the cookie.
+     *    Called by the login page's own `fetch` (JSON body). Uniform `401` on ANY failure — unknown
+     *    user, wrong password, or a throwing hook — so there is no user-enumeration.
+     * - `GET  <base>/logout` → clears the cookie and redirects back to the login page. A plain `GET`
+     *    (idempotent, only ever destroys the caller's own session) so a simple `<a href>` works.
+     */
+    registerAuthRoutes(config, auth) {
+        const loginPath = `${config.path}/login`;
+        const logoutPath = `${config.path}/logout`;
+        router
+            .get(loginPath, async (ctx) => {
+            ctx.response.header('content-type', 'text/html; charset=utf-8');
+            ctx.response.header('cache-control', 'no-store, must-revalidate');
+            return ctx.response.send(renderLoginPage(config.path));
+        })
+            .as('durable_dashboard.login.page');
+        router
+            .post(loginPath, async (ctx) => {
+            const outcome = await performLogin(auth, ctx.request.body(), config.path);
+            if (outcome.kind === 'bad-request') {
+                return ctx.response.status(400).json({ error: outcome.message });
+            }
+            if (outcome.kind === 'unauthorized') {
+                // A throwing hook is a denial (never a 500), warn-logged once so a buggy hook doesn't
+                // flood the logs. The client sees the same uniform 401 either way.
+                if (outcome.hookError !== undefined && !this.warnedOnHookThrow) {
+                    this.warnedOnHookThrow = true;
+                    const message = outcome.hookError instanceof Error
+                        ? outcome.hookError.message
+                        : String(outcome.hookError);
+                    const logger = await this.app.container.make('logger');
+                    logger.warn(`dashboardAuth login hook threw; treating as denial. ${message}`);
+                }
+                return ctx.response.status(401).json({ error: outcome.message });
+            }
+            this.writeSessionCookie(ctx, auth, outcome.cookieValue);
+            return ctx.response.status(200).json({ redirectTo: outcome.redirectTo });
+        })
+            .as('durable_dashboard.login.submit');
+        router
+            .get(logoutPath, async (ctx) => {
+            ctx.response.clearCookie(SESSION_COOKIE_NAME, { path: '/' });
+            return ctx.response.redirect().toPath(loginPath);
+        })
+            .as('durable_dashboard.logout');
+    }
+    /**
+     * Run the guards for a dashboard resource. Composes the existing `authorize` hook (bearer
+     * token/custom) with the optional `dashboardAuth` session guard — BOTH must pass:
+     *
+     * 1. `authorize` fails → `403` (unchanged behavior).
+     * 2. `dashboardAuth` configured AND no valid session → for a `page` request, redirect `302` to
+     *    the login page carrying a sanitized `returnTo`; for an `api` request, a plain `401`.
+     *
+     * When `dashboardAuth` is unconfigured only step 1 runs, so behavior is byte-for-byte unchanged.
+     * Returns `false` (and has already written the response) when the request must short-circuit.
      */
-    async guard(config, ctx) {
+    async enforce(config, ctx, mode) {
         const allowed = await config.authorize(ctx);
         if (!allowed) {
             ctx.response.status(403).json({ error: 'forbidden' });
             return false;
         }
-        return true;
+        const auth = config.dashboardAuth;
+        if (!auth)
+            return true;
+        const session = readSession(auth, this.readSessionCookie(ctx));
+        if (session)
+            return true;
+        if (mode === 'page') {
+            const returnTo = ctx.request.url(true);
+            ctx.response.redirect().withQs('returnTo', returnTo).toPath(`${config.path}/login`);
+            return false;
+        }
+        ctx.response.status(401).json({ error: 'unauthorized' });
+        return false;
+    }
+    /** Read the raw (unencoded) session cookie value, or `undefined` when absent. */
+    readSessionCookie(ctx) {
+        const value = ctx.request.plainCookie(SESSION_COOKIE_NAME, undefined, false);
+        return typeof value === 'string' && value !== '' ? value : undefined;
+    }
+    /**
+     * Write the signed session as an unsigned (`plainCookie`, `encode: false`) cookie — the value
+     * carries its own HMAC signature, so AdonisJS's cookie signing would be redundant double-wrapping.
+     * `HttpOnly` + `SameSite=Lax` (blocks cross-site POSTs carrying the cookie — CSRF coverage) +
+     * `Secure` on https. `Path=/` so it reaches both the UI and API mounts regardless of prefix.
+     */
+    writeSessionCookie(ctx, auth, value) {
+        ctx.response.plainCookie(SESSION_COOKIE_NAME, value, {
+            httpOnly: true,
+            sameSite: 'lax',
+            secure: ctx.request.secure(),
+            path: '/',
+            maxAge: Math.floor(auth.ttlMs / 1000),
+            encode: false,
+        });
     }
 }
 /** Adapt an AdonisJS `HttpContext` to the framework-light {@link ApiRequest}. */

package/dist/providers/dashboard_provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard_provider.js","sourceRoot":"","sources":["../../providers/dashboard_provider.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,gCAAgC,CAAC;AAEpD,OAAO,EAGL,aAAa,GACd,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAIL,SAAS,EACT,MAAM,EACN,MAAM,EACN,QAAQ,EACR,QAAQ,GACT,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAiB;IACd;IAAtB,YAAsB,GAAuB;QAAvB,QAAG,GAAH,GAAG,CAAoB;IAAG,CAAC;IAEjD,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAAG,aAAa,CAC1B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAyB,mBAAmB,EAAE,EAAE,CAAC,CACrE,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO;QAE5B,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAEO,cAAc,CAAC,MAAsC;QAC3D,MAAM,OAAO,GAAG,GAAG,MAAM,CAAC,IAAI,MAAM,CAAC;QAErC,mEAAmE;QACnE,kFAAkF;QAClF,8EAA8E;QAC9E,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;YACrC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,CAAC,CAAC;QAEF,iBAAiB;QACjB,MAAM;aACH,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACzD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;gBAAE,OAAO;YAC7C,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,0BAA0B,CAAC,CAAC;YAChE,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;QACrD,CAAC,CAAC;aACD,EAAE,CAAC,yBAAyB,CAAC,CAAC;QAEjC,YAAY;QACZ,MAAM,IAAI,GAAG,CAAC,OAA2D,EAAE,EAAE;YAC3E,OAAO,KAAK,EAAE,GAAgB,EAAE,EAAE;gBAChC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;oBAAE,OAAO;gBAC7C,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,IAAI,EAAE,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;oBAC9D,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC9D,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,GAAG,CAAC,QAAQ;yBAChB,MAAM,CAAC,GAAG,CAAC;yBACX,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC;gBAChF,CAAC;YACH,CAAC,CAAC;QACJ,CAAC,CAAC;QAEF,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,8BAA8B,CAAC,CAAC;QACjF,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,6BAA6B,CAAC,CAAC;QAClF,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,iBAAiB,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,8BAA8B,CAAC,CAAC;QAC5F,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,kBAAkB,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,+BAA+B,CAAC,CAAC;QAC/F,MAAM;aACH,GAAG,CACF,GAAG,OAAO,SAAS,EACnB,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CACvB;aACA,EAAE,CAAC,0BAA0B,CAAC,CAAC;IACpC,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,KAAK,CAAC,MAAsC,EAAE,GAAgB;QAC1E,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;YACtD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,iFAAiF;AACjF,SAAS,YAAY,CAAC,GAAgB;IACpC,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAA4C;QACxD,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,EAAmD;QACxE,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE;KACzB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"dashboard_provider.js","sourceRoot":"","sources":["../../providers/dashboard_provider.ts"],"names":[],"mappings":"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"}

package/dist/src/base-workflow.d.ts

@@ -0,0 +1,78 @@
+import { WorkflowEngine } from './engine.js';
+import type { StartOptions } from './engine.js';
+import type { WorkflowCtx } from './interfaces.js';
+import type { WorkflowClass, WorkflowInputOf, WorkflowOptions, WorkflowOutputOf } from './workflow-ref.js';
+/**
+ * Options for `BaseWorkflow`'s static `start`/`dispatch`. A superset of {@link StartOptions} (priority,
+ * namespace, tags, searchAttributes) plus an explicit `runId`:
+ * - **Outside** a running workflow, `runId` sets the new run's id; omitted → a fresh `randomUUID()`.
+ * - **Inside** a running workflow, `runId` is the deterministic child id; omitted → the ctx derives a
+ *   replay-stable id from the call position (DO NOT pass a random one — it breaks determinism).
+ */
+export type WorkflowDispatchOptions = {
+    runId?: string | undefined;
+} & StartOptions;
+/**
+ * How `BaseWorkflow`'s OUTSIDE static path locates the {@link WorkflowEngine}. Defaults to resolving
+ * the engine from the AdonisJS container (a module-singleton locator, exactly how a queue `Job`
+ * resolves its manager). Tests (or advanced embeddings) override it with {@link setWorkflowEngineResolver}
+ * to inject a specific engine without booting an application.
+ */
+export type WorkflowEngineResolver = () => WorkflowEngine | Promise<WorkflowEngine>;
+/**
+ * Override how `BaseWorkflow.start`/`dispatch` resolve the engine when called OUTSIDE a running
+ * workflow. Pass a resolver returning the engine to use; pass `undefined` to restore the default
+ * (container lookup). Primarily a testing seam — inject an in-memory engine, then reset in teardown.
+ */
+export declare function setWorkflowEngineResolver(resolver: WorkflowEngineResolver | undefined): void;
+/**
+ * Base class for a durable workflow. Declare the workflow's identity as a
+ * `static workflow = { name, version }` config and implement `run(ctx, input)`:
+ *
+ * ```ts
+ * export default class CheckoutWorkflow extends BaseWorkflow {
+ *   static workflow = { name: 'checkout', version: '1' }
+ *   async run(ctx: WorkflowCtx, order: Order) { … }
+ * }
+ * ```
+ *
+ * The static `workflow` config is resolved through `workflowName()` and registered via
+ * `app/workflows` auto-discovery.
+ *
+ * ## Context-aware dispatch
+ * The statics behave differently depending on whether they're called inside or outside a running
+ * workflow body (detected via the ambient ctx — see {@link getCurrentWorkflowCtx}):
+ *
+ * |            | OUTSIDE (controller/service/script)                      | INSIDE a running workflow body        |
+ * |------------|----------------------------------------------------------|---------------------------------------|
+ * | `.start`   | `engine.start` + `waitForRun` → blocks, returns result   | `ctx.child` → linked child, awaits it |
+ * | `.dispatch`| `engine.start` → fire-and-forget, returns `{ runId }`    | `ctx.startChild` → fire-and-forget    |
+ *
+ * `.start` always means "I want the result"; `.dispatch` always means "fire and forget" — in both
+ * contexts. Inside a workflow, routing through `ctx.child`/`ctx.startChild` (never the engine) is what
+ * keeps the run deterministic and replay-safe.
+ */
+export declare abstract class BaseWorkflow {
+    /**
+     * The workflow's identity + options. Read by `workflowMeta()`/`workflowName()` and by
+     * `app/workflows` auto-discovery. Omit it and the class is not a registrable workflow.
+     */
+    static workflow?: WorkflowOptions;
+    /** The workflow body. `ctx` is the durable context; `input` is the run's typed input. */
+    abstract run(ctx: WorkflowCtx, input: unknown): unknown;
+    /**
+     * Start a run and **wait for its result**. Outside a workflow, enqueues via the engine and blocks
+     * until the run settles, returning its output. Inside a running workflow, starts a **linked child**
+     * (`ctx.child`) — the parent suspends until the child settles — and returns the child's output.
+     */
+    static start<C extends WorkflowClass>(this: C, input: WorkflowInputOf<C>, opts?: WorkflowDispatchOptions): Promise<WorkflowOutputOf<C>>;
+    /**
+     * Start a run **fire-and-forget** and return its `{ runId }` without waiting. Outside a workflow,
+     * enqueues via the engine and returns immediately. Inside a running workflow, kicks off a
+     * fire-and-forget child (`ctx.startChild`) — the parent keeps running — and returns the child id.
+     */
+    static dispatch<C extends WorkflowClass>(this: C, input: WorkflowInputOf<C>, opts?: WorkflowDispatchOptions): Promise<{
+        runId: string;
+    }>;
+}
+//# sourceMappingURL=base-workflow.d.ts.map

package/dist/src/base-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-workflow.d.ts","sourceRoot":"","sources":["../../src/base-workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,eAAe,EACf,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,YAAY,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAIpF;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,SAAS,GAAG,IAAI,CAE5F;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,8BAAsB,YAAY;IAChC;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAElC,yFAAyF;IACzF,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO;IAEvD;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,aAAa,EAClC,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EACzB,IAAI,CAAC,EAAE,uBAAuB,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAwB/B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,aAAa,EACrC,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EACzB,IAAI,CAAC,EAAE,uBAAuB,GAC7B,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAkB9B"}