solid-objects 1.0.5 → 1.0.6

package/docs/benchmarks.md

@@ -1,23 +1,170 @@
 # Benchmarks
 
-The benchmark harness measures committed actor operations. It shows tradeoffs
-and catches large regressions. It does not predict application capacity.
+The benchmark harness measures committed actor operations. It shows tradeoffs and catches large
+regressions. It does not predict application capacity.
+
+## Version 1.0.5 measurements
+
+The current dataset runs the released `v1.0.5` source at commit
+`8975f6e2ad94c114f3638cea8f167956061a9bc3`. The runtime source is unchanged; the measurement harness
+is overlaid from this repository. Every JSON report records that source revision, runtime source and
+built-artifact SHA-256 values, harness SHA-256, the loaded package version, actual driver versions,
+database version, host, and Node version. At collection time, the development branch also reported
+1.0.5 but contained SQLite WAL changes absent from the release tag. Use the recorded source and
+artifact hashes to reproduce the measured 1.0.5 implementation. Version 1.0.6 includes the later
+SQLite WAL changes.
+
+The archived reports were collected with harness revision
+`da5fe31b1ffa18eca92ce43fc26bca619d424d6e`. They verified committed operation
+counts. The current collector additionally verifies cart quantities, totals, and
+one pending effect with the correct total for every committed operation, after
+the timed interval. Those additional assertions were not run retrospectively on
+the archived measurements.
+
+### Recorded environment and results
+
+Measured November 7, 2026 on Apple M2 Ultra, 24 logical CPUs, 64 GiB RAM, darwin 27.2.0, and Node.js
+v24.18.0. Drivers were pg 8.23.0 and mysql2 3.23.3.
+
+The workstation was concurrently used for other development tasks. CPU and storage activity were
+shared. Absolute timings and workload comparisons require controlled repeats before capacity
+planning. For example, the three SQLite four-process synchronous hot-counter samples were 17.89,
+20.69, 79.42 operations/second. Every sample is retained.
+
+[Complete tables and raw reports](../benchmarks/results/v1.0.5-2026-11-07/README.md)
+include all 216 matrix rows, 12 state-size rows, three idle rows, and 57,600 individual operation
+latencies.
+
+| Database   | Version          | Durability settings                         |
+| ---------- | ---------------- | ------------------------------------------- |
+| sqlite     | 3.53.1           | `journalMode=delete, synchronous=2`         |
+| postgresql | 16.15 (Homebrew) | `fsync=on, synchronousCommit=on`            |
+| mysql      | 26.10.0          | `innodbFlushLogAtTrxCommit=1, syncBinlog=1` |
+
+The next table shows synchronous handlers with four worker processes. One-process and
+yielding-handler results are in the complete tables.
+
+| Database   | Workload    | Shape     |  ops/s |  p50 ms |   p95 ms |   p99 ms |
+| ---------- | ----------- | --------- | -----: | ------: | -------: | -------: |
+| sqlite     | counter     | warm-hot  |  20.69 |  733.52 | 1,595.35 | 1,754.31 |
+| sqlite     | counter     | warm-many |  13.51 |  818.09 | 3,205.47 |  6,056.1 |
+| sqlite     | counter     | cold-many |   5.77 | 2,497.5 | 5,538.34 | 6,346.58 |
+| sqlite     | cart-outbox | warm-hot  | 106.27 |  147.92 |   205.03 |   283.86 |
+| sqlite     | cart-outbox | warm-many |  56.87 |  264.62 |    454.1 |   588.05 |
+| sqlite     | cart-outbox | cold-many |   35.4 |  393.17 |  1,037.9 | 1,286.45 |
+| postgresql | counter     | warm-hot  |  88.84 |  160.37 |   275.92 |   293.19 |
+| postgresql | counter     | warm-many | 146.88 |   70.92 |   176.45 | 1,103.97 |
+| postgresql | counter     | cold-many |  20.25 |  808.09 | 1,069.78 | 1,140.48 |
+| postgresql | cart-outbox | warm-hot  |  99.15 |  159.81 |   227.97 |   244.67 |
+| postgresql | cart-outbox | warm-many | 107.12 |   93.49 |   253.75 |  1,307.5 |
+| postgresql | cart-outbox | cold-many |  21.56 |   651.8 |    979.4 | 1,056.95 |
+| mysql      | counter     | warm-hot  |   72.5 |  200.22 |   328.44 |   390.64 |
+| mysql      | counter     | warm-many | 105.16 |   58.47 |   363.58 | 1,728.53 |
+| mysql      | counter     | cold-many |  31.69 |   445.1 |   935.43 | 1,060.47 |
+| mysql      | cart-outbox | warm-hot  |  52.96 |  287.93 |   408.07 |   446.53 |
+| mysql      | cart-outbox | warm-many |  74.75 |  134.94 |   549.13 | 1,926.81 |
+| mysql      | cart-outbox | cold-many |  20.69 |  720.19 | 1,118.29 | 1,176.44 |
+
+State-size results use sequential operations on one actor in a SQLite file:
+
+| Payload KiB | Persisted state bytes | ops/s | p50 ms | p95 ms | p99 ms |
+| ----------: | --------------------: | ----: | -----: | -----: | -----: |
+|           0 |                    26 |  93.6 |   9.29 |  21.09 |  26.88 |
+|          16 |                16,410 | 86.65 |   10.4 |  21.12 |  26.33 |
+|         128 |               131,098 |  70.4 |  12.86 |  22.93 |  27.15 |
+|       1,024 |             1,048,602 | 42.27 |  22.55 |  33.05 |  42.64 |
+
+Idle CPU uses one timed sample per interval, in-memory SQLite, and all four polling roles:
+
+| Fast interval ms | Empty polls/s | Process CPU |
+| ---------------: | ------------: | ----------: |
+|               20 |             4 |       0.12% |
+|              100 |             4 |       0.12% |
+|              500 |             4 |        0.1% |
+
+### Workloads and measurement boundary
+
+The counter matrix includes one hot identity, 100 warm identities, and newly created identities,
+each with synchronous and yielding handlers and one or four processes. A second matrix uses a cart
+with 20 line items. Every cart operation updates a quantity, recalculates the total, and commits one
+outbox effect with the actor state. Effect workers are disabled: the cart results measure durable
+outbox staging, not delivery to an external service. The yielding handler uses `setImmediate()`; it
+does not model external network latency.
+
+Each scenario has three separate samples of 250 measured operations after 25 warmup operations, at
+client concurrency 16 and four actor workers. Counters are verified against all submitted operations
+after the timed batch. Tables report the median of each statistic across the three samples.
+Percentiles use nearest rank within each sample; samples are not pooled. The raw JSON retains all
+operation latencies, including slow samples. This short run is a development measurement, not a soak
+test or an application capacity guarantee.
+
+The state-size run has three samples of 300 operations after 25 warmups, at concurrency one. It
+verifies final committed count and payload size, records actual serialized state bytes, and retains
+operation latencies. Idle CPU uses three seconds of warmup and ten seconds of measurement per
+polling interval. The historical idle wake-up latency table below has not been rerun as part of this
+dataset.
+
+### Reproduce the released runtime
+
+Use a separate checkout so later runtime changes cannot enter the result. Install the locked
+dependencies and overlay the measurement harness from the commit containing this dataset before
+building the runtime:
+
+```bash
+# Run from your normal checkout; pin the collector used by the archived reports.
+repository_root=$(pwd)
+harness_ref=da5fe31b1ffa18eca92ce43fc26bca619d424d6e
+# To collect new results with the stronger verifier instead:
+# harness_ref=$(git rev-parse HEAD)
+git worktree add --detach /tmp/solid-objects-v1.0.5 v1.0.5
+git archive "$harness_ref" benchmarks | tar -x -C /tmp/solid-objects-v1.0.5
+cd /tmp/solid-objects-v1.0.5
+pnpm install --frozen-lockfile
+pnpm exec tsc -p tsconfig.build.json
+git diff --exit-code v1.0.5 -- src
+
+node benchmarks/run.ts --database sqlite --workload counter \
+  --operations 250 --warmup 25 --repetitions 3 > sqlite-counter.json
+node benchmarks/run.ts --database sqlite --workload cart-outbox \
+  --operations 250 --warmup 25 --repetitions 3 > sqlite-cart-outbox.json
+node benchmarks/large-state.ts --operations 300 --warmup 25 \
+  --repetitions 3 > sqlite-large-state.json
+node benchmarks/idle.ts > sqlite-idle.json
+cd "$repository_root"
+```
+
+Repeat the matrix with `--database postgresql` and `--database mysql` and the benchmark URLs shown
+below, using disposable local databases. Reports contain driver versions and durability settings
+without connection URLs or credentials. Run all scenarios sequentially. Use the recorded host, Node,
+database settings, and driver versions when comparing results; ordinary shared-host activity and
+storage behavior still affect them.
+
+Generate the complete tables from the retained reports with:
+
+```bash
+node benchmarks/summarize.mjs benchmarks/results/v1.0.5-2026-11-07/*.json
+```
+
+The summarizer rejects mixed runtime/harness provenance, missing scenarios or samples, and missing
+per-operation latencies. Keep the per-sample JSON when reporting a median so the variability remains
+reviewable.
+
+The August measurements below retain their original versions, hardware, and methodology.
 
 ## Idle polling
 
-The idle harness measures process CPU and empty database passes for the four
-runtime roles:
+The idle harness measures process CPU and empty database passes for the four runtime roles:
 
 ```bash
 pnpm run benchmark:idle
 ```
 
-It warms each interval for three seconds, measures for ten seconds, and reports
-process user plus system CPU time divided by wall time.
+It warms each interval for three seconds, measures for ten seconds, and reports process user plus
+system CPU time divided by wall time.
 
-Measured on August 16, 2026 on an Apple M5 with Node.js 26.7.0 and in-memory
-SQLite. The before run used 0.13.0; the after run used the prepared 0.13.1 tree.
-Each run started one actor, effect, reminder, and broadcast role.
+Measured on August 16, 2026 on an Apple M5 with Node.js 26.7.0 and in-memory SQLite. The before run
+used 0.13.0; the after run used the prepared 0.13.1 tree. Each run started one actor, effect,
+reminder, and broadcast role.
 
 | Fast interval | Before polls/s | Before CPU | After polls/s | After CPU |
 | ------------: | -------------: | ---------: | ------------: | --------: |
@@ -25,29 +172,28 @@ Each run started one actor, effect, reminder, and broadcast role.
 |        100 ms |         39.596 |     0.906% |         3.999 |    0.121% |
 |        500 ms |          7.999 |     0.251% |         3.999 |    0.104% |
 
-The after run reached the one-second ceiling for all four roles. These are
-developer-laptop measurements, not a CPU guarantee; timer scheduling, JIT,
-database path, and unrelated host activity affect short samples.
+The after run reached the one-second ceiling for all four roles. These are developer-laptop
+measurements, not a CPU guarantee; timer scheduling, JIT, database path, and unrelated host activity
+affect short samples.
 
-Five SQLite samples measured durable enqueue through committed completion after
-2.5 seconds of idleness. The polling-only multi-process harness submits just
-after an empty pass, so it measures approximately the full polling wait rather
-than average arrival latency.
+Five SQLite samples measured durable enqueue through committed completion after 2.5 seconds of
+idleness. The polling-only multi-process harness submits just after an empty pass, so it measures
+approximately the full polling wait rather than average arrival latency.
 
 | Topology                        | 0.13.0 p50 | Prepared 0.13.1 p50 |
 | ------------------------------- | ---------: | ------------------: |
 | One process, in-process wake-up |   2.589 ms |            2.662 ms |
 | Two processes, polling only     | 107.945 ms |        1,006.232 ms |
 
-The local wake-up keeps the one-process path prompt after backoff. The
-polling-only row is the explicit tradeoff: use PostgreSQL notifications or
-optional Redis Pub/Sub when separate processes need low-latency delivery.
+The local wake-up keeps the one-process path prompt after backoff. The polling-only row is the
+explicit tradeoff: use PostgreSQL notifications or optional Redis Pub/Sub when separate processes
+need low-latency delivery.
 
 ## Large state
 
-The large-state harness measures how the committed state size changes
-throughput. It runs one actor and one `increment()` operation with sequential
-turns, so each row isolates the per-turn serialization and row write:
+The large-state harness measures how the committed state size changes throughput. It runs one actor
+and one `increment()` operation with sequential turns, so each row isolates the per-turn
+serialization and row write:
 
 ```bash
 pnpm run benchmark:large-state
@@ -55,11 +201,10 @@ pnpm run benchmark:large-state
 
 Use `--sizes`, `--operations`, and `--warmup` to change the recorded dataset.
 
-Measured on August 29, 2026 on an Apple M5, macOS 26.6, Node.js 24.18.0, and
-SQLite 3.53.1 through `node:sqlite` on a temporary file. Each row is the median
-of three runs of 300 measured operations. The before column used the `0.14.3`
-tree; the after column used the `0.14.4` tree, which removes the redundant
-per-turn state serialization.
+Measured on August 29, 2026 on an Apple M5, macOS 26.6, Node.js 24.18.0, and SQLite 3.53.1 through
+`node:sqlite` on a temporary file. Each row is the median of three runs of 300 measured operations.
+The before column used the `0.14.3` tree; the after column used the `0.14.4` tree, which removes the
+redundant per-turn state serialization.
 
 | Persisted state | Before ms/op | Before ops/s | After ms/op | After ops/s | Gain |
 | --------------: | -----------: | -----------: | ----------: | ----------: | ---: |
@@ -68,15 +213,13 @@ per-turn state serialization.
 |          128 KB |         4.01 |          250 |        2.53 |         395 | 1.6x |
 |            1 MB |        19.11 |           52 |        9.32 |         107 | 2.1x |
 
-The before tree traversed the whole state eight times for each committed
-operation, and nine times for a query. The after tree traverses it four times:
-one image for rollback and comparison, one committed image, and one read for
-each of the two observables guards. The remaining cost at 1 MB is the database
-write of a large row, which the whole-image commit model cannot avoid.
+The before tree traversed the whole state eight times for each committed operation, and nine times
+for a query. The after tree traverses it four times: one image for rollback and comparison, one
+committed image, and one read for each of the two observables guards. The remaining cost at 1 MB is
+the database write of a large row, which the whole-image commit model cannot avoid.
 
-The curve, not the ratio, is the operating instruction. Throughput falls by
-about 6x between 0 KB and 1 MB even after the change. Keep one actor's state
-small. See
+The curve, not the ratio, is the operating instruction. Throughput falls by about 6x between 0 KB
+and 1 MB even after the change. Keep one actor's state small. See
 [State size and throughput](state-and-lifecycle.md#state-size-and-throughput).
 
 ## Scenarios
@@ -85,15 +228,13 @@ small. See
 - `warm-many`: operations rotate across 100 previously created identities.
 - `cold-many`: every measured operation creates a new identity.
 - `synchronous`: the actor method mutates state without yielding.
-- `asynchronous`: the actor method yields through `setImmediate()` before the
-  same mutation.
+- `asynchronous`: the actor method yields through `setImmediate()` before the same mutation.
 - `one-process`: four actor workers run in the caller's Node process.
 - `four-processes`: four Node worker processes share the database.
 
-Latency begins before durable enqueue and ends when the committed result is
-available. Throughput uses the wall time for the measured batch. Percentiles
-use nearest rank. Defaults are 25 warmup operations, 250 measured operations,
-and client concurrency 16.
+Latency begins before durable enqueue and ends when the committed result is available. Throughput
+uses the wall time for the measured batch. Percentiles use nearest rank. Defaults are 25 warmup
+operations, 250 measured operations, and client concurrency 16.
 
 ## Run the harness
 
@@ -103,8 +244,8 @@ SQLite needs no service:
 pnpm run benchmark -- --database sqlite
 ```
 
-PostgreSQL and MySQL runs require a disposable database. The harness deletes
-benchmark rows but leaves its uniquely prefixed empty tables for inspection.
+PostgreSQL and MySQL runs require a disposable database. The harness deletes benchmark rows but
+leaves its uniquely prefixed empty tables for inspection.
 
 ```bash
 SOLID_OBJECTS_POSTGRESQL_BENCHMARK_URL=postgresql://... \
@@ -114,8 +255,9 @@ SOLID_OBJECTS_MYSQL_BENCHMARK_URL=mysql://... \
   pnpm run benchmark -- --database mysql
 ```
 
-Use `--operations`, `--warmup`, and `--concurrency` to change the recorded
-dataset. Redirect stdout to retain the JSON result.
+Use `--operations`, `--warmup`, `--concurrency`, and `--repetitions` to change the recorded dataset.
+The matrix defaults to three repetitions. Select `--workload counter` or `--workload cart-outbox`.
+Redirect stdout to retain the JSON result; progress and runtime diagnostics go to stderr.
 
 ## Observed results
 
@@ -125,8 +267,8 @@ Measured on August 22, 2026 with the `0.14.0` source tree:
 - macOS 26.6
 - Node.js 24.18.0
 - SQLite 3.53.1 through `node:sqlite` on the internal SSD
-- PostgreSQL 17.11 and MySQL 9.7.1, both installed natively and started on a
-  scoped temporary data directory
+- PostgreSQL 17.11 and MySQL 9.7.1, both installed natively and started on a scoped temporary data
+  directory
 - 25 warmup operations, 250 measured operations, concurrency 16
 
 ### SQLite 3.53.1
@@ -180,16 +322,15 @@ Measured on August 22, 2026 with the `0.14.0` source tree:
 | four processes | cold many | synchronous  |  51.82 |   306.1 |  407.22 |  424.45 |
 | four processes | cold many | asynchronous |  27.35 |  554.03 |  807.18 |  868.48 |
 
-The cold and asynchronous cases keep the poorest throughput and the longest
-tail. These are observed limitations. They are not capacity recommendations.
-Repeat the runs on application-shaped payloads before you draw a general
-conclusion. Integration tests cover PostgreSQL 14, MySQL 8.0, and other database
-versions, but this harness did not measure them.
+The cold and asynchronous cases keep the poorest throughput and the longest tail. These are observed
+limitations. They are not capacity recommendations. Repeat the runs on application-shaped payloads
+before you draw a general conclusion. Integration tests cover PostgreSQL 14, MySQL 8.0, and other
+database versions, but this harness did not measure them.
 
 ### Virtualization cost
 
-The same server version ran natively and in Docker Desktop on the same machine,
-on the same day, through the same harness. Only the container boundary changes.
+The same server version ran natively and in Docker Desktop on the same machine, on the same day,
+through the same harness. Only the container boundary changes.
 
 | Database         | Topology and shape              | Native ops/s | Docker ops/s | Native gain |
 | ---------------- | ------------------------------- | -----------: | -----------: | ----------: |
@@ -198,25 +339,23 @@ on the same day, through the same harness. Only the container boundary changes.
 | MySQL 9.7.1      | four processes, warm hot, async |       228.32 |        60.27 |        3.8x |
 | MySQL 9.7.1      | one process, warm hot, sync     |        79.59 |        44.56 |        1.8x |
 
-Across the full matrix, Docker Desktop cost between 1.0x and 7.8x of the native
-throughput. The multi-process rows lose the most, because more connections and
-more commits cross the container boundary. Measure a database on the deployment
-shape you intend to run, and state the boundary with any number you publish.
+Across the full matrix, Docker Desktop cost between 1.0x and 7.8x of the native throughput. The
+multi-process rows lose the most, because more connections and more commits cross the container
+boundary. Measure a database on the deployment shape you intend to run, and state the boundary with
+any number you publish.
 
-Earlier releases of this document reported PostgreSQL 18.4 and MySQL 8.4.11 in
-Docker Desktop on the `0.13.0` tree. Those numbers measured the container as
-much as the database, so the tables above replace them.
+Earlier releases of this document reported PostgreSQL 18.4 and MySQL 8.4.11 in Docker Desktop on the
+`0.13.0` tree. Those numbers measured the container as much as the database, so the tables above
+replace them.
 
 ## Sources of bias
 
 - A developer laptop shares CPU, memory, and storage with unrelated processes.
 - Loopback database connections exclude production network latency.
-- Filesystem cache, SQLite WAL state, Node JIT warmup, and garbage collection
-  affect short runs.
-- Docker Desktop costs between 1.0x and 7.8x of the native throughput. The
-  tables above use native servers. See [Virtualization cost](#virtualization-cost).
-- The payload is a small counter, not a representative application state size.
-  See [Large state](#large-state) for the measured effect of state size.
+- Filesystem cache, SQLite WAL state, Node JIT warmup, and garbage collection affect short runs.
+- Docker Desktop costs between 1.0x and 7.8x of the native throughput. The tables above use native
+  servers. See [Virtualization cost](#virtualization-cost).
+- The payload is a small counter, not a representative application state size. See
+  [Large state](#large-state) for the measured effect of state size.
 - The harness measures default durability settings and one client concurrency.
-- Hot-identity results deliberately include serialization and cannot be scaled
-  by adding workers.
+- Hot-identity results deliberately include serialization and cannot be scaled by adding workers.

package/docs/compare/ai-agents.md

@@ -0,0 +1,252 @@
+# Durable execution for TypeScript AI agents on PostgreSQL: Restate, DBOS, Temporal, and Solid Objects
+
+A long-lived AI agent session must keep its conversation state, apply messages in order, and wake up later for a follow-up, after deploys and crashes. Restate, DBOS Transact, and Temporal do this with durable execution: each tool records the steps of a handler or workflow and resumes after a crash. Solid Objects (the `solid-objects` npm package) does it with an actor for each session: an ordered mailbox, durable state, and reminders in the SQLite, PostgreSQL, or MySQL database that the app already uses. Only DBOS and Solid Objects write their state from your app process to a PostgreSQL database. Restate keeps it in the Restate server. Temporal keeps it in the Temporal Service, which can use PostgreSQL as its own store.
+
+Solid Objects is an independent project. It is not affiliated with Restate, DBOS, or Temporal Technologies.
+
+## The short answer
+
+| Tool          | Where the state lives                                                                                                                               | What a crash repeats                                                                                                                                  | How a delayed follow-up works                                                                                  | What you run                                                                                                                             |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Restate       | A journal and a key-value store inside the Restate server, not in PostgreSQL                                                                        | "Restate replays the journal, skipping completed steps". A `ctx.run` action that did not record its result can run again                              | A delayed message: `ctx.objectSendClient(...).handler(input, restate.rpc.sendOpts({ delay }))`, or `ctx.sleep` | Restate Cloud, Restate BYOC, or a self-hosted Restate server (a single binary with a persistent volume), and your service                |
+| DBOS Transact | Checkpoints in a PostgreSQL system database. DBOS recommends "storing long-lived objects directly in your database"                                 | "Steps are tried _at least once_ but are never re-executed after they complete"                                                                       | Durable sleep with `DBOS.sleep(milliseconds)` in a workflow, or `delaySeconds` when you enqueue                | The library in your Node.js processes and PostgreSQL. The docs say that distributed applications "should also connect to DBOS Conductor" |
+| Temporal      | The event history of each workflow, in the Temporal Service. The service stores it in Cassandra, MySQL, or PostgreSQL (SQLite for development only) | Workflow code replays its event history. "completed Activities will not re-execute", but an activity that did not report its result "will be retried" | A durable timer: `sleep('2 hours')` from `@temporalio/workflow`, or `condition` with a timeout                 | A Temporal Service (the Temporal Server and a database) or Temporal Cloud, and your worker processes                                     |
+| Solid Objects | Actor state, the mailbox, and reminders in tables in your SQL database                                                                              | A turn that did not commit runs again. Effects run at least once with a stable effect ID                                                              | A reminder: `this.schedule({ at, key }).followUp(input)`, stored as a row                                      | Your Node.js process, which calls `runtime.run(signal)`, and your database                                                               |
+
+The facts come from the [Restate documentation](https://docs.restate.dev), the [DBOS documentation](https://docs.dbos.dev), and the [Temporal documentation](https://docs.temporal.io) (checked October 18, 2026).
+
+## Messages in order for one session
+
+- Restate: a virtual object for each session. "Only one write handler runs at a time per key", and "concurrent requests to the same session are automatically queued".
+- DBOS Transact: a workflow for each session that waits with `DBOS.recv`. "Messages are dequeued first-in, first-out from a queue associated with the topic." A partitioned queue with `queuePartitionKey` and `partitionConcurrency: 1` also runs one workflow at a time for each key.
+- Temporal: a long-lived workflow for each session that gets Signals or Updates. Temporal processes messages "in the order they were received". Handlers that wait "can run interleaved with the main Workflow and with one another".
+- Solid Objects: an actor for each session. Messages run one turn at a time, in the order that the runtime stores them.
+
+## Where the model call runs
+
+- Restate: in a `ctx.run` step inside the handler. Restate says that model calls are "Persisted so responses are not re-fetched on recovery". In an exclusive handler, a new message for the same session waits until the handler finishes.
+- DBOS Transact: in a step of the workflow. After the step completes, DBOS does not run it again.
+- Temporal: in an activity. The Temporal integration with the OpenAI Agents SDK for TypeScript is marked "Pre-release". It says that "model calls are executed as Activities, so they retry durably and are not repeated during Workflow replay".
+- Solid Objects: in an effect, outside the turn. The turn ends at once, so a new message does not wait for the model. The effect handler sends the effect ID as the idempotency key.
+
+## Choose Restate when
+
+- You want a journal of each step, and you can run the Restate server or use Restate Cloud.
+- You want workflows, service calls, and virtual objects in one runtime.
+
+See [Restate virtual objects and Solid Objects](restate.md) for the same agent session in each, with code.
+
+## Choose DBOS Transact when
+
+- The agent is a workflow of steps, and a completed step must not run again after a crash.
+- You want the checkpoints in PostgreSQL, with no separate orchestration server.
+
+See [DBOS Transact and Solid Objects](dbos.md) for the details.
+
+## Choose Temporal when
+
+- The agent is a long workflow of many steps, and you want its event history and replay.
+- You already run a Temporal Service, or you can use Temporal Cloud.
+- A session can stay inside the history limit: "51,200 Events or 50 MB". A longer session continues as new with a new history.
+
+## Choose Solid Objects when
+
+- Each session has state that many messages change in order, and the session must wake up later.
+- You want the session state in the SQL database that you already operate, back up, and query.
+- You want a state change and its effects and reminders to commit in one SQL transaction.
+- You do not want to run another server.
+
+## An AI agent session with Solid Objects
+
+The task: a Node.js TypeScript backend runs a long-lived AI agent session for each user. A session holds conversation state. It receives user messages and tool results that must apply in order. It can schedule its own follow-up, for example "check the order status again in 2 hours". Sessions must survive deploys and process crashes. The app uses PostgreSQL and runs several Node.js processes.
+
+There is one `AgentSession` actor for each user ID.
+
+```typescript
+import { Actor, type EffectSuccessPayload } from "solid-objects"
+
+export const FOLLOW_UP_MILLISECONDS = 2 * 60 * 60 * 1000
+
+const KEPT_ENTRIES = 50
+
+export type Entry = { role: "user" | "tool" | "assistant"; content: string }
+
+type ReplyArguments = { turn: number; history: Entry[] }
+type ReplyResult = { content: string }
+
+export class AgentSession extends Actor {
+  static override readonly actorType = "AgentSession"
+
+  history: Entry[] = []
+  turn = 0
+  followUps: string[] = []
+
+  receive({ role, content }: { role: "user" | "tool"; content: string }): { turn: number } {
+    this.#append({ role, content })
+    return { turn: this.turn }
+  }
+
+  followUpLater({ topic }: { topic: string }): void {
+    this.schedule({ at: new Date(Date.now() + FOLLOW_UP_MILLISECONDS), key: topic }).followUp({
+      topic,
+    })
+  }
+
+  followUp({ topic }: { topic: string }): void {
+    this.followUps = [...this.followUps, topic]
+    this.#append({ role: "tool", content: `Follow-up due: ${topic}` })
+  }
+
+  replied({ arguments: reply, result }: EffectSuccessPayload<ReplyArguments, ReplyResult>): void {
+    if (reply.turn !== this.turn) return
+    this.history = [...this.history, { role: "assistant" as const, content: result.content }].slice(
+      -KEPT_ENTRIES,
+    )
+  }
+
+  #append(entry: Entry): void {
+    this.history = [...this.history, entry].slice(-KEPT_ENTRIES)
+    this.turn += 1
+    this.emit("model_reply", {
+      arguments: { turn: this.turn, history: this.history },
+      onSuccess: "replied",
+    })
+  }
+}
+```
+
+The runtime registers the actor and the effect that calls the model:
+
+```typescript
+import { createRuntime, type SolidObjectsRuntime } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+import { AgentSession, type Entry } from "./agent-session.js"
+
+export type ModelClient = {
+  reply(options: { idempotencyKey: string; history: Entry[] }): Promise<{ content: string }>
+}
+
+const CALLER_OPERATIONS = new Set(["receive", "followUpLater"])
+
+export function agentRuntime({
+  path,
+  model,
+  retryDelayMilliseconds,
+}: {
+  path: string
+  model: ModelClient
+  retryDelayMilliseconds?: (attempt: number) => number
+}): SolidObjectsRuntime {
+  const runtime = createRuntime({
+    database: sqlite({ path }),
+    ...(retryDelayMilliseconds ? { retryDelayMilliseconds } : {}),
+    authorizeMessage: ({ actorType, actorId, operation, authorizationContext }) =>
+      actorType === AgentSession.actorType &&
+      CALLER_OPERATIONS.has(operation) &&
+      ownsSession({ actorId, authorizationContext }),
+    authorizeQuery: ({ actorType, actorId, authorizationContext }) =>
+      actorType === AgentSession.actorType && ownsSession({ actorId, authorizationContext }),
+  })
+  runtime.register(AgentSession)
+  runtime.registerEffect("model_reply", (argumentsValue, context) =>
+    model.reply({ idempotencyKey: context.id, history: argumentsValue.history as Entry[] }),
+  )
+  return runtime
+}
+
+function ownsSession({
+  actorId,
+  authorizationContext,
+}: {
+  actorId: string
+  authorizationContext: unknown
+}): boolean {
+  if (typeof authorizationContext !== "object" || authorizationContext === null) return false
+  return "userId" in authorizationContext && authorizationContext.userId === actorId
+}
+```
+
+The example uses SQLite so that the tests run without a database server. For PostgreSQL, import `postgresql` from `solid-objects/database/postgresql` and pass `postgresql({ connectionString })` as `database`.
+
+The app sends each message with `send`, so that the message is stored before the call returns:
+
+```typescript
+await runtime
+  .ref(AgentSession, user.id)
+  .send.with({ authorizationContext: { userId: user.id }, idempotencyKey: message.id })
+  .receive({ role: "user", content: message.text })
+```
+
+At least one process calls `runtime.run(signal)`. It runs the stored messages, the effects, and the reminders.
+
+How it works:
+
+- `receive` appends the entry, moves `turn` forward, and stages a `model_reply` effect. The model call runs outside the turn.
+- If the effect fails, the runtime retries it with the same ID, up to `maxAttempts` (5 by default).
+- `replied` adds the model reply only if no newer message or follow-up arrived.
+- `followUpLater` schedules a keyed reminder. The reminder is a row in the database, so it runs after a deploy or a restart.
+
+A model call can run again after a crash, because effects run at least once. If the model API does not accept an idempotency key, the repeated call can cost tokens again. A step in Restate, DBOS, or Temporal that crashes before its result is recorded runs again too.
+
+### What the tests prove
+
+[The tests](../../test/compare-agent-session.test.ts) show these results:
+
+- Two user messages and a tool result apply in the order that they were sent.
+- A model call that fails and runs again uses the same idempotency key, and the session keeps one reply.
+- When two messages arrive before the model replies, the session keeps only the reply for the newest turn.
+- A follow-up runs after a runtime restart.
+- A caller who does not own the session gets `Unauthorized`.
+
+## Questions that teams ask
+
+**Which of these keep state in my PostgreSQL database?** DBOS Transact keeps its checkpoints in a PostgreSQL system database. Solid Objects keeps actor state in your SQLite, PostgreSQL, or MySQL database. Restate keeps state in its own server. For that state, Restate says "SQL is supported only for analytics / introspection, not for updates/transactions". Temporal keeps the event history in the Temporal Service, which can use PostgreSQL as its own store.
+
+**Is Solid Objects mature enough?** Here are the facts:
+
+- Version 1.0.0: October 13, 2026. The public API follows [semantic versioning](../versioning.md).
+- [Maintenance and continuity](../maintenance.md) tells you who maintains the project and how a release is made.
+- One first-party application with more than 100,000 users runs it in production. That is a count of users, not a measure of load.
+- The [benchmarks](../benchmarks.md) are development measurements. [Versioning](../versioning.md) states what version 1.0 does not claim.
+
+The npm packages of Temporal, Restate, and DBOS were first published between 2021 and 2023 ([npm registry](https://www.npmjs.com), checked October 18, 2026). If a longer history matters more than keeping the session state in your own database, choose one of them.
+
+**Is delivery exactly once?** No. In Solid Objects, delivery is at least once. Use the effect ID as the idempotency key for each external call. See [correctness](../correctness.md) and [effect recovery](../effect-recovery.md).
+
+**Can I use more than one?** Yes. For example, keep each session in a Solid Objects actor, and run a long multi-step task as a workflow in DBOS or Temporal.
+
+## Sources
+
+Checked October 18, 2026:
+
+- [Restate key concepts](https://docs.restate.dev/foundations/key-concepts)
+- [Restate durable sessions](https://docs.restate.dev/ai/patterns/sessions)
+- [Restate durable agents](https://docs.restate.dev/ai/patterns/durable-agents)
+- [Restate scheduling and timers](https://docs.restate.dev/develop/ts/durable-timers)
+- [Restate service communication](https://docs.restate.dev/develop/ts/service-communication)
+- [Restate hosting overview](https://docs.restate.dev/hosting/overview)
+- [Restate server overview](https://docs.restate.dev/server/overview)
+- [Restate databases guide](https://docs.restate.dev/guides/databases)
+- [DBOS architecture](https://docs.dbos.dev/architecture)
+- [Migrating from Temporal to DBOS](https://docs.dbos.dev/explanations/migrating-from-temporal)
+- [DBOS workflow tutorial](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial)
+- [DBOS workflow communication](https://docs.dbos.dev/typescript/tutorials/workflow-communication)
+- [DBOS methods reference](https://docs.dbos.dev/typescript/reference/methods)
+- [DBOS queue tutorial](https://docs.dbos.dev/typescript/tutorials/queue-tutorial)
+- [Temporal workflow execution](https://docs.temporal.io/workflow-execution)
+- [Temporal event history](https://docs.temporal.io/workflow-execution/event)
+- [Temporal activity definition](https://docs.temporal.io/activity-definition)
+- [Temporal TypeScript timers](https://docs.temporal.io/develop/typescript/workflows/timers)
+- [Temporal message handling](https://docs.temporal.io/handling-messages)
+- [Temporal workflow execution limits](https://docs.temporal.io/workflow-execution/limits)
+- [Temporal Service persistence](https://docs.temporal.io/temporal-service/persistence)
+- [Temporal workers](https://docs.temporal.io/workers)
+- [Temporal and the OpenAI Agents SDK for TypeScript](https://docs.temporal.io/develop/typescript/integrations/openai-agents)
+
+## More information
+
+- [All comparisons](../comparisons.md)
+- [Restate virtual objects and Solid Objects](restate.md)
+- [DBOS Transact and Solid Objects](dbos.md)
+- [Virtual actors in TypeScript](../virtual-actors.md)
+- [Guide for coding agents](../agents.md)