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

package/docs/quickstart.md

@@ -0,0 +1,159 @@
+---
+title: "Quickstart"
+description: "Admit a steer and a follow-up to a run, drain them at a turn boundary, and read the receipt, over an in-memory journal that needs no configuration."
+sidebar:
+  order: 2
+---
+
+This quickstart runs the durable queue end to end. The journal is the
+production SQLite one over an in-memory database, so nothing is stubbed and
+nothing needs configuring. By the end you will have admitted two notifications
+from one process, drained them from the code that stands in for a run, and read
+back what each step decided.
+
+## Prerequisites
+
+- Node.js 26.4.0 or later.
+- A project with the packages installed: `npm install @smthrs/notifications@next @smthrs/journal@next effect`.
+
+## Write the notifications
+
+A notification names what will read it, carries the provenance of whoever wrote
+it, and declares how it may be delivered. `targetLineageId` is that first part:
+an opaque address for the run, or for one branch of the run that closes turns of
+its own. The queue only compares it for equality, so `"run-1/root"` below is a
+readable choice rather than a required format. Create `quickstart.ts`:
+
+```ts
+import type { Notification } from "@smthrs/notifications/Notification"
+
+const from = {
+  sourceRunId: "operator",
+  sourceLineageId: "operator",
+  sourceTurn: 0,
+  sourceActor: "human:will"
+}
+
+/** Urgent: this one is delivered in a batch when the current turn closes. */
+const steer: Notification = {
+  _tag: "human-steer",
+  id: "message-1",
+  delivery: "steer",
+  targetLineageId: "run-1/root",
+  provenance: from,
+  payload: { kind: "Message", body: "look at the failing test first" }
+}
+
+/** Not urgent: this one waits until the run would otherwise have nothing to do. */
+const followup: Notification = {
+  _tag: "human-followup",
+  id: "message-2",
+  delivery: "queue",
+  targetLineageId: "run-1/root",
+  provenance: from,
+  payload: { kind: "Message", body: "and update the changelog when you get a moment" }
+}
+```
+
+`id` is your idempotency key. Admitting it twice with the same content is one
+notification; admitting it with different content is a producer bug the queue
+refuses.
+
+## Admit, then drain
+
+`admit` and `drain` are separate calls because in production they happen in
+different processes at different times. Here they run in one file, which changes
+nothing about what the journal records:
+
+```ts
+import { NotificationQueue } from "@smthrs/notifications"
+import * as Effect from "effect/Effect"
+
+const ids = (receipt: NotificationQueue.DrainReceipt) => receipt.notifications.map((item) => item.id)
+
+const program = Effect.gen(function*() {
+  const queue = yield* NotificationQueue.NotificationQueue
+
+  const first = yield* queue.admit("run-1", steer)
+  const second = yield* queue.admit("run-1", followup)
+
+  // The run closes a turn. Steers are delivered at turn close, in a batch.
+  const turn1 = yield* queue.drain({
+    runId: "run-1",
+    targetLineageId: "run-1/root",
+    boundary: "turn-1",
+    wouldIdle: true
+  })
+
+  // The run closes the next turn with nothing left to do, so it accepts one
+  // queued follow-up.
+  const turn2 = yield* queue.drain({
+    runId: "run-1",
+    targetLineageId: "run-1/root",
+    boundary: "turn-2",
+    wouldIdle: true
+  })
+
+  return {
+    admitted: [first.decision, second.decision],
+    turn1: ids(turn1),
+    turn2: ids(turn2),
+    stillPending: (yield* queue.pending("run-1")).map((item) => item.id)
+  }
+})
+```
+
+## Provide the journal and run it
+
+`TestJournal.layer()` is the production SQLite journal over an in-memory
+database, with migrations already run:
+
+```ts
+import * as TestJournal from "@smthrs/journal/test/TestJournal"
+
+export const main = program.pipe(
+  Effect.provide(NotificationQueue.layer),
+  Effect.provide(TestJournal.layer()),
+  Effect.scoped,
+  Effect.orDie
+)
+
+console.log(await Effect.runPromise(main))
+```
+
+Run the file with your TypeScript runner:
+
+```text
+{
+  admitted: [ 'admitted', 'admitted' ],
+  turn1: [ 'message-1' ],
+  turn2: [ 'message-2' ],
+  stillPending: []
+}
+```
+
+## What just happened
+
+The first boundary delivered the steer and nothing else. A queued notification
+is promoted one at a time, and only when the boundary has no steer to deliver
+and the run would otherwise stall, so the follow-up waited for the second
+boundary. Set `wouldIdle` to `false` on both drains and `message-2` stays
+pending indefinitely, which is the correct answer: a run that always has work
+never needs it.
+
+Both operations are journaled, so a second process over the same database sees
+the same answers. Drain `turn-1` again and the receipt comes back with
+`duplicate: true` and the same notifications, read from the committed promotion
+record rather than decided a second time.
+
+## Next steps
+
+- [Admission and promotion](./concepts/admission-and-promotion.md): what
+  delivery classes, coalescing, the capacity bound, and the drain identity
+  actually mean.
+- [Handle a full queue](./guides/handle-a-full-queue.md): the one receipt field
+  a caller must never ignore.
+- [Steer a run](./guides/steer-a-run.md): the payload vocabulary that turns a
+  notification into a seat change or a thinking-level change.
+- [Test against the queue](./guides/testing.md): the same in-memory stack as a
+  test habit, plus the pure state machine underneath it.

package/docs/troubleshooting.md

@@ -0,0 +1,254 @@
+---
+title: "Troubleshooting"
+description: "The failures @smthrs/notifications reports and the silent ones it does not: what each symptom means, what causes it, and what to change."
+---
+
+## A notification never reaches the run, and nothing failed
+
+**Symptom.** `admit` returned successfully. The run drains and never sees the
+notification, and no error was raised anywhere.
+
+**Cause.** `AdmissionReceipt.decision` was `rejected-full`. The run already held
+its capacity of pending notifications, so the queue retained nothing and wrote
+no journal entry. `admit` does not fail on a full queue.
+
+**Fix.** Read `receipt.decision` on every call. Retry the identical notification
+once a boundary has drained: the id was never burned. See
+[Handle a full queue](./guides/handle-a-full-queue.md).
+
+## notification_id_reused: already admitted with different content
+
+**Symptom.** `NotificationError` with `code: "notification_id_reused"` and a
+message naming the id.
+
+**Cause.** The same `id` was admitted earlier with different content. The
+comparison is on a canonical rendering, with keys sorted and absent values
+dropped, so field order is not the difference; something in the payload,
+provenance, delivery, or lineage changed.
+
+**Fix.** Decide which one you mean. A retry of the same instruction sends the
+identical value. A different instruction gets a different id.
+
+The common source is a value that varies with time. An alert stamped with the
+reading clock instead of journal time changes between ticks, and becomes
+permanently undeliverable the moment one tick is refused. Every field of an
+`Alerts.Alert` is derived from the journal for exactly this reason; keep your own
+notifications the same way.
+
+## notification_id_reused: the journal identity holds an event this queue did not write
+
+**Symptom.** The message says the journal identity for a notification holds an
+event this queue did not write.
+
+**Cause.** Something else committed under the source id
+`/notifications/admission/<id>` for that run. The emit deduplicated against it,
+so nothing of yours was written and there is no admission to report.
+
+**Fix.** Find the other writer. A second component journaling under this
+package's source-id namespace is the defect; the queue refuses to invent an
+admission rather than reporting one that does not exist.
+
+## notification_invalid, with a path
+
+**Symptom.** `NotificationError` with `code: "notification_invalid"` and a
+`path` such as `provenance.sourceTurn` or `id`.
+
+**Cause.** The value is not a `Notification.Notification`. `admit` decodes at the
+durability boundary, before anything is journaled, because a structurally invalid
+notification that reached the journal would be acknowledged at a real sequence
+and then skipped by every replay.
+
+Common failures:
+
+| Field                   | What is wrong                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------- |
+| `id`                    | Empty, or not a string. The id is the idempotency key and must be a non-empty string. |
+| `targetLineageId`       | Empty, or not a string.                                                               |
+| `provenance.sourceTurn` | Not an integer, or below zero. Reported as `path: "provenance.sourceTurn"`.           |
+| `payload`               | Not JSON. A function or a symbol anywhere inside it fails with `path: "payload"`.     |
+
+**Fix.** Correct the field `path` names. Neither the message nor `path` carries
+the offending value, on purpose: a refusal is logged and journaled in places the
+value must not reach.
+
+Two fields can be absent from the error. `path` is absent when the value did not
+match any member of the union closely enough to name one field, and
+`notificationId` is absent when the value carries no readable string `id`, which
+is the honest answer rather than an invented one.
+
+## notification_invalid: nests deeper than the 256 level bound
+
+**Symptom.** The message names a depth bound.
+
+**Cause.** The payload nests past 256 levels, or contains a cycle. A cycle has no
+finite depth, so it trips the same bound rather than looping forever.
+
+**Fix.** Flatten the payload. The bound exists because the value is walked and
+serialized on the way to the journal, and an unbounded walk turns a hostile
+payload into an untyped `RangeError` instead of a refusal a caller can read.
+
+## notification_invalid: larger than the 1048576 code unit bound
+
+**Symptom.** The message names a code unit bound.
+
+**Cause.** The notification is larger than 1,048,576 UTF-16 code units, counting
+every string and object key at its length and every other value as one.
+
+**Fix.** Store the large content elsewhere and put a reference in the payload.
+The bound is checked before the notification is copied, decoded, fingerprinted,
+or journaled, so an oversized payload costs the notifying process no more than
+the bound.
+
+## notification_unavailable
+
+**Symptom.** Every call fails with `code: "notification_unavailable"` and a
+message like `admit is unavailable`.
+
+**Cause.** The composition provided `NotificationQueue.layerNoop()` or
+`makeNoop()`. That is the explicit absence: a seam that is present and serves
+nothing.
+
+**Fix.** Provide `NotificationQueue.layer` and a `Journal.Journal`. If the noop
+is deliberate, handle the failure: a run listing that annotates pending counts
+should catch `/notifications/NotificationError` and leave the field absent
+rather than reporting zero. See
+[Report what a run is waiting on](./guides/report-pending-notifications.md).
+
+The same code also reports that the journal identity for a drain boundary holds
+an event this queue did not write, which has the same cause and fix as the
+admission case above.
+
+## A steer stays pending across several boundaries
+
+**Symptom.** `pending` keeps returning the notification; `drain` keeps returning
+nothing.
+
+**Causes, in the order worth checking:**
+
+1. **The lineage does not match.** `drain` promotes only notifications whose
+   `targetLineageId` equals `DrainInput.targetLineageId`. A child lineage
+   draining under the parent's id leaves its own notifications untouched.
+2. **The cutoff excludes it.** `cutoffSeq` is the sequence that opened the turn.
+   A steer admitted after it is held until the next boundary. That is correct
+   behavior once; if it repeats, the caller is passing a stale cutoff.
+3. **The boundary name repeats.** The drain identity is
+   `(runId, targetLineageId, boundary)`, and the first record committed for it is
+   the delivery. Draining the same boundary name again reports that record with
+   `duplicate: true` and promotes nothing new. Give each boundary its own name.
+
+## A follow-up is never delivered
+
+**Symptom.** A `human-followup` or a `system-event` stays pending while steers
+flow through.
+
+**Cause.** A queued notification is promoted only when `DrainInput.wouldIdle` is
+true and the same boundary promoted no steer. A run that always has work, or a
+caller that always passes `wouldIdle: false`, never reaches that case.
+
+**Fix.** Pass the run's real idleness. If the notification must not wait for
+idleness, admit it as a `human-steer` instead.
+
+## Two system events became one
+
+**Symptom.** An earlier event's payload was replaced, and the receipt said
+`coalesced`.
+
+**Cause.** Both are `system-event` values sharing a `coalescingKey`, and the
+first is still pending. That is the design: ten updates about one condition are
+one pending notification carrying the latest of them.
+
+**Fix.** Drop the `coalescingKey` for events that must not collapse. A
+`human-followup` never coalesces, whatever it carries.
+
+## A drain returns the same notifications twice
+
+**Symptom.** `drain` answers with notifications the run already handled, and
+`duplicate` is true.
+
+**Cause.** The boundary had already drained. The receipt is read back from the
+committed promotion record, so two processes draining one boundary report the
+same delivery rather than two divergent guesses.
+
+**Fix.** Branch on `DrainReceipt.duplicate`. A resumed run walks its boundaries
+until one answers `duplicate: false`, which is the first it has not consulted.
+
+## An alert never fires
+
+**Symptom.** The condition is visibly true in the journal, and `tick` returns
+empty arrays.
+
+**Causes, in the order worth checking:**
+
+1. **No rule.** Only conditions named in `Policy.rules` are watched at all.
+2. **No detector.** A rule whose condition is in neither `defaultDetectors` nor
+   the policy's own `detectors` raises nothing.
+3. **`eventTypes` excludes the entry.** A detector that names event types
+   consults no others. Every default detector consults only `control.*`.
+4. **The payload is not a record.** An entry whose payload is a string, an array,
+   or `null` is skipped.
+5. **The delay has not elapsed.** `decide` compares `now` against
+   `since + afterMs`, both in journal time.
+6. **It already fired.** A delivered alert comes back in `Tick.suppressed`, not
+   `Tick.delivered`.
+
+## An alert pages twice about one condition
+
+**Symptom.** The receiving system shows two pages with the same `alertId`.
+
+**Cause.** Delivery is at-least-once. A process that dies between an accepted
+send and the `flows.alerts.delivered` record pages again on the next tick. The
+alternative, recording the delivery first, turns the same crash into a page
+nobody receives.
+
+**Fix.** Deduplicate in the sink on `Alerts.alertId(alert)`. The webhook sink
+sends it as an `Idempotency-Key` header and in the body for exactly this. See
+[Send alerts to a webhook](./guides/send-alerts-to-a-webhook.md).
+
+## An alert re-fires after the condition cleared and came back
+
+**Symptom.** A second page about the same run and condition.
+
+**Cause.** This is correct. `alertId` includes the opening time, so a condition
+that clears and re-opens is a new alert. The second approval wait is not the
+first one, and an id without the time would suppress it forever.
+
+## The alert runtime dies when the layer builds
+
+**Symptom.** Building `Alerts.layer(policy)` fails the composition rather than
+returning a runtime.
+
+**Cause.** The policy did not decode. `afterMs` must be a whole number at or
+above zero: a `NaN` delay would fire on the first tick and stamp a `firedAt`
+that JSON writes as `null`, and a negative one would fire with a `firedAt`
+earlier than the condition it describes.
+
+**Fix.** Correct the rule. Failing at composition time is deliberate: the
+alternative is mis-paging at 3am.
+
+## The projection reports a capacity the run was not built at
+
+**Symptom.** A composition built with `NotificationQueue.layerWith({ capacity:
+512 })` projects a state whose `capacity` is 128.
+
+**Cause.** `Projection.derive` starts at
+`NotificationState.empty(NotificationState.defaultCapacity)`, and no journal
+record carries the bound the layer was built at, so replay has nothing to
+restore it from.
+
+**Fix.** Read `items` rather than `capacity`. Replay never re-decides: an
+admitted record is retained whatever the projected bound says, so the projection
+reports every pending notification a raised-capacity run holds. See
+[the journal records](./concepts/journal-records.md).
+
+## Mutating a notification after admitting it changes nothing
+
+**Symptom.** A field edited on the object after the call does not appear in the
+journal or in a later drain.
+
+**Cause.** `admit` decodes and structurally copies its argument at the durability
+boundary, and journals the snapshot. `SteerPayload.encode` does the same for the
+record it returns.
+
+**Fix.** Nothing to fix. Build the value fully before admitting it; a queue whose
+durable record could change after the call returned would be a queue that cannot
+promise what it wrote.

package/package.json

@@ -1,6 +1,185 @@
 {
   "name": "@smthrs/notifications",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.13",
+  "license": "MIT",
+  "smthrs": {
+    "group": "agent"
+  },
+  "description": "Durable notification queue, admission policy, and journal projection for flows",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/notifications"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "journal",
+    "durability"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "journal",
+    "durability"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./internal/*": null,
+    "./*/index": null,
+    "./Alerts": {
+      "import": {
+        "types": "./dist/esm/Alerts.d.ts",
+        "default": "./dist/esm/Alerts.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Alerts.d.ts",
+        "default": "./dist/cjs/Alerts.js"
+      }
+    },
+    "./Notification": {
+      "import": {
+        "types": "./dist/esm/Notification.d.ts",
+        "default": "./dist/esm/Notification.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Notification.d.ts",
+        "default": "./dist/cjs/Notification.js"
+      }
+    },
+    "./NotificationEvent": {
+      "import": {
+        "types": "./dist/esm/NotificationEvent.d.ts",
+        "default": "./dist/esm/NotificationEvent.js"
+      },
+      "require": {
+        "types": "./dist/cjs/NotificationEvent.d.ts",
+        "default": "./dist/cjs/NotificationEvent.js"
+      }
+    },
+    "./NotificationQueue": {
+      "import": {
+        "types": "./dist/esm/NotificationQueue.d.ts",
+        "default": "./dist/esm/NotificationQueue.js"
+      },
+      "require": {
+        "types": "./dist/cjs/NotificationQueue.d.ts",
+        "default": "./dist/cjs/NotificationQueue.js"
+      }
+    },
+    "./NotificationState": {
+      "import": {
+        "types": "./dist/esm/NotificationState.d.ts",
+        "default": "./dist/esm/NotificationState.js"
+      },
+      "require": {
+        "types": "./dist/cjs/NotificationState.d.ts",
+        "default": "./dist/cjs/NotificationState.js"
+      }
+    },
+    "./Projection": {
+      "import": {
+        "types": "./dist/esm/Projection.d.ts",
+        "default": "./dist/esm/Projection.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Projection.d.ts",
+        "default": "./dist/cjs/Projection.js"
+      }
+    },
+    "./SteerPayload": {
+      "import": {
+        "types": "./dist/esm/SteerPayload.d.ts",
+        "default": "./dist/esm/SteerPayload.js"
+      },
+      "require": {
+        "types": "./dist/cjs/SteerPayload.d.ts",
+        "default": "./dist/cjs/SteerPayload.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/canonical": "1.0.0-rc.13",
+    "@smthrs/crypto": "1.0.0-rc.13",
+    "@smthrs/journal": "1.0.0-rc.13"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/vitest": "4.0.5",
+    "@eslint/js": "9.39.5",
+    "@smthrs/database": "1.0.0-rc.13",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.5",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0",
+    "fast-check": "4.9.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.5"
+  },
+  "scripts": {
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  }
 }