@nwire/forge 0.7.0

package/dist/__tests__/inline-handler.test.js.map

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

package/dist/__tests__/lifecycle-logging.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lifecycle events flow into the telemetry stream and through to the dev
+ * logger. Every framework-event firing becomes a `kind: "lifecycle"`
+ * record with a `namespace` derived from the event's dotted name
+ * (`nwire.app.booting` → `namespace: "app"`).
+ *
+ * This is the substrate behind `nwire dev`'s lifecycle logs in the CLI
+ * console + Studio Live's "Lifecycle" panel — both subscribe to the
+ * same telemetry stream the dev logger writes to.
+ */
+export {};
+//# sourceMappingURL=lifecycle-logging.test.d.ts.map

package/dist/__tests__/lifecycle-logging.test.d.ts.map

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

package/dist/__tests__/lifecycle-logging.test.js

@@ -0,0 +1,112 @@
+/**
+ * Lifecycle events flow into the telemetry stream and through to the dev
+ * logger. Every framework-event firing becomes a `kind: "lifecycle"`
+ * record with a `namespace` derived from the event's dotted name
+ * (`nwire.app.booting` → `namespace: "app"`).
+ *
+ * This is the substrate behind `nwire dev`'s lifecycle logs in the CLI
+ * console + Studio Live's "Lifecycle" panel — both subscribe to the
+ * same telemetry stream the dev logger writes to.
+ */
+import { describe, it, expect } from "vitest";
+import { createApp, defineModule, definePlugin } from "../foundation.js";
+import { attachDevLogger, formatTelemetry } from "../dev-logger.js";
+import { AppRegistering } from "../framework-events.js";
+describe("framework events → telemetry → dev logger", () => {
+    it("app start fires PluginRegistered + PluginBooting + PluginBooted + AppBooting + AppBooted as lifecycle records", async () => {
+        const records = [];
+        const app = createApp({
+            modules: [defineModule("m", {})],
+            plugins: [definePlugin("audit", { boot: async () => undefined })],
+        });
+        app.runtime.onTelemetry((r) => {
+            if (r.kind === "lifecycle")
+                records.push(r);
+        });
+        await app.start();
+        await app.stop();
+        const eventNames = records.map((r) => (r.kind === "lifecycle" ? r.event : "")).filter(Boolean);
+        // Every lifecycle event we care about should be present.
+        expect(eventNames).toContain("nwire.plugin.registered");
+        expect(eventNames).toContain("nwire.app.registering");
+        expect(eventNames).toContain("nwire.app.booting");
+        expect(eventNames).toContain("nwire.plugin.booting");
+        expect(eventNames).toContain("nwire.plugin.booted");
+        expect(eventNames).toContain("nwire.app.booted");
+        expect(eventNames).toContain("nwire.app.shutting-down");
+        expect(eventNames).toContain("nwire.plugin.shutting-down");
+        expect(eventNames).toContain("nwire.plugin.shutdown");
+        expect(eventNames).toContain("nwire.app.shutdown");
+    });
+    it("namespace is derived from the second dotted segment", async () => {
+        const records = [];
+        const app = createApp({
+            modules: [defineModule("m", {})],
+            plugins: [definePlugin("audit", {})],
+        });
+        app.runtime.onTelemetry((r) => {
+            if (r.kind === "lifecycle")
+                records.push(r);
+        });
+        await app.start();
+        await app.stop();
+        const namespaces = new Set(records
+            .filter((r) => r.kind === "lifecycle")
+            .map((r) => r.namespace));
+        expect(namespaces.has("app")).toBe(true);
+        expect(namespaces.has("plugin")).toBe(true);
+    });
+    it("dev logger formats lifecycle records with namespace + name", async () => {
+        const lines = [];
+        const app = createApp({
+            modules: [defineModule("m", {})],
+            plugins: [definePlugin("trace", { boot: async () => undefined })],
+            devLogs: false, // disable auto-attach; we'll attach manually with a buffer
+        });
+        attachDevLogger(app.runtime, {
+            write: (line) => lines.push(line),
+        });
+        await app.start();
+        await app.stop();
+        // Multiple lifecycle lines should be present.
+        const lifecycleLines = lines.filter((l) => l.includes("nwire:"));
+        expect(lifecycleLines.length).toBeGreaterThan(5);
+        // Plugin-booted line should include the plugin name (`trace`).
+        const booted = lifecycleLines.find((l) => l.includes("plugin.booted"));
+        expect(booted).toBeTruthy();
+        expect(booted).toContain("trace");
+    });
+    it("formatTelemetry handles lifecycle records standalone", () => {
+        const rec = {
+            kind: "lifecycle",
+            event: "nwire.wire.mounted",
+            namespace: "wire",
+            payload: { transport: "http" },
+            phase: "fired",
+            appName: "test",
+            ts: new Date().toISOString(),
+        };
+        const line = formatTelemetry(rec);
+        expect(line).toContain("nwire:wire");
+        expect(line).toContain("wire.mounted");
+        expect(line).toContain("http");
+    });
+    it("series-bail veto fires lifecycle with phase=prevented", async () => {
+        const records = [];
+        const blocker = definePlugin("blocker", ({ on }) => {
+            on(AppRegistering, () => false);
+        });
+        const app = createApp({
+            modules: [defineModule("m", {})],
+            plugins: [blocker],
+        });
+        app.runtime.onTelemetry((r) => {
+            if (r.kind === "lifecycle")
+                records.push(r);
+        });
+        await expect(app.start()).rejects.toThrow(/Boot prevented/);
+        const prevented = records.find((r) => r.event === "nwire.app.registering");
+        expect(prevented?.phase).toBe("prevented");
+    });
+});
+//# sourceMappingURL=lifecycle-logging.test.js.map

package/dist/__tests__/lifecycle-logging.test.js.map

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

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

@@ -0,0 +1,7 @@
+/**
+ * Dispatch middleware contract — onion-style layers around action dispatch.
+ * Layers run outside the retry loop (one pass per dispatch). Registration
+ * order is execution order: the first `use(m)` is the outermost layer.
+ */
+export {};
+//# sourceMappingURL=middleware.test.d.ts.map

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

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

package/dist/__tests__/middleware.test.js

@@ -0,0 +1,109 @@
+/**
+ * Dispatch middleware contract — onion-style layers around action dispatch.
+ * Layers run outside the retry loop (one pass per dispatch). Registration
+ * order is execution order: the first `use(m)` is the outermost layer.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import * as forge from "../foundation.js";
+const { defineAction, defineHandler, Runtime } = forge;
+describe("runtime middleware", () => {
+    it("wraps the handler call exactly once per dispatch", async () => {
+        const action = defineAction({ name: "mw.simple", schema: z.object({}) });
+        const handler = defineHandler(action, async () => undefined);
+        const calls = [];
+        const runtime = new Runtime();
+        runtime.registerHandler(handler);
+        runtime.use(async (next) => {
+            calls.push("before");
+            const result = await next();
+            calls.push("after");
+            return result;
+        });
+        await runtime.dispatch(action, {});
+        expect(calls).toEqual(["before", "after"]);
+    });
+    it("runs middlewares in registration order (outermost first)", async () => {
+        const action = defineAction({ name: "mw.order", schema: z.object({}) });
+        const handler = defineHandler(action, async () => undefined);
+        const trace = [];
+        const runtime = new Runtime();
+        runtime.registerHandler(handler);
+        runtime.use(async (next) => {
+            trace.push("outer:before");
+            await next();
+            trace.push("outer:after");
+        });
+        runtime.use(async (next) => {
+            trace.push("inner:before");
+            await next();
+            trace.push("inner:after");
+        });
+        await runtime.dispatch(action, {});
+        expect(trace).toEqual(["outer:before", "inner:before", "inner:after", "outer:after"]);
+    });
+    it("middleware can short-circuit without calling next", async () => {
+        const action = defineAction({ name: "mw.shortcircuit", schema: z.object({}) });
+        let handlerRan = false;
+        const handler = defineHandler(action, async () => {
+            handlerRan = true;
+            return undefined;
+        });
+        const runtime = new Runtime();
+        runtime.registerHandler(handler);
+        runtime.use(async () => {
+            // intentionally do not call next()
+            return undefined;
+        });
+        await runtime.dispatch(action, {});
+        expect(handlerRan).toBe(false);
+    });
+    it("middleware sees the action definition, validated input, and envelope-scoped ctx", async () => {
+        const action = defineAction({
+            name: "mw.inspect",
+            schema: z.object({ studentId: z.string() }),
+        });
+        const handler = defineHandler(action, async () => undefined);
+        let seenName = "";
+        let seenInput;
+        let seenTenant;
+        const runtime = new Runtime();
+        runtime.registerHandler(handler);
+        runtime.use(async (next, def, input, ctx) => {
+            seenName = def.name;
+            seenInput = input;
+            seenTenant = ctx.envelope.tenant;
+            return next();
+        });
+        await runtime.dispatch(action, { studentId: "avi-1" });
+        expect(seenName).toBe("mw.inspect");
+        expect(seenInput).toEqual({ studentId: "avi-1" });
+        // dispatch without a parent envelope seeds a fresh one with no tenant
+        expect(seenTenant).toBeUndefined();
+    });
+    it("middleware runs once per dispatch even when the handler retries internally", async () => {
+        const action = defineAction({
+            name: "mw.retry",
+            schema: z.object({}),
+            retry: { max: 2, backoff: "fixed", baseDelayMs: 1 },
+        });
+        let handlerCalls = 0;
+        const handler = defineHandler(action, async () => {
+            handlerCalls++;
+            if (handlerCalls < 3)
+                throw new Error(`flake ${handlerCalls}`);
+            return undefined;
+        });
+        let mwCalls = 0;
+        const runtime = new Runtime();
+        runtime.registerHandler(handler);
+        runtime.use(async (next) => {
+            mwCalls++;
+            return next();
+        });
+        await runtime.dispatch(action, {});
+        expect(handlerCalls).toBe(3);
+        expect(mwCalls).toBe(1);
+    });
+});
+//# sourceMappingURL=middleware.test.js.map

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * Module `needs` — explicit cross-module dep graph validated at createApp.
+ *
+ * Each module's `events: [...]` and `actions: [...]` arrays are its implicit
+ * provides. `needs: { events?, actions? }` lists what this module consumes
+ * from OTHER modules. createApp validates that every need has a provider,
+ * with visibility checks for events.
+ */
+export {};
+//# sourceMappingURL=module-needs.test.d.ts.map

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

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

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

@@ -0,0 +1,77 @@
+/**
+ * Module `needs` — explicit cross-module dep graph validated at createApp.
+ *
+ * Each module's `events: [...]` and `actions: [...]` arrays are its implicit
+ * provides. `needs: { events?, actions? }` lists what this module consumes
+ * from OTHER modules. createApp validates that every need has a provider,
+ * with visibility checks for events.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import { defineAction, defineModule, createApp } from "../foundation.js";
+const PublishedEvent = defineEvent({
+    name: "test.published",
+    schema: z.object({ id: z.string() }),
+});
+const InternalEvent = defineEvent({
+    name: "test.internal",
+    schema: z.object({ id: z.string() }),
+    visibility: "internal",
+});
+const publicAction = defineAction({
+    name: "test.public-action",
+    schema: z.object({}),
+});
+describe("module needs / provides dep graph", () => {
+    it("passes when every needed event/action is provided + .public() by another module", () => {
+        const producer = defineModule("producer", {
+            events: [PublishedEvent.public()],
+            actions: [publicAction.public()],
+        });
+        const consumer = defineModule("consumer", {
+            needs: {
+                events: [PublishedEvent],
+                actions: [publicAction],
+            },
+        });
+        // Should not throw.
+        createApp({ modules: [producer, consumer] });
+    });
+    it("throws when a needed event has no provider and no bus", () => {
+        const consumer = defineModule("consumer", {
+            needs: { events: [PublishedEvent] },
+        });
+        expect(() => createApp({ modules: [consumer] })).toThrow(/needs event "test\.published" but no module in this app provides it and no bus is configured/);
+    });
+    it("throws when a needed action has no provider", () => {
+        const consumer = defineModule("consumer", {
+            needs: { actions: [publicAction] },
+        });
+        expect(() => createApp({ modules: [consumer] })).toThrow(/needs action "test\.public-action" but no module provides it/);
+    });
+    it("throws on self-reference (a module needing its own event)", () => {
+        const selfish = defineModule("selfish", {
+            events: [PublishedEvent.public()],
+            needs: { events: [PublishedEvent] },
+        });
+        expect(() => createApp({ modules: [selfish] })).toThrow(/provides it itself/);
+    });
+    it("throws when a needed event was not marked .public() in its owning module", () => {
+        const producer = defineModule("producer", {
+            events: [InternalEvent], // no .public() → internal
+        });
+        const consumer = defineModule("consumer", {
+            needs: { events: [InternalEvent] },
+        });
+        expect(() => createApp({ modules: [producer, consumer] })).toThrow(/marks it as visibility: 'internal'/);
+    });
+    it("a module without `needs` is unaffected (back-compat)", () => {
+        const lonely = defineModule("lonely", {
+            events: [PublishedEvent],
+        });
+        // Should not throw — no needs declared.
+        createApp({ modules: [lonely] });
+    });
+});
+//# sourceMappingURL=module-needs.test.js.map

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

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

package/dist/__tests__/module-topo-sort.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `createApp` topologically sorts modules by `needs.events` /
+ * `needs.actions` before registering them with the runtime. Producers
+ * register before consumers regardless of declaration order. Cycles
+ * throw a readable error naming every module on the loop.
+ *
+ * Registration order is observable through `runtime.frameworkEvents`
+ * (PluginRegistered fires in topo order for plugins, and we use the
+ * module loop's order via the same lens here by registering a probe
+ * plugin that records each module's name as it's seen — but for a
+ * leaner test we just construct two modules and assert no throw +
+ * cycle detection.
+ */
+export {};
+//# sourceMappingURL=module-topo-sort.test.d.ts.map

package/dist/__tests__/module-topo-sort.test.d.ts.map

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

package/dist/__tests__/module-topo-sort.test.js

@@ -0,0 +1,105 @@
+/**
+ * `createApp` topologically sorts modules by `needs.events` /
+ * `needs.actions` before registering them with the runtime. Producers
+ * register before consumers regardless of declaration order. Cycles
+ * throw a readable error naming every module on the loop.
+ *
+ * Registration order is observable through `runtime.frameworkEvents`
+ * (PluginRegistered fires in topo order for plugins, and we use the
+ * module loop's order via the same lens here by registering a probe
+ * plugin that records each module's name as it's seen — but for a
+ * leaner test we just construct two modules and assert no throw +
+ * cycle detection.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import { defineAction, defineModule, createApp } from "../foundation.js";
+describe("createApp topological module sort", () => {
+    it("producer-first order is preserved when declared producer-first", async () => {
+        const SubmittedEvent = defineEvent({
+            name: "submissions.submitted",
+            schema: z.object({ submissionId: z.string() }),
+        }).public();
+        const submitAction = defineAction({
+            name: "submissions.submit",
+            schema: z.object({ id: z.string() }),
+            handler: async () => undefined,
+        });
+        const submissions = defineModule("submissions", {
+            events: [SubmittedEvent],
+            actions: [submitAction],
+        });
+        const mastery = defineModule("mastery", {
+            needs: { events: [SubmittedEvent] },
+        });
+        const app = createApp({ modules: [submissions, mastery] });
+        expect(app.modules.map((m) => m.name)).toEqual(["submissions", "mastery"]);
+        await app.start();
+        await app.stop();
+    });
+    it("reverse-declared order is FIXED — consumer first → topo flips to producer first", async () => {
+        const PaymentChargedEvent = defineEvent({
+            name: "payments.charged",
+            schema: z.object({ paymentId: z.string() }),
+        }).public();
+        const chargeAction = defineAction({
+            name: "payments.charge",
+            schema: z.object({ amount: z.number() }),
+            handler: async () => undefined,
+        });
+        const payments = defineModule("payments", {
+            events: [PaymentChargedEvent],
+            actions: [chargeAction],
+        });
+        const ledger = defineModule("ledger", {
+            needs: { events: [PaymentChargedEvent] },
+        });
+        // Declared consumer-first; topo sort must reorder to producer-first.
+        const app = createApp({ modules: [ledger, payments] });
+        expect(app.modules.map((m) => m.name)).toEqual(["ledger", "payments"]); // declared modules are preserved
+        // The actual REGISTRATION pass uses the sorted order under the hood.
+        // We can't observe that order without a more invasive probe; the
+        // primary contract is "no error + start() works." The cycle test
+        // below proves the sort logic is actually consulting needs.
+        await app.start();
+        await app.stop();
+    });
+    it("throws a readable error when modules form a cycle", () => {
+        const FooEvent = defineEvent({
+            name: "foo.happened",
+            schema: z.object({ id: z.string() }),
+        }).public();
+        const BarEvent = defineEvent({
+            name: "bar.happened",
+            schema: z.object({ id: z.string() }),
+        }).public();
+        const foo = defineModule("foo", {
+            events: [FooEvent],
+            needs: { events: [BarEvent] },
+        });
+        const bar = defineModule("bar", {
+            events: [BarEvent],
+            needs: { events: [FooEvent] },
+        });
+        expect(() => createApp({ modules: [foo, bar] })).toThrow(/cycle detected in module needs graph among: bar, foo/);
+    });
+    it("three-module chain orders correctly regardless of declaration order", async () => {
+        const AEvent = defineEvent({
+            name: "a.happened",
+            schema: z.object({ id: z.string() }),
+        }).public();
+        const BEvent = defineEvent({
+            name: "b.happened",
+            schema: z.object({ id: z.string() }),
+        }).public();
+        const a = defineModule("a", { events: [AEvent] });
+        const b = defineModule("b", { events: [BEvent], needs: { events: [AEvent] } });
+        const c = defineModule("c", { needs: { events: [BEvent] } });
+        // Declared c → a → b; topo order should produce a → b → c.
+        const app = createApp({ modules: [c, a, b] });
+        await app.start();
+        await app.stop();
+    });
+});
+//# sourceMappingURL=module-topo-sort.test.js.map

package/dist/__tests__/module-topo-sort.test.js.map

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

package/dist/__tests__/multi-tenancy.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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).
+ */
+export {};
+//# sourceMappingURL=multi-tenancy.test.d.ts.map

package/dist/__tests__/multi-tenancy.test.d.ts.map

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