Skip to content

docs: tighten the README prose #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cardmagic merged 1 commit into from
Sep 7, 2026
+4 −6
Merged

docs: tighten the README prose #44

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,8 +138,7 @@ policies must bind actor IDs and operations to the authenticated user or tenant.

The handwritten version usually starts with a row lock. Then it gains an
`expiresAt` column, a sweeper, retries, per-room ordering, and a broadcast path
that must agree with the write. The original transaction has developed a robust
interplay with four other subsystems.
that must agree with the write. The original transaction now depends on four other subsystems.

Solid Objects makes the application-defined identity the coordination boundary.
Its state, mailbox, retries, reminders, and staged consequences live in SQLite,
Expand All @@ -153,8 +152,7 @@ required. Redis is optional wake-up plumbing, not durable state.
- Accounts, devices, and long-lived jobs whose next action depends on committed state.
- Realtime multi-user state where publications must follow committed revisions.

Different identities can run concurrently. One global identity is merely a
queue wearing an ambitious name.
Different identities can run concurrently. One global identity serializes everything.

## Solid Objects in the browser

Expand Down Expand Up @@ -233,7 +231,7 @@ The wire shapes are documented in the
## When a transaction is better

Often. If all the work happens in one request, use a transaction, constraint, or
`SELECT ... FOR UPDATE`. It is smaller, faster, and does not need a manifesto.
`SELECT ... FOR UPDATE`. It is smaller and faster.

Use Solid Objects when the critical section outlives that transaction: work
must happen later, survive a restart, or remain ordered across several requests
Expand All @@ -250,7 +248,7 @@ or jobs. A plain counter is not a reason to install this package.
- Background work needs `runtime.run(signal)`. If no process is running, committed work waits in SQL rather than disappearing.
- Your application still owns authorization, database backups, failover, WebSocket transport, and capacity planning.

Exactly once remains absent, despite its excellent branding. Read the
There is no exactly-once delivery. Read the
[correctness contract](docs/correctness.md) before using important data.

## Read more
Expand Down