@nwire/messages 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @nwire/messages
+
+> Command + event primitives — `defineCommand` / `defineEvent` and the message-envelope types.
+
+## What it is
+
+Typed message primitives for the CQRS surface: `defineCommand` for intent (one handler, one response) and `defineEvent` for facts (many subscribers, fan-out). Includes the visibility/scope/outcome enums and zod-binding types every Nwire transport, bus, and store agrees on.
+
+## Install
+
+```bash
+pnpm add @nwire/messages
+```
+
+## Standalone use
+
+For developers who want a typed message contract layer for their own architecture — works against any in-process bus, queue, or RPC.
+
+```ts
+import { z } from "zod";
+import { defineCommand, defineEvent } from "@nwire/messages";
+
+export const EnrolStudent = defineCommand("EnrolStudent", {
+  schema: z.object({ studentId: z.string(), courseId: z.string() }),
+});
+
+export const StudentWasEnrolled = defineEvent("StudentWasEnrolled", {
+  schema: z.object({ studentId: z.string(), courseId: z.string() }),
+  scope: "domain",
+  visibility: "public",
+});
+
+// Validate at the edge:
+const payload = EnrolStudent.schema.parse(req.body);
+// Construct an event message:
+const msg = StudentWasEnrolled({ studentId: "s-1", courseId: "c-1" });
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack. `@nwire/forge`'s `defineEvent` wraps this one with extra hooks (bus republish, projection fan-out). Touch `@nwire/messages` directly when you need just the contracts — typically in shared kits a foreign service imports.
+
+```ts
+import { defineEvent } from "@nwire/forge"; // adds bus + projection wiring
+const StudentWasEnrolled = defineEvent("StudentWasEnrolled", {
+  schema: z.object({ studentId: z.string(), courseId: z.string() }),
+}).public();
+```
+
+## API
+
+- `defineCommand(name, { schema })` — intent contract; one handler, one response.
+- `defineEvent(name, { schema, scope?, visibility?, outcome? })` — fact contract; many subscribers.
+- `CommandDefinition`, `EventDefinition`, `EventMessageOf`, `CommandPayload`, `EventPayload` — inferred types.
+- `EventVisibility` / `EventScope` / `EventOutcome` — enums (`public`/`internal`, `domain`/`integration`, success/failure tags).
+- `ServiceBootedEvent`, `NoopCommand` — built-in baseline contracts.
+
+## See also
+
+- [Architecture sketch §05 — Primitives tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/forge](../nwire-forge), [@nwire/bus](../nwire-bus), [@nwire/envelope](../nwire-envelope)

package/dist/__tests__/define-event.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * defineEvent — returns a callable factory that IS the event definition.
+ */
+export {};
+//# sourceMappingURL=define-event.test.d.ts.map

package/dist/__tests__/define-event.test.d.ts.map

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

package/dist/__tests__/define-event.test.js

@@ -0,0 +1,44 @@
+/**
+ * defineEvent — returns a callable factory that IS the event definition.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "../message-contracts.js";
+describe("defineEvent (callable)", () => {
+    const AnswerWasSubmitted = defineEvent({
+        name: "submissions.answer-was-submitted",
+        description: "Avi just tapped Submit.",
+        outcome: "milestone",
+        audience: ["product"],
+        visibility: "public",
+        // Integration events require a version since Phase 42.2.
+        version: 1,
+        schema: z.object({
+            studentId: z.string(),
+            submittedAt: z.string().datetime(),
+        }),
+    });
+    it("preserves meta fields as own properties", () => {
+        expect(AnswerWasSubmitted.name).toBe("submissions.answer-was-submitted");
+        expect(AnswerWasSubmitted.description).toBe("Avi just tapped Submit.");
+        expect(AnswerWasSubmitted.outcome).toBe("milestone");
+        expect(AnswerWasSubmitted.audience).toEqual(["product"]);
+        expect(AnswerWasSubmitted.visibility).toBe("public");
+        expect(AnswerWasSubmitted.schema).toBeDefined();
+    });
+    it("is callable as a factory and validates payload", () => {
+        const at = new Date().toISOString();
+        const msg = AnswerWasSubmitted({ studentId: "alice", submittedAt: at });
+        expect(msg).toEqual({
+            eventName: "submissions.answer-was-submitted",
+            payload: { studentId: "alice", submittedAt: at },
+        });
+    });
+    it("throws on invalid payload via zod parse", () => {
+        expect(() => AnswerWasSubmitted({ studentId: "alice", submittedAt: "not-a-date" })).toThrow();
+    });
+    it("toString returns the event name", () => {
+        expect(String(AnswerWasSubmitted)).toBe("submissions.answer-was-submitted");
+    });
+});
+//# sourceMappingURL=define-event.test.js.map

package/dist/__tests__/define-event.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-event.test.js","sourceRoot":"","sources":["../../src/__tests__/define-event.test.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;IACtC,MAAM,kBAAkB,GAAG,WAAW,CAAC;QACrC,IAAI,EAAE,kCAAkC;QACxC,WAAW,EAAE,yBAAyB;QACtC,OAAO,EAAE,WAAW;QACpB,QAAQ,EAAE,CAAC,SAAS,CAAC;QACrB,UAAU,EAAE,QAAQ;QACpB,yDAAyD;QACzD,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;YACf,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;YACrB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SACnC,CAAC;KACH,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;QACzE,MAAM,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;QACvE,MAAM,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACrD,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACzD,MAAM,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrD,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,kBAAkB,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;QACxE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;YAClB,SAAS,EAAE,kCAAkC;YAC7C,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE;SACjD,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,GAAG,EAAE,CACV,kBAAkB,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAW,CAAC,CAC/E,CAAC,OAAO,EAAE,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/commands/noop.command.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export declare const NoopCommand: import("../message-contracts.js").CommandDefinition<z.ZodObject<{
+    traceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+//# sourceMappingURL=noop.command.d.ts.map

package/dist/commands/noop.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.command.d.ts","sourceRoot":"","sources":["../../src/commands/noop.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,WAAW;;kBAMtB,CAAC"}

package/dist/commands/noop.command.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { defineCommand } from "../message-contracts.js";
+export const NoopCommand = defineCommand({
+    name: "system.noop",
+    description: "Placeholder command demonstrating the cross-service contract pattern.",
+    schema: z.object({
+        traceId: z.string().optional(),
+    }),
+});
+//# sourceMappingURL=noop.command.js.map

package/dist/commands/noop.command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.command.js","sourceRoot":"","sources":["../../src/commands/noop.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;IACvC,IAAI,EAAE,aAAa;IACnB,WAAW,EAAE,uEAAuE;IACpF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC;CACH,CAAC,CAAC"}

package/dist/events/service-booted.event.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export declare const ServiceBootedEvent: import("../message-contracts.js").EventDefinition<z.ZodObject<{
+    service: z.ZodString;
+    version: z.ZodString;
+    bootedAt: z.ZodString;
+}, z.core.$strip>>;
+//# sourceMappingURL=service-booted.event.d.ts.map

package/dist/events/service-booted.event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-booted.event.d.ts","sourceRoot":"","sources":["../../src/events/service-booted.event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,kBAAkB;;;;kBAS7B,CAAC"}

package/dist/events/service-booted.event.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { defineEvent } from "../message-contracts.js";
+export const ServiceBootedEvent = defineEvent({
+    name: "system.service.booted",
+    description: "Emitted when a service finishes its boot sequence; consumed by ops dashboards and trace pipelines.",
+    schema: z.object({
+        service: z.string(),
+        version: z.string(),
+        bootedAt: z.string().datetime(),
+    }),
+});
+//# sourceMappingURL=service-booted.event.js.map

package/dist/events/service-booted.event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-booted.event.js","sourceRoot":"","sources":["../../src/events/service-booted.event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAAC;IAC5C,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACT,oGAAoG;IACtG,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAChC,CAAC;CACH,CAAC,CAAC"}

package/dist/message-contracts.d.ts

@@ -0,0 +1,112 @@
+import type { z, ZodType } from "zod";
+/**
+ * Workspace alias for "any zod schema". Zod 4 dropped the `ZodTypeAny`
+ * export; this alias keeps the rest of the codebase reading naturally
+ * without a hundred `ZodType<any>` sprinkled inline.
+ *
+ * `ZodType<any>` preserves bivariance so concrete schemas (e.g.
+ * `ZodObject<{...}>`) assign to `ZodTypeAny` without complaint — the same
+ * behaviour zod 3 gave us out of the box.
+ */
+export type ZodTypeAny = ZodType<any>;
+export interface CommandDefinition<TSchema extends ZodTypeAny = ZodTypeAny> {
+    readonly name: string;
+    readonly schema: TSchema;
+    readonly description?: string;
+}
+/**
+ * Event visibility — controls whether the event is part of the public,
+ * cross-bounded-context API of its module.
+ *
+ * - `'public'` (default) — exported as part of the module's public surface;
+ *   other modules MAY listen to it via `when(SomeEvent, ...)`. The
+ *   `@nwire/messages` workspace package re-exports public events for
+ *   external consumers (frontends, BFFs, sync services).
+ * - `'internal'` — the event is module-internal. Other modules MUST NOT
+ *   subscribe; the framework can warn or refuse cross-module listeners.
+ *   Use for transient implementation-detail events.
+ */
+export type EventVisibility = "public" | "internal";
+/**
+ * Domain outcome an event represents. Lets Studio score success rates and
+ * surface warnings/failures without parsing event names. Default `'success'`.
+ *   - `'success'`     — a positive thing happened (default)
+ *   - `'failure'`     — something failed in a domain-meaningful way (not a system error)
+ *   - `'milestone'`   — significant progress event (lesson completed, onboarding finished)
+ *   - `'warning'`     — anomaly that's not yet a failure (low confidence, manual review needed)
+ */
+export type EventOutcome = "success" | "failure" | "milestone" | "warning";
+/**
+ * Event scope — the structural distinction between domain and integration.
+ *
+ * - `'domain'` — internal to a bounded context. Folded by actors, projections,
+ *   reactions inside the BC. Never bus-eligible. Refactor freely.
+ * - `'integration'` — public contract on the bus. Versioned, audience-tagged,
+ *   slim. Other BCs and services subscribe to these, not to domain events.
+ *
+ * `scope` is structural and complements `visibility`:
+ *   - `scope: "domain"` → implies `visibility: "internal"` unless overridden
+ *   - `scope: "integration"` → implies `visibility: "public"`
+ *
+ * If `scope` is omitted, the framework infers it from `visibility`.
+ */
+export type EventScope = "domain" | "integration";
+export interface EventDefinitionMeta<TSchema extends ZodTypeAny = ZodTypeAny> {
+    readonly name: string;
+    readonly schema: TSchema;
+    readonly description?: string;
+    /** Defaults to `'public'`. */
+    readonly visibility?: EventVisibility;
+    /** Domain outcome semantics. Defaults to `'success'`. */
+    readonly outcome?: EventOutcome;
+    /**
+     * Relative business weight (e.g. `100` for money-flow events, `1` for
+     * telemetry chatter). Studio uses this to weight dashboards so a single
+     * payment-failed event doesn't get drowned out by a thousand pings.
+     */
+    readonly businessWeight?: number;
+    /**
+     * Free-form audience tags — who cares about this event outside engineering?
+     * `['product']`, `['ops', 'support']`, `['finance']`.
+     */
+    readonly audience?: readonly string[];
+    /**
+     * Domain vs integration scope. Domain events are BC-internal; integration
+     * events are versioned public contracts on the bus. If omitted, inferred
+     * from `visibility` (public → integration, internal → domain).
+     */
+    readonly scope?: EventScope;
+    /**
+     * Integer version of an integration event's schema (`v1`, `v2`, ...).
+     * Required for `scope: "integration"`. Ignored for domain events.
+     */
+    readonly version?: number;
+}
+/** Shape returned when an event definition is called as a factory. */
+export interface EventMessageOf<TSchema extends ZodTypeAny> {
+    readonly eventName: string;
+    readonly payload: z.output<TSchema>;
+}
+/**
+ * `defineEvent` returns a callable factory that *is* the event definition.
+ * Call it to mint a typed `EventMessage` (validates against the zod schema),
+ * or read its meta fields (`name`, `schema`, `outcome`, …) directly.
+ *
+ *   const AnswerWasSubmitted = defineEvent({ name: "...", schema: ... })
+ *   AnswerWasSubmitted.name            // "submissions.answer-was-submitted"
+ *   AnswerWasSubmitted({ ... })        // { eventName, payload }
+ *
+ * Domain→integration translation lives in `defineWorkflow`. Subscribe with
+ * `on(SourceEvent, async (e) => { await publish(TargetEvent({ ... })); })`.
+ */
+export type EventDefinition<TSchema extends ZodTypeAny = ZodTypeAny> = EventDefinitionMeta<TSchema> & ((payload: z.output<TSchema>) => EventMessageOf<TSchema>) & {
+    /** Module-manifest visibility marker. See `defineWorkflow.public()` notes. */
+    readonly $public?: true;
+    /** Return a callable event clone with `$public: true`. */
+    public: () => EventDefinition<TSchema>;
+};
+export declare function defineCommand<TSchema extends ZodTypeAny>(def: CommandDefinition<TSchema>): CommandDefinition<TSchema>;
+export declare function defineEvent<TSchema extends ZodTypeAny>(def: EventDefinitionMeta<TSchema>): EventDefinition<TSchema>;
+export type CommandPayload<C> = C extends CommandDefinition<infer S> ? z.output<S> : never;
+export type EventPayload<E> = E extends EventDefinition<infer S> ? z.output<S> : never;
+//# sourceMappingURL=message-contracts.d.ts.map

package/dist/message-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-contracts.d.ts","sourceRoot":"","sources":["../src/message-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEtC;;;;;;;;GAQG;AAEH,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;AAEtC,MAAM,WAAW,iBAAiB,CAAC,OAAO,SAAS,UAAU,GAAG,UAAU;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAE3E;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;AAElD,MAAM,WAAW,mBAAmB,CAAC,OAAO,SAAS,UAAU,GAAG,UAAU;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,UAAU;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,SAAS,UAAU,GAAG,UAAU,IACjE,mBAAmB,CAAC,OAAO,CAAC,GAC1B,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,cAAc,CAAC,OAAO,CAAC,CAAC,GAAG;IAC1D,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;IACxB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;CACxC,CAAC;AAEN,wBAAgB,aAAa,CAAC,OAAO,SAAS,UAAU,EACtD,GAAG,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAC9B,iBAAiB,CAAC,OAAO,CAAC,CAE5B;AAED,wBAAgB,WAAW,CAAC,OAAO,SAAS,UAAU,EACpD,GAAG,EAAE,mBAAmB,CAAC,OAAO,CAAC,GAChC,eAAe,CAAC,OAAO,CAAC,CAgD1B;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AAC3F,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC"}

package/dist/message-contracts.js

@@ -0,0 +1,47 @@
+export function defineCommand(def) {
+    return def;
+}
+export function defineEvent(def) {
+    // Infer scope from visibility when not explicit.
+    const scope = def.scope ??
+        (def.visibility === "internal"
+            ? "domain"
+            : def.visibility === "public"
+                ? "integration"
+                : undefined);
+    // Integration events must carry a version.
+    if (scope === "integration" && def.version === undefined) {
+        throw new Error(`defineEvent("${def.name}"): integration events must specify \`version: <number>\`.`);
+    }
+    const factory = (payload) => ({
+        eventName: def.name,
+        payload: def.schema.parse(payload),
+    });
+    // `.public()` — the module-manifest visibility marker. Calling it
+    // returns a callable event factory clone with `$public: true`, leaving
+    // the original definition unmarked so it stays visibility-agnostic.
+    const publicMethod = function publicMarker() {
+        const cloned = defineEvent(def);
+        Object.defineProperty(cloned, "$public", {
+            value: true,
+            enumerable: false,
+            configurable: true,
+        });
+        return cloned;
+    };
+    Object.defineProperties(factory, {
+        name: { value: def.name, enumerable: true, configurable: true },
+        schema: { value: def.schema, enumerable: true },
+        description: { value: def.description, enumerable: true },
+        visibility: { value: def.visibility, enumerable: true },
+        outcome: { value: def.outcome, enumerable: true },
+        businessWeight: { value: def.businessWeight, enumerable: true },
+        audience: { value: def.audience, enumerable: true },
+        scope: { value: scope, enumerable: true },
+        version: { value: def.version, enumerable: true },
+        toString: { value: () => def.name, enumerable: false },
+        public: { value: publicMethod, enumerable: false, configurable: true },
+    });
+    return factory;
+}
+//# sourceMappingURL=message-contracts.js.map

package/dist/message-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-contracts.js","sourceRoot":"","sources":["../src/message-contracts.ts"],"names":[],"mappings":"AAuHA,MAAM,UAAU,aAAa,CAC3B,GAA+B;IAE/B,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,GAAiC;IAEjC,iDAAiD;IACjD,MAAM,KAAK,GACT,GAAG,CAAC,KAAK;QACT,CAAC,GAAG,CAAC,UAAU,KAAK,UAAU;YAC5B,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,GAAG,CAAC,UAAU,KAAK,QAAQ;gBAC3B,CAAC,CAAC,aAAa;gBACf,CAAC,CAAC,SAAS,CAAC,CAAC;IACnB,2CAA2C;IAC3C,IAAI,KAAK,KAAK,aAAa,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CACb,gBAAgB,GAAG,CAAC,IAAI,4DAA4D,CACrF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,OAA0B,EAA2B,EAAE,CAAC,CAAC;QACxE,SAAS,EAAE,GAAG,CAAC,IAAI;QACnB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAsB;KACxD,CAAC,CAAC;IAEH,kEAAkE;IAClE,uEAAuE;IACvE,oEAAoE;IACpE,MAAM,YAAY,GAAG,SAAS,YAAY;QACxC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE;YACvC,KAAK,EAAE,IAAI;YACX,UAAU,EAAE,KAAK;YACjB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IAEF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE;QAC/B,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE;QAC/D,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE;QAC/C,WAAW,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE;QACzD,UAAU,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE;QACvD,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE;QACjD,cAAc,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,cAAc,EAAE,UAAU,EAAE,IAAI,EAAE;QAC/D,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE;QACnD,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE;QACzC,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE;QACjD,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE;QACtD,MAAM,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE;KACvE,CAAC,CAAC;IACH,OAAO,OAAmC,CAAC;AAC7C,CAAC"}

package/dist/messages.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@nwire/messages` — command + event contract primitives.
+ *
+ * `defineCommand` for intent (one handler, one response), `defineEvent` for
+ * facts (many subscribers, fan-out). Visibility/scope/outcome enums + zod-
+ * binding types every Nwire transport, bus, and store agrees on.
+ *
+ * See: architecture-sketch.html §05 (Primitives tier).
+ */
+export { defineCommand, defineEvent, type CommandDefinition, type EventDefinition, type EventDefinitionMeta, type EventMessageOf, type CommandPayload, type EventPayload, type EventVisibility, type EventOutcome, type EventScope, type ZodTypeAny, } from "./message-contracts.js";
+export { NoopCommand } from "./commands/noop.command.js";
+export { ServiceBootedEvent } from "./events/service-booted.event.js";
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/messages.js

@@ -0,0 +1,13 @@
+/**
+ * `@nwire/messages` — command + event contract primitives.
+ *
+ * `defineCommand` for intent (one handler, one response), `defineEvent` for
+ * facts (many subscribers, fan-out). Visibility/scope/outcome enums + zod-
+ * binding types every Nwire transport, bus, and store agrees on.
+ *
+ * See: architecture-sketch.html §05 (Primitives tier).
+ */
+export { defineCommand, defineEvent, } from "./message-contracts.js";
+export { NoopCommand } from "./commands/noop.command.js";
+export { ServiceBootedEvent } from "./events/service-booted.event.js";
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,WAAW,GAWZ,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@nwire/messages",
+  "version": "0.7.0",
+  "description": "Nwire — typed command and event contracts. defineCommand, defineEvent with public/internal visibility. Zod-validated; shareable across the backend, frontends, BFFs.",
+  "keywords": [
+    "commands",
+    "contracts",
+    "events",
+    "messages",
+    "nwire"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/messages.js",
+  "types": "./dist/messages.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/messages.js",
+      "types": "./dist/messages.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}