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

package/src/NotificationState.ts

@@ -0,0 +1,295 @@
+/**
+ * Pure pending-notification queue state.
+ *
+ * @since 0.1.0
+ */
+
+import type { Notification } from "./Notification.ts"
+import { admissionClass, coalesceKey } from "./Notification.ts"
+import type * as NotificationEvent from "./NotificationEvent.ts"
+
+/**
+ * The default maximum number of pending notifications retained per run.
+ *
+ * The bound is what makes an undrained run a known quantity instead of a
+ * function of how long it was ignored. Admitting past it decides
+ * `rejected-full`, which retains nothing and writes no journal entry, so the
+ * notification is admissible again once a boundary drains.
+ * `NotificationQueue.layerWith` raises or lowers it for one composition.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const defaultCapacity = 128
+
+/**
+ * A notification retained until it is promoted at a harness safe point.
+ *
+ * `seq` is the journal sequence the admission committed at, which is what a
+ * turn-close cutoff compares against.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Pending {
+  readonly notification: Notification
+  readonly seq: number
+}
+
+/**
+ * The result recorded for one durable notification admission.
+ *
+ * Re-exported from `NotificationEvent`, which owns the single declaration, so
+ * the type these signatures use and the schema the journal validates against
+ * can never drift apart.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type AdmissionDecision = NotificationEvent.AdmissionDecision
+
+/**
+ * Immutable bounded queue state derived from the notification journal.
+ *
+ * The value is immutable in its own structure: the state and the `Pending`
+ * wrappers it holds are frozen, and every transition returns a new state
+ * rather than editing this one. The notifications inside are not re-frozen
+ * here, because `NotificationQueue.admit` already snapshots a notification at
+ * the durability boundary, so no state built by the queue shares mutable
+ * structure with a caller.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface State {
+  readonly capacity: number
+  readonly items: ReadonlyArray<Pending>
+}
+
+/**
+ * One pure admission transition and its visible decision.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Admission {
+  readonly state: State
+  readonly decision: AdmissionDecision
+}
+
+/**
+ * A pure promotion transition: what a boundary takes, and what is left.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Promotion {
+  readonly state: State
+  readonly promoted: ReadonlyArray<Pending>
+}
+
+const immutable = (capacity: number, items: ReadonlyArray<Pending>): State =>
+  Object.freeze({
+    capacity,
+    items: Object.freeze(items.map((item) => Object.freeze({ ...item })))
+  })
+
+const normalizedCapacity = (capacity: number): number =>
+  Number.isFinite(capacity) ? Math.max(0, Math.floor(capacity)) : 0
+
+const immutablePromotion = (state: State, promoted: ReadonlyArray<Pending>): Promotion =>
+  Object.freeze({
+    state,
+    promoted: Object.freeze(promoted.map((item) => Object.freeze({ ...item })))
+  })
+
+/**
+ * Creates an empty bounded notification queue.
+ *
+ * A capacity that is not a finite number becomes zero, so a misconfigured
+ * bound refuses everything loudly rather than retaining an unbounded backlog.
+ *
+ * @param capacity the maximum number of pending notifications
+ * @category constructors
+ * @since 0.1.0
+ */
+export const empty = (capacity: number): State => immutable(normalizedCapacity(capacity), [])
+
+/**
+ * The pending item a notification coalesces into, or `-1` when it coalesces
+ * with nothing.
+ *
+ * A coalescing key is scoped to one lineage. `targetLineageId` is the reader's
+ * address, so two branches reporting the same condition under one ordinary key
+ * are two pending notifications, and neither erases the other's.
+ */
+const coalesceIndex = (state: State, notification: Notification): number => {
+  const key = coalesceKey(notification)
+  if (key === null) return -1
+  return state.items.findIndex((item) =>
+    item.notification.targetLineageId === notification.targetLineageId &&
+    coalesceKey(item.notification) === key
+  )
+}
+
+/**
+ * Admits a notification, coalescing only pending system events that share both
+ * a key and a target lineage. Coalescing retains the first sequence so replay
+ * order remains stable.
+ *
+ * A queue already at capacity decides `rejected-full` and retains nothing. The
+ * caller owns what happens next: `NotificationQueue.admit` writes no journal
+ * entry for that decision, so the same notification is admissible again once a
+ * boundary drains.
+ *
+ * @param state the current queue state
+ * @param notification the notification to admit
+ * @param seq the journal sequence the admission is recorded at
+ * @category operations
+ * @since 0.1.0
+ */
+export const admit = (state: State, notification: Notification, seq: number): Admission => {
+  const coalesced = coalesceIndex(state, notification)
+  if (coalesced !== -1) {
+    const existing = state.items[coalesced]!
+    const items = [...state.items]
+    items[coalesced] = { notification, seq: existing.seq }
+    return Object.freeze({ state: immutable(state.capacity, items), decision: "coalesced" })
+  }
+
+  if (state.items.length >= state.capacity) {
+    return Object.freeze({ state, decision: "rejected-full" })
+  }
+
+  return Object.freeze({
+    state: immutable(state.capacity, [...state.items, { notification, seq }]),
+    decision: "admitted"
+  })
+}
+
+/**
+ * Applies the decision already committed in an admission journal event.
+ *
+ * Replay never re-decides: the committed decision is the one that happened,
+ * whatever this process's state would have chosen. The `rejected-full` branch
+ * stays reachable for a record written by any other writer, even though this
+ * package never writes one.
+ *
+ * @param state the state so far
+ * @param notification the notification the record admitted
+ * @param seq the journal sequence the record committed at
+ * @param decision the decision the record carries
+ * @category operations
+ * @since 0.1.0
+ */
+export const applyAdmission = (
+  state: State,
+  notification: Notification,
+  seq: number,
+  decision: AdmissionDecision
+): State => {
+  if (decision === "rejected-full") return state
+  if (decision === "admitted") {
+    return immutable(state.capacity, [...state.items, { notification, seq }])
+  }
+  const index = coalesceIndex(state, notification)
+  // A record whose lineage holds nothing under the key is retained rather than
+  // dropped, which is also what keeps a decision recorded before coalescing
+  // was lineage-scoped replayable: it applies to the item it named, or to none.
+  if (index === -1) return immutable(state.capacity, [...state.items, { notification, seq }])
+  const items = [...state.items]
+  items[index] = { notification, seq: items[index]!.seq }
+  return immutable(state.capacity, items)
+}
+
+/**
+ * Returns still-pending notifications in their durable journal order.
+ *
+ * @param state the current queue state
+ * @param admission which admission class to report
+ * @param targetLineageId the lineage to report for, or every lineage when absent
+ * @category getters
+ * @since 0.1.0
+ */
+export const pending = (
+  state: State,
+  admission: "steer" | "queue",
+  targetLineageId?: string
+): ReadonlyArray<Pending> =>
+  Object.freeze(
+    state.items.filter((item) =>
+      admissionClass(item.notification) === admission &&
+      (targetLineageId === undefined || item.notification.targetLineageId === targetLineageId)
+    )
+  )
+
+/**
+ * Promotes every steer notification admitted at or before the turn-close
+ * cutoff. Notifications admitted after the cutoff remain pending.
+ *
+ * The cutoff is what holds a steer that arrived mid-turn until the next
+ * boundary, and `NotificationQueue.DrainInput.cutoffSeq` is how a caller sets
+ * it. A drain that names no cutoff delivers everything pending for the lineage.
+ *
+ * @param state the current queue state
+ * @param cutoffSeq the highest admission sequence this boundary may deliver
+ * @param targetLineageId the lineage the boundary belongs to, or every lineage when absent
+ * @category operations
+ * @since 0.1.0
+ */
+export const promoteSteers = (state: State, cutoffSeq: number, targetLineageId?: string): Promotion => {
+  const promoted: Array<Pending> = []
+  const remaining: Array<Pending> = []
+  for (const item of state.items) {
+    if (
+      (admissionClass(item.notification) === "steer" || (
+        item.notification._tag === "system-event" &&
+        typeof item.notification.payload === "object" && item.notification.payload !== null &&
+        !Array.isArray(item.notification.payload) &&
+        (item.notification.payload as Readonly<Record<string, unknown>>).kind === "outside_change"
+      )) &&
+      item.seq <= cutoffSeq &&
+      (targetLineageId === undefined || item.notification.targetLineageId === targetLineageId)
+    ) {
+      promoted.push(item)
+    } else {
+      remaining.push(item)
+    }
+  }
+  return immutablePromotion(immutable(state.capacity, remaining), promoted)
+}
+
+/**
+ * Promotes exactly the oldest pending queue notification.
+ *
+ * @param state the current queue state
+ * @param targetLineageId the lineage the boundary belongs to, or every lineage when absent
+ * @category operations
+ * @since 0.1.0
+ */
+export const promoteQueued = (state: State, targetLineageId?: string): Promotion => {
+  const index = state.items.findIndex((item) =>
+    admissionClass(item.notification) === "queue" &&
+    (targetLineageId === undefined || item.notification.targetLineageId === targetLineageId)
+  )
+  if (index === -1) return immutablePromotion(state, [])
+  const promoted = state.items[index]!
+  return immutablePromotion(
+    immutable(state.capacity, [...state.items.slice(0, index), ...state.items.slice(index + 1)]),
+    [promoted]
+  )
+}
+
+/**
+ * Applies a durable promotion record while replaying journal history.
+ *
+ * @param state the state so far
+ * @param ids the notification ids the record promoted
+ * @category operations
+ * @since 0.1.0
+ */
+export const applyPromoted = (state: State, ids: ReadonlyArray<string>): State => {
+  if (ids.length === 0) return state
+  const promoted = new Set(ids)
+  return immutable(state.capacity, state.items.filter((item) => !promoted.has(item.notification.id)))
+}

package/src/Projection.ts

@@ -0,0 +1,46 @@
+/**
+ * Journal projection for pending notifications.
+ *
+ * @since 0.1.0
+ */
+
+import { Projection as JournalProjection } from "@smthrs/journal"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as NotificationEvent from "./NotificationEvent.ts"
+import * as NotificationState from "./NotificationState.ts"
+
+/**
+ * Re-derives pending notifications from admitted and promoted journal events.
+ * Foreign journal entries leave the state unchanged.
+ *
+ * Replay never re-decides, so capacity does not truncate it:
+ * `NotificationState.applyAdmission` applies the decision each record already
+ * committed, and an admitted record is retained however many are pending. A
+ * composition built with `NotificationQueue.layerWith` above the default
+ * replays every admission it wrote.
+ *
+ * The projected `capacity` is `NotificationState.defaultCapacity` because the
+ * initial state has to start somewhere and no journal record carries the bound
+ * the layer was built at. Read `items`, not `capacity`, to learn what a run
+ * holds.
+ *
+ * @category projections
+ * @since 0.1.0
+ */
+export const derive = JournalProjection.make({
+  name: "flows/notifications",
+  initial: NotificationState.empty(NotificationState.defaultCapacity),
+  reduce: (state, entry) => {
+    const decoded = NotificationEvent.fromEntry(entry)
+    if (Option.isNone(decoded)) return Effect.succeed(state)
+
+    const event = decoded.value
+    if (NotificationEvent.isAdmitted(event)) {
+      return Effect.succeed(
+        NotificationState.applyAdmission(state, event.notification, entry.seq, event.decision)
+      )
+    }
+    return Effect.succeed(NotificationState.applyPromoted(state, event.ids))
+  }
+})

package/src/SteerPayload.ts

@@ -0,0 +1,198 @@
+/**
+ * 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 const Thinking = Schema.Literals(["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 const MessagePayload = Schema.Struct({
+  kind: Schema.Literal("Message"),
+  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 const SeatPayload = Schema.Struct({
+  kind: Schema.Literal("Seat"),
+  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 const ThinkingPayload = Schema.Struct({
+  kind: Schema.Literal("Thinking"),
+  thinking: Thinking
+})
+
+/**
+ * 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 const ToolsPayload = Schema.Struct({
+  kind: Schema.Literal("Tools"),
+  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 const SteerPayload = Schema.Union([MessagePayload, SeatPayload, ThinkingPayload, ToolsPayload])
+
+/**
+ * Any steering item a notification payload can carry.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SteerPayload = typeof SteerPayload.Type
+
+const parse = Schema.decodeUnknownOption(SteerPayload)
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Readonly<Record<string, unknown>>
+    : 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: Notification.Notification): SteerPayload | undefined => {
+  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: SteerPayload): SteerPayload =>
+  item.kind === "Tools" ? { ...item, toolNames: [...item.toolNames] } : { ...item }

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * 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"

package/src/internal/foldCache.ts

@@ -0,0 +1,72 @@
+/**
+ * Bounded, scan-resistant retention for the per-run folds a journal reader
+ * keeps in memory.
+ *
+ * @private
+ * @since 1.0.0
+ */
+
+/** One retained fold, and whether a later read has come back for it. */
+interface Held<A> {
+  value: A
+  reused: boolean
+}
+
+/**
+ * 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 const make = <A>(bound: number): FoldCache<A> => {
+  const held = new Map<string, Held<A>>()
+  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: string | undefined
+        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 })
+    }
+  }
+}