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

package/dist/cjs/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/cjs/NotificationQueue.d.ts.map

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

package/dist/cjs/NotificationQueue.js

@@ -0,0 +1,477 @@
+"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 NotificationQueue_exports = {};
+__export(NotificationQueue_exports, {
+  NotificationError: () => NotificationError,
+  NotificationQueue: () => NotificationQueue,
+  layer: () => layer,
+  layerNoop: () => layerNoop,
+  layerWith: () => layerWith,
+  make: () => make,
+  makeNoop: () => makeNoop
+});
+module.exports = __toCommonJS(NotificationQueue_exports);
+var import_canonical = require("@smthrs/canonical");
+var import_Sha256 = require("@smthrs/crypto/Sha256");
+var import_journal = require("@smthrs/journal");
+var import_effect = require("effect");
+var FoldCache = __toESM(require("./internal/foldCache.js"), 1);
+var Replay = __toESM(require("./internal/replay.js"), 1);
+var NotificationModel = __toESM(require("./Notification.js"), 1);
+var NotificationEvent = __toESM(require("./NotificationEvent.js"), 1);
+var NotificationState = __toESM(require("./NotificationState.js"), 1);
+class NotificationError extends import_effect.Schema.TaggedError()(
+  "/notifications/NotificationError",
+  {
+    code: import_effect.Schema.Literals([
+      "notification_unavailable",
+      "notification_closed",
+      "notification_full",
+      "notification_id_reused",
+      "notification_invalid",
+      "notification_refused"
+    ]).pipe(
+      import_effect.Schema.withConstructorDefault(import_effect.Effect.succeed("notification_unavailable"))
+    ),
+    message: import_effect.Schema.String,
+    /** The notification the failure is about, when one was readable. */
+    notificationId: import_effect.Schema.optional(import_effect.Schema.String),
+    /** Dotted path of the offending field, for `notification_invalid`. */
+    path: import_effect.Schema.optional(import_effect.Schema.String)
+  }
+) {
+}
+class NotificationQueue extends import_effect.Context.Service()(
+  "/notifications/NotificationQueue"
+) {
+}
+const make = (implementation) => NotificationQueue.of(implementation);
+const unavailable = (operation) => new NotificationError({ code: "notification_unavailable", message: `${operation} is unavailable` });
+const makeNoop = (overrides = {}) => make({
+  admit: import_effect.Effect.fn("NotificationQueue.admit")(() => import_effect.Effect.fail(unavailable("admit"))),
+  drain: import_effect.Effect.fn("NotificationQueue.drain")(() => import_effect.Effect.fail(unavailable("drain"))),
+  pending: import_effect.Effect.fn("NotificationQueue.pending")(() => import_effect.Effect.fail(unavailable("pending"))),
+  ...overrides
+});
+const layerNoop = (overrides = {}) => import_effect.Layer.succeed(NotificationQueue)(makeNoop(overrides));
+const maximumPayloadDepth = 256;
+const maximumNotificationCodeUnits = 1048576;
+const maximumIssueCodeUnits = 200;
+const exceededBound = (value) => {
+  const pending = [{ value, depth: 0 }];
+  let size = 0;
+  while (pending.length > 0) {
+    const next = pending.pop();
+    size += typeof next.value === "string" ? next.value.length : 1;
+    if (size > maximumNotificationCodeUnits) return "size";
+    if (typeof next.value !== "object" || next.value === null) continue;
+    if (next.depth >= maximumPayloadDepth) return "depth";
+    if (Array.isArray(next.value)) {
+      for (const child of next.value) pending.push({ value: child, depth: next.depth + 1 });
+      continue;
+    }
+    for (const [key, child] of Object.entries(next.value)) {
+      size += key.length;
+      pending.push({ value: child, depth: next.depth + 1 });
+    }
+  }
+  return void 0;
+};
+const copied = (value) => {
+  if (Array.isArray(value)) return value.map(copied);
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, copied(nested)]));
+  }
+  return value;
+};
+const formatIssue = import_effect.SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue) => issue._tag });
+const bounded = (text) => text.length <= maximumIssueCodeUnits ? text : `${text.slice(0, maximumIssueCodeUnits - 3)}...`;
+const identifiedBy = (value) => {
+  if (typeof value !== "object" || value === null) return void 0;
+  const id = value["id"];
+  return typeof id === "string" ? id : void 0;
+};
+const decodeNotification = import_effect.Schema.decodeUnknownEffect(NotificationModel.Notification);
+const validated = (notification) => import_effect.Effect.gen(function* () {
+  const notificationId = identifiedBy(notification);
+  const exceeded = exceededBound(notification);
+  if (exceeded !== void 0) {
+    return yield* new NotificationError({
+      code: "notification_invalid",
+      message: exceeded === "depth" ? `A notification nests deeper than the ${maximumPayloadDepth} level bound` : `A notification is larger than the ${maximumNotificationCodeUnits} code unit bound`,
+      ...notificationId === void 0 ? {} : { notificationId }
+    });
+  }
+  return yield* decodeNotification(copied(notification)).pipe(
+    import_effect.Effect.mapError((error) => {
+      const issue = formatIssue(error.issue).issues[0];
+      const path = issue.path.map(String).join(".");
+      return new NotificationError({
+        code: "notification_invalid",
+        message: bounded(issue.message),
+        ...notificationId === void 0 ? {} : { notificationId },
+        ...path === "" ? {} : { path }
+      });
+    })
+  );
+});
+const canonical = (value) => (0, import_canonical.canonicalize)(value, { loneSurrogates: "escape" });
+const fingerprint = (notification) => import_effect.Effect.sync(() => (0, import_Sha256.digestSync)(canonical(notification)));
+const freeze = (value) => {
+  if (typeof value !== "object" || value === null) return;
+  for (const nested of Object.values(value)) freeze(nested);
+  Object.freeze(value);
+};
+const maximumCachedRuns = 64;
+const layerWith = (options = {}) => import_effect.Layer.effect(
+  NotificationQueue,
+  import_effect.Effect.gen(function* () {
+    const journal = yield* import_journal.Journal.Journal;
+    const operations = yield* import_effect.Semaphore.make(1);
+    const capacity = options.capacity ?? NotificationState.defaultCapacity;
+    const folded = FoldCache.make(maximumCachedRuns);
+    const entryAt = (runId, seq) => import_effect.Effect.map(
+      journal.entries({
+        runId,
+        ...seq === 0 ? {} : { after: import_journal.JournalEvent.Seq.make(seq - 1) },
+        limit: 1
+      }),
+      (page) => {
+        const found = page.entries[0];
+        return found !== void 0 && found.seq === seq ? import_effect.Option.some(found) : import_effect.Option.none();
+      }
+    );
+    const admittedAt = (runId, seq) => import_effect.Effect.map(entryAt(runId, seq), (entry) => {
+      if (import_effect.Option.isNone(entry)) return import_effect.Option.none();
+      const decoded = NotificationEvent.fromEntry(entry.value);
+      if (import_effect.Option.isNone(decoded) || !NotificationEvent.isAdmitted(decoded.value)) return import_effect.Option.none();
+      freeze(decoded.value.notification);
+      return import_effect.Option.some(decoded.value);
+    });
+    const promotedAt = (runId, seq) => import_effect.Effect.map(entryAt(runId, seq), (entry) => {
+      if (import_effect.Option.isNone(entry)) return import_effect.Option.none();
+      const decoded = NotificationEvent.fromEntry(entry.value);
+      if (import_effect.Option.isNone(decoded) || !NotificationEvent.isPromoted(decoded.value)) return import_effect.Option.none();
+      return import_effect.Option.some(decoded.value);
+    });
+    const load = (runId) => import_effect.Effect.gen(function* () {
+      const base = folded.get(runId) ?? {
+        state: NotificationState.empty(capacity),
+        admissions: import_effect.HashMap.empty(),
+        promotions: import_effect.HashMap.empty(),
+        cursor: void 0
+      };
+      const fresh = [];
+      let after = base.cursor === void 0 ? void 0 : import_journal.JournalEvent.Seq.make(base.cursor);
+      while (true) {
+        const page = yield* journal.entries({
+          runId,
+          eventTypes: [NotificationEvent.AdmittedEventType, NotificationEvent.PromotedEventType],
+          ...after === void 0 ? {} : { after },
+          limit: 512
+        });
+        fresh.push(...page.entries);
+        if (!page.hasMore || page.entries.length === 0) break;
+        after = page.entries.at(-1).seq;
+      }
+      if (fresh.length === 0) return base;
+      let state = base.state;
+      let cursor = base.cursor;
+      let admissions = base.admissions;
+      let promotions = base.promotions;
+      for (const entry of fresh) {
+        cursor = entry.seq;
+        const decoded = NotificationEvent.fromEntry(entry);
+        if (import_effect.Option.isNone(decoded)) continue;
+        const event = decoded.value;
+        if (NotificationEvent.isAdmitted(event)) {
+          freeze(event.notification);
+          admissions = import_effect.HashMap.set(admissions, event.notification.id, {
+            version: event.version,
+            fingerprint: event.fingerprint,
+            decision: event.decision,
+            seq: entry.seq
+          });
+          state = Replay.applyAdmitted(state, event, entry.seq);
+        } else {
+          promotions = import_effect.HashMap.set(
+            promotions,
+            NotificationEvent.drainKey(event.targetLineageId, event.boundary),
+            entry.seq
+          );
+          state = NotificationState.applyPromoted(state, event.ids);
+        }
+      }
+      const loaded = { state, admissions, promotions, cursor };
+      yield* journal.whenCommitted(import_effect.Effect.sync(() => folded.put(runId, loaded)));
+      return loaded;
+    });
+    const admitInTransaction = (runId, admitted, admittedFingerprint, version) => import_effect.Effect.gen(function* () {
+      const loaded = yield* load(runId);
+      const prior = import_effect.Option.getOrUndefined(import_effect.HashMap.get(loaded.admissions, admitted.id));
+      const replacing = prior !== void 0 && version !== void 0 && version > (prior.version ?? 0);
+      if (replacing) {
+        const original = yield* admittedAt(runId, prior.seq);
+        if (import_effect.Option.isNone(original)) {
+          return yield* new NotificationError({
+            code: "notification_unavailable",
+            notificationId: admitted.id,
+            message: "Original steering input is unreadable"
+          });
+        }
+        const identity = (input) => ({ ...input, payload: null });
+        if (canonical(identity(original.value.notification)) !== canonical(identity(admitted))) {
+          return yield* new NotificationError({
+            code: "notification_id_reused",
+            notificationId: admitted.id,
+            message: "An edit cannot change the notification owner or delivery binding"
+          });
+        }
+      }
+      if (replacing && !loaded.state.items.some((item) => item.notification.id === admitted.id)) {
+        const original = yield* admittedAt(runId, prior.seq);
+        if (import_effect.Option.isNone(original)) {
+          return yield* new NotificationError({
+            code: "notification_unavailable",
+            message: "Consumed input is unreadable"
+          });
+        }
+        return {
+          notificationId: admitted.id,
+          decision: prior.decision,
+          seq: prior.seq,
+          duplicate: true,
+          consumed: true,
+          consumedNotification: original.value.notification
+        };
+      }
+      if (prior !== void 0 && version !== void 0 && version < (prior.version ?? 0)) {
+        return { notificationId: admitted.id, decision: prior.decision, seq: prior.seq, duplicate: true };
+      }
+      if (prior !== void 0 && !replacing) {
+        let same = prior.fingerprint === admittedFingerprint;
+        if (prior.fingerprint === void 0) {
+          const original = yield* admittedAt(runId, prior.seq);
+          if (import_effect.Option.isNone(original)) {
+            return yield* new NotificationError({
+              code: "notification_unavailable",
+              notificationId: admitted.id,
+              message: `The admission for notification ${admitted.id} is no longer readable`
+            });
+          }
+          same = canonical(original.value.notification) === canonical(admitted);
+        }
+        if (!same) {
+          return yield* new NotificationError({
+            code: "notification_id_reused",
+            notificationId: admitted.id,
+            message: `Notification id ${admitted.id} was already admitted with different content`
+          });
+        }
+        return {
+          notificationId: admitted.id,
+          decision: prior.decision,
+          seq: prior.seq,
+          duplicate: true
+        };
+      }
+      const admission = replacing ? { decision: "coalesced" } : NotificationState.admit(
+        loaded.state,
+        admitted,
+        loaded.cursor === void 0 ? 0 : loaded.cursor + 1
+      );
+      if (admission.decision === "rejected-full") {
+        return {
+          notificationId: admitted.id,
+          decision: admission.decision,
+          seq: void 0,
+          duplicate: false
+        };
+      }
+      const receipt = yield* journal.emitDurableUnfenced(
+        new import_journal.JournalEvent.Input({
+          runId,
+          sourceId: NotificationEvent.admissionSourceId(admitted.id),
+          sourceSeq: import_journal.JournalEvent.SourceSeq.make(version ?? 0),
+          // The sequence is derived from the notification's own id, so
+          // a collision IS this admission observed twice. Comparing
+          // bytes instead would fail the second writer over `decision`,
+          // a field neither caller supplied and each derives from the
+          // fill level it happened to load at.
+          dedupe: "identity",
+          eventType: NotificationEvent.AdmittedEventType,
+          payload: {
+            notification: admitted,
+            decision: admission.decision,
+            fingerprint: admittedFingerprint,
+            ...version === void 0 ? {} : { version }
+          }
+        })
+      );
+      const committed = import_effect.Option.getOrUndefined(import_effect.HashMap.get((yield* load(runId)).admissions, admitted.id));
+      if (committed === void 0) {
+        return yield* new NotificationError({
+          code: "notification_id_reused",
+          notificationId: admitted.id,
+          message: `The journal identity for notification ${admitted.id} holds an event this queue did not write`
+        });
+      }
+      return {
+        notificationId: admitted.id,
+        decision: committed.decision,
+        seq: committed.seq,
+        duplicate: receipt._tag === "Duplicate"
+      };
+    });
+    return make({
+      admit: import_effect.Effect.fn("NotificationQueue.admit")(
+        (rawRunId, notification, version) => import_effect.Effect.gen(function* () {
+          if (version !== void 0 && (!Number.isSafeInteger(version) || version < 1)) {
+            return yield* new NotificationError({
+              code: "notification_invalid",
+              message: "version must be a positive safe integer"
+            });
+          }
+          const admitted = yield* validated(notification);
+          const payload = admitted.payload;
+          if (typeof payload === "object" && payload !== null && !Array.isArray(payload) && payload["kind"] === "outside_change") {
+            return yield* new NotificationError({
+              code: "notification_refused",
+              notificationId: admitted.id,
+              message: "Outside-change delivery requires authenticated watcher facts and stale-write enforcement"
+            });
+          }
+          const admittedFingerprint = yield* fingerprint(admitted);
+          return yield* journal.transact(
+            operations.withPermits(1)(
+              admitInTransaction(import_journal.JournalEvent.RunId.make(rawRunId), admitted, admittedFingerprint, version)
+            )
+          );
+        })
+      ),
+      drain: import_effect.Effect.fn("NotificationQueue.drain")(
+        (input) => journal.transact(
+          operations.withPermits(1)(import_effect.Effect.gen(function* () {
+            if (input.cutoffSeq !== void 0 && !(Number.isSafeInteger(input.cutoffSeq) && input.cutoffSeq >= 0)) {
+              return yield* new NotificationError({
+                code: "notification_invalid",
+                message: "A drain cutoff must be a non-negative integer journal sequence",
+                path: "cutoffSeq"
+              });
+            }
+            const runId = import_journal.JournalEvent.RunId.make(input.runId);
+            const key = NotificationEvent.drainKey(input.targetLineageId, input.boundary);
+            const loaded = yield* load(runId);
+            const delivered = (record, admissions) => import_effect.Effect.forEach(record.ids, (id) => import_effect.Effect.gen(function* () {
+              const committed2 = import_effect.HashMap.get(admissions, id);
+              const event = import_effect.Option.isNone(committed2) ? import_effect.Option.none() : yield* admittedAt(runId, committed2.value.seq);
+              if (import_effect.Option.isNone(event)) {
+                return yield* new NotificationError({
+                  code: "notification_unavailable",
+                  notificationId: id,
+                  message: `The delivered notification ${id} is no longer readable`
+                });
+              }
+              return event.value.notification;
+            }));
+            const replayed = (seq, admissions) => import_effect.Effect.gen(function* () {
+              const record = yield* promotedAt(runId, seq);
+              if (import_effect.Option.isNone(record)) {
+                return yield* new NotificationError({
+                  code: "notification_unavailable",
+                  message: `The drain record for boundary ${input.boundary} is no longer readable`
+                });
+              }
+              return {
+                notifications: yield* delivered(record.value, admissions),
+                boundary: input.boundary,
+                duplicate: true
+              };
+            });
+            const prior = import_effect.HashMap.get(loaded.promotions, key);
+            if (import_effect.Option.isSome(prior)) return yield* replayed(prior.value, loaded.admissions);
+            const cutoff = input.cutoffSeq ?? loaded.cursor ?? 0;
+            const promotionState = /^\d+:[a-f0-9]{64}:park:\d+$/.test(input.boundary) ? {
+              ...loaded.state,
+              items: loaded.state.items.filter((item) => {
+                const payload = item.notification.payload;
+                return !(typeof payload === "object" && payload !== null && !Array.isArray(payload) && payload.kind === "outside_change");
+              })
+            } : loaded.state;
+            const steers = NotificationState.promoteSteers(promotionState, cutoff, input.targetLineageId);
+            const queued = input.wouldIdle && steers.promoted.length === 0 ? NotificationState.promoteQueued(steers.state, input.targetLineageId) : { state: steers.state, promoted: [] };
+            const promoted = [...steers.promoted, ...queued.promoted].map((item) => item.notification);
+            const receipt = yield* journal.emitDurableUnfenced(
+              new import_journal.JournalEvent.Input({
+                runId,
+                sourceId: NotificationEvent.drainSourceId(input.targetLineageId, input.boundary),
+                sourceSeq: import_journal.JournalEvent.SourceSeq.make(0),
+                // The identity is the drain: this lineage closing this
+                // boundary. Two processes that both reach it have observed one
+                // event, and the first record committed is the delivery.
+                dedupe: "identity",
+                eventType: NotificationEvent.PromotedEventType,
+                payload: {
+                  boundary: input.boundary,
+                  targetLineageId: input.targetLineageId,
+                  ids: promoted.map((notification) => notification.id)
+                }
+              })
+            );
+            const settled = yield* load(runId);
+            const committed = import_effect.HashMap.get(settled.promotions, key);
+            if (import_effect.Option.isNone(committed)) {
+              return yield* new NotificationError({
+                code: "notification_unavailable",
+                message: `The journal identity for boundary ${input.boundary} holds an event this queue did not write`
+              });
+            }
+            if (receipt._tag === "Accepted") {
+              return { notifications: promoted, boundary: input.boundary, duplicate: false };
+            }
+            return yield* replayed(committed.value, settled.admissions);
+          }))
+        )
+      ),
+      pending: import_effect.Effect.fn("NotificationQueue.pending")(
+        (rawRunId) => import_effect.Effect.map(
+          load(import_journal.JournalEvent.RunId.make(rawRunId)),
+          // The fold `load` already performs: admissions add, promotions
+          // remove. Read outside the operations semaphore, because a count
+          // taken while a boundary drains is a count taken at some instant
+          // either side of it, and blocking a supervisor behind a turn
+          // boundary would be the worse answer.
+          (loaded) => loaded.state.items.map((item) => item.notification)
+        )
+      )
+    });
+  })
+);
+const layer = layerWith();
+//# sourceMappingURL=NotificationQueue.js.map