@nwire/forge 0.7.0

package/dist/__tests__/multi-tenancy.test.js

@@ -0,0 +1,122 @@
+/**
+ * Multi-tenancy contract — same actor key in two tenants stays fully isolated.
+ *
+ * The envelope's `tenant` field flows through every store operation. Two
+ * tenants can submit, transition, and read with the same id without
+ * leakage. Cross-tenant scans require explicit code (the timer scheduler
+ * does this; nothing else should).
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import * as forge from "../foundation.js";
+import { seedEnvelope } from "../foundation.js";
+const { defineAction, defineActor, defineHandler, defineProjection, defineQuery, eventFactory, Runtime, InMemoryActorStore, InMemoryProjectionStore, } = forge;
+const TodoCreatedEventDef = defineEvent({
+    name: "todos.created",
+    schema: z.object({
+        todoId: z.string(),
+        title: z.string(),
+    }),
+});
+const TodoCreated = eventFactory(TodoCreatedEventDef);
+const TodoActorData = z.object({
+    todoId: z.string(),
+    title: z.string().optional(),
+    status: z.enum(["open", "completed"]).optional(),
+});
+const Todo = defineActor("todo", {
+    schema: TodoActorData,
+    key: "todoId",
+    initial: "open",
+    states: {
+        open: {
+            on: {
+                [TodoCreated.name]: {
+                    assign: (_, event) => {
+                        const e = event;
+                        return { todoId: e.todoId, title: e.title, status: "open" };
+                    },
+                },
+            },
+        },
+        completed: { final: true },
+    },
+});
+const createTodo = defineAction({
+    name: "todos.create",
+    schema: z.object({ todoId: z.string(), title: z.string() }),
+});
+const createTodoHandler = defineHandler(createTodo, async (input) => TodoCreated({ todoId: input.todoId, title: input.title }));
+const TodosByOwner = defineProjection("todos-by-owner", {
+    listens: [TodoCreatedEventDef],
+    initial: () => ({}),
+    on: {
+        [TodoCreatedEventDef.name]: (state, event) => {
+            const e = event;
+            return { ...state, [e.todoId]: { todoId: e.todoId, title: e.title } };
+        },
+    },
+});
+const todosByOwner = defineQuery(TodosByOwner, {
+    name: "todos.by-owner",
+    schema: z.object({}),
+    execute: (state) => Object.values(state),
+});
+describe("multi-tenancy — actor + projection scoping by envelope.tenant", () => {
+    let runtime;
+    let actorStore;
+    let projectionStore;
+    beforeEach(() => {
+        actorStore = new InMemoryActorStore();
+        projectionStore = new InMemoryProjectionStore();
+        runtime = new Runtime({ actorStore, projectionStore });
+        runtime.registerActor(Todo);
+        runtime.registerHandler(createTodoHandler);
+        runtime.registerProjection(TodosByOwner);
+        runtime.registerQuery(todosByOwner);
+    });
+    it("the same todoId in two tenants creates two independent actor instances", async () => {
+        await runtime.dispatch(createTodo, { todoId: "t-1", title: "Avi: read aleph" }, seedEnvelope({ tenant: "school-tlv" }));
+        await runtime.dispatch(createTodo, { todoId: "t-1", title: "Maya: read bet" }, seedEnvelope({ tenant: "school-jlm" }));
+        const tlv = await actorStore.load("todo", "t-1", "school-tlv");
+        const jlm = await actorStore.load("todo", "t-1", "school-jlm");
+        expect(tlv).not.toBeNull();
+        expect(jlm).not.toBeNull();
+        expect((tlv?.data).title).toBe("Avi: read aleph");
+        expect((jlm?.data).title).toBe("Maya: read bet");
+        // The default scope ('') sees nothing — explicit tenancy required.
+        const def = await actorStore.load("todo", "t-1");
+        expect(def).toBeNull();
+    });
+    it("queries scope to the envelope's tenant — no cross-tenant projection read", async () => {
+        await runtime.dispatch(createTodo, { todoId: "t-tlv-1", title: "Avi A" }, seedEnvelope({ tenant: "school-tlv" }));
+        await runtime.dispatch(createTodo, { todoId: "t-tlv-2", title: "Avi B" }, seedEnvelope({ tenant: "school-tlv" }));
+        await runtime.dispatch(createTodo, { todoId: "t-jlm-1", title: "Maya" }, seedEnvelope({ tenant: "school-jlm" }));
+        const tlv = await runtime.query("todos.by-owner", {}, "school-tlv");
+        const jlm = await runtime.query("todos.by-owner", {}, "school-jlm");
+        expect(tlv).toHaveLength(2);
+        expect(tlv.map((t) => t.title).sort()).toEqual(["Avi A", "Avi B"]);
+        expect(jlm).toHaveLength(1);
+        expect(jlm[0]?.title).toBe("Maya");
+    });
+    it("listInstances with no tenant returns instances across all tenants", async () => {
+        await runtime.dispatch(createTodo, { todoId: "t-1", title: "A" }, seedEnvelope({ tenant: "school-tlv" }));
+        await runtime.dispatch(createTodo, { todoId: "t-2", title: "B" }, seedEnvelope({ tenant: "school-jlm" }));
+        const all = await actorStore.listInstances("todo");
+        const scoped = await actorStore.listInstances("todo", "school-tlv");
+        expect(all).toHaveLength(2);
+        expect(scoped).toHaveLength(1);
+        expect(scoped[0]?.tenant).toBe("school-tlv");
+    });
+    it("a missing tenant on dispatch falls back to the global scope", async () => {
+        // No tenant on envelope → goes to '' scope.
+        await runtime.dispatch(createTodo, { todoId: "t-1", title: "global" });
+        const global = await actorStore.load("todo", "t-1");
+        expect(global).not.toBeNull();
+        expect(global?.tenant).toBe("");
+        const tlv = await actorStore.load("todo", "t-1", "school-tlv");
+        expect(tlv).toBeNull();
+    });
+});
+//# sourceMappingURL=multi-tenancy.test.js.map

package/dist/__tests__/multi-tenancy.test.js.map

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

package/dist/__tests__/needs-topology.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `needs.events` is topology-flexible:
+ *   - If a producer is in the SAME app: in-process apply (no bus needed).
+ *   - If a producer is in ANOTHER app and a bus is configured: auto-subscribe
+ *     via the bus, route received messages through `applyExternalEvent`.
+ *
+ * Same module declaration works in monolith and split topologies. This is
+ * what unblocks the 8-services-× -21-bounded-contexts shape.
+ */
+export {};
+//# sourceMappingURL=needs-topology.test.d.ts.map

package/dist/__tests__/needs-topology.test.d.ts.map

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

package/dist/__tests__/needs-topology.test.js

@@ -0,0 +1,82 @@
+/**
+ * `needs.events` is topology-flexible:
+ *   - If a producer is in the SAME app: in-process apply (no bus needed).
+ *   - If a producer is in ANOTHER app and a bus is configured: auto-subscribe
+ *     via the bus, route received messages through `applyExternalEvent`.
+ *
+ * Same module declaration works in monolith and split topologies. This is
+ * what unblocks the 8-services-× -21-bounded-contexts shape.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import { InMemoryEventBus } from "@nwire/bus";
+import { defineAction, defineModule, createApp, eventFactory, defineWorkflow } from "../foundation.js";
+const StudentEnrolledEvent = defineEvent({
+    name: "roster.student-enrolled",
+    schema: z.object({ studentId: z.string(), courseId: z.string() }),
+});
+const StudentEnrolled = eventFactory(StudentEnrolledEvent);
+const enrollStudent = defineAction({
+    name: "roster.enroll",
+    schema: z.object({ studentId: z.string(), courseId: z.string() }),
+    handler: async (input) => StudentEnrolled({ studentId: input.studentId, courseId: input.courseId }),
+});
+const rosterModule = defineModule("roster", {
+    actions: [enrollStudent],
+    events: [StudentEnrolledEvent.public()],
+});
+// "lx" module: REACTS to enrollment events. Same declaration, two topologies.
+function makeConsumerModule() {
+    const observed = {};
+    const noticeWorkflow = defineWorkflow("lx.notice-enrollment", ({ on }) => {
+        on(StudentEnrolledEvent, (payload) => {
+            observed.studentId = payload.studentId;
+            observed.courseId = payload.courseId;
+        });
+    });
+    const module = defineModule("lx", {
+        workflows: [noticeWorkflow],
+        needs: { events: [StudentEnrolledEvent] },
+    });
+    return { module, observed };
+}
+describe("needs.events — topology-flexible", () => {
+    it("monolith: roster + lx in one app, no bus → in-process apply", async () => {
+        const { module: lxModule, observed } = makeConsumerModule();
+        const app = createApp({ modules: [rosterModule, lxModule] });
+        await app.runtime.dispatch(enrollStudent, {
+            studentId: "avi",
+            courseId: "hebrew-letters",
+        });
+        expect(observed.studentId).toBe("avi");
+        expect(observed.courseId).toBe("hebrew-letters");
+    });
+    it("split: roster in app A, lx in app B, bus between them → bus-subscribed", async () => {
+        const bus = new InMemoryEventBus();
+        const lmsApp = createApp({
+            modules: [rosterModule],
+            bus,
+            publishToBus: true,
+            appName: "lms",
+        });
+        const { module: lxModule, observed } = makeConsumerModule();
+        const lxApp = createApp({
+            modules: [lxModule],
+            bus,
+            appName: "lx",
+        });
+        await lmsApp.runtime.dispatch(enrollStudent, {
+            studentId: "maya",
+            courseId: "math-101",
+        });
+        expect(observed.studentId).toBe("maya");
+        expect(observed.courseId).toBe("math-101");
+        await bus.stop();
+    });
+    it("lx without a local roster AND without a bus → boot fails with helpful message", () => {
+        const { module: lxModule } = makeConsumerModule();
+        expect(() => createApp({ modules: [lxModule] })).toThrow(/no module in this app provides it and no bus is configured/);
+    });
+});
+//# sourceMappingURL=needs-topology.test.js.map

package/dist/__tests__/needs-topology.test.js.map

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

package/dist/__tests__/plugin-closure.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `definePlugin` closure form — bind / resolve / on / before / after /
+ * middleware / actorHook / boot / shutdown bundled into one builder.
+ *
+ * Verifies:
+ *   - bind() registers a singleton resolvable via container or api.resolve
+ *   - on(FrameworkEvent, ...) wires subscriptions
+ *   - before(action, ...) fires only for that action and can veto
+ *   - after(action, ...) fires only for that action's completion
+ *   - middleware() runs onion-style around dispatch
+ *   - boot() / shutdown() fire in order / reverse-order
+ *   - object form still works (back-compat)
+ */
+export {};
+//# sourceMappingURL=plugin-closure.test.d.ts.map

package/dist/__tests__/plugin-closure.test.d.ts.map

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

package/dist/__tests__/plugin-closure.test.js

@@ -0,0 +1,140 @@
+/**
+ * `definePlugin` closure form — bind / resolve / on / before / after /
+ * middleware / actorHook / boot / shutdown bundled into one builder.
+ *
+ * Verifies:
+ *   - bind() registers a singleton resolvable via container or api.resolve
+ *   - on(FrameworkEvent, ...) wires subscriptions
+ *   - before(action, ...) fires only for that action and can veto
+ *   - after(action, ...) fires only for that action's completion
+ *   - middleware() runs onion-style around dispatch
+ *   - boot() / shutdown() fire in order / reverse-order
+ *   - object form still works (back-compat)
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { ActionDispatching, createApp, defineAction, defineHandler, defineModule, definePlugin, } from "../foundation.js";
+const Ping = defineAction({
+    name: "test/ping",
+    schema: z.object({ n: z.number() }),
+});
+const handler = defineHandler(Ping, async () => undefined);
+const mod = defineModule("test", {
+    actions: [Ping],
+    handlers: [handler],
+});
+describe("definePlugin (closure form)", () => {
+    it("bind + resolve registers and reads back a singleton", async () => {
+        class Audit {
+            messages = [];
+        }
+        let resolved;
+        const plugin = definePlugin("audit", ({ bind, resolve, boot }) => {
+            bind("audit", () => new Audit());
+            boot(() => {
+                resolved = resolve("audit");
+            });
+        });
+        const app = createApp({ modules: [mod], plugins: [plugin] });
+        await app.start();
+        expect(resolved).toBeInstanceOf(Audit);
+        await app.stop();
+    });
+    it("after(action) fires only for that action, with the result", async () => {
+        const seen = [];
+        const plugin = definePlugin("watcher", ({ after }) => {
+            after("test/ping", (p) => {
+                seen.push({ action: p.action.name, n: p.input.n });
+            });
+            after("test/other", () => {
+                seen.push({ action: "OTHER", n: -1 });
+            });
+        });
+        const app = createApp({ modules: [mod], plugins: [plugin] });
+        await app.start();
+        await app.runtime.dispatch(Ping, { n: 7 });
+        // ActionCompleted is parallel/non-awaited; settle.
+        await new Promise((r) => setImmediate(r));
+        expect(seen).toEqual([{ action: "test/ping", n: 7 }]);
+        await app.stop();
+    });
+    it("before(action) can veto a dispatch by returning false", async () => {
+        const plugin = definePlugin("gate", ({ before }) => {
+            before("test/ping", () => false);
+        });
+        const app = createApp({ modules: [mod], plugins: [plugin] });
+        await app.start();
+        const result = await app.runtime.dispatch(Ping, { n: 1 });
+        expect(result).toBeUndefined();
+        await app.stop();
+    });
+    it("middleware() runs onion-style around dispatch", async () => {
+        const order = [];
+        const plugin = definePlugin("timing", ({ middleware }) => {
+            middleware(async (next) => {
+                order.push("before");
+                const out = await next();
+                order.push("after");
+                return out;
+            });
+        });
+        const app = createApp({ modules: [mod], plugins: [plugin] });
+        await app.start();
+        await app.runtime.dispatch(Ping, { n: 1 });
+        expect(order).toEqual(["before", "after"]);
+        await app.stop();
+    });
+    it("boot/shutdown fire in registration / reverse order", async () => {
+        const order = [];
+        const plugin = definePlugin("ordered", ({ boot, shutdown }) => {
+            boot(() => {
+                order.push("boot-1");
+            });
+            boot(() => {
+                order.push("boot-2");
+            });
+            shutdown(() => {
+                order.push("shutdown-1");
+            });
+            shutdown(() => {
+                order.push("shutdown-2");
+            });
+        });
+        const app = createApp({ modules: [mod], plugins: [plugin] });
+        await app.start();
+        await app.stop();
+        expect(order).toEqual(["boot-1", "boot-2", "shutdown-2", "shutdown-1"]);
+    });
+    it("on(ActionDispatching) sees every action (not just one)", async () => {
+        const seen = [];
+        const plugin = definePlugin("watch-all", ({ on }) => {
+            on(ActionDispatching, (p) => {
+                seen.push(p.action.name);
+            });
+        });
+        const app = createApp({ modules: [mod], plugins: [plugin] });
+        await app.start();
+        await app.runtime.dispatch(Ping, { n: 1 });
+        expect(seen).toEqual(["test/ping"]);
+        await app.stop();
+    });
+    it("object form still works (back-compat)", async () => {
+        let registered = false;
+        const plugin = definePlugin("legacy", {
+            register: () => {
+                registered = true;
+            },
+        });
+        const app = createApp({ modules: [], plugins: [plugin] });
+        expect(registered).toBe(true); // register runs at createApp construction
+        await app.start();
+        await app.stop();
+    });
+    it("rejects an async setup function — must use api.boot for async work", () => {
+        const plugin = definePlugin("bad", async () => {
+            await Promise.resolve();
+        });
+        expect(() => createApp({ modules: [], plugins: [plugin] })).toThrow(/synchronous/i);
+    });
+});
+//# sourceMappingURL=plugin-closure.test.js.map

package/dist/__tests__/plugin-closure.test.js.map

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

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

@@ -0,0 +1,10 @@
+/**
+ * `definePlugin` — the only extension primitive.
+ *
+ * Plugins compose alongside modules. They bind values on the container,
+ * subscribe to framework events, contribute middleware + actor hooks, and
+ * own boot/shutdown lifecycle. Both authoring forms (object + closure)
+ * route through the same registration loop.
+ */
+export {};
+//# sourceMappingURL=plugin.test.d.ts.map

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

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

package/dist/__tests__/plugin.test.js

@@ -0,0 +1,225 @@
+/**
+ * `definePlugin` — the only extension primitive.
+ *
+ * Plugins compose alongside modules. They bind values on the container,
+ * subscribe to framework events, contribute middleware + actor hooks, and
+ * own boot/shutdown lifecycle. Both authoring forms (object + closure)
+ * route through the same registration loop.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import { definePlugin, defineAction, defineActor, defineModule, createApp, eventFactory, } from "../foundation.js";
+describe("definePlugin", () => {
+    it("object-form register/boot/shutdown lifecycle fires in correct order", async () => {
+        const order = [];
+        const plugin = definePlugin("audit", {
+            register: (container) => {
+                order.push("plugin.register");
+                container.register("auditLog", { tag: "audit" });
+            },
+            boot: async () => {
+                order.push("plugin.boot");
+            },
+            shutdown: async () => {
+                order.push("plugin.shutdown");
+            },
+        });
+        const app = createApp({ modules: [], plugins: [plugin] });
+        await app.start();
+        await app.stop();
+        expect(order).toEqual(["plugin.register", "plugin.boot", "plugin.shutdown"]);
+    });
+    it("closure-form: bind / boot / shutdown / resolve compose end-to-end", async () => {
+        const counterPlugin = definePlugin("counter", ({ bind }) => {
+            bind("counter", () => {
+                const counter = {
+                    value: 0,
+                    incr() {
+                        counter.value += 1;
+                    },
+                };
+                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] })],
+            plugins: [counterPlugin],
+        });
+        await app.start();
+        await app.runtime.dispatch(bump, {});
+        await app.runtime.dispatch(bump, {});
+        expect(observed).toBe(2);
+        await app.stop();
+    });
+    it("middleware composes around dispatch", async () => {
+        const trace = [];
+        const action = defineAction({
+            name: "ping",
+            schema: z.object({}),
+            handler: async () => {
+                trace.push("handler");
+                return undefined;
+            },
+        });
+        const plugin = definePlugin("trace", {
+            middleware: [
+                async (next) => {
+                    trace.push("mw:before");
+                    const r = await next();
+                    trace.push("mw:after");
+                    return r;
+                },
+            ],
+        });
+        const app = createApp({
+            modules: [defineModule("m", { actions: [action] })],
+            plugins: [plugin],
+        });
+        await app.start();
+        await app.runtime.dispatch(action, {});
+        await app.stop();
+        expect(trace).toEqual(["mw:before", "handler", "mw:after"]);
+    });
+    it("actorHooks.afterTransition fires AFTER actor state change persists", async () => {
+        const TickSchema = z.object({ counter: z.number() });
+        const TickedEventDef = defineEvent({
+            name: "tick.ticked",
+            schema: z.object({ tickId: z.string() }),
+        });
+        const Ticked = eventFactory(TickedEventDef);
+        const Tick = defineActor("tick", {
+            schema: TickSchema,
+            key: "tickId",
+            initial: "fresh",
+            states: {
+                fresh: {
+                    on: {
+                        [TickedEventDef.name]: {
+                            target: "done",
+                            assign: (state) => ({ counter: (state.counter ?? 0) + 1 }),
+                        },
+                    },
+                },
+                done: { final: true },
+            },
+        });
+        const tickIt = defineAction({
+            name: "tick.it",
+            schema: z.object({ tickId: z.string() }),
+            handler: async (input) => Ticked({ tickId: input.tickId }),
+        });
+        const observed = [];
+        const observer = definePlugin("observer", {
+            actorHooks: {
+                afterTransition: (_actor, _key, fromState, toState) => {
+                    observed.push({ from: fromState, to: toState });
+                },
+            },
+        });
+        const app = createApp({
+            modules: [
+                defineModule("m", {
+                    actions: [tickIt],
+                    actors: [Tick],
+                    events: [TickedEventDef],
+                }),
+            ],
+            plugins: [observer],
+        });
+        await app.start();
+        await app.runtime.dispatch(tickIt, { tickId: "t1" });
+        await app.stop();
+        expect(observed).toEqual([{ from: "fresh", to: "done" }]);
+    });
+    it("plugins boot in declaration order; shutdown in REVERSE", async () => {
+        const order = [];
+        const a = definePlugin("a", {
+            boot: async () => {
+                order.push("a.boot");
+            },
+            shutdown: async () => {
+                order.push("a.shutdown");
+            },
+        });
+        const b = definePlugin("b", {
+            boot: async () => {
+                order.push("b.boot");
+            },
+            shutdown: async () => {
+                order.push("b.shutdown");
+            },
+        });
+        const app = createApp({ modules: [], plugins: [a, b] });
+        await app.start();
+        await app.stop();
+        expect(order).toEqual(["a.boot", "b.boot", "b.shutdown", "a.shutdown"]);
+    });
+    it("shutdown errors propagate (so wires can detect stuck shutdowns)", async () => {
+        const flaky = definePlugin("flaky", {
+            boot: async () => undefined,
+            shutdown: async () => {
+                throw new Error("shutdown failed");
+            },
+        });
+        const app = createApp({ modules: [], plugins: [flaky] });
+        await app.start();
+        await expect(app.stop()).rejects.toThrow(/shutdown failed/);
+    });
+    it("a bad plugin's shutdown does NOT block subsequent plugins", async () => {
+        const order = [];
+        const bad = definePlugin("bad", {
+            shutdown: async () => {
+                order.push("bad.attempted");
+                throw new Error("boom");
+            },
+        });
+        const good = definePlugin("good", {
+            shutdown: async () => {
+                order.push("good.shutdown");
+            },
+        });
+        // Declaration order: bad → good. Reverse shutdown: good → bad. Good
+        // must run before bad's failure is surfaced.
+        const app = createApp({ modules: [], plugins: [bad, good] });
+        await app.start();
+        await expect(app.stop()).rejects.toThrow(/boom/);
+        expect(order).toEqual(["good.shutdown", "bad.attempted"]);
+    });
+    it("plugin can register values on the container at register time", async () => {
+        const auditPlugin = definePlugin("audit", {
+            register: (container) => {
+                container.register("auditLogger", { tag: "audit" });
+            },
+        });
+        let seen = null;
+        const action = defineAction({
+            name: "audited",
+            schema: z.object({}),
+            handler: async (_input, ctx) => {
+                seen = ctx.resolve("auditLogger");
+                return undefined;
+            },
+        });
+        const app = createApp({
+            modules: [defineModule("m", { actions: [action] })],
+            plugins: [auditPlugin],
+        });
+        await app.start();
+        await app.runtime.dispatch(action, {});
+        expect(seen).toEqual({ tag: "audit" });
+        await app.stop();
+    });
+});
+//# sourceMappingURL=plugin.test.js.map