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

package/dist/esm/SteerPayload.d.ts

@@ -0,0 +1,177 @@
+/**
+ * The steering vocabulary carried inside a notification payload.
+ *
+ * A steer crosses two packages that must not depend on each other. A control
+ * plane admits it into the durable queue; a harness drains it at a turn
+ * boundary and turns it into a change the model sees. Both depend on this
+ * package, so the shape they have to agree on lives here rather than in
+ * either of them.
+ *
+ * The payload is stored as JSON in the journal, which makes decoding the
+ * interesting half. Only a `human-steer` or `human-followup` carries a steer: a
+ * `system-event` decodes as nothing whatever its payload says, because system
+ * events carry webhook bodies and machine reports, and reading one as an
+ * instruction would let its producer message the model or change its seat,
+ * thinking, or tools. Inside a human notification, a record carrying a `body`
+ * string and no `kind` decodes as a message, because that is what a minimal
+ * caller means by it: the control plane's steer RPC accepts the same shape. A
+ * payload this module cannot classify decodes as nothing at all.
+ *
+ * @since 0.1.0
+ */
+import { Schema } from "effect";
+import type * as Notification from "./Notification.ts";
+/**
+ * How hard the model should think.
+ *
+ * A subset of `ModelRequest.ReasoningEffort` in `@smthrs/model`, which this
+ * package deliberately does not depend on: a durable payload schema that
+ * pulled in a provider client would make every queue reader carry one. Every
+ * literal here is one of that schema's, so the harness assigns a `Thinking`
+ * to a `ReasoningEffort` directly; `ReasoningEffort` also admits `"max"`,
+ * which steering does not offer.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Thinking: Schema.Literals<readonly ["none", "minimal", "low", "medium", "high", "xhigh"]>;
+/**
+ * How hard the model should think.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Thinking = typeof Thinking.Type;
+/**
+ * A message inserted into the transcript at the next turn boundary.
+ *
+ * The body may be empty. An operator who steers an empty message has still told
+ * the run something: that a human is watching, and that the turn should
+ * continue. Refusing it here would turn a deliberate nudge into a lost steer.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const MessagePayload: Schema.Struct<{
+    readonly kind: Schema.Literal<"Message">;
+    readonly body: Schema.String;
+}>;
+/**
+ * The decoded form of {@link MessagePayload}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type MessagePayload = typeof MessagePayload.Type;
+/**
+ * A model-seat change that applies from the next turn on.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const SeatPayload: Schema.Struct<{
+    readonly kind: Schema.Literal<"Seat">;
+    readonly seat: Schema.NonEmptyString;
+}>;
+/**
+ * The decoded form of {@link SeatPayload}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SeatPayload = typeof SeatPayload.Type;
+/**
+ * A thinking-level change that applies from the next turn on.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const ThinkingPayload: Schema.Struct<{
+    readonly kind: Schema.Literal<"Thinking">;
+    readonly thinking: Schema.Literals<readonly ["none", "minimal", "low", "medium", "high", "xhigh"]>;
+}>;
+/**
+ * The decoded form of {@link ThinkingPayload}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ThinkingPayload = typeof ThinkingPayload.Type;
+/**
+ * Tools added to the active set for future turns.
+ *
+ * Additive only: steering can widen what the agent may reach for, and cannot
+ * narrow it, because a turn already in flight may hold a call to a tool a
+ * narrowing steer would have removed.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const ToolsPayload: Schema.Struct<{
+    readonly kind: Schema.Literal<"Tools">;
+    readonly toolNames: Schema.NonEmptyArray<Schema.NonEmptyString>;
+}>;
+/**
+ * The decoded form of {@link ToolsPayload}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ToolsPayload = typeof ToolsPayload.Type;
+/**
+ * Any steering item a notification payload can carry.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const SteerPayload: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"Message">;
+    readonly body: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"Seat">;
+    readonly seat: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"Thinking">;
+    readonly thinking: Schema.Literals<readonly ["none", "minimal", "low", "medium", "high", "xhigh"]>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"Tools">;
+    readonly toolNames: Schema.NonEmptyArray<Schema.NonEmptyString>;
+}>]>;
+/**
+ * Any steering item a notification payload can carry.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SteerPayload = typeof SteerPayload.Type;
+/**
+ * Reads a notification as a steering item, or reports that it is not one.
+ *
+ * The notification, not its payload, is the argument: a `system-event` is
+ * never a steer, so the classification cannot be separated from who sent it.
+ *
+ * @param notification the admitted notification
+ * @category conversions
+ * @since 0.1.0
+ */
+export declare const decode: (notification: Notification.Notification) => SteerPayload | undefined;
+/**
+ * The payload a steering item is stored as.
+ *
+ * Every item is written with its `kind`, including a message: the body-only
+ * form is read as a convenience and never written.
+ *
+ * The result is typed as the item itself. Every item is JSON, so it is
+ * assignable to `Notification.payload` without an assertion.
+ *
+ * The returned record shares no mutable structure with `item`. A caller hands
+ * the result to an admission that serializes it later, so an array still
+ * aliased to the caller could change what is durably journaled after the call
+ * returned.
+ *
+ * @param item the steering item
+ * @category conversions
+ * @since 0.1.0
+ */
+export declare const encode: (item: SteerPayload) => SteerPayload;
+//# sourceMappingURL=SteerPayload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SteerPayload.d.ts","sourceRoot":"","sources":["../../src/SteerPayload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEtD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,iFAAyE,CAAA;AAE9F;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc;;;EAGzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;EAGtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;EAG1B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY;;;EAGvB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;IAA6E,CAAA;AAEtG;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AASnD;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,GAAI,cAAc,YAAY,CAAC,YAAY,KAAG,YAAY,GAAG,SAW/E,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,YAAY,KAAG,YACuC,CAAA"}

package/dist/esm/SteerPayload.js

@@ -0,0 +1,139 @@
+/**
+ * The steering vocabulary carried inside a notification payload.
+ *
+ * A steer crosses two packages that must not depend on each other. A control
+ * plane admits it into the durable queue; a harness drains it at a turn
+ * boundary and turns it into a change the model sees. Both depend on this
+ * package, so the shape they have to agree on lives here rather than in
+ * either of them.
+ *
+ * The payload is stored as JSON in the journal, which makes decoding the
+ * interesting half. Only a `human-steer` or `human-followup` carries a steer: a
+ * `system-event` decodes as nothing whatever its payload says, because system
+ * events carry webhook bodies and machine reports, and reading one as an
+ * instruction would let its producer message the model or change its seat,
+ * thinking, or tools. Inside a human notification, a record carrying a `body`
+ * string and no `kind` decodes as a message, because that is what a minimal
+ * caller means by it: the control plane's steer RPC accepts the same shape. A
+ * payload this module cannot classify decodes as nothing at all.
+ *
+ * @since 0.1.0
+ */
+import { Schema } from "effect";
+/**
+ * How hard the model should think.
+ *
+ * A subset of `ModelRequest.ReasoningEffort` in `@smthrs/model`, which this
+ * package deliberately does not depend on: a durable payload schema that
+ * pulled in a provider client would make every queue reader carry one. Every
+ * literal here is one of that schema's, so the harness assigns a `Thinking`
+ * to a `ReasoningEffort` directly; `ReasoningEffort` also admits `"max"`,
+ * which steering does not offer.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Thinking = Schema.Literals(["none", "minimal", "low", "medium", "high", "xhigh"]);
+/**
+ * A message inserted into the transcript at the next turn boundary.
+ *
+ * The body may be empty. An operator who steers an empty message has still told
+ * the run something: that a human is watching, and that the turn should
+ * continue. Refusing it here would turn a deliberate nudge into a lost steer.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const MessagePayload = Schema.Struct({
+    kind: Schema.Literal("Message"),
+    body: Schema.String
+});
+/**
+ * A model-seat change that applies from the next turn on.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const SeatPayload = Schema.Struct({
+    kind: Schema.Literal("Seat"),
+    seat: Schema.NonEmptyString
+});
+/**
+ * A thinking-level change that applies from the next turn on.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const ThinkingPayload = Schema.Struct({
+    kind: Schema.Literal("Thinking"),
+    thinking: Thinking
+});
+/**
+ * Tools added to the active set for future turns.
+ *
+ * Additive only: steering can widen what the agent may reach for, and cannot
+ * narrow it, because a turn already in flight may hold a call to a tool a
+ * narrowing steer would have removed.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const ToolsPayload = Schema.Struct({
+    kind: Schema.Literal("Tools"),
+    toolNames: Schema.NonEmptyArray(Schema.NonEmptyString)
+});
+/**
+ * Any steering item a notification payload can carry.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const SteerPayload = Schema.Union([MessagePayload, SeatPayload, ThinkingPayload, ToolsPayload]);
+const parse = Schema.decodeUnknownOption(SteerPayload);
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * Reads a notification as a steering item, or reports that it is not one.
+ *
+ * The notification, not its payload, is the argument: a `system-event` is
+ * never a steer, so the classification cannot be separated from who sent it.
+ *
+ * @param notification the admitted notification
+ * @category conversions
+ * @since 0.1.0
+ */
+export const decode = (notification) => {
+    if (notification._tag === "system-event")
+        return undefined;
+    const fields = record(notification.payload);
+    if (fields === undefined)
+        return undefined;
+    // A record with a body and no kind is a message: it is the shape a caller
+    // writes when it has nothing else to say.
+    const candidate = fields["kind"] === undefined && typeof fields["body"] === "string"
+        ? { kind: "Message", body: fields["body"] }
+        : fields;
+    const decoded = parse(candidate);
+    return decoded._tag === "Some" ? decoded.value : undefined;
+};
+/**
+ * The payload a steering item is stored as.
+ *
+ * Every item is written with its `kind`, including a message: the body-only
+ * form is read as a convenience and never written.
+ *
+ * The result is typed as the item itself. Every item is JSON, so it is
+ * assignable to `Notification.payload` without an assertion.
+ *
+ * The returned record shares no mutable structure with `item`. A caller hands
+ * the result to an admission that serializes it later, so an array still
+ * aliased to the caller could change what is durably journaled after the call
+ * returned.
+ *
+ * @param item the steering item
+ * @category conversions
+ * @since 0.1.0
+ */
+export const encode = (item) => item.kind === "Tools" ? { ...item, toolNames: [...item.toolNames] } : { ...item };
+//# sourceMappingURL=SteerPayload.js.map

package/dist/esm/SteerPayload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SteerPayload.js","sourceRoot":"","sources":["../../src/SteerPayload.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The steering vocabulary carried inside a notification payload.\n *\n * A steer crosses two packages that must not depend on each other. A control\n * plane admits it into the durable queue; a harness drains it at a turn\n * boundary and turns it into a change the model sees. Both depend on this\n * package, so the shape they have to agree on lives here rather than in\n * either of them.\n *\n * The payload is stored as JSON in the journal, which makes decoding the\n * interesting half. Only a `human-steer` or `human-followup` carries a steer: a\n * `system-event` decodes as nothing whatever its payload says, because system\n * events carry webhook bodies and machine reports, and reading one as an\n * instruction would let its producer message the model or change its seat,\n * thinking, or tools. Inside a human notification, a record carrying a `body`\n * string and no `kind` decodes as a message, because that is what a minimal\n * caller means by it: the control plane's steer RPC accepts the same shape. A\n * payload this module cannot classify decodes as nothing at all.\n *\n * @since 0.1.0\n */\n\nimport { Schema } from \"effect\"\nimport type * as Notification from \"./Notification.ts\"\n\n/**\n * How hard the model should think.\n *\n * A subset of `ModelRequest.ReasoningEffort` in `@smthrs/model`, which this\n * package deliberately does not depend on: a durable payload schema that\n * pulled in a provider client would make every queue reader carry one. Every\n * literal here is one of that schema's, so the harness assigns a `Thinking`\n * to a `ReasoningEffort` directly; `ReasoningEffort` also admits `\"max\"`,\n * which steering does not offer.\n *\n * @category models\n * @since 0.1.0\n */\nexport const Thinking = Schema.Literals([\"none\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\"])\n\n/**\n * How hard the model should think.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Thinking = typeof Thinking.Type\n\n/**\n * A message inserted into the transcript at the next turn boundary.\n *\n * The body may be empty. An operator who steers an empty message has still told\n * the run something: that a human is watching, and that the turn should\n * continue. Refusing it here would turn a deliberate nudge into a lost steer.\n *\n * @category models\n * @since 0.1.0\n */\nexport const MessagePayload = Schema.Struct({\n  kind: Schema.Literal(\"Message\"),\n  body: Schema.String\n})\n\n/**\n * The decoded form of {@link MessagePayload}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type MessagePayload = typeof MessagePayload.Type\n\n/**\n * A model-seat change that applies from the next turn on.\n *\n * @category models\n * @since 0.1.0\n */\nexport const SeatPayload = Schema.Struct({\n  kind: Schema.Literal(\"Seat\"),\n  seat: Schema.NonEmptyString\n})\n\n/**\n * The decoded form of {@link SeatPayload}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type SeatPayload = typeof SeatPayload.Type\n\n/**\n * A thinking-level change that applies from the next turn on.\n *\n * @category models\n * @since 0.1.0\n */\nexport const ThinkingPayload = Schema.Struct({\n  kind: Schema.Literal(\"Thinking\"),\n  thinking: Thinking\n})\n\n/**\n * The decoded form of {@link ThinkingPayload}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type ThinkingPayload = typeof ThinkingPayload.Type\n\n/**\n * Tools added to the active set for future turns.\n *\n * Additive only: steering can widen what the agent may reach for, and cannot\n * narrow it, because a turn already in flight may hold a call to a tool a\n * narrowing steer would have removed.\n *\n * @category models\n * @since 0.1.0\n */\nexport const ToolsPayload = Schema.Struct({\n  kind: Schema.Literal(\"Tools\"),\n  toolNames: Schema.NonEmptyArray(Schema.NonEmptyString)\n})\n\n/**\n * The decoded form of {@link ToolsPayload}.\n *\n * @category models\n * @since 0.1.0\n */\nexport type ToolsPayload = typeof ToolsPayload.Type\n\n/**\n * Any steering item a notification payload can carry.\n *\n * @category models\n * @since 0.1.0\n */\nexport const SteerPayload = Schema.Union([MessagePayload, SeatPayload, ThinkingPayload, ToolsPayload])\n\n/**\n * Any steering item a notification payload can carry.\n *\n * @category models\n * @since 0.1.0\n */\nexport type SteerPayload = typeof SteerPayload.Type\n\nconst parse = Schema.decodeUnknownOption(SteerPayload)\n\nconst record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value)\n    ? value as Readonly<Record<string, unknown>>\n    : undefined\n\n/**\n * Reads a notification as a steering item, or reports that it is not one.\n *\n * The notification, not its payload, is the argument: a `system-event` is\n * never a steer, so the classification cannot be separated from who sent it.\n *\n * @param notification the admitted notification\n * @category conversions\n * @since 0.1.0\n */\nexport const decode = (notification: Notification.Notification): SteerPayload | undefined => {\n  if (notification._tag === \"system-event\") return undefined\n  const fields = record(notification.payload)\n  if (fields === undefined) return undefined\n  // A record with a body and no kind is a message: it is the shape a caller\n  // writes when it has nothing else to say.\n  const candidate = fields[\"kind\"] === undefined && typeof fields[\"body\"] === \"string\"\n    ? { kind: \"Message\", body: fields[\"body\"] }\n    : fields\n  const decoded = parse(candidate)\n  return decoded._tag === \"Some\" ? decoded.value : undefined\n}\n\n/**\n * The payload a steering item is stored as.\n *\n * Every item is written with its `kind`, including a message: the body-only\n * form is read as a convenience and never written.\n *\n * The result is typed as the item itself. Every item is JSON, so it is\n * assignable to `Notification.payload` without an assertion.\n *\n * The returned record shares no mutable structure with `item`. A caller hands\n * the result to an admission that serializes it later, so an array still\n * aliased to the caller could change what is durably journaled after the call\n * returned.\n *\n * @param item the steering item\n * @category conversions\n * @since 0.1.0\n */\nexport const encode = (item: SteerPayload): SteerPayload =>\n  item.kind === \"Tools\" ? { ...item, toolNames: [...item.toolNames] } : { ...item }\n"]}

package/dist/esm/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Durable notification queue services.
+ *
+ * @since 0.1.0
+ */
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as Alerts from "./Alerts.ts";
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as Notification from "./Notification.ts";
+/**
+ * @category events
+ * @since 0.1.0
+ */
+export * as NotificationEvent from "./NotificationEvent.ts";
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as NotificationState from "./NotificationState.ts";
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as NotificationQueue from "./NotificationQueue.ts";
+/**
+ * @category projections
+ * @since 0.1.0
+ */
+export * as Projection from "./Projection.ts";
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as SteerPayload from "./SteerPayload.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;GAGG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA;AAE3D;;;GAGG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA;AAE3D;;;GAGG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA;AAE3D;;;GAGG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;;GAGG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA"}

package/dist/esm/index.js

@@ -0,0 +1,41 @@
+/**
+ * Durable notification queue services.
+ *
+ * @since 0.1.0
+ */
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as Alerts from "./Alerts.js";
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as Notification from "./Notification.js";
+/**
+ * @category events
+ * @since 0.1.0
+ */
+export * as NotificationEvent from "./NotificationEvent.js";
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as NotificationState from "./NotificationState.js";
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as NotificationQueue from "./NotificationQueue.js";
+/**
+ * @category projections
+ * @since 0.1.0
+ */
+export * as Projection from "./Projection.js";
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as SteerPayload from "./SteerPayload.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD;;;GAGG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA;AAE3D;;;GAGG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA;AAE3D;;;GAGG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA;AAE3D;;;GAGG;AACH,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAE7C;;;GAGG;AACH,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA","sourcesContent":["/**\n * Durable notification queue services.\n *\n * @since 0.1.0\n */\n\n/**\n * @category services\n * @since 0.1.0\n */\nexport * as Alerts from \"./Alerts.ts\"\n\n/**\n * @category models\n * @since 0.1.0\n */\nexport * as Notification from \"./Notification.ts\"\n\n/**\n * @category events\n * @since 0.1.0\n */\nexport * as NotificationEvent from \"./NotificationEvent.ts\"\n\n/**\n * @category models\n * @since 0.1.0\n */\nexport * as NotificationState from \"./NotificationState.ts\"\n\n/**\n * @category services\n * @since 0.1.0\n */\nexport * as NotificationQueue from \"./NotificationQueue.ts\"\n\n/**\n * @category projections\n * @since 0.1.0\n */\nexport * as Projection from \"./Projection.ts\"\n\n/**\n * @category models\n * @since 0.1.0\n */\nexport * as SteerPayload from \"./SteerPayload.ts\"\n"]}

package/dist/esm/internal/foldCache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bounded, scan-resistant retention for the per-run folds a journal reader
+ * keeps in memory.
+ *
+ * @private
+ * @since 1.0.0
+ */
+/**
+ * A bounded per-run fold cache.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export interface FoldCache<A> {
+    readonly get: (key: string) => A | undefined;
+    readonly put: (key: string, value: A) => void;
+}
+/**
+ * A bounded map of per-run folds that a sweep wider than the bound cannot
+ * empty.
+ *
+ * Least-recently-used eviction has a zero hit rate under exactly the workload
+ * a supervisor produces: an ordered sweep of `bound + 1` runs evicts the fold
+ * the next read is about to want, so every poll replays every journal from
+ * sequence zero instead of reading its tail. Under pressure this instead
+ * sacrifices the NEWEST fold no later read has reused, so a sweep of any width
+ * keeps every fold it has read twice and pays for its width in a fixed handful
+ * of refolds. Only when every retained fold has been reused does it fall back
+ * to evicting the oldest, and it then clears the reuse marks so a fold cannot
+ * hold a slot on one ancient read forever.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const make: <A>(bound: number) => FoldCache<A>;
+//# sourceMappingURL=foldCache.d.ts.map

package/dist/esm/internal/foldCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foldCache.d.ts","sourceRoot":"","sources":["../../../src/internal/foldCache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;;GAKG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;CAC9C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,OAAO,MAAM,KAAG,SAAS,CAAC,CAAC,CA6BlD,CAAA"}

package/dist/esm/internal/foldCache.js

@@ -0,0 +1,58 @@
+/**
+ * Bounded, scan-resistant retention for the per-run folds a journal reader
+ * keeps in memory.
+ *
+ * @private
+ * @since 1.0.0
+ */
+/**
+ * A bounded map of per-run folds that a sweep wider than the bound cannot
+ * empty.
+ *
+ * Least-recently-used eviction has a zero hit rate under exactly the workload
+ * a supervisor produces: an ordered sweep of `bound + 1` runs evicts the fold
+ * the next read is about to want, so every poll replays every journal from
+ * sequence zero instead of reading its tail. Under pressure this instead
+ * sacrifices the NEWEST fold no later read has reused, so a sweep of any width
+ * keeps every fold it has read twice and pays for its width in a fixed handful
+ * of refolds. Only when every retained fold has been reused does it fall back
+ * to evicting the oldest, and it then clears the reuse marks so a fold cannot
+ * hold a slot on one ancient read forever.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const make = (bound) => {
+    const held = new Map();
+    return {
+        get: (key) => {
+            const entry = held.get(key);
+            if (entry === undefined)
+                return undefined;
+            entry.reused = true;
+            return entry.value;
+        },
+        put: (key, value) => {
+            const existing = held.get(key);
+            if (existing !== undefined) {
+                existing.value = value;
+                return;
+            }
+            if (held.size >= bound) {
+                let victim;
+                for (const [candidate, entry] of held) {
+                    if (!entry.reused)
+                        victim = candidate;
+                }
+                if (victim === undefined) {
+                    victim = held.keys().next().value;
+                    for (const entry of held.values())
+                        entry.reused = false;
+                }
+                held.delete(victim);
+            }
+            held.set(key, { value, reused: false });
+        }
+    };
+};
+//# sourceMappingURL=foldCache.js.map

package/dist/esm/internal/foldCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foldCache.js","sourceRoot":"","sources":["../../../src/internal/foldCache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmBH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAI,KAAa,EAAgB,EAAE;IACrD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAA;IACvC,OAAO;QACL,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE;YACX,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC3B,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAA;YACzC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAA;YACnB,OAAO,KAAK,CAAC,KAAK,CAAA;QACpB,CAAC;QACD,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC9B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAA;gBACtB,OAAM;YACR,CAAC;YACD,IAAI,IAAI,CAAC,IAAI,IAAI,KAAK,EAAE,CAAC;gBACvB,IAAI,MAA0B,CAAA;gBAC9B,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;oBACtC,IAAI,CAAC,KAAK,CAAC,MAAM;wBAAE,MAAM,GAAG,SAAS,CAAA;gBACvC,CAAC;gBACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAA;oBAClC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE;wBAAE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAA;gBACzD,CAAC;gBACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YACrB,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;QACzC,CAAC;KACF,CAAA;AACH,CAAC,CAAA","sourcesContent":["/**\n * Bounded, scan-resistant retention for the per-run folds a journal reader\n * keeps in memory.\n *\n * @private\n * @since 1.0.0\n */\n\n/** One retained fold, and whether a later read has come back for it. */\ninterface Held<A> {\n  value: A\n  reused: boolean\n}\n\n/**\n * A bounded per-run fold cache.\n *\n * @private\n * @since 1.0.0\n */\nexport interface FoldCache<A> {\n  readonly get: (key: string) => A | undefined\n  readonly put: (key: string, value: A) => void\n}\n\n/**\n * A bounded map of per-run folds that a sweep wider than the bound cannot\n * empty.\n *\n * Least-recently-used eviction has a zero hit rate under exactly the workload\n * a supervisor produces: an ordered sweep of `bound + 1` runs evicts the fold\n * the next read is about to want, so every poll replays every journal from\n * sequence zero instead of reading its tail. Under pressure this instead\n * sacrifices the NEWEST fold no later read has reused, so a sweep of any width\n * keeps every fold it has read twice and pays for its width in a fixed handful\n * of refolds. Only when every retained fold has been reused does it fall back\n * to evicting the oldest, and it then clears the reuse marks so a fold cannot\n * hold a slot on one ancient read forever.\n *\n * @private\n * @since 1.0.0\n */\nexport const make = <A>(bound: number): FoldCache<A> => {\n  const held = new Map<string, Held<A>>()\n  return {\n    get: (key) => {\n      const entry = held.get(key)\n      if (entry === undefined) return undefined\n      entry.reused = true\n      return entry.value\n    },\n    put: (key, value) => {\n      const existing = held.get(key)\n      if (existing !== undefined) {\n        existing.value = value\n        return\n      }\n      if (held.size >= bound) {\n        let victim: string | undefined\n        for (const [candidate, entry] of held) {\n          if (!entry.reused) victim = candidate\n        }\n        if (victim === undefined) {\n          victim = held.keys().next().value!\n          for (const entry of held.values()) entry.reused = false\n        }\n        held.delete(victim)\n      }\n      held.set(key, { value, reused: false })\n    }\n  }\n}\n"]}

package/dist/esm/internal/replay.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one replay rule for an admission record, shared by the queue's fold and
+ * the journal projection so the two read the same history to the same state.
+ *
+ * @private
+ * @since 1.0.0
+ */
+import type * as NotificationEvent from "../NotificationEvent.ts";
+import * as NotificationState from "../NotificationState.ts";
+/**
+ * Applies one committed admission record to the state so far.
+ *
+ * A versioned record whose id is still pending is an edit: it replaces that
+ * item in place and keeps its original sequence, so the edit is delivered at
+ * the cutoff the first version was admitted under. Every other record applies
+ * the decision it committed.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const applyAdmitted: (state: NotificationState.State, event: NotificationEvent.Admitted, seq: number) => NotificationState.State;
+//# sourceMappingURL=replay.d.ts.map

package/dist/esm/internal/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../../src/internal/replay.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,iBAAiB,MAAM,yBAAyB,CAAA;AACjE,OAAO,KAAK,iBAAiB,MAAM,yBAAyB,CAAA;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,iBAAiB,CAAC,KAAK,EAC9B,OAAO,iBAAiB,CAAC,QAAQ,EACjC,KAAK,MAAM,KACV,iBAAiB,CAAC,KAYpB,CAAA"}

package/dist/esm/internal/replay.js

@@ -0,0 +1,31 @@
+/**
+ * The one replay rule for an admission record, shared by the queue's fold and
+ * the journal projection so the two read the same history to the same state.
+ *
+ * @private
+ * @since 1.0.0
+ */
+import * as NotificationState from "../NotificationState.js";
+/**
+ * Applies one committed admission record to the state so far.
+ *
+ * A versioned record whose id is still pending is an edit: it replaces that
+ * item in place and keeps its original sequence, so the edit is delivered at
+ * the cutoff the first version was admitted under. Every other record applies
+ * the decision it committed.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const applyAdmitted = (state, event, seq) => {
+    if (event.version !== undefined && state.items.some((item) => item.notification.id === event.notification.id)) {
+        return Object.freeze({
+            ...state,
+            items: Object.freeze(state.items.map((item) => item.notification.id === event.notification.id
+                ? Object.freeze({ notification: event.notification, seq: item.seq })
+                : item))
+        });
+    }
+    return NotificationState.applyAdmission(state, event.notification, seq, event.decision);
+};
+//# sourceMappingURL=replay.js.map

package/dist/esm/internal/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../../src/internal/replay.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,iBAAiB,MAAM,yBAAyB,CAAA;AAE5D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,KAA8B,EAC9B,KAAiC,EACjC,GAAW,EACc,EAAE;IAC3B,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,KAAK,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC;QAC9G,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,GAAG,KAAK;YACR,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAC5C,IAAI,CAAC,YAAY,CAAC,EAAE,KAAK,KAAK,CAAC,YAAY,CAAC,EAAE;gBAC5C,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;gBACpE,CAAC,CAAC,IAAI,CACT,CAAC;SACH,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,iBAAiB,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;AACzF,CAAC,CAAA","sourcesContent":["/**\n * The one replay rule for an admission record, shared by the queue's fold and\n * the journal projection so the two read the same history to the same state.\n *\n * @private\n * @since 1.0.0\n */\n\nimport type * as NotificationEvent from \"../NotificationEvent.ts\"\nimport * as NotificationState from \"../NotificationState.ts\"\n\n/**\n * Applies one committed admission record to the state so far.\n *\n * A versioned record whose id is still pending is an edit: it replaces that\n * item in place and keeps its original sequence, so the edit is delivered at\n * the cutoff the first version was admitted under. Every other record applies\n * the decision it committed.\n *\n * @private\n * @since 1.0.0\n */\nexport const applyAdmitted = (\n  state: NotificationState.State,\n  event: NotificationEvent.Admitted,\n  seq: number\n): NotificationState.State => {\n  if (event.version !== undefined && state.items.some((item) => item.notification.id === event.notification.id)) {\n    return Object.freeze({\n      ...state,\n      items: Object.freeze(state.items.map((item) =>\n        item.notification.id === event.notification.id\n          ? Object.freeze({ notification: event.notification, seq: item.seq })\n          : item\n      ))\n    })\n  }\n  return NotificationState.applyAdmission(state, event.notification, seq, event.decision)\n}\n"]}

package/dist/esm/layerWebhook.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The webhook alert sink: one POST per alert, keyed so the receiver can
+ * dedupe on it.
+ *
+ * The transport rules live here rather than beside the policy, because which
+ * endpoint is paged, over which scheme, carrying which credential is a
+ * deployment's decision and the delays are not.
+ *
+ * @since 1.0.0
+ */
+import { Duration, Layer } from "effect";
+import { Sink } from "./AlertSink.ts";
+/**
+ * How long the webhook sink waits for an answer before it calls the page
+ * refused.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const defaultWebhookTimeout: Duration.Duration;
+/**
+ * A sink that POSTs each alert to one webhook.
+ *
+ * The body is the alert plus its {@link alertId}, and the same id is sent as
+ * an `Idempotency-Key` header, because the package requires the receiver to
+ * dedupe on it and a body without it cannot. The header is set after the
+ * caller's headers, so it is the one this sink sends.
+ *
+ * The endpoint must be an absolute `http:` or `https:` URL, checked when the
+ * layer is built, and the request is made with redirect following disabled:
+ * the caller's headers can carry a credential, and a followed redirect would
+ * re-send them to an origin the deployment never named. A 3xx answer is a
+ * refusal like any other non-2xx, not a forwarding instruction. The sink owns
+ * its Fetch transport; an externally supplied `HttpClient` is not used.
+ * Each delivery has its own scope, which aborts the request and releases any
+ * unread response body on completion, failure, timeout, or interruption.
+ *
+ * The url is treated as a credential, because a webhook's secret usually is
+ * its path or query. The delivery's HTTP span is named for the method and
+ * records the scheme, host, port and answering status, never the path, the
+ * query or userinfo, and it fails with the same url-free reason the sink
+ * returns. A host that records HTTP headers on spans gets every name in
+ * `headers`, and a redirect's `location`, as `<redacted>`.
+ *
+ * A non-2xx response is a failure, not a delivery, and an endpoint that never
+ * answers is a failure after `timeout`. Paging is exactly the case where a
+ * silently dropped request is worse than a retry, and a hung request is worse
+ * than either: it is indistinguishable from silence, so it must not be
+ * possible to wait on one forever.
+ *
+ * @param options the endpoint, any headers it needs, and how long to wait
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerWebhook: (options: {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    readonly timeout?: Duration.Duration | undefined;
+}) => Layer.Layer<Sink>;
+//# sourceMappingURL=layerWebhook.d.ts.map