@smthrs/notifications 0.0.0-stage → 1.0.0-rc.3

package/dist/cjs/Notification.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Durable notification payloads and their admission classification.
+ *
+ * @since 0.1.0
+ */
+import { Schema } from "effect";
+/**
+ * Producer-supplied attribution carried as data alongside the authenticated
+ * source actor. These labels never authorize a notification or a model action.
+ * They pass through the journal's ordinary redaction policy.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Attribution: Schema.$Record<Schema.String, Schema.String>;
+/**
+ * Durable origin of a notification: who said it, from where, and at which
+ * turn.
+ *
+ * Provenance travels with the notification because the run that receives one
+ * is not the run that wrote it. An operator steer, a parent run's event, and a
+ * webhook all arrive on the same queue, and only these fields say which is
+ * which after the fact.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Provenance: Schema.Struct<{
+    readonly sourceRunId: Schema.String;
+    readonly sourceLineageId: Schema.String;
+    readonly sourceTurn: Schema.Int;
+    readonly sourceActor: Schema.String;
+    readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+}>;
+/**
+ * The decoded form of {@link Provenance}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Provenance = typeof Provenance.Type;
+/**
+ * A human message that must reach the model before the current turn closes.
+ *
+ * `id` is the caller's idempotency key: admitting it twice with the same
+ * content is one notification, and admitting it with different content is a
+ * producer bug the queue refuses. New admissions fingerprint the validated
+ * content before journal redaction, so redaction does not change retry identity.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const HumanSteer: Schema.TaggedStruct<"human-steer", {
+    readonly delivery: Schema.Literal<"steer">;
+    readonly id: Schema.NonEmptyString;
+    readonly targetLineageId: Schema.NonEmptyString;
+    readonly provenance: Schema.Struct<{
+        readonly sourceRunId: Schema.String;
+        readonly sourceLineageId: Schema.String;
+        readonly sourceTurn: Schema.Int;
+        readonly sourceActor: Schema.String;
+        readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    }>;
+    readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+/**
+ * The decoded form of {@link HumanSteer}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type HumanSteer = typeof HumanSteer.Type;
+/**
+ * A human message that waits for the run to become idle.
+ *
+ * The delivery class is the whole difference from {@link HumanSteer}: a
+ * follow-up is not urgent enough to interrupt the turn in flight, so it is
+ * promoted one at a time when the run would otherwise have nothing to do.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const HumanFollowup: Schema.TaggedStruct<"human-followup", {
+    readonly delivery: Schema.Literal<"queue">;
+    readonly id: Schema.NonEmptyString;
+    readonly targetLineageId: Schema.NonEmptyString;
+    readonly provenance: Schema.Struct<{
+        readonly sourceRunId: Schema.String;
+        readonly sourceLineageId: Schema.String;
+        readonly sourceTurn: Schema.Int;
+        readonly sourceActor: Schema.String;
+        readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    }>;
+    readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+/**
+ * The decoded form of {@link HumanFollowup}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type HumanFollowup = typeof HumanFollowup.Type;
+/**
+ * A machine-originated event. Events sharing a coalescing key and a target
+ * lineage collapse to the most recent one while pending.
+ *
+ * Coalescing is what keeps a chatty producer from filling the queue: ten
+ * updates about one condition are one pending notification carrying the latest
+ * of them. The key is scoped to `targetLineageId`, so two branches reporting
+ * one condition under the same ordinary key each keep their own event. An
+ * event with no key never coalesces.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const SystemEvent: Schema.TaggedStruct<"system-event", {
+    readonly delivery: Schema.Literal<"queue">;
+    readonly coalescingKey: Schema.optional<Schema.String>;
+    readonly id: Schema.NonEmptyString;
+    readonly targetLineageId: Schema.NonEmptyString;
+    readonly provenance: Schema.Struct<{
+        readonly sourceRunId: Schema.String;
+        readonly sourceLineageId: Schema.String;
+        readonly sourceTurn: Schema.Int;
+        readonly sourceActor: Schema.String;
+        readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    }>;
+    readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+/**
+ * The decoded form of {@link SystemEvent}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SystemEvent = typeof SystemEvent.Type;
+/**
+ * Any durable notification retained by the pending queue.
+ *
+ * `NotificationQueue.admit` decodes its argument against this union before it
+ * journals anything, so a value that does not match it is refused rather than
+ * acknowledged and then skipped by every replay. Journal-backed queues deeply
+ * freeze decoded notifications, including payloads, before returning them from
+ * `pending` or `drain`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Notification: Schema.Union<readonly [Schema.TaggedStruct<"human-steer", {
+    readonly delivery: Schema.Literal<"steer">;
+    readonly id: Schema.NonEmptyString;
+    readonly targetLineageId: Schema.NonEmptyString;
+    readonly provenance: Schema.Struct<{
+        readonly sourceRunId: Schema.String;
+        readonly sourceLineageId: Schema.String;
+        readonly sourceTurn: Schema.Int;
+        readonly sourceActor: Schema.String;
+        readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    }>;
+    readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.TaggedStruct<"human-followup", {
+    readonly delivery: Schema.Literal<"queue">;
+    readonly id: Schema.NonEmptyString;
+    readonly targetLineageId: Schema.NonEmptyString;
+    readonly provenance: Schema.Struct<{
+        readonly sourceRunId: Schema.String;
+        readonly sourceLineageId: Schema.String;
+        readonly sourceTurn: Schema.Int;
+        readonly sourceActor: Schema.String;
+        readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    }>;
+    readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.TaggedStruct<"system-event", {
+    readonly delivery: Schema.Literal<"queue">;
+    readonly coalescingKey: Schema.optional<Schema.String>;
+    readonly id: Schema.NonEmptyString;
+    readonly targetLineageId: Schema.NonEmptyString;
+    readonly provenance: Schema.Struct<{
+        readonly sourceRunId: Schema.String;
+        readonly sourceLineageId: Schema.String;
+        readonly sourceTurn: Schema.Int;
+        readonly sourceActor: Schema.String;
+        readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    }>;
+    readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>]>;
+/**
+ * Any durable notification retained by the pending queue.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Notification = typeof Notification.Type;
+/**
+ * How a notification is allowed to reach the model.
+ *
+ * `steer` notifications are promoted in a batch at turn close; `queue`
+ * notifications are promoted one at a time when the run would otherwise idle.
+ *
+ * @param notification the notification to classify
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const admissionClass: (notification: Notification) => "steer" | "queue";
+/**
+ * The key a pending notification coalesces on, or `null` when it must never
+ * be coalesced. Only system events coalesce, and only when they declare a key.
+ *
+ * @param notification the notification to key
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const coalesceKey: (notification: Notification) => string | null;
+//# sourceMappingURL=Notification.d.ts.map

package/dist/cjs/Notification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Notification.d.ts","sourceRoot":"","sources":["../../src/Notification.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,8CAA8C,CAAA;AAEtE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU;;;;;;EAMrB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;AAS/C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;EAGrB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;AAE/C;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;EAGxB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;EAItB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAAyD,CAAA;AAElF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,cAAc,YAAY,KAAG,OAAO,GAAG,OAAgC,CAAA;AAEtG;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,cAAc,YAAY,KAAG,MAAM,GAAG,IACgB,CAAA"}

package/dist/cjs/Notification.js

@@ -0,0 +1,62 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Notification_exports = {};
+__export(Notification_exports, {
+  Attribution: () => Attribution,
+  HumanFollowup: () => HumanFollowup,
+  HumanSteer: () => HumanSteer,
+  Notification: () => Notification,
+  Provenance: () => Provenance,
+  SystemEvent: () => SystemEvent,
+  admissionClass: () => admissionClass,
+  coalesceKey: () => coalesceKey
+});
+module.exports = __toCommonJS(Notification_exports);
+var import_effect = require("effect");
+const Attribution = import_effect.Schema.Record(import_effect.Schema.String, import_effect.Schema.String);
+const Provenance = import_effect.Schema.Struct({
+  sourceRunId: import_effect.Schema.String,
+  sourceLineageId: import_effect.Schema.String,
+  sourceTurn: import_effect.Schema.Int.pipe(import_effect.Schema.check(import_effect.Schema.isGreaterThanOrEqualTo(0))),
+  sourceActor: import_effect.Schema.String,
+  attribution: import_effect.Schema.optional(Attribution)
+});
+const common = {
+  id: import_effect.Schema.NonEmptyString,
+  targetLineageId: import_effect.Schema.NonEmptyString,
+  provenance: Provenance,
+  payload: import_effect.Schema.Json
+};
+const HumanSteer = import_effect.Schema.TaggedStruct("human-steer", {
+  ...common,
+  delivery: import_effect.Schema.Literal("steer")
+});
+const HumanFollowup = import_effect.Schema.TaggedStruct("human-followup", {
+  ...common,
+  delivery: import_effect.Schema.Literal("queue")
+});
+const SystemEvent = import_effect.Schema.TaggedStruct("system-event", {
+  ...common,
+  delivery: import_effect.Schema.Literal("queue"),
+  coalescingKey: import_effect.Schema.optional(import_effect.Schema.String)
+});
+const Notification = import_effect.Schema.Union([HumanSteer, HumanFollowup, SystemEvent]);
+const admissionClass = (notification) => notification.delivery;
+const coalesceKey = (notification) => notification._tag === "system-event" ? notification.coalescingKey ?? null : null;
+//# sourceMappingURL=Notification.js.map

package/dist/cjs/Notification.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Notification.ts"],
+  "sourcesContent": ["/**\n * Durable notification payloads and their admission classification.\n *\n * @since 0.1.0\n */\n\nimport { Schema } from \"effect\"\n\n/**\n * Producer-supplied attribution carried as data alongside the authenticated\n * source actor. These labels never authorize a notification or a model action.\n * They pass through the journal's ordinary redaction policy.\n *\n * @category models\n * @since 1.0.0\n */\nexport const Attribution = Schema.Record(Schema.String, Schema.String)\n\n/**\n * Durable origin of a notification: who said it, from where, and at which\n * turn.\n *\n * Provenance travels with the notification because the run that receives one\n * is not the run that wrote it. An operator steer, a parent run's event, and a\n * webhook all arrive on the same queue, and only these fields say which is\n * which after the fact.\n *\n * @category models\n * @since 0.1.0\n */\nexport const Provenance = Schema.Struct({\n  sourceRunId: Schema.String,\n  sourceLineageId: Schema.String,\n  sourceTurn: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),\n  sourceActor: Schema.String,\n  attribution: Schema.optional(Attribution)\n})\n\n/**\n * The decoded form of {@link Provenance}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Provenance = typeof Provenance.Type\n\nconst common = {\n  id: Schema.NonEmptyString,\n  targetLineageId: Schema.NonEmptyString,\n  provenance: Provenance,\n  payload: Schema.Json\n}\n\n/**\n * A human message that must reach the model before the current turn closes.\n *\n * `id` is the caller's idempotency key: admitting it twice with the same\n * content is one notification, and admitting it with different content is a\n * producer bug the queue refuses. New admissions fingerprint the validated\n * content before journal redaction, so redaction does not change retry identity.\n *\n * @category models\n * @since 0.1.0\n */\nexport const HumanSteer = Schema.TaggedStruct(\"human-steer\", {\n  ...common,\n  delivery: Schema.Literal(\"steer\")\n})\n\n/**\n * The decoded form of {@link HumanSteer}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type HumanSteer = typeof HumanSteer.Type\n\n/**\n * A human message that waits for the run to become idle.\n *\n * The delivery class is the whole difference from {@link HumanSteer}: a\n * follow-up is not urgent enough to interrupt the turn in flight, so it is\n * promoted one at a time when the run would otherwise have nothing to do.\n *\n * @category models\n * @since 0.1.0\n */\nexport const HumanFollowup = Schema.TaggedStruct(\"human-followup\", {\n  ...common,\n  delivery: Schema.Literal(\"queue\")\n})\n\n/**\n * The decoded form of {@link HumanFollowup}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type HumanFollowup = typeof HumanFollowup.Type\n\n/**\n * A machine-originated event. Events sharing a coalescing key and a target\n * lineage collapse to the most recent one while pending.\n *\n * Coalescing is what keeps a chatty producer from filling the queue: ten\n * updates about one condition are one pending notification carrying the latest\n * of them. The key is scoped to `targetLineageId`, so two branches reporting\n * one condition under the same ordinary key each keep their own event. An\n * event with no key never coalesces.\n *\n * @category models\n * @since 0.1.0\n */\nexport const SystemEvent = Schema.TaggedStruct(\"system-event\", {\n  ...common,\n  delivery: Schema.Literal(\"queue\"),\n  coalescingKey: Schema.optional(Schema.String)\n})\n\n/**\n * The decoded form of {@link SystemEvent}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type SystemEvent = typeof SystemEvent.Type\n\n/**\n * Any durable notification retained by the pending queue.\n *\n * `NotificationQueue.admit` decodes its argument against this union before it\n * journals anything, so a value that does not match it is refused rather than\n * acknowledged and then skipped by every replay. Journal-backed queues deeply\n * freeze decoded notifications, including payloads, before returning them from\n * `pending` or `drain`.\n *\n * @category models\n * @since 0.1.0\n */\nexport const Notification = Schema.Union([HumanSteer, HumanFollowup, SystemEvent])\n\n/**\n * Any durable notification retained by the pending queue.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Notification = typeof Notification.Type\n\n/**\n * How a notification is allowed to reach the model.\n *\n * `steer` notifications are promoted in a batch at turn close; `queue`\n * notifications are promoted one at a time when the run would otherwise idle.\n *\n * @param notification the notification to classify\n * @category getters\n * @since 0.1.0\n */\nexport const admissionClass = (notification: Notification): \"steer\" | \"queue\" => notification.delivery\n\n/**\n * The key a pending notification coalesces on, or `null` when it must never\n * be coalesced. Only system events coalesce, and only when they declare a key.\n *\n * @param notification the notification to key\n * @category getters\n * @since 0.1.0\n */\nexport const coalesceKey = (notification: Notification): string | null =>\n  notification._tag === \"system-event\" ? notification.coalescingKey ?? null : null\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,oBAAuB;AAUhB,MAAM,cAAc,qBAAO,OAAO,qBAAO,QAAQ,qBAAO,MAAM;AAc9D,MAAM,aAAa,qBAAO,OAAO;AAAA,EACtC,aAAa,qBAAO;AAAA,EACpB,iBAAiB,qBAAO;AAAA,EACxB,YAAY,qBAAO,IAAI,KAAK,qBAAO,MAAM,qBAAO,uBAAuB,CAAC,CAAC,CAAC;AAAA,EAC1E,aAAa,qBAAO;AAAA,EACpB,aAAa,qBAAO,SAAS,WAAW;AAC1C,CAAC;AAUD,MAAM,SAAS;AAAA,EACb,IAAI,qBAAO;AAAA,EACX,iBAAiB,qBAAO;AAAA,EACxB,YAAY;AAAA,EACZ,SAAS,qBAAO;AAClB;AAaO,MAAM,aAAa,qBAAO,aAAa,eAAe;AAAA,EAC3D,GAAG;AAAA,EACH,UAAU,qBAAO,QAAQ,OAAO;AAClC,CAAC;AAoBM,MAAM,gBAAgB,qBAAO,aAAa,kBAAkB;AAAA,EACjE,GAAG;AAAA,EACH,UAAU,qBAAO,QAAQ,OAAO;AAClC,CAAC;AAuBM,MAAM,cAAc,qBAAO,aAAa,gBAAgB;AAAA,EAC7D,GAAG;AAAA,EACH,UAAU,qBAAO,QAAQ,OAAO;AAAA,EAChC,eAAe,qBAAO,SAAS,qBAAO,MAAM;AAC9C,CAAC;AAsBM,MAAM,eAAe,qBAAO,MAAM,CAAC,YAAY,eAAe,WAAW,CAAC;AAoB1E,MAAM,iBAAiB,CAAC,iBAAkD,aAAa;AAUvF,MAAM,cAAc,CAAC,iBAC1B,aAAa,SAAS,iBAAiB,aAAa,iBAAiB,OAAO;",
+  "names": []
+}

package/dist/cjs/NotificationEvent.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Journal event types owned by the notification queue.
+ *
+ * @since 0.1.0
+ */
+import { JournalEvent } from "@smthrs/journal";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+/**
+ * The journal `eventType` recorded for one admission decision.
+ *
+ * The spelling is slashes and a PascalCase leaf, where every other event type
+ * in this repository is dot-separated and lowercase (`control.run.parked`,
+ * `flows.alerts.delivered`). The value is already durable in every engine
+ * database, and a rename would silently stop matching the projections that
+ * consumers key on, so it stays as written. A foreign projection must match
+ * this literal rather than the repository convention, which is why the two
+ * spellings are frozen by `test/WireFormat.test.ts`.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const AdmittedEventType = "flows/notifications/Admitted";
+/**
+ * The journal `eventType` recorded when pending notifications are promoted.
+ *
+ * Spelled like {@link AdmittedEventType}, and frozen for the same reason.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const PromotedEventType = "flows/notifications/Promoted";
+/**
+ * What a durable admission record says was decided.
+ *
+ * This is the one declaration of the admission vocabulary: it validates every
+ * journal entry through {@link fromEntry}, and `NotificationState` types its
+ * public signatures against it, so a fourth decision cannot be added to one
+ * half and forgotten in the other.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const AdmissionDecision: Schema.Literals<readonly ["admitted", "coalesced", "rejected-full"]>;
+/**
+ * The decoded form of {@link AdmissionDecision}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type AdmissionDecision = typeof AdmissionDecision.Type;
+/**
+ * A durable admission record: the notification a run was told about, and what
+ * the queue decided to do with it.
+ *
+ * A `rejected-full` decision is never written. The queue refuses a full queue
+ * in the receipt alone, so the notification id stays admissible once a
+ * boundary drains. The literal remains in {@link AdmissionDecision} because a
+ * reader must stay total over a record any writer could have produced.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Admitted: Schema.Struct<{
+    readonly notification: Schema.Union<readonly [Schema.TaggedStruct<"human-steer", {
+        readonly delivery: Schema.Literal<"steer">;
+        readonly id: Schema.NonEmptyString;
+        readonly targetLineageId: Schema.NonEmptyString;
+        readonly provenance: Schema.Struct<{
+            readonly sourceRunId: Schema.String;
+            readonly sourceLineageId: Schema.String;
+            readonly sourceTurn: Schema.Int;
+            readonly sourceActor: Schema.String;
+            readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+        }>;
+        readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>, Schema.TaggedStruct<"human-followup", {
+        readonly delivery: Schema.Literal<"queue">;
+        readonly id: Schema.NonEmptyString;
+        readonly targetLineageId: Schema.NonEmptyString;
+        readonly provenance: Schema.Struct<{
+            readonly sourceRunId: Schema.String;
+            readonly sourceLineageId: Schema.String;
+            readonly sourceTurn: Schema.Int;
+            readonly sourceActor: Schema.String;
+            readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+        }>;
+        readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>, Schema.TaggedStruct<"system-event", {
+        readonly delivery: Schema.Literal<"queue">;
+        readonly coalescingKey: Schema.optional<Schema.String>;
+        readonly id: Schema.NonEmptyString;
+        readonly targetLineageId: Schema.NonEmptyString;
+        readonly provenance: Schema.Struct<{
+            readonly sourceRunId: Schema.String;
+            readonly sourceLineageId: Schema.String;
+            readonly sourceTurn: Schema.Int;
+            readonly sourceActor: Schema.String;
+            readonly attribution: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+        }>;
+        readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>]>;
+    readonly decision: Schema.Literals<readonly ["admitted", "coalesced", "rejected-full"]>;
+    /** SHA-256 of canonical validated input, absent in legacy admission rows. */
+    readonly fingerprint: Schema.optional<Schema.String>;
+    readonly version: Schema.optional<Schema.Number>;
+}>;
+/**
+ * The decoded form of {@link Admitted}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Admitted = typeof Admitted.Type;
+/**
+ * A durable promotion record: which notifications one boundary of one lineage
+ * delivered.
+ *
+ * The triple `(runId, targetLineageId, boundary)` is the unit of promotion, so
+ * a second lineage draining the same boundary name is a separate record rather
+ * than a repeat of the first.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Promoted: Schema.Struct<{
+    readonly boundary: Schema.String;
+    readonly targetLineageId: Schema.String;
+    readonly ids: Schema.$Array<Schema.String>;
+}>;
+/**
+ * The decoded form of {@link Promoted}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Promoted = typeof Promoted.Type;
+/**
+ * Any journal event owned by this package.
+ *
+ * The two members are told apart with {@link isAdmitted} and
+ * {@link isPromoted} rather than a stored discriminant, because the discriminant
+ * would be a durable field this vocabulary does not have.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Event = Admitted | Promoted;
+/**
+ * Whether an owned event is an admission record.
+ *
+ * @param event an owned event
+ * @category refinements
+ * @since 1.0.0
+ */
+export declare const isAdmitted: (event: Event) => event is Admitted;
+/**
+ * Whether an owned event is a promotion record.
+ *
+ * @param event an owned event
+ * @category refinements
+ * @since 1.0.0
+ */
+export declare const isPromoted: (event: Event) => event is Promoted;
+/**
+ * The journal source every admission of one notification is written under.
+ *
+ * @param notificationId the admitted notification's id
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const admissionSourceId: (notificationId: string) => JournalEvent.SourceId;
+/**
+ * The identity of one drain: the lineage and the boundary, each encoded so a
+ * value containing a slash cannot forge another pair's identity.
+ *
+ * @param targetLineageId the lineage the boundary closed on
+ * @param boundary the boundary name
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const drainKey: (targetLineageId: string, boundary: string) => string;
+/**
+ * The journal source one drain's promotion record is written under.
+ *
+ * @param targetLineageId the lineage the boundary closed on
+ * @param boundary the boundary name
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const drainSourceId: (targetLineageId: string, boundary: string) => JournalEvent.SourceId;
+/**
+ * Decodes an owned notification event from a journal entry.
+ *
+ * Foreign entries and structurally invalid payloads decode to `None` so a
+ * projection over a shared journal stays total.
+ *
+ * The event type alone does not make an entry owned: any producer on a shared
+ * journal can choose one. An admission counts only under
+ * {@link admissionSourceId} for the notification it carries, and a promotion
+ * only under the `/notifications/drain/` source family the queue writes, so
+ * another producer's record with the same event type stays out of the
+ * projection. This scopes records; it does not authenticate the writer. The
+ * journal fences writes on run ownership, not on source, so a writer that
+ * sets this package's source id is read as this package. The drain check is
+ * a prefix because records written before the lineage joined the identity
+ * carry the boundary alone.
+ *
+ * @param entry one journal entry, owned or foreign
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const fromEntry: (entry: JournalEvent.Entry) => Option.Option<Event>;
+//# sourceMappingURL=NotificationEvent.d.ts.map

package/dist/cjs/NotificationEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationEvent.d.ts","sourceRoot":"","sources":["../../src/NotificationEvent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,iCAAiC,CAAA;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,iCAAiC,CAAA;AAE/D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,sEAA8D,CAAA;AAE5F;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;AAE7D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAGnB,6EAA6E;;;EAG7E,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ;;;;EAInB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;;;;GASG;AACH,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,KAAK,KAAG,KAAK,IAAI,QAAmC,CAAA;AAEtF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,KAAK,KAAG,KAAK,IAAI,QAA8B,CAAA;AAEjF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,gBAAgB,MAAM,KAAG,YAAY,CAAC,QACC,CAAA;AAEzE;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,GAAI,iBAAiB,MAAM,EAAE,UAAU,MAAM,KAAG,MACK,CAAA;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,iBAAiB,MAAM,EAAE,UAAU,MAAM,KAAG,YAAY,CAAC,QACG,CAAA;AAQ1F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,YAAY,CAAC,KAAK,KAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAWxE,CAAA"}

package/dist/cjs/NotificationEvent.js

@@ -0,0 +1,84 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var NotificationEvent_exports = {};
+__export(NotificationEvent_exports, {
+  AdmissionDecision: () => AdmissionDecision,
+  Admitted: () => Admitted,
+  AdmittedEventType: () => AdmittedEventType,
+  Promoted: () => Promoted,
+  PromotedEventType: () => PromotedEventType,
+  admissionSourceId: () => admissionSourceId,
+  drainKey: () => drainKey,
+  drainSourceId: () => drainSourceId,
+  fromEntry: () => fromEntry,
+  isAdmitted: () => isAdmitted,
+  isPromoted: () => isPromoted
+});
+module.exports = __toCommonJS(NotificationEvent_exports);
+var import_journal = require("@smthrs/journal");
+var Option = __toESM(require("effect/Option"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var Notification = __toESM(require("./Notification.js"), 1);
+const AdmittedEventType = "flows/notifications/Admitted";
+const PromotedEventType = "flows/notifications/Promoted";
+const AdmissionDecision = Schema.Literals(["admitted", "coalesced", "rejected-full"]);
+const Admitted = Schema.Struct({
+  notification: Notification.Notification,
+  decision: AdmissionDecision,
+  /** SHA-256 of canonical validated input, absent in legacy admission rows. */
+  fingerprint: Schema.optional(Schema.String),
+  version: Schema.optional(Schema.Number)
+});
+const Promoted = Schema.Struct({
+  boundary: Schema.String,
+  targetLineageId: Schema.String,
+  ids: Schema.Array(Schema.String)
+});
+const isAdmitted = (event) => "notification" in event;
+const isPromoted = (event) => !isAdmitted(event);
+const admissionSourceId = (notificationId) => import_journal.JournalEvent.SourceId.make(`${admissionSourcePrefix}${notificationId}`);
+const drainKey = (targetLineageId, boundary) => `${encodeURIComponent(targetLineageId)}/${encodeURIComponent(boundary)}`;
+const drainSourceId = (targetLineageId, boundary) => import_journal.JournalEvent.SourceId.make(`${drainSourcePrefix}${drainKey(targetLineageId, boundary)}`);
+const admissionSourcePrefix = "/notifications/admission/";
+const drainSourcePrefix = "/notifications/drain/";
+const decodeAdmitted = Schema.decodeUnknownOption(Admitted);
+const decodePromoted = Schema.decodeUnknownOption(Promoted);
+const fromEntry = (entry) => {
+  if (entry.eventType === AdmittedEventType) {
+    return Option.filter(
+      decodeAdmitted(entry.payload),
+      (event) => entry.sourceId === admissionSourceId(event.notification.id)
+    );
+  }
+  if (entry.eventType === PromotedEventType && entry.sourceId.startsWith(drainSourcePrefix)) {
+    return decodePromoted(entry.payload);
+  }
+  return Option.none();
+};
+//# sourceMappingURL=NotificationEvent.js.map

package/dist/cjs/NotificationEvent.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/NotificationEvent.ts"],
+  "sourcesContent": ["/**\n * Journal event types owned by the notification queue.\n *\n * @since 0.1.0\n */\n\nimport { JournalEvent } from \"@smthrs/journal\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport * as Notification from \"./Notification.ts\"\n\n/**\n * The journal `eventType` recorded for one admission decision.\n *\n * The spelling is slashes and a PascalCase leaf, where every other event type\n * in this repository is dot-separated and lowercase (`control.run.parked`,\n * `flows.alerts.delivered`). The value is already durable in every engine\n * database, and a rename would silently stop matching the projections that\n * consumers key on, so it stays as written. A foreign projection must match\n * this literal rather than the repository convention, which is why the two\n * spellings are frozen by `test/WireFormat.test.ts`.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const AdmittedEventType = \"flows/notifications/Admitted\"\n\n/**\n * The journal `eventType` recorded when pending notifications are promoted.\n *\n * Spelled like {@link AdmittedEventType}, and frozen for the same reason.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const PromotedEventType = \"flows/notifications/Promoted\"\n\n/**\n * What a durable admission record says was decided.\n *\n * This is the one declaration of the admission vocabulary: it validates every\n * journal entry through {@link fromEntry}, and `NotificationState` types its\n * public signatures against it, so a fourth decision cannot be added to one\n * half and forgotten in the other.\n *\n * @category models\n * @since 1.0.0\n */\nexport const AdmissionDecision = Schema.Literals([\"admitted\", \"coalesced\", \"rejected-full\"])\n\n/**\n * The decoded form of {@link AdmissionDecision}.\n *\n * @category models\n * @since 1.0.0\n */\nexport type AdmissionDecision = typeof AdmissionDecision.Type\n\n/**\n * A durable admission record: the notification a run was told about, and what\n * the queue decided to do with it.\n *\n * A `rejected-full` decision is never written. The queue refuses a full queue\n * in the receipt alone, so the notification id stays admissible once a\n * boundary drains. The literal remains in {@link AdmissionDecision} because a\n * reader must stay total over a record any writer could have produced.\n *\n * @category models\n * @since 0.1.0\n */\nexport const Admitted = Schema.Struct({\n  notification: Notification.Notification,\n  decision: AdmissionDecision,\n  /** SHA-256 of canonical validated input, absent in legacy admission rows. */\n  fingerprint: Schema.optional(Schema.String),\n  version: Schema.optional(Schema.Number)\n})\n\n/**\n * The decoded form of {@link Admitted}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Admitted = typeof Admitted.Type\n\n/**\n * A durable promotion record: which notifications one boundary of one lineage\n * delivered.\n *\n * The triple `(runId, targetLineageId, boundary)` is the unit of promotion, so\n * a second lineage draining the same boundary name is a separate record rather\n * than a repeat of the first.\n *\n * @category models\n * @since 0.1.0\n */\nexport const Promoted = Schema.Struct({\n  boundary: Schema.String,\n  targetLineageId: Schema.String,\n  ids: Schema.Array(Schema.String)\n})\n\n/**\n * The decoded form of {@link Promoted}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Promoted = typeof Promoted.Type\n\n/**\n * Any journal event owned by this package.\n *\n * The two members are told apart with {@link isAdmitted} and\n * {@link isPromoted} rather than a stored discriminant, because the discriminant\n * would be a durable field this vocabulary does not have.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Event = Admitted | Promoted\n\n/**\n * Whether an owned event is an admission record.\n *\n * @param event an owned event\n * @category refinements\n * @since 1.0.0\n */\nexport const isAdmitted = (event: Event): event is Admitted => \"notification\" in event\n\n/**\n * Whether an owned event is a promotion record.\n *\n * @param event an owned event\n * @category refinements\n * @since 1.0.0\n */\nexport const isPromoted = (event: Event): event is Promoted => !isAdmitted(event)\n\n/**\n * The journal source every admission of one notification is written under.\n *\n * @param notificationId the admitted notification's id\n * @category constructors\n * @since 1.0.0\n */\nexport const admissionSourceId = (notificationId: string): JournalEvent.SourceId =>\n  JournalEvent.SourceId.make(`${admissionSourcePrefix}${notificationId}`)\n\n/**\n * The identity of one drain: the lineage and the boundary, each encoded so a\n * value containing a slash cannot forge another pair's identity.\n *\n * @param targetLineageId the lineage the boundary closed on\n * @param boundary the boundary name\n * @category constructors\n * @since 1.0.0\n */\nexport const drainKey = (targetLineageId: string, boundary: string): string =>\n  `${encodeURIComponent(targetLineageId)}/${encodeURIComponent(boundary)}`\n\n/**\n * The journal source one drain's promotion record is written under.\n *\n * @param targetLineageId the lineage the boundary closed on\n * @param boundary the boundary name\n * @category constructors\n * @since 1.0.0\n */\nexport const drainSourceId = (targetLineageId: string, boundary: string): JournalEvent.SourceId =>\n  JournalEvent.SourceId.make(`${drainSourcePrefix}${drainKey(targetLineageId, boundary)}`)\n\nconst admissionSourcePrefix = \"/notifications/admission/\"\nconst drainSourcePrefix = \"/notifications/drain/\"\n\nconst decodeAdmitted = Schema.decodeUnknownOption(Admitted)\nconst decodePromoted = Schema.decodeUnknownOption(Promoted)\n\n/**\n * Decodes an owned notification event from a journal entry.\n *\n * Foreign entries and structurally invalid payloads decode to `None` so a\n * projection over a shared journal stays total.\n *\n * The event type alone does not make an entry owned: any producer on a shared\n * journal can choose one. An admission counts only under\n * {@link admissionSourceId} for the notification it carries, and a promotion\n * only under the `/notifications/drain/` source family the queue writes, so\n * another producer's record with the same event type stays out of the\n * projection. This scopes records; it does not authenticate the writer. The\n * journal fences writes on run ownership, not on source, so a writer that\n * sets this package's source id is read as this package. The drain check is\n * a prefix because records written before the lineage joined the identity\n * carry the boundary alone.\n *\n * @param entry one journal entry, owned or foreign\n * @category constructors\n * @since 0.1.0\n */\nexport const fromEntry = (entry: JournalEvent.Entry): Option.Option<Event> => {\n  if (entry.eventType === AdmittedEventType) {\n    return Option.filter(\n      decodeAdmitted(entry.payload),\n      (event) => entry.sourceId === admissionSourceId(event.notification.id)\n    )\n  }\n  if (entry.eventType === PromotedEventType && entry.sourceId.startsWith(drainSourcePrefix)) {\n    return decodePromoted(entry.payload)\n  }\n  return Option.none()\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,qBAA6B;AAC7B,aAAwB;AACxB,aAAwB;AACxB,mBAA8B;AAgBvB,MAAM,oBAAoB;AAU1B,MAAM,oBAAoB;AAa1B,MAAM,oBAAoB,OAAO,SAAS,CAAC,YAAY,aAAa,eAAe,CAAC;AAsBpF,MAAM,WAAW,OAAO,OAAO;AAAA,EACpC,cAAc,aAAa;AAAA,EAC3B,UAAU;AAAA;AAAA,EAEV,aAAa,OAAO,SAAS,OAAO,MAAM;AAAA,EAC1C,SAAS,OAAO,SAAS,OAAO,MAAM;AACxC,CAAC;AAqBM,MAAM,WAAW,OAAO,OAAO;AAAA,EACpC,UAAU,OAAO;AAAA,EACjB,iBAAiB,OAAO;AAAA,EACxB,KAAK,OAAO,MAAM,OAAO,MAAM;AACjC,CAAC;AA6BM,MAAM,aAAa,CAAC,UAAoC,kBAAkB;AAS1E,MAAM,aAAa,CAAC,UAAoC,CAAC,WAAW,KAAK;AASzE,MAAM,oBAAoB,CAAC,mBAChC,4BAAa,SAAS,KAAK,GAAG,qBAAqB,GAAG,cAAc,EAAE;AAWjE,MAAM,WAAW,CAAC,iBAAyB,aAChD,GAAG,mBAAmB,eAAe,CAAC,IAAI,mBAAmB,QAAQ,CAAC;AAUjE,MAAM,gBAAgB,CAAC,iBAAyB,aACrD,4BAAa,SAAS,KAAK,GAAG,iBAAiB,GAAG,SAAS,iBAAiB,QAAQ,CAAC,EAAE;AAEzF,MAAM,wBAAwB;AAC9B,MAAM,oBAAoB;AAE1B,MAAM,iBAAiB,OAAO,oBAAoB,QAAQ;AAC1D,MAAM,iBAAiB,OAAO,oBAAoB,QAAQ;AAuBnD,MAAM,YAAY,CAAC,UAAoD;AAC5E,MAAI,MAAM,cAAc,mBAAmB;AACzC,WAAO,OAAO;AAAA,MACZ,eAAe,MAAM,OAAO;AAAA,MAC5B,CAAC,UAAU,MAAM,aAAa,kBAAkB,MAAM,aAAa,EAAE;AAAA,IACvE;AAAA,EACF;AACA,MAAI,MAAM,cAAc,qBAAqB,MAAM,SAAS,WAAW,iBAAiB,GAAG;AACzF,WAAO,eAAe,MAAM,OAAO;AAAA,EACrC;AACA,SAAO,OAAO,KAAK;AACrB;",
+  "names": []
+}