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

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"}

package/dist/esm/NotificationEvent.js

@@ -0,0 +1,158 @@
+/**
+ * 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";
+import * as Notification from "./Notification.js";
+/**
+ * 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 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 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 const AdmissionDecision = Schema.Literals(["admitted", "coalesced", "rejected-full"]);
+/**
+ * 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 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)
+});
+/**
+ * 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 const Promoted = Schema.Struct({
+    boundary: Schema.String,
+    targetLineageId: Schema.String,
+    ids: Schema.Array(Schema.String)
+});
+/**
+ * Whether an owned event is an admission record.
+ *
+ * @param event an owned event
+ * @category refinements
+ * @since 1.0.0
+ */
+export const isAdmitted = (event) => "notification" in event;
+/**
+ * Whether an owned event is a promotion record.
+ *
+ * @param event an owned event
+ * @category refinements
+ * @since 1.0.0
+ */
+export const isPromoted = (event) => !isAdmitted(event);
+/**
+ * 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 const admissionSourceId = (notificationId) => JournalEvent.SourceId.make(`${admissionSourcePrefix}${notificationId}`);
+/**
+ * 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 const drainKey = (targetLineageId, boundary) => `${encodeURIComponent(targetLineageId)}/${encodeURIComponent(boundary)}`;
+/**
+ * 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 const drainSourceId = (targetLineageId, boundary) => 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);
+/**
+ * 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 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/esm/NotificationEvent.js.map

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

package/dist/esm/NotificationQueue.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Journal-backed durable notification admission and turn-boundary drain.
+ *
+ * Governing contract: `packages/smithers/notifications/docs/api.md`, published as
+ * `/api/notifications`.
+ *
+ * @since 0.1.0
+ */
+import { Journal } from "@smthrs/journal";
+import { Context, Effect, Layer, Schema } from "effect";
+import * as NotificationModel from "./Notification.ts";
+import * as NotificationState from "./NotificationState.ts";
+declare const NotificationError_base: Schema.Class<NotificationError, Schema.TaggedStruct<"/notifications/NotificationError", {
+    readonly code: Schema.withConstructorDefault<Schema.Literals<readonly ["notification_unavailable", "notification_closed", "notification_full", "notification_id_reused", "notification_invalid", "notification_refused"]>>;
+    readonly message: Schema.String;
+    /** The notification the failure is about, when one was readable. */
+    readonly notificationId: Schema.optional<Schema.String>;
+    /** Dotted path of the offending field, for `notification_invalid`. */
+    readonly path: Schema.optional<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The queue could not be reached, or it refused what a caller handed it.
+ *
+ * `code` is the stable half and the one to branch on. `notification_unavailable`
+ * is the seam reporting that it serves nothing; `notification_id_reused` says a
+ * stable id was admitted once already with different content, which is a
+ * producer bug rather than a storage failure; `notification_invalid` says the
+ * value is not a notification, and `path` names the field inside it that failed.
+ * `notification_closed` means the receiver has finished and the caller must
+ * start a new request; `notification_full` means nothing was retained and the
+ * same notification may be retried after pending work drains. Neither the
+ * message nor `path` ever carries the offending value.
+ * `notification_refused` rejects reserved outside-change payloads before admission.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class NotificationError extends NotificationError_base {
+}
+/**
+ * What admitting one notification decided.
+ *
+ * `seq` is the journal sequence the admission committed at, and it is absent
+ * exactly when nothing was written, which today means a `rejected-full`
+ * refusal. `duplicate` says the id was already admitted, in which case
+ * `decision` and `seq` are read back from the committed record rather than
+ * recomputed here.
+ *
+ * A caller MUST inspect `decision`: `rejected-full` means the queue was at
+ * capacity and retained nothing, so the notification never reaches the model
+ * unless the caller admits it again once a boundary has drained.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface AdmissionReceipt {
+    readonly notificationId: string;
+    readonly decision: NotificationState.AdmissionDecision;
+    readonly seq: number | undefined;
+    readonly duplicate: boolean;
+    readonly consumed?: boolean;
+    readonly consumedNotification?: NotificationModel.Notification;
+}
+/**
+ * The boundary a drain is attempted at, and whether the run would go idle
+ * if nothing were delivered.
+ *
+ * `(runId, targetLineageId, boundary)` is the unit of drain: two lineages
+ * closing a turn under the same boundary name are two drains, and each is
+ * recorded separately.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DrainInput {
+    readonly runId: string;
+    readonly targetLineageId: string;
+    readonly boundary: string;
+    readonly wouldIdle: boolean;
+    /**
+     * The journal sequence that opened this turn. A steer admitted after it is
+     * held for the next boundary, which is what keeps a message that arrived
+     * mid-turn out of the turn already in flight. Omitting it delivers
+     * everything pending for the lineage. A value that is not a non-negative
+     * integer fails the drain with `notification_invalid` and records nothing.
+     */
+    readonly cutoffSeq?: number | undefined;
+}
+/**
+ * The notifications this boundary delivers, and whether the boundary had
+ * already drained.
+ *
+ * The notifications are the ones the committed promotion record names, so two
+ * processes draining one boundary report the same delivery rather than two
+ * divergent guesses.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DrainReceipt {
+    readonly notifications: ReadonlyArray<NotificationModel.Notification>;
+    readonly boundary: string;
+    readonly duplicate: boolean;
+}
+/**
+ * The durable pending queue: admit a notification exactly once, and drain
+ * what a boundary is allowed to deliver.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly admit: (runId: string, notification: NotificationModel.Notification, version?: number) => Effect.Effect<AdmissionReceipt, Journal.JournalError | NotificationError>;
+    readonly drain: (input: DrainInput) => Effect.Effect<DrainReceipt, Journal.JournalError | NotificationError>;
+    /**
+     * What this run has been told that no boundary has delivered yet, in
+     * admission order.
+     *
+     * The queue is the owner of that fact: pending is admitted minus promoted,
+     * and both halves are its own journal records. A supervisor that counted
+     * admissions alone would report a steer as waiting forever.
+     */
+    readonly pending: (runId: string) => Effect.Effect<ReadonlyArray<NotificationModel.Notification>, Journal.JournalError | NotificationError>;
+}
+declare const NotificationQueue_base: Context.ServiceClass<NotificationQueue, "/notifications/NotificationQueue", Service>;
+/**
+ * The {@link Service} tag.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class NotificationQueue extends NotificationQueue_base {
+}
+/**
+ * Builds a {@link Service} from an implementation of its methods.
+ *
+ * @param implementation the methods to serve
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (implementation: Service) => Service;
+/**
+ * A {@link Service} that fails every method as unavailable. Overrides
+ * replace individual methods.
+ *
+ * @param overrides methods to serve instead of failing
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @param overrides methods to serve instead of failing
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: (overrides?: Partial<Service>) => Layer.Layer<NotificationQueue>;
+/**
+ * Journal-backed production layer, with the pending capacity a composition
+ * chooses.
+ *
+ * Admission and drain evidence is written through `emitDurableUnfenced`, so
+ * both return only after the corresponding entry is durably committed and a
+ * dropped lifecycle event is unrepresentable. The channel is the unfenced one
+ * on purpose: the notifying process owns no run, so there is no ownership
+ * fence to hand over, and both records are first-writer-wins on their own
+ * identity instead.
+ *
+ * The capacity guard is a conditional write at the storage layer, not a check
+ * against a fold one process happened to load: the fold, the guard, and the
+ * admission record are decided and written inside ONE `journal.transact`
+ * write transaction, which the durable writer serializes against every other
+ * writer of the database and replays when a concurrent writer commits between
+ * the guard's reads and the insert. Two processes admitting to one full queue
+ * therefore produce one admission and one `rejected-full`, never two
+ * admissions.
+ *
+ * @param options the pending capacity, defaulting to `NotificationState.defaultCapacity`
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerWith: (options?: {
+    readonly capacity?: number | undefined;
+}) => Layer.Layer<NotificationQueue, never, Journal.Journal>;
+/**
+ * Journal-backed production layer at the default capacity.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<NotificationQueue, never, Journal.Journal>;
+export {};
+//# sourceMappingURL=NotificationQueue.d.ts.map

package/dist/esm/NotificationQueue.d.ts.map

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