@geonosis/events 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,217 @@
+# `@geonosis/events`
+
+An event declares its type, its payload schema and what it is **about**, once. A registry that
+refuses a duplicate name. A totality type that makes every event answerable before it can ship. An
+outbox port.
+
+The engines' own facts live behind their own doors — `@geonosis/events/medusa` and
+`@geonosis/events/cloudflare-queues` — and neither adapter imports the engine it adapts.
+
+Zero runtime dependencies.
+
+```bash
+pnpm add @geonosis/events
+```
+
+## The core
+
+```ts
+import { createEventRegistry, defineEvent } from '@geonosis/events'
+import { z } from 'zod'
+
+export const workflowCompleted = defineEvent(
+  'workflow.completed',
+  z.object({ name: z.string().min(1), runId: z.string().min(1) }),
+  (payload) => ({ kind: 'workflow-run', id: payload.runId }),
+)
+
+const registry = createEventRegistry([workflowCompleted, workflowCompensated])
+```
+
+The third argument is a **function**, not a string. It derives the subject from the payload, which
+is what lets one call validate a payload and name its subject together:
+
+```ts
+registry.describe('workflow.completed', raw)
+// { ok: true, payload: {...}, subject: { kind: 'workflow-run', id: 'r-1' } }
+// { ok: false, reason: 'unknown-type' }      — a producer nobody deployed
+// { ok: false, reason: 'invalid-payload' }   — a payload that drifted from its name
+```
+
+Those two failures are told apart because the answers are different: one is a name nothing answers
+to, the other is drift under a name that is still declared.
+
+### There is no `attempts` and no `priority` here
+
+Both are facts about **Medusa's redis bus**, which has no dead-letter queue and treats only
+`attempts > 1` as retry-configured. Measured: neither appears anywhere in during.day. Putting them
+in a runtime-agnostic core would import one engine's failure mode into the contract the other engine
+also has to hold. They live in `@geonosis/events/medusa`, and so does `subscriberId`.
+
+## Totality — the type is the instrument, the check is the backstop
+
+during.day's totality is a **compile-time** fact, and — this is the part worth being exact about —
+`defineEvent` enforces none of it. Adding a contract widens the union of declared types, and that
+widening breaks two total maps somewhere else entirely:
+
+| Map | Where | How |
+|---|---|---|
+| narration | `packages/domains/src/events/narration.ts:12` | `{ [Type in DomainEventType]: (payload) => EventNarration }` |
+| notification channel | `packages/domains/src/notification/dispatch.ts:15` | `Record<DomainEventType, NotificationChannel>` |
+
+A new event cannot ship until someone has written words for it and decided how it notifies —
+enforced by the checker, in the files that own those answers, at no runtime cost and with no way to
+forget. That is the instrument this package leads with:
+
+```ts
+import type { EventTypeOf, TotalOver } from '@geonosis/events'
+
+const events = [workflowCompleted, workflowCompensated] as const
+type DomainEventType = EventTypeOf<typeof events>
+
+const narrators: TotalOver<DomainEventType, Narrator> = { ... }  // missing one → does not compile
+```
+
+`assertTotal` is the **backstop**, for a map assembled from configuration or built where the checker
+cannot follow. It reports both directions — a type nothing answers for, and an entry answering for a
+type no event declares, which is how a map keeps a handler for an event renamed two releases ago:
+
+```ts
+assertTotal(registry, 'notification', channels)
+```
+
+Sold as equivalent to the type, this would be a downgrade dressed as a feature. It is documented
+here as second best because it is second best.
+
+## The outbox is a port, and only a port
+
+```ts
+export type Outbox<Envelope> = {
+  enqueue: (batch: readonly Envelope[]) => Promise<void>
+  listUndispatched: (params: { before: number; limit: number }) => Promise<readonly Envelope[]>
+  markDispatched: (params: { ids: readonly string[]; dispatchedAt?: number }) => Promise<void>
+  deleteDispatchedBefore: (params: { before: number }) => Promise<number>
+}
+```
+
+**No adapter ships here, and the reason is a measurement.** during.day is usually described —
+including in this kit's own law — as "Cloudflare Workers + D1". It is hybrid: the **tenant** plane is
+Postgres (`pgTable` in all 13 files under `schema/tenant/`, and the outbox is one of them), and only
+the **control** plane is D1 (`sqliteTable` in three files under `schema/control/`). A D1 outbox
+adapter would have been written for the wrong half of the only repo that has an outbox at all.
+
+**Four operations, not two.** Plan 022 described the port as `enqueue(batch)` + `sweep(now)`.
+during.day spells it across three files, and the spread is deliberate:
+`deleteDispatchedEventsBefore` removes only *delivered* rows however old, because "an undelivered
+row is a committed mutation's only trail". Collapsed into one `sweep`, listing, marking and deleting
+share a name while failing in three different ways.
+
+`enqueue` is a port method because the write belongs inside the caller's own transaction — in
+during.day, the batch that closes a run. That transaction is the consumer's database's, not this
+package's, which is the whole reason this is an interface.
+
+## `@geonosis/events/medusa`
+
+dielime's `retryableEvent`, generalised, with its source proof intact:
+`@medusajs/event-bus-redis` 2.19 defaults every job to `attempts: 1`; the worker computes
+`isRetriesConfigured = configuredAttempts > 1`; and when a subscriber throws with retrying not
+configured it logs a warning and **returns**, so the job completes. The work is dropped and the only
+trace is a warn line.
+
+```ts
+import { createMedusaEmitter } from '@geonosis/events/medusa'
+import { emitEventStep } from '@medusajs/medusa/core-flows'
+
+const emit = createMedusaEmitter({ emitEventStep, droppable: [/^search\./, /^telemetry\./] })
+
+emit(orderPlaced, { orderId })   // options.attempts = 3, exponential backoff, always
+```
+
+`retryableEvent` throws on `attempts <= 1` rather than accepting it: one attempt is exactly the
+configuration it exists to prevent, and a caller passing it has misunderstood the option rather than
+chosen it. `defaultAttempts` is a repo option — three is a choice, not a law — and a repo default of
+one is refused for the same reason.
+
+`droppable` is a **deny** list and empty by default, so a repo that configures nothing drops nothing.
+That direction is dielime's, written down after an allow-list of load-bearing prefixes was tried
+first: it misclassified half the catalogue, because event names are `<plugin>.<entity>.<verb>` as
+often as `<entity>.<verb>` — and worse, it failed OPEN, so an event nobody thought to list was
+silently droppable.
+
+`defineSubscriber` requires `subscriberId`. Medusa infers one from the filename otherwise, and the
+bus keys its already-succeeded set on that id, so a rename silently re-runs a subscriber that had
+already done its work.
+
+### The 132-line test this replaces
+
+dielime holds the invariant across **56** `emitEventStep` call sites with **56** `retryableEvent`
+calls, policed by `packages/shared/src/events/emits-are-retryable.test.ts` — a source walker with
+its own brace matcher, and a comment recording that its first version omitted `apps/backend` and so
+"reported green for the wrong reason". That is a lint rule wearing a test's clothes. The rule it
+should be is `biological-architecture/emit-declares-attempts`, in this kit's plugin, and the proof
+that it covers all 56 sites is in `proofs/022-W5-consumers/`.
+
+## `@geonosis/events/cloudflare-queues`
+
+during.day's `EventSink` is `sendBatch`-only by declaration, and there is no `send`. Adding one
+would let a caller put a single message on the queue with a round trip per event — the shape a queue
+producer exists to avoid, and the outbox already hands work over in batches.
+
+```ts
+import { createQueueSink } from '@geonosis/events/cloudflare-queues'
+
+const sink = createQueueSink(env.EVENTS)
+await sink.send(envelopes)   // batched at 100, Cloudflare's ceiling; no call at all for an empty list
+```
+
+The binding is injected rather than imported: `@cloudflare/workers-types` is types only, the queue is
+handed to the worker by the runtime, and a package that imported either would be unusable in a test.
+
+## Migration — dielime, five lines
+
+```diff
+-import { retryableEvent } from '@dielime/shared/events/retry'
+-emitEventStep({ eventName: 'order.placed', data, options: retryableEvent({ priority: 10 }) })
++import { createMedusaEmitter } from '@geonosis/events/medusa'
++const emit = createMedusaEmitter({ emitEventStep })
++emit(orderPlaced, data, { priority: 10 })
+```
+
+`packages/shared/src/events/retry.ts` and its 132-line audit test both go. The event name stops being
+a string at the call site, so `emit-declares-attempts` and the contract check the same fact.
+
+## Migration — during.day, five lines
+
+```diff
+-import { defineEvent } from '@during/domains/events'
++import { defineEvent } from '@geonosis/events'
+ export const workflowCompletedEvent = defineEvent('workflow.completed', z.object({...}), (p) => ({...}))
+
+-const narrators: EventNarrators = { ... }
++const narrators: TotalOver<EventTypeOf<typeof eventContracts>, Narrator> = { ... }
+```
+
+The declarations do not change — the signature is during.day's. `indexEventContracts` becomes
+`createEventRegistry`, which throws the same "two event contracts are declared for X". The envelope
+stays in during.day: it carries `orgId`, a tenant key this package cannot assume.
+
+## Equivalence status (D-027)
+
+| Piece | Status |
+|---|---|
+| `defineEvent(type, payload, subjectOf)` | **extracted** — during.day's signature, argument for argument |
+| `createEventRegistry` duplicate refusal | **extracted** — `indexEventContracts`, same error text |
+| `retryableEvent` + the `attempts > 1` refusal | **extracted** — dielime's, generalised with `defaultAttempts` |
+| `defineSubscriber` requiring an id | **extracted** — dielime's convention, Medusa's inference the reason |
+| `droppable` deny-list | **extracted** — dielime's `DROPPABLE_EVENT_PATTERNS`, defaulted to empty so it is opt-in |
+| `sendBatch`-only sink | **extracted** — during.day's `EventSink`, plus the 100-message chunking |
+| `TotalOver` / `EventTypeOf` | **named here** — the idiom is during.day's (`{ [T in DomainEventType]: … }`); this gives it a name and an export |
+| `assertTotal` | **written here** — a backstop neither consumer needs; both use the type |
+| `Outbox` port | **extracted as an interface** — during.day's four operations. No adapter, deliberately |
+
+**Adopted by:** nobody yet. Published with contract tests over both consumers' measured shapes; not
+a migration that has happened.
+
+## Licence
+
+Apache-2.0

package/dist/cloudflare-queues/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * during.day's `EventSink`, honoured exactly: `sendBatch`-only.
+ *
+ * `{ sendBatch: (messages: { body: EventEnvelope }[]) => Promise<unknown> }` is declared beside the
+ * envelope it carries, and there is no `send`. Adding one would let a caller put a single message
+ * on the queue with a round trip per event, which is the shape a Cloudflare queue producer exists
+ * to avoid — and the outbox already hands work over in batches.
+ *
+ * The adapter takes the queue rather than importing one: `@cloudflare/workers-types` is a type
+ * package, the binding is injected by the runtime, and a package that imported either would be
+ * unusable in a test and in every other runtime.
+ */
+type QueueLike<Envelope> = {
+    sendBatch: (messages: {
+        body: Envelope;
+    }[]) => Promise<unknown>;
+};
+type QueueSink<Envelope> = {
+    send: (envelopes: readonly Envelope[]) => Promise<void>;
+};
+declare const createQueueSink: <Envelope>(queue: QueueLike<Envelope>, options?: {
+    maxPerBatch?: number;
+}) => QueueSink<Envelope>;
+
+export { type QueueLike, type QueueSink, createQueueSink };

package/dist/cloudflare-queues/index.js

@@ -0,0 +1,15 @@
+// src/cloudflare-queues/index.ts
+var MAX_MESSAGES_PER_BATCH = 100;
+var createQueueSink = (queue, options = {}) => {
+  const maxPerBatch = options.maxPerBatch ?? MAX_MESSAGES_PER_BATCH;
+  return {
+    send: async (envelopes) => {
+      for (let at = 0; at < envelopes.length; at += maxPerBatch) {
+        await queue.sendBatch(envelopes.slice(at, at + maxPerBatch).map((body) => ({ body })));
+      }
+    }
+  };
+};
+export {
+  createQueueSink
+};

package/dist/define-CAjVcMva.d.ts

@@ -0,0 +1,55 @@
+/**
+ * One event: its type, the schema of its payload, and what it is ABOUT — declared together, once.
+ *
+ * This is during.day's `defineEvent(type, payload, subject)` shape, and the third argument being a
+ * FUNCTION rather than a string is the part worth keeping. It derives the subject from the payload,
+ * which is what lets `describe()` validate a payload and name its subject in a single act. Split
+ * across two fields, the pairing is lost and an audit row can name a subject its payload never had.
+ *
+ * There is deliberately no `attempts` and no `priority`. Both are facts about Medusa's redis event
+ * bus, which has no dead-letter queue and treats only `attempts > 1` as retry-configured; neither
+ * appears anywhere in during.day. Putting them here would import one engine's failure mode into the
+ * contract the other engine also has to hold. They live in `@geonosis/events/medusa`.
+ */
+/** A schema, recognised by what it does. See `@geonosis/integrations` for why this is structural. */
+type SchemaLike<Value = unknown> = {
+    safeParse: (value: unknown) => {
+        data: Value;
+        success: true;
+    } | {
+        success: false;
+    };
+};
+type EventSubject = {
+    id: string;
+    kind: string;
+};
+type Described<Payload> = {
+    ok: false;
+} | {
+    ok: true;
+    payload: Payload;
+    subject: EventSubject;
+};
+type EventContract<Type extends string, Payload> = {
+    describe: (value: unknown) => Described<Payload>;
+    payload: SchemaLike<Payload>;
+    subject: (payload: Payload) => EventSubject;
+    type: Type;
+};
+/**
+ * Any contract, as a constraint. `subject` is typed `(payload: never) => …` deliberately: a
+ * function's parameter is contravariant, so that is the one annotation every concrete contract
+ * satisfies. Writing `unknown` there instead makes `EventContract<'x', {id: string}>` fail to
+ * satisfy its own umbrella type, which is how a registry generic ends up needing a cast.
+ */
+type AnyEventContract = {
+    describe: (value: unknown) => Described<unknown>;
+    payload: SchemaLike<unknown>;
+    subject: (payload: never) => EventSubject;
+    type: string;
+};
+declare const isEventContract: (value: unknown) => value is AnyEventContract;
+declare const defineEvent: <const Type extends string, Payload>(type: Type, payload: SchemaLike<Payload>, subject: (payload: Payload) => EventSubject) => EventContract<Type, Payload>;
+
+export { type AnyEventContract as A, type Described as D, type EventContract as E, type SchemaLike as S, type EventSubject as a, defineEvent as d, isEventContract as i };

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import { A as AnyEventContract, D as Described, E as EventContract } from './define-CAjVcMva.js';
+export { a as EventSubject, S as SchemaLike, d as defineEvent, i as isEventContract } from './define-CAjVcMva.js';
+
+/**
+ * The transactional outbox as a PORT, and nothing else. There is no adapter in this package.
+ *
+ * The measurement that decided it: during.day's outbox is `pgTable('event_outbox', …)` on the
+ * TENANT plane, and that plane is Postgres — `pgTable` in all 13 files under `schema/tenant/`. Only
+ * the CONTROL plane is D1 (`sqliteTable` in three files under `schema/control/`). A D1 outbox
+ * adapter, which is what "Cloudflare Workers + D1" would have led to, would have been written for
+ * the wrong half of the only repo that has an outbox at all.
+ *
+ * Four operations, not two. Plan 022 described the port as `enqueue(batch)` + `sweep(now)`; during
+ * .day spells it across three files, and the spread is deliberate — `deleteDispatchedEventsBefore`
+ * removes ONLY delivered rows however old, because "an undelivered row is a committed mutation's
+ * only trail". Collapsed into one `sweep`, listing, marking and deleting share a name while failing
+ * in three different ways.
+ *
+ * `enqueue` is a port method here and is written inside the caller's own transaction — in
+ * during.day, in the batch that closes a run. That is the whole point of an outbox, and it is why
+ * this is an interface: the transaction belongs to the consumer's database, not to this package.
+ */
+type Outbox<Envelope> = {
+    /** Delivered rows only, however old. */
+    deleteDispatchedBefore: (params: {
+        before: number;
+    }) => Promise<number>;
+    /** Written in the same transaction as the mutation that produced the events. */
+    enqueue: (batch: readonly Envelope[]) => Promise<void>;
+    /** `before` is the grace for a run that is about to drain its own events. */
+    listUndispatched: (params: {
+        before: number;
+        limit: number;
+    }) => Promise<readonly Envelope[]>;
+    markDispatched: (params: {
+        dispatchedAt?: number;
+        ids: readonly string[];
+    }) => Promise<void>;
+};
+/**
+ * The consumer's other half. Delivery is at-least-once and the envelope id is the only thing known
+ * before a message is read, so this is the one question a queue consumer asks before doing work.
+ */
+type SeenBefore = (id: string) => Promise<boolean>;
+
+/**
+ * The name index, with the one invariant a name registry has to hold: two contracts may not be
+ * declared for one type. during.day's `indexEventContracts` already throws exactly that, and it is
+ * the reason its consumer door can trust the name it looked up.
+ *
+ * What is added here is the ability to ASK the registry what it knows. during.day never needs to —
+ * a mapped type over the union covers it at compile time — but a runtime totality check has to
+ * compare a map against something, and a map loaded from configuration has no union to check.
+ */
+type DescribeFailure = {
+    ok: false;
+    reason: 'invalid-payload' | 'unknown-type';
+};
+type EventRegistry<Contract extends AnyEventContract> = {
+    describe: (type: string, payload: unknown) => Described<unknown> | DescribeFailure;
+    get: (type: string) => Contract;
+    has: (type: string) => boolean;
+    list: () => readonly Contract[];
+    types: () => readonly string[];
+};
+declare const createEventRegistry: <const Contract extends AnyEventContract>(contracts: readonly Contract[]) => EventRegistry<Contract>;
+
+/**
+ * The instrument during.day actually uses, and the one this package leads with.
+ *
+ * Its totality is a COMPILE-TIME fact, and — this is the part worth being precise about —
+ * `defineEvent` enforces none of it. Adding a contract widens the union of declared types, and the
+ * widening breaks two total maps somewhere else entirely: `events/narration.ts:12` declares
+ * `{ [Type in DomainEventType]: (payload) => EventNarration }` and `notification/dispatch.ts:15`
+ * declares `Record<DomainEventType, NotificationChannel>`. A new event therefore cannot ship until
+ * someone has written words for it and decided how it notifies — enforced by the checker, in the
+ * files that own those answers, with no runtime cost and no way to forget.
+ *
+ * `assertTotal` below is the BACKSTOP, not the equivalent: for a map assembled from configuration,
+ * loaded at runtime, or built somewhere the checker cannot follow. Advertised as equivalent it
+ * would be a downgrade sold as a feature.
+ */
+/** The union of types a contract list declares — during.day's `DomainEventType`. */
+type EventTypeOf<Contracts extends readonly AnyEventContract[]> = Contracts[number]['type'];
+/** One entry per type, or it does not compile. The `satisfies Record<…>` idiom, named. */
+type TotalOver<Type extends string, Value> = {
+    [Key in Type]: Value;
+};
+/** The payload a given type carries, so a total map can be typed per entry. */
+type PayloadOf<Contracts extends readonly AnyEventContract[], Type extends EventTypeOf<Contracts>> = Extract<Contracts[number], {
+    type: Type;
+}> extends EventContract<string, infer Payload> ? Payload : never;
+/**
+ * Both directions. A type nothing answers for is the failure everyone expects; an entry answering
+ * for a type no event declares is the other one, and it is how a map keeps a handler for an event
+ * that was renamed two releases ago.
+ */
+declare const assertTotal: (registry: EventRegistry<AnyEventContract>, channel: string, handled: Record<string, unknown>) => void;
+
+export { AnyEventContract, type DescribeFailure, Described, EventContract, type EventRegistry, type EventTypeOf, type Outbox, type PayloadOf, type SeenBefore, type TotalOver, assertTotal, createEventRegistry };

package/dist/index.js

@@ -0,0 +1,91 @@
+// src/define.ts
+var DECLARED = /* @__PURE__ */ Symbol.for("geonosis.events.declared");
+var isEventContract = (value) => typeof value === "object" && value !== null && value[DECLARED] === true;
+var defineEvent = (type, payload, subject) => {
+  if (typeof type !== "string" || type === "") {
+    throw new TypeError(
+      "defineEvent: `type` must be a non-empty string. The type is how a consumer finds the contract that reads a message, so an event without one cannot be delivered to anything."
+    );
+  }
+  if (typeof payload?.safeParse !== "function") {
+    throw new TypeError(
+      `defineEvent("${type}"): the payload schema must expose \`safeParse\`. A queue carries whatever anyone put on it \u2014 an older producer, a hand-sent message, a payload that drifted \u2014 so the schema is the only thing standing between that and the audit log.`
+    );
+  }
+  if (typeof subject !== "function") {
+    throw new TypeError(
+      `defineEvent("${type}"): \`subject\` must be a function of the payload. Naming what an event is about is derived from the payload, not declared beside it \u2014 otherwise a row can name a subject its payload never carried.`
+    );
+  }
+  return {
+    [DECLARED]: true,
+    describe: (value) => {
+      const parsed = payload.safeParse(value);
+      if (!parsed.success) return { ok: false };
+      return { ok: true, payload: parsed.data, subject: subject(parsed.data) };
+    },
+    payload,
+    subject,
+    type
+  };
+};
+
+// src/registry.ts
+var createEventRegistry = (contracts) => {
+  const byType = /* @__PURE__ */ new Map();
+  for (const contract of contracts ?? []) {
+    if (!isEventContract(contract)) {
+      throw new TypeError(
+        "createEventRegistry: every entry must come from `defineEvent`. A hand-written contract skips the checks on the type, the schema and the subject, and the registry is what the consumer door trusts."
+      );
+    }
+    if (byType.has(contract.type)) {
+      throw new Error(`two event contracts are declared for "${contract.type}"`);
+    }
+    byType.set(contract.type, contract);
+  }
+  const get = (type) => {
+    const found = byType.get(type);
+    if (found === void 0) {
+      throw new Error(`no event contract is declared for "${type}"`);
+    }
+    return found;
+  };
+  return {
+    // Two of the three failures happen to a message that is otherwise well formed — a name nothing
+    // answers to, and a payload that no longer fits the name it came under — and they are told
+    // apart because the answers differ: one is a producer nobody deployed, the other is drift.
+    describe: (type, payload) => {
+      const contract = byType.get(type);
+      if (contract === void 0) return { ok: false, reason: "unknown-type" };
+      const described = contract.describe(payload);
+      return described.ok ? described : { ok: false, reason: "invalid-payload" };
+    },
+    get,
+    has: (type) => byType.has(type),
+    list: () => [...byType.values()],
+    types: () => [...byType.keys()]
+  };
+};
+
+// src/totality.ts
+var assertTotal = (registry, channel, handled) => {
+  const declared = new Set(registry.types());
+  const answered = new Set(Object.keys(handled ?? {}));
+  const missing = [...declared].filter((type) => !answered.has(type)).toSorted();
+  const stray = [...answered].filter((type) => !declared.has(type)).toSorted();
+  if (missing.length === 0 && stray.length === 0) return;
+  const parts = [
+    missing.length > 0 ? `nothing answers for ${missing.join(", ")}` : "",
+    stray.length > 0 ? `${stray.join(", ")} is answered for but declared by no event` : ""
+  ].filter((part) => part !== "");
+  throw new Error(
+    `the "${channel}" channel is not total over the declared events: ${parts.join("; ")}. Prefer the compile-time form \u2014 \`TotalOver<EventTypeOf<typeof events>, Handler>\` \u2014 and keep this check for a map the checker cannot see into.`
+  );
+};
+export {
+  assertTotal,
+  createEventRegistry,
+  defineEvent,
+  isEventContract
+};

package/dist/medusa/index.d.ts

@@ -0,0 +1,66 @@
+import { E as EventContract } from '../define-CAjVcMva.js';
+
+/**
+ * Medusa's own silence, made impossible to keep by accident. dielime's `retryableEvent`, generalised.
+ *
+ * The source proof, against `@medusajs/event-bus-redis` 2.19: `buildEvents()` defaults every job to
+ * `attempts: 1`; the worker computes `isRetriesConfigured = configuredAttempts > 1`; and when a
+ * subscriber throws with retrying not configured it logs "One or more subscribers of <name> failed.
+ * Retrying is not configured." at WARN and RETURNS — so the job completes successfully. The work is
+ * dropped and the only trace is a warn line. For a quote that never expires or a shipment exception
+ * nobody is told about, that is a silent business failure.
+ *
+ * With `attempts > 1` the same worker stores `completedSubscriberIds` on the job before throwing to
+ * trigger the retry and filters them out of the next attempt, so a subscriber that already
+ * succeeded is not re-run. Configuring attempts buys retry for the failed one AND exactly-once
+ * delivery for the ones that worked.
+ *
+ * This is the adapter, not the core, because none of it is true of the other engine: during.day has
+ * a transactional outbox and a queue consumer that dedupes on the envelope id, and carries neither
+ * `attempts` nor `priority` anywhere.
+ */
+/** Three: the first failure is usually a blip, the third is usually real. */
+declare const DEFAULT_EVENT_ATTEMPTS = 3;
+type EventRetryOptions = {
+    attempts?: number;
+    [option: string]: unknown;
+};
+type RetryDefaults = {
+    defaultAttempts?: number;
+};
+/**
+ * Throws on `attempts <= 1` rather than accepting it: one attempt is exactly the configuration this
+ * function exists to prevent, and a caller passing it has misunderstood the option rather than
+ * chosen it.
+ */
+declare const retryableEvent: (options?: EventRetryOptions, defaults?: RetryDefaults) => Record<string, unknown>;
+type EmitEventStep = (input: {
+    data: unknown;
+    eventName: string;
+    options: Record<string, unknown>;
+}) => unknown;
+type EmitterOptions = {
+    defaultAttempts?: number;
+    /**
+     * The events this repo is willing to lose — a DENY list, and the direction is the whole point.
+     * dielime tried an allow-list of load-bearing prefixes first and it misclassified half the
+     * catalogue, because event names are `<plugin>.<entity>.<verb>` as often as `<entity>.<verb>`.
+     * Worse, it fails OPEN: an event nobody thought to list is silently droppable. Empty by default,
+     * so a repo that configures nothing drops nothing.
+     */
+    droppable?: readonly RegExp[];
+    emitEventStep: EmitEventStep;
+};
+declare const createMedusaEmitter: (options: EmitterOptions) => <Type extends string, Payload>(contract: EventContract<Type, Payload>, data: Payload, emitOptions?: EventRetryOptions) => unknown;
+type Subscriber = {
+    handler: (...args: never[]) => Promise<void>;
+    subscriberId: string;
+};
+/**
+ * Medusa infers a subscriber's id from its filename when none is given, so two subscribers that
+ * move or get renamed can silently become one registration — or stop being the one the bus
+ * remembers has already succeeded, which is what `completedSubscriberIds` is keyed on.
+ */
+declare const defineSubscriber: <const S extends Subscriber>(subscriber: S) => S;
+
+export { DEFAULT_EVENT_ATTEMPTS, type EmitEventStep, type EmitterOptions, type EventRetryOptions, type RetryDefaults, type Subscriber, createMedusaEmitter, defineSubscriber, retryableEvent };

package/dist/medusa/index.js

@@ -0,0 +1,50 @@
+// src/medusa/index.ts
+var DEFAULT_EVENT_ATTEMPTS = 3;
+var DEFAULT_BACKOFF = { delay: 1e3, type: "exponential" };
+var NO_RETRY = 1;
+var retryableEvent = (options = {}, defaults = {}) => {
+  const fallback = defaults.defaultAttempts ?? DEFAULT_EVENT_ATTEMPTS;
+  if (fallback <= NO_RETRY) {
+    throw new Error(
+      `retryableEvent: \`defaultAttempts\` must be > 1 (got ${fallback}). A repo default of one attempt makes every emit droppable while every call site looks configured.`
+    );
+  }
+  const { attempts = fallback, ...rest } = options;
+  if (attempts <= NO_RETRY) {
+    throw new Error(
+      `retryableEvent: \`attempts\` must be > 1 (got ${attempts}). One attempt IS "retrying is not configured" to the redis bus, which is the failure this helper exists to prevent.`
+    );
+  }
+  return { attempts, backoff: { ...DEFAULT_BACKOFF }, ...rest };
+};
+var createMedusaEmitter = (options) => {
+  const { defaultAttempts, droppable = [], emitEventStep } = options;
+  return (contract, data, emitOptions = {}) => {
+    const parsed = contract.payload.safeParse(data);
+    if (!parsed.success) {
+      throw new Error(
+        `emit("${contract.type}"): the payload does not satisfy the contract's own schema. The bus carries whatever it is handed, so this is the last place the shape can be refused.`
+      );
+    }
+    const isDroppable = droppable.some((pattern) => pattern.test(contract.type));
+    return emitEventStep({
+      data: parsed.data,
+      eventName: contract.type,
+      options: isDroppable ? { ...emitOptions } : retryableEvent(emitOptions, defaultAttempts === void 0 ? {} : { defaultAttempts })
+    });
+  };
+};
+var defineSubscriber = (subscriber) => {
+  if (typeof subscriber?.subscriberId !== "string" || subscriber.subscriberId === "") {
+    throw new TypeError(
+      "defineSubscriber: `subscriberId` is required. Medusa infers it from the filename otherwise, and the bus keys its already-succeeded set on that id \u2014 so a rename silently re-runs a subscriber that had already done its work."
+    );
+  }
+  return subscriber;
+};
+export {
+  DEFAULT_EVENT_ATTEMPTS,
+  createMedusaEmitter,
+  defineSubscriber,
+  retryableEvent
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@geonosis/events",
+  "version": "1.0.0",
+  "description": "An event declares its type, its payload schema and what it is about, once. A registry that refuses a duplicate name, a totality type that makes every event answerable, and an outbox port — with the engines' own facts kept in their adapters.",
+  "keywords": [
+    "events",
+    "outbox",
+    "registry",
+    "zod",
+    "medusa",
+    "cloudflare-queues"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/packages/events",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "packages/events"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./medusa": "./dist/medusa/index.js",
+    "./cloudflare-queues": "./dist/cloudflare-queues/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "zod": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}