solid-objects 0.14.2 → 0.14.4

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.14.4 - 2026-08-29
+
+- Cut the per-turn state traversals from eight to four. The runtime built the
+  whole state image eight times for each committed operation, and nine times
+  for a query, where two are necessary. The commit path now passes the image it
+  already holds to the observables guard, and the query check reads the
+  committed image instead of taking its own. The guard is unchanged: it still
+  reads the state after `observables()` returns, because only that read sees a
+  mutation.
+- Compute the default state once for each registered actor class. Every `send`
+  and every hydration constructed a throwaway actor and serialized its full
+  default state. The constructor must not depend on external state, so one
+  cached image per validated definition is correct. Each caller receives a
+  detached copy.
+- Stop building a string that `normalizeJson` discards. It called
+  `JSON.stringify` on every value, then used the result only when a byte limit
+  was given. `actorState`, `deepCopy`, and `stableJson` all pass no limit.
+- Measured on an Apple M5 with SQLite: 1.2x throughput at 0 KB of state, 1.3x
+  at 16 KB, 1.6x at 128 KB, and 2.1x at 1 MB. See
+  [Large state](docs/benchmarks.md#large-state).
+- Add `warnStateBytes`, a soft threshold that defaults to 128 KB. A commit
+  above it reports one `solid_objects.state.large` instrumentation event with
+  the actor type, the actor ID, the byte count, and the threshold. The runtime
+  reports it only after the commit succeeds, so a turn that rolls back stays
+  silent. The event holds no application state, and the runtime measures the
+  size only when an `instrumentation` callback is configured. `maxStateBytes` keeps its 5 MB hard
+  default, which fails the turn. Throughput at that size is about one operation
+  per second, so the warning names the constraint before an application meets
+  it.
+- Add a `large-state` benchmark scenario, `pnpm run benchmark:large-state`,
+  that reports operations per second at 0 KB, 16 KB, 128 KB, and 1 MB, and
+  document the measured curve in `docs/state-and-lifecycle.md`.
+
+- Align the use-case claims with the Ruby gem. The README table sold per-key
+  rate limits, while the Ruby fit guide called a rate limiter an anti-pattern.
+  Both projects now draw one line: a low-rate quota that a reminder refills
+  fits, because each check is one durable ordered message, and a limiter that
+  every request touches does not.
+- Point the high-QPS reader at [Solid Objects Pro](https://solidobjects.pro/)
+  from the rate-limit sentence in the README and `docs/fit.md`, and name what
+  it adds for that shape: grouped commits and ephemeral operations. The README
+  states that it ships for the Rails gem today and that the Node build is in
+  development.
+- Move the early-release caveat off the first screen. It is now a `Status`
+  section at the end of the README, with a table-of-contents entry, which
+  matches where the Ruby gem keeps the same statement. The first screen keeps
+  the transaction caveat, because that one changes whether a reader should
+  install anything.
+- State the workflow limit next to the workflow row instead of only in
+  `docs/fit.md`. A workflow fits when one entity owns the mutable state and its
+  mailbox holds the step order. A durable execution engine that replays named
+  steps from a step log is a different tool.
+
+## 0.14.3 - 2026-08-25
+
+- Rewrite the first screen around the objection a reader actually has. The
+  README led with a shopping cart that appended to an array, which invites the
+  reply that one SQL statement already does it. It now leads with the ticket
+  sale from the homepage: 100 seats, a hold, a ten-minute expiry that frees the
+  seat, and a published count. That is the smallest example needing three
+  things from one number, and the three things are the argument.
+- Answer "why not just use transactions?" in the first screen instead of
+  burying the fit sections. The section concedes the transaction and the row
+  lock first, including `navigator.locks` in the browser, then argues scope
+  rather than discipline: any `expiresAt` or `scheduledAt` column is evidence
+  the critical section already outlived the lock, and what follows it is a
+  sweeper and a race.
+- Add "Is it worth installing here?", which names who should not install this,
+  and point readers with high-QPS reads or hot identities at
+  [Solid Objects Pro](https://solidobjects.pro/).
+- Correct two claims. The realtime section said a value is published once per
+  change from the saving turn; the turn records the publication atomically,
+  while delivery is a separate worker and is at least once. Design provenance
+  said the API was redesigned around Web Components; there is no
+  `customElements` or `HTMLElement` in the package.
+- Cut the README from 590 to about 540 lines by removing what `docs/` already
+  documented and what the page said three times, and add the table of contents
+  the standard-readme specification asks for above 100 lines.
+
 ## 0.14.2 - 2026-08-24
 
 - State that background pickup needs `runtime.run(signal)`
@@ -136,8 +215,8 @@
   `createdAtMs` rather than comparing `instanceId` values directly.
   `createdAtMs` orders incarnations at millisecond granularity; destroying
   and recreating the same actor identity within the same millisecond
-  produces two incarnations a caller cannot order by `createdAtMs` alone —
-  see `docs/correctness.md`.
+  produces two incarnations a caller cannot order by `createdAtMs` alone.
+  See `docs/correctness.md`.
 
 ## 0.13.3 - 2026-08-18