Merge main and prepare 0.13.3

main released 0.13.2 while this branch was open, and this branch had
claimed that number for the Node floor change. Both the changelog and the
README quickstart conflicted on it.

The released 0.13.2 section stays as main wrote it, and the floor entries
move to a new 0.13.3 section. 0.13.3 also matches the Ruby gem, whose
release carries the same date.

The rest of the version references follow the release procedure:
package.json, src/version.ts, the process metadata test literal, the
README quickstart, docs/parity.md, and the example tag in
docs/releasing.md.

Author: cardmagic

.github/workflows/ci.yml

@@ -144,7 +144,7 @@ jobs:
     needs: [quality, floor, postgresql, mysql, browser, redis]
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write
       id-token: write
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
@@ -178,3 +178,10 @@ jobs:
           fi
       - if: steps.registry.outputs.exists != 'true'
         run: npm publish --access public
+      - name: Write release notes
+        run: node scripts/release-notes.mjs "${GITHUB_REF_NAME#v}" > "${RUNNER_TEMP}/release-notes.md"
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
+        with:
+          name: ${{ github.ref_name }}
+          body_path: ${{ runner.temp }}/release-notes.md

CHANGELOG.md

@@ -1,17 +1,31 @@
 # Changelog
 
-## 0.13.2 - 2026-08-18
+## 0.13.3 - 2026-08-18
 
 - Lower the supported Node.js floor from 24.15.0 to 24.4.0. Node.js 24.4.0 is
   the first release that accepts `readBigInts` on the `DatabaseSync`
   constructor, which the SQLite adapter needs to read 64-bit integers without
   losing precision. Node.js 24.0.0 through 24.3.x ignore the option, and the
   effect recovery and transaction retry tests fail there. A new CI job runs the
-  default suite, the build, the packaged artifact smoke test, and the
-  recovery demo on the floor.
+  default suite, the build, the packaged artifact smoke test, and the recovery
+  demo on the floor.
 - Record that `node:sqlite` stays experimental until Node.js 24.15.0 and prints
   a warning on stderr before it.
 
+## 0.13.2 - 2026-08-17
+
+- Accept a `key` on `schedule`, naming a reminder for the item it is waiting
+  on rather than for its operation, so one actor can hold an alarm per queued
+  item. Scheduling the same key again moves that item's alarm and leaves the
+  others alone. Without a key the name is still the operation, so existing
+  reminders keep their names and their coalescing behaviour. Adds a nullable
+  `message_operation` column to the reminders table, left null on existing rows.
+  The composed name is bounded by the 255 characters MySQL holds it in, checked
+  on the name rather than the key alone.
+- Add an authorized `runtime.administration.processes()` query for inspecting
+  live and stale process rows through the runtime's database adapter.
+- Document rolling-deployment overlap as a reason for the polling-only warning.
+
 ## 0.13.1 - 2026-08-16
 
 - Back idle actor, effect, reminder, and broadcast polling off exponentially

README.md

@@ -1,8 +1,11 @@
-# Durable Objects for Node, backed by your existing SQL database
+# Solid Objects JS
 
 [![CI](https://github.com/cardmagic/solid-objects-js/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cardmagic/solid-objects-js/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/solid-objects)](https://www.npmjs.com/package/solid-objects)
 
+Self-hosted, distributed Durable Objects in Node without a daemon using your
+existing SQL database.
+
 Build addressable TypeScript objects with serialized calls and durable state
 using SQLite, PostgreSQL, or MySQL, without deploying to Cloudflare.
 
@@ -58,11 +61,11 @@ processes submit them concurrently.
 ## Run it now with SQLite
 
 Node.js 24.4.0 or newer is required. Node.js 24.15 or newer is preferred,
-because `node:sqlite` prints an experimental warning before it. The `0.13.2`
+because `node:sqlite` prints an experimental warning before it. The `0.13.3`
 release includes a packaged quickstart:
 
 ```bash
-npm exec --yes --package=solid-objects@0.13.2 -- solid-objects quickstart
+npm exec --yes --package=solid-objects@0.13.3 -- solid-objects quickstart
 ```
 
 The command needs no repository checkout, database server, Redis, container, or
@@ -77,6 +80,28 @@ local run, it verifies that:
 - operations for two different identities overlap in time; and
 - the runtime closes and temporary state is removed.
 
+## What Solid Objects is for
+
+Use Solid Objects when more than one request, job, or process can act on the
+same logical thing and the next action must use its latest committed state.
+These are the stateful coordination patterns for which people often reach for
+Durable Objects:
+
+| Pattern                                 | One identity per              | What the object coordinates                                                                 |
+| --------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
+| Multiplayer, presence, or collaboration | Room, session, or document    | Joins, moves, and edits commit in order; subscribers refresh from committed state           |
+| Reservations and expiring holds         | Show, resource, or stock item | Availability checks and holds cannot interleave; a durable reminder can release an old hold |
+| Checkout and account workflows          | Cart, order, account, device  | The current step, retries, and effect results return to the same ordered mailbox            |
+| Per-key rate limits                     | API key, account, or device   | Token checks and decrements are serialized; a reminder can refill the bucket                |
+| Stateful agent sessions                 | Agent session                 | Messages and tool results apply in order and pending work survives a worker exit            |
+
+The common shape is one durable coordination boundary with an application
+defined identity. Work for that identity is serialized, while unrelated rooms,
+carts, accounts, or sessions can progress concurrently. A single global rate
+limiter or another very hot identity is a poor fit because it becomes an
+intentional bottleneck. If one ordinary row transaction solves the problem,
+prefer that. See [Choosing Solid Objects](docs/fit.md) for the longer guide.
+
 ## Running in a deployed application
 
 [Shuffle Up and Play](https://shuffleupandplay.com/) is a deployed reference
@@ -112,28 +137,6 @@ and multi-process lease fencing are verified separately by the library's
 [correctness contract](docs/correctness.md). Evaluate those guarantees and
 limits against your own workload.
 
-## What Solid Objects is for
-
-Use Solid Objects when more than one request, job, or process can act on the
-same logical thing and the next action must use its latest committed state.
-These are the stateful coordination patterns for which people often reach for
-Durable Objects:
-
-| Pattern                                 | One identity per              | What the object coordinates                                                                 |
-| --------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
-| Multiplayer, presence, or collaboration | Room, session, or document    | Joins, moves, and edits commit in order; subscribers refresh from committed state           |
-| Reservations and expiring holds         | Show, resource, or stock item | Availability checks and holds cannot interleave; a durable reminder can release an old hold |
-| Checkout and account workflows          | Cart, order, account, device  | The current step, retries, and effect results return to the same ordered mailbox            |
-| Per-key rate limits                     | API key, account, or device   | Token checks and decrements are serialized; a reminder can refill the bucket                |
-| Stateful agent sessions                 | Agent session                 | Messages and tool results apply in order and pending work survives a worker exit            |
-
-The common shape is one durable coordination boundary with an application
-defined identity. Work for that identity is serialized, while unrelated rooms,
-carts, accounts, or sessions can progress concurrently. A single global rate
-limiter or another very hot identity is a poor fit because it becomes an
-intentional bottleneck. If one ordinary row transaction solves the problem,
-prefer that. See [Choosing Solid Objects](docs/fit.md) for the longer guide.
-
 ## How it works
 
 An object is addressed by its TypeScript class and application-defined ID.

docs/api.md

@@ -79,6 +79,48 @@ function playerForSession<PlayerType extends { sessionId: string }>(options: {
 }
 ```
 
+### Reminders
+
+A reminder is one alarm per actor and name. Scheduling a name that is already
+armed **moves the existing alarm** rather than adding a second one, which is
+what makes a reminder safe to re-arm from a handler that may run more than once.
+
+Without a key that name is the operation, so one actor holds one alarm per
+operation, and arming one per queued item keeps only the last:
+
+```typescript
+// Wrong. Every entry overwrites the previous entry's alarm.
+add({ entry }: { entry: Entry }): void {
+  this.entries = [...this.entries, entry]
+  this.schedule({ at: new Date(entry.waitUntil) }).deliver!()
+}
+```
+
+Pass `key` when an actor is waiting on several things at once. The key is your
+own identifier for the item and names that item's alarm, so each item gets one:
+
+```typescript
+add({ entry }: { entry: Entry }): void {
+  this.entries = [...this.entries, entry]
+  this.schedule({ at: new Date(entry.waitUntil), key: entry.id }).deliver!()
+}
+```
+
+Scheduling the same key again moves that item's alarm and leaves the others
+alone. The operation still decides which handler runs; the key only decides
+which alarm is which.
+
+A key must be non-empty, and the name it composes must fit the 255 characters
+MySQL holds it in. That is checked on the composed name rather than the key
+alone, so a long operation with a short key is caught too. A key may hold colons
+of its own, because an actor member name cannot.
+
+An actor that only needs to know "what is next" can still keep one alarm and
+drain everything due when it fires. That costs one row instead of one per item
+and cannot strand an entry when an occurrence is coalesced, so prefer it for a
+large queue of interchangeable items and prefer `key` when an item needs an
+alarm that can be moved on its own.
+
 ### Runtime managers
 
 Every manager below is available as a property on `SolidObjectsRuntime`; the
@@ -89,6 +131,9 @@ class and result types are also exported for integration typing.
   idempotent paused-alarm `resume()`.
 - `runtime.processes` / `ProcessManager`: immutable role `all()` and stale-owner
   `cleanup()`.
+- `runtime.administration` / `AdministrationManager`: an authorized
+  `processes()` query for inspecting live and stale process rows through the
+  runtime's own database adapter.
 - `runtime.reconciliation` / `ReconciliationManager`: `active()`,
   `withoutPendingWork()`, `statesFor()`, and `orphaned()` bounded reads.
 - `runtime.retention` / `RetentionManager`: `preview()` and authorized `prune()`

docs/operations.md

@@ -17,6 +17,14 @@ delivery; without one, newly committed work can wait up to the current idle
 polling interval. Notification errors are isolated and logged by role and error
 class without failing the committed work.
 
+The warning excludes process rows with the current hostname and host process ID.
+It can therefore appear during a rolling deployment or restart overlap when an
+older and newer process briefly share the same database. A process that stopped
+without graceful cleanup remains live until its heartbeat exceeds
+`processAliveThresholdMilliseconds`; inspect
+`runtime.administration.processes()` to distinguish a live overlap from a stale
+row.
+
 Each role exposes `currentPollingIntervalMilliseconds`.
 `solid_objects.polling.interval_changed` reports the role, reason, previous
 interval, and current interval. The polling-only warning is also emitted as
@@ -62,9 +70,12 @@ runs under the application-write guard, and `onDeactivate()` is best effort:
 it may not run after a crash, cannot establish a correctness guarantee, and a
 failure is logged without preventing lease release.
 
-`runtime.processes.all()` returns administration-authorized immutable process
-metadata with hostname, host process ID, Node and Solid Objects versions, and a
-current `stale` flag. Graceful shutdown first persists `draining` with a
+`runtime.administration.processes()` returns the same administration-authorized
+immutable process metadata as `runtime.processes.all()`, with hostname, host
+process ID, Node and Solid Objects versions, and a current `stale` flag. It is
+safe to call through the runtime's database adapter while workers are running;
+the query is serialized with other database access and does not require a
+second SQLite connection. Graceful shutdown first persists `draining` with a
 `shutdownRequestedAt` timestamp, then deactivates owned actors and atomically
 releases every role claim before persisting `stopped`. `cleanup()` reauthorizes
 separately and performs the same release for stale running or draining

docs/parity.md

@@ -4,11 +4,11 @@ This ledger tracks capability parity with the Ruby `solid_objects` gem.
 Parity means preserving a capability and its correctness or security boundary,
 not copying a Rails API into Node.
 
-Reference: Ruby `solid_objects` 0.13.1. The JavaScript package began at the
+Reference: Ruby `solid_objects` 0.13.3. The JavaScript package began at the
 Ruby design's `0.12` capability generation; that version number did not imply
 earlier JavaScript releases.
 
-The Node `0.13.1` implementation has capability parity with that reference. Its
+The Node `0.13.3` implementation has capability parity with that reference. Its
 relational runtime, correctness boundaries, administration, diagnostics,
 operator dashboard, realtime projections, browser behavior, and supported
 adapters have native equivalents. Rails-specific rendering surfaces are

docs/releasing.md

@@ -28,7 +28,8 @@ npm trust github solid-objects \
 
 1. Update the version in `package.json` and `src/version.ts`, refresh the
    lockfile when needed, and move the release notes out of the Unreleased
-   section in `CHANGELOG.md`.
+   section in `CHANGELOG.md` into a dated section for the new version. The
+   publish job reads that section, so a version without one fails the release.
 2. Run `pnpm run format:check`, `pnpm run check`, `pnpm run test:coverage`,
    `pnpm run build`, `pnpm run pack:check`, `pnpm run test:package`,
    `pnpm run test:recovery`, `pnpm run test:browser`, and
@@ -38,11 +39,16 @@ npm trust github solid-objects \
 4. Create and push an annotated tag matching the package version:
 
    ```shell
-   git tag -a v0.13.1 -m "Version 0.13.1"
-   git push origin v0.13.1
+   git tag -a v0.13.3 -m "Version 0.13.3"
+   git push origin v0.13.3
    ```
 
 The tag runs the complete CI matrix. The publish job starts only after every
 quality, database, Redis, and browser job succeeds. It rejects tags that do not
 match `package.json`, safely skips versions already present in npm, and
 publishes new versions with npm provenance.
+
+The job then builds the release notes with `scripts/release-notes.mjs`, which
+prints the `CHANGELOG.md` section for the tagged version, and creates the GitHub
+release for the tag. Re-running the job on a tag that npm already holds still
+creates a missing release.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-objects",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "Race-free realtime state per application identity, backed by your SQL database",
   "type": "module",
   "license": "MIT",

scripts/release-notes.mjs

@@ -0,0 +1,64 @@
+import fs from "node:fs"
+import process from "node:process"
+
+const version = process.argv[2]
+
+if (!version) {
+  process.stderr.write("usage: node scripts/release-notes.mjs <version>\n")
+  process.exit(1)
+}
+
+const entry = findEntry(fs.readFileSync("CHANGELOG.md", "utf8"), version)
+
+if (!entry) {
+  process.stderr.write(`CHANGELOG.md has no entry for ${version}\n`)
+  process.exit(1)
+}
+
+const manifest = JSON.parse(fs.readFileSync("package.json", "utf8"))
+const repository = manifest.repository.url.replace(/^git\+/, "").replace(/\.git$/, "")
+const tag = `v${version}`
+const changelogLink = `${repository}/blob/${tag}/CHANGELOG.md#${anchor(entry.heading)}`
+const correctnessLink = `${repository}/blob/${tag}/docs/correctness.md`
+
+process.stdout.write(
+  [
+    entry.body,
+    "",
+    `Install with \`npm install ${manifest.name}@${version}\`.`,
+    "",
+    `See the [full changelog](${changelogLink}) and [correctness boundaries](${correctnessLink}).`,
+    "",
+  ].join("\n"),
+)
+
+function findEntry(changelog, releasedVersion) {
+  const lines = changelog.split("\n")
+  const start = lines.findIndex((line) => isHeadingFor(line, releasedVersion))
+  if (start === -1) return undefined
+
+  const remainder = lines.slice(start + 1)
+  const end = remainder.findIndex((line) => line.startsWith("## "))
+  const body = end === -1 ? remainder : remainder.slice(0, end)
+
+  return { heading: heading(lines[start]), body: body.join("\n").trim() }
+}
+
+function isHeadingFor(line, releasedVersion) {
+  if (!line.startsWith("## ")) return false
+
+  const text = heading(line)
+
+  return text === releasedVersion || text.startsWith(`${releasedVersion} `)
+}
+
+function heading(line) {
+  return line.replace(/^##\s+/, "").trim()
+}
+
+function anchor(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\- ]+/g, "")
+    .replace(/ /g, "-")
+}