@nwire/forge 0.7.0

package/dist/__tests__/production-readiness.test.js

@@ -0,0 +1,196 @@
+/**
+ * Production-readiness audit — L4 forge runtime properties teams must
+ * trust before adopting workflows + projections in prod.
+ *
+ * Each test pins a real-world invariant:
+ *
+ *   1. Workflow correlation respects envelope.tenant (no cross-tenant
+ *      saga bleed).
+ *   2. Plugin shutdown error isolation — one bad plugin's shutdown error
+ *      doesn't prevent other plugins from cleaning up.
+ *   3. Projection state is deterministic — replaying the same event log
+ *      against a fresh projection store rebuilds an identical view.
+ *   4. Cascade integrity — when a workflow handler dispatches another
+ *      action, downstream events emit exactly once (not duplicated by
+ *      the parent dispatch's event-publish loop).
+ *
+ * Actor restart durability is verified at the store layer (see
+ * `nwire-store-mongo`, `nwire-store-file`); a round-trip integration
+ * test belongs there, not in this file.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import * as forge from "../foundation.js";
+import { seedEnvelope } from "../foundation.js";
+const { defineAction, defineHandler, defineProjection, defineWorkflow, eventFactory, Runtime, InMemoryActorStore, InMemoryProjectionStore, createApp, definePlugin, } = forge;
+// ─── Shared fixtures ─────────────────────────────────────────────────
+const PaymentFailedDef = defineEvent({
+    name: "billing.payment-failed",
+    schema: z.object({ subscriptionId: z.string(), reason: z.string() }),
+});
+const PaymentFailed = eventFactory(PaymentFailedDef);
+const ChargeAttemptedDef = defineEvent({
+    name: "billing.charge-attempted",
+    schema: z.object({ subscriptionId: z.string() }),
+});
+const ChargeAttempted = eventFactory(ChargeAttemptedDef);
+const chargeSubscription = defineAction({
+    name: "billing.charge",
+    description: "Attempt to charge the subscription.",
+    schema: z.object({ subscriptionId: z.string(), willFail: z.boolean().default(false) }),
+    emits: [ChargeAttemptedDef, PaymentFailedDef],
+});
+const chargeHandler = defineHandler(chargeSubscription, async (input) => {
+    const out = [ChargeAttempted({ subscriptionId: input.subscriptionId })];
+    if (input.willFail) {
+        out.push(PaymentFailed({ subscriptionId: input.subscriptionId, reason: "card-declined" }));
+    }
+    return out;
+});
+// ─── 1. Workflow correlation respects tenant ─────────────────────────
+describe("workflow correlation respects envelope.tenant", () => {
+    it("two tenants with the same subscriptionId have independent saga instances", async () => {
+        const attemptsObservedPerFire = [];
+        const renewal = defineWorkflow("renewal", ({ on, data, assign }) => {
+            on(PaymentFailedDef, async () => {
+                attemptsObservedPerFire.push(data.attempts);
+                await assign({ attempts: data.attempts + 1 });
+            });
+        }, {
+            data: z.object({ subscriptionId: z.string().default(""), attempts: z.number().default(0) }),
+            correlate: (map) => {
+                map(PaymentFailedDef, (e) => e.subscriptionId);
+            },
+        });
+        const runtime = new Runtime({
+            actorStore: new InMemoryActorStore(),
+            projectionStore: new InMemoryProjectionStore(),
+        });
+        runtime.registerHandler(chargeHandler);
+        runtime.registerWorkflow(renewal);
+        await runtime.dispatch(chargeSubscription, { subscriptionId: "sub-1", willFail: true }, seedEnvelope({ tenant: "tlv" }));
+        await runtime.dispatch(chargeSubscription, { subscriptionId: "sub-1", willFail: true }, seedEnvelope({ tenant: "jlm" }));
+        // Both tenants fired the workflow with `attempts === 0` — meaning each
+        // tenant got its OWN fresh saga instance. If they shared a key (sub-1)
+        // across tenants, the second fire would see attempts === 1.
+        //
+        // If this test FAILS, the runtime's workflow correlationKey derivation
+        // is missing the tenant axis — workflows with the same business key
+        // across tenants will collide.
+        expect(attemptsObservedPerFire).toEqual([0, 0]);
+    });
+});
+// ─── 2. Plugin shutdown error isolation ──────────────────────────────
+describe("plugin shutdown error isolation", () => {
+    it("a plugin that throws on shutdown does not block other plugins from shutting down", async () => {
+        const shutdownsAttempted = [];
+        const bad = definePlugin("bad-plugin", {
+            shutdown: async () => {
+                shutdownsAttempted.push("bad");
+                throw new Error("bad-plugin: shutdown failure");
+            },
+        });
+        const good = definePlugin("good-plugin", {
+            shutdown: async () => {
+                shutdownsAttempted.push("good");
+            },
+        });
+        const app = createApp({
+            modules: [],
+            plugins: [good, bad],
+        });
+        await app.start();
+        // app.stop() collects errors but still runs every shutdown step.
+        // It re-throws the first collected error AFTER the sweep — wires
+        // can detect the failure (existing contract from provider.test.ts)
+        // AND every plugin/provider still gets a chance to clean up.
+        await expect(app.stop()).rejects.toThrow(/bad-plugin: shutdown failure/);
+        // Both plugins' shutdown handlers got a chance to run.
+        expect(shutdownsAttempted).toContain("bad");
+        expect(shutdownsAttempted).toContain("good");
+    });
+});
+// ─── 3. Projection rebuild is deterministic ──────────────────────────
+describe("projection rebuild is deterministic (replay = identity)", () => {
+    const BumpedDef = defineEvent({
+        name: "counter.bumped",
+        schema: z.object({ counterId: z.string(), delta: z.number() }),
+    });
+    const totalsProj = defineProjection("totals", {
+        description: "Per-counter totals folded from Bumped events.",
+        listens: [BumpedDef],
+        initial: () => ({ totals: {} }),
+        on: {
+            [BumpedDef.name]: (state, event) => {
+                const e = event;
+                return {
+                    totals: { ...state.totals, [e.counterId]: (state.totals[e.counterId] ?? 0) + e.delta },
+                };
+            },
+        },
+    });
+    it("applying the same event sequence to two fresh projections yields identical state", async () => {
+        const store1 = new InMemoryProjectionStore();
+        const store2 = new InMemoryProjectionStore();
+        const runtime1 = new Runtime({ actorStore: new InMemoryActorStore(), projectionStore: store1 });
+        const runtime2 = new Runtime({ actorStore: new InMemoryActorStore(), projectionStore: store2 });
+        runtime1.registerProjection(totalsProj);
+        runtime2.registerProjection(totalsProj);
+        // Same event sequence to both runtimes.
+        const eventSequence = [
+            { counterId: "a", delta: 1 },
+            { counterId: "b", delta: 2 },
+            { counterId: "a", delta: 5 },
+            { counterId: "c", delta: 10 },
+            { counterId: "a", delta: -3 },
+        ];
+        for (const payload of eventSequence) {
+            await runtime1.publish([{ eventName: BumpedDef.name, payload }], seedEnvelope({}));
+            await runtime2.publish([{ eventName: BumpedDef.name, payload }], seedEnvelope({}));
+        }
+        const proj1 = await store1.load("totals", "");
+        const proj2 = await store2.load("totals", "");
+        expect(proj1).toEqual(proj2);
+        expect(proj1?.totals).toEqual({ a: 3, b: 2, c: 10 });
+    });
+});
+// ─── 4. Cascade integrity — no double-emit ───────────────────────────
+describe("cascade integrity — handler-initiated dispatch emits each event exactly once", () => {
+    it("workflow sends → cascade fires → events emit once per dispatch (no duplicates)", async () => {
+        const eventCounts = {};
+        const cascade = defineWorkflow("cascade-probe", ({ on, send, data, assign }) => {
+            on(PaymentFailedDef, async (e) => {
+                const attempt = data.attempts;
+                await assign({ attempts: attempt + 1 });
+                if (attempt < 1) {
+                    await send(chargeSubscription, { subscriptionId: e.subscriptionId, willFail: false });
+                }
+            });
+        }, {
+            data: z.object({ subscriptionId: z.string().default(""), attempts: z.number().default(0) }),
+            correlate: (map) => {
+                map(PaymentFailedDef, (e) => e.subscriptionId);
+            },
+        });
+        const runtime = new Runtime({
+            actorStore: new InMemoryActorStore(),
+            projectionStore: new InMemoryProjectionStore(),
+        });
+        runtime.registerHandler(chargeHandler);
+        runtime.registerWorkflow(cascade);
+        runtime.onTelemetry((rec) => {
+            if (rec.kind === "event.published") {
+                eventCounts[rec.event.eventName] = (eventCounts[rec.event.eventName] ?? 0) + 1;
+            }
+        });
+        // Dispatch a failing charge → workflow retries once with a success.
+        //   first  dispatch (willFail=true)  → charge-attempted + payment-failed
+        //   second dispatch (willFail=false) → charge-attempted only
+        // Total: charge-attempted ×2, payment-failed ×1.
+        await runtime.dispatch(chargeSubscription, { subscriptionId: "sub-cascade", willFail: true });
+        expect(eventCounts["billing.charge-attempted"]).toBe(2);
+        expect(eventCounts["billing.payment-failed"]).toBe(1);
+    });
+});
+//# sourceMappingURL=production-readiness.test.js.map

package/dist/__tests__/production-readiness.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-readiness.test.js","sourceRoot":"","sources":["../../src/__tests__/production-readiness.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/provider.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `defineProvider` — bootable dependencies registered on the container
+ * during `app.start()`, shut down in reverse order during `app.stop()`.
+ */
+export {};
+//# sourceMappingURL=provider.test.d.ts.map

package/dist/__tests__/provider.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/provider.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/__tests__/provider.test.js

@@ -0,0 +1,122 @@
+/**
+ * `defineProvider` — bootable dependencies registered on the container
+ * during `app.start()`, shut down in reverse order during `app.stop()`.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineProvider, defineAction, defineModule, createApp } from "../foundation.js";
+describe("defineProvider", () => {
+    it("boots providers in declaration order and registers them on the container", async () => {
+        const bootOrder = [];
+        const dbProvider = defineProvider("database", {
+            boot: async () => {
+                bootOrder.push("database");
+                return { tag: "db-pool" };
+            },
+        });
+        const redisProvider = defineProvider("redis", {
+            boot: async () => {
+                bootOrder.push("redis");
+                return { tag: "redis-client" };
+            },
+        });
+        const app = createApp({
+            modules: [],
+            providers: [dbProvider, redisProvider],
+        });
+        await app.start();
+        expect(bootOrder).toEqual(["database", "redis"]);
+        const db = app.runtime.getContainer().resolve("database");
+        const redis = app.runtime.getContainer().resolve("redis");
+        expect(db.tag).toBe("db-pool");
+        expect(redis.tag).toBe("redis-client");
+        await app.stop();
+    });
+    it("shuts down providers in reverse boot order", async () => {
+        const shutdownOrder = [];
+        const a = defineProvider("a", {
+            boot: async () => "a-val",
+            shutdown: async () => {
+                shutdownOrder.push("a");
+            },
+        });
+        const b = defineProvider("b", {
+            boot: async () => "b-val",
+            shutdown: async () => {
+                shutdownOrder.push("b");
+            },
+        });
+        const c = defineProvider("c", {
+            boot: async () => "c-val",
+            shutdown: async () => {
+                shutdownOrder.push("c");
+            },
+        });
+        const app = createApp({ modules: [], providers: [a, b, c] });
+        await app.start();
+        await app.stop();
+        expect(shutdownOrder).toEqual(["c", "b", "a"]);
+    });
+    it("a handler can resolve a provider via ctx.resolve", async () => {
+        const counterProvider = defineProvider("counter", {
+            boot: async () => {
+                const counter = {
+                    value: 0,
+                    incr() {
+                        counter.value++;
+                    },
+                };
+                return counter;
+            },
+        });
+        let observed = -1;
+        const bump = defineAction({
+            name: "bump",
+            schema: z.object({}),
+            handler: async (_input, ctx) => {
+                const counter = ctx.resolve("counter");
+                counter.incr();
+                observed = counter.value;
+                return undefined;
+            },
+        });
+        const app = createApp({
+            modules: [defineModule("m", { actions: [bump] })],
+            providers: [counterProvider],
+        });
+        await app.start();
+        await app.runtime.dispatch(bump, {});
+        await app.runtime.dispatch(bump, {});
+        expect(observed).toBe(2);
+        await app.stop();
+    });
+    it("shutdown errors propagate (so wires can detect stuck shutdowns)", async () => {
+        const p = defineProvider("flaky", {
+            boot: async () => "ok",
+            shutdown: async () => {
+                throw new Error("shutdown failed");
+            },
+        });
+        const app = createApp({ modules: [], providers: [p] });
+        await app.start();
+        await expect(app.stop()).rejects.toThrow(/shutdown failed/);
+    });
+    it("healthCheck is a no-op invocation (smoke — the framework just stores the function)", async () => {
+        const checks = [];
+        const p = defineProvider("hc", {
+            boot: async () => "ok",
+            healthCheck: async () => {
+                checks.push("checked");
+            },
+        });
+        const app = createApp({ modules: [], providers: [p] });
+        await app.start();
+        // Health-check invocation API will land with the CLI inspector;
+        // for now confirm the provider def carries the function.
+        expect(typeof p.healthCheck).toBe("function");
+        await p.healthCheck("ok");
+        expect(checks).toEqual(["checked"]);
+        await app.stop();
+    });
+});
+//# sourceMappingURL=provider.test.js.map

package/dist/__tests__/provider.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.test.js","sourceRoot":"","sources":["../../src/__tests__/provider.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/public-marker.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `.public()` marker — verify it's chainable, returns a clone (doesn't
+ * mutate the original), and the `$public` flag is non-enumerable so it
+ * doesn't pollute JSON output.
+ */
+export {};
+//# sourceMappingURL=public-marker.test.d.ts.map

package/dist/__tests__/public-marker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-marker.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/public-marker.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/__tests__/public-marker.test.js

@@ -0,0 +1,54 @@
+/**
+ * `.public()` marker — verify it's chainable, returns a clone (doesn't
+ * mutate the original), and the `$public` flag is non-enumerable so it
+ * doesn't pollute JSON output.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import { defineAction } from "../define-action.js";
+import { defineWorkflow } from "../define-workflow.js";
+import { isPublic } from "../public-marker.js";
+const CarWasWashed = defineEvent({
+    name: "stations.car-was-washed",
+    schema: z.object({ stationId: z.string() }),
+});
+const recordWash = defineAction({
+    name: "stations.record-wash",
+    schema: z.object({ stationId: z.string() }),
+});
+describe(".public() marker", () => {
+    it("action.public() returns a clone marked $public", () => {
+        const original = recordWash;
+        const exposed = original.public();
+        expect(isPublic(original)).toBe(false);
+        expect(isPublic(exposed)).toBe(true);
+        // Same routing identity — same name, same schema.
+        expect(exposed.name).toBe(original.name);
+        expect(exposed.schema).toBe(original.schema);
+    });
+    it("event.public() returns a callable clone with $public", () => {
+        const exposed = CarWasWashed.public();
+        expect(isPublic(CarWasWashed)).toBe(false);
+        expect(isPublic(exposed)).toBe(true);
+        // Still callable like the original.
+        const msg = exposed({ stationId: "s1" });
+        expect(msg.eventName).toBe("stations.car-was-washed");
+        expect(msg.payload).toEqual({ stationId: "s1" });
+    });
+    it("workflow.public() works for cross-module visibility", () => {
+        const wf = defineWorkflow("audit.on-wash", ({ on }) => {
+            on(CarWasWashed, async () => { });
+        });
+        const exposed = wf.public();
+        expect(isPublic(wf)).toBe(false);
+        expect(isPublic(exposed)).toBe(true);
+        expect(exposed.name).toBe("audit.on-wash");
+    });
+    it("$public is non-enumerable (JSON.stringify ignores it)", () => {
+        const exposed = recordWash.public();
+        const json = JSON.parse(JSON.stringify(exposed));
+        expect(json.$public).toBeUndefined();
+    });
+});
+//# sourceMappingURL=public-marker.test.js.map

package/dist/__tests__/public-marker.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-marker.test.js","sourceRoot":"","sources":["../../src/__tests__/public-marker.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/retry-dlq.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Retry / DLQ contract — handler throws are retried per `RetryPolicy`, then
+ * dead-lettered to the configured `DeadLetterSink` after `max + 1` attempts.
+ */
+export {};
+//# sourceMappingURL=retry-dlq.test.d.ts.map

package/dist/__tests__/retry-dlq.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-dlq.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/retry-dlq.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/__tests__/retry-dlq.test.js

@@ -0,0 +1,68 @@
+/**
+ * Retry / DLQ contract — handler throws are retried per `RetryPolicy`, then
+ * dead-lettered to the configured `DeadLetterSink` after `max + 1` attempts.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import * as forge from "../foundation.js";
+const { defineAction, defineHandler, Runtime, InMemoryDeadLetterSink } = forge;
+describe("retry + DLQ", () => {
+    it("a handler that throws is retried per RetryPolicy and succeeds on a later attempt", async () => {
+        const flakyAction = defineAction({
+            name: "flaky",
+            schema: z.object({}),
+            retry: { max: 2, backoff: "fixed", baseDelayMs: 1 },
+        });
+        let calls = 0;
+        const handler = defineHandler(flakyAction, async () => {
+            calls++;
+            if (calls < 3)
+                throw new Error(`flake ${calls}`);
+            return undefined;
+        });
+        const runtime = new Runtime();
+        runtime.registerHandler(handler);
+        await runtime.dispatch(flakyAction, {});
+        expect(calls).toBe(3);
+        const dlq = await runtime.getDeadLetterSink().list();
+        expect(dlq).toHaveLength(0);
+    });
+    it("a handler that throws on every attempt dead-letters and re-raises", async () => {
+        const dlq = new InMemoryDeadLetterSink();
+        const broken = defineAction({
+            name: "broken",
+            schema: z.object({ id: z.string() }),
+            retry: { max: 2, backoff: "fixed", baseDelayMs: 1 },
+        });
+        const handler = defineHandler(broken, async () => {
+            throw new Error("always fails");
+        });
+        const runtime = new Runtime({ deadLetterSink: dlq });
+        runtime.registerHandler(handler);
+        await expect(runtime.dispatch(broken, { id: "x-1" })).rejects.toThrow(/always fails/);
+        const entries = await dlq.list();
+        expect(entries).toHaveLength(1);
+        expect(entries[0]?.actionName).toBe("broken");
+        expect(entries[0]?.attempts).toBe(3);
+        expect(entries[0]?.lastError.message).toBe("always fails");
+        expect((entries[0]?.input).id).toBe("x-1");
+    });
+    it("an action with no retry policy fails immediately on first throw", async () => {
+        const dlq = new InMemoryDeadLetterSink();
+        const action = defineAction({
+            name: "noretry",
+            schema: z.object({}),
+            // no retry → maxAttempts = 1
+        });
+        const handler = defineHandler(action, async () => {
+            throw new Error("boom");
+        });
+        const runtime = new Runtime({ deadLetterSink: dlq });
+        runtime.registerHandler(handler);
+        await expect(runtime.dispatch(action, {})).rejects.toThrow(/boom/);
+        const entries = await dlq.list();
+        expect(entries).toHaveLength(1);
+        expect(entries[0]?.attempts).toBe(1);
+    });
+});
+//# sourceMappingURL=retry-dlq.test.js.map

package/dist/__tests__/retry-dlq.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-dlq.test.js","sourceRoot":"","sources":["../../src/__tests__/retry-dlq.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/validate.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * validate(input, [preds]) — invariant helper.
+ */
+export {};
+//# sourceMappingURL=validate.test.d.ts.map

package/dist/__tests__/validate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/validate.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/validate.test.js

@@ -0,0 +1,53 @@
+/**
+ * validate(input, [preds]) — invariant helper.
+ */
+import { describe, it, expect } from "vitest";
+import { InvariantError, validate, isInvariantError } from "../validate.js";
+describe("validate", () => {
+    const hasName = (input) => (input.name?.length ?? 0) > 0 || "Name required";
+    const hasEmail = (input) => (input.email?.includes("@") ?? false) || "Email must contain @";
+    it("passes silently when all invariants hold", () => {
+        expect(() => validate({ name: "Alice", email: "alice@example.com" }, [hasName, hasEmail])).not.toThrow();
+    });
+    it("throws InvariantError with the failing message", () => {
+        try {
+            validate({ name: "", email: "alice@example.com" }, [hasName, hasEmail]);
+            expect.fail("should have thrown");
+        }
+        catch (e) {
+            expect(isInvariantError(e)).toBe(true);
+            expect(e.failures).toEqual(["Name required"]);
+        }
+    });
+    it("aggregates every failure into one throw", () => {
+        try {
+            validate({ name: "", email: "not-an-email" }, [hasName, hasEmail]);
+            expect.fail("should have thrown");
+        }
+        catch (e) {
+            expect(isInvariantError(e)).toBe(true);
+            expect(e.failures).toEqual(["Name required", "Email must contain @"]);
+            expect(e.message).toContain("Name required");
+            expect(e.message).toContain("Email must contain @");
+        }
+    });
+    it("predicates can read actor state via the second arg", () => {
+        const isModerator = (_input, s) => s.isModerator || "Must be moderator";
+        expect(() => validate({}, [isModerator], { isModerator: true })).not.toThrow();
+        expect(() => validate({}, [isModerator], { isModerator: false })).toThrow(InvariantError);
+    });
+    it("supports an empty predicate list (no-op)", () => {
+        expect(() => validate({ foo: 1 }, [])).not.toThrow();
+    });
+    it("falls back to a generic message when a predicate returns non-string falsy", () => {
+        const badPred = () => false;
+        try {
+            validate({}, [badPred]);
+            expect.fail("should have thrown");
+        }
+        catch (e) {
+            expect(e.failures).toEqual(["invariant failed"]);
+        }
+    });
+});
+//# sourceMappingURL=validate.test.js.map

package/dist/__tests__/validate.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.test.js","sourceRoot":"","sources":["../../src/__tests__/validate.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/workflow-saga.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stateful (saga) workflows — verify the closure-based state-machine
+ * runtime fires entry effects, transitions on handler return, persists
+ * data across events, and emits `complete` on final states.
+ */
+export {};
+//# sourceMappingURL=workflow-saga.test.d.ts.map

package/dist/__tests__/workflow-saga.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-saga.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/workflow-saga.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}