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

package/dist/esm/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/esm/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/esm/Notification.js

@@ -0,0 +1,121 @@
+/**
+ * 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 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 const Provenance = Schema.Struct({
+    sourceRunId: Schema.String,
+    sourceLineageId: Schema.String,
+    sourceTurn: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    sourceActor: Schema.String,
+    attribution: Schema.optional(Attribution)
+});
+const common = {
+    id: Schema.NonEmptyString,
+    targetLineageId: Schema.NonEmptyString,
+    provenance: Provenance,
+    payload: Schema.Json
+};
+/**
+ * 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 const HumanSteer = Schema.TaggedStruct("human-steer", {
+    ...common,
+    delivery: Schema.Literal("steer")
+});
+/**
+ * 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 const HumanFollowup = Schema.TaggedStruct("human-followup", {
+    ...common,
+    delivery: Schema.Literal("queue")
+});
+/**
+ * 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 const SystemEvent = Schema.TaggedStruct("system-event", {
+    ...common,
+    delivery: Schema.Literal("queue"),
+    coalescingKey: Schema.optional(Schema.String)
+});
+/**
+ * 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 const Notification = Schema.Union([HumanSteer, HumanFollowup, SystemEvent]);
+/**
+ * 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 const admissionClass = (notification) => notification.delivery;
+/**
+ * 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 const coalesceKey = (notification) => notification._tag === "system-event" ? notification.coalescingKey ?? null : null;
+//# sourceMappingURL=Notification.js.map

package/dist/esm/Notification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Notification.js","sourceRoot":"","sources":["../../src/Notification.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC,MAAM;IAC1B,eAAe,EAAE,MAAM,CAAC,MAAM;IAC9B,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,WAAW,EAAE,MAAM,CAAC,MAAM;IAC1B,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC;CAC1C,CAAC,CAAA;AAUF,MAAM,MAAM,GAAG;IACb,EAAE,EAAE,MAAM,CAAC,cAAc;IACzB,eAAe,EAAE,MAAM,CAAC,cAAc;IACtC,UAAU,EAAE,UAAU;IACtB,OAAO,EAAE,MAAM,CAAC,IAAI;CACrB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE;IAC3D,GAAG,MAAM;IACT,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;CAClC,CAAC,CAAA;AAUF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,YAAY,CAAC,gBAAgB,EAAE;IACjE,GAAG,MAAM;IACT,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;CAClC,CAAC,CAAA;AAUF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,YAAY,CAAC,cAAc,EAAE;IAC7D,GAAG,MAAM;IACT,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CAC9C,CAAC,CAAA;AAUF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC,CAAA;AAUlF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,YAA0B,EAAqB,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAA;AAEtG;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,YAA0B,EAAiB,EAAE,CACvE,YAAY,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA","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"]}

package/dist/esm/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/esm/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"}