solid-objects 0.14.1 → 0.14.2

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.14.2 - 2026-08-24
+
+- State that background pickup needs `runtime.run(signal)`
+  ([#22](https://github.com/cardmagic/solid-objects-js/issues/22)). The
+  README's programming-model example works without it because the caller's
+  own path executes the call, and nothing on that page said that a process
+  which installs and then waits claims nothing. An external prober built a
+  two-process harness from the README and read the unclaimed messages as
+  stranded. The README and `docs/operations.md` now state it, and
+  `test/background-pickup.test.ts` pins it: a sent message reads `ready`
+  after `install()`, and `completed` once `run(signal)` starts the roles.
+- Build the same example with `configure()` and address the actor as
+  `Cart.ref("cart-123")`, matching every other reference example in the
+  documentation. `createRuntime()` deliberately leaves the process default
+  unset, so the static form needs `configure()`.
+- Add `examples/at-least-once` and `pnpm run test:at-least-once`
+  ([#23](https://github.com/cardmagic/solid-objects-js/issues/23)): an
+  executable proof that the at-least-once clause fires and that the
+  documented remedy absorbs it. An effect worker crashes between the
+  external sink write and the acknowledgement; after restart the sink
+  reads 2 with deduplication off, and 1 when a guard on the stable
+  effect id is in place. The state commit happens exactly once in both
+  runs, and both deliveries carry the same effect id. CI runs the demo
+  alongside the recovery demo.
+
 ## 0.14.1 - 2026-08-23
 
 - Add `solid-objects/signals`, live signals on actor references

package/README.md

@@ -39,7 +39,7 @@ contract. See [Solid Objects in the browser](#solid-objects-in-the-browser).
 ## The programming model
 
 ```typescript
-import { Actor, createRuntime } from "solid-objects"
+import { Actor, configure } from "solid-objects"
 import { sqlite } from "solid-objects/database/sqlite"
 
 class Cart extends Actor {
@@ -53,7 +53,7 @@ class Cart extends Actor {
   }
 }
 
-const runtime = createRuntime({
+const runtime = configure({
   database: sqlite({ path: "cart.sqlite3" }),
   authorizeMessage: () => true,
   authorizeQuery: () => true,
@@ -62,7 +62,7 @@ const runtime = createRuntime({
 await runtime.install()
 
 try {
-  const cart = runtime.ref(Cart, "cart-123")
+  const cart = Cart.ref("cart-123")
   await Promise.all([cart.add({ sku: "blue-shirt" }), cart.add({ sku: "green-hat" })])
 } finally {
   await runtime.close()
@@ -73,6 +73,18 @@ Both calls enter the durable mailbox for `cart-123`. They execute in order and
 commit one state transition at a time, even when different requests or Node.js
 processes submit them concurrently.
 
+`install()` prepares the database and starts nothing. The example above finishes
+because the caller's own path executes each call. A process serves background
+work only after `runtime.run(signal)` starts its roles, so a process that
+installs and then waits never claims a ready message. Nothing is lost while no
+process runs. The message stays ready until one does.
+
+```typescript
+const controller = new AbortController()
+process.on("SIGTERM", () => controller.abort())
+await runtime.run(controller.signal)
+```
+
 ## Run it now with SQLite
 
 Node.js 24.4.0 or newer is required. Node.js 24.15 or newer is preferred,

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.14.1";
+export declare const VERSION = "0.14.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.14.1";
+export const VERSION = "0.14.2";
 //# sourceMappingURL=version.js.map

package/docs/correctness.md

@@ -58,7 +58,12 @@
 
 - At-least-once execution means actor code may begin more than once. State and
   staged intents from a failed turn roll back, but arbitrary external work does
-  not. External systems need stable idempotency keys.
+  not. External systems need stable idempotency keys. This clause is
+  observable, not decorative: `pnpm run test:at-least-once` crashes an
+  effect worker between the sink write and the acknowledgement, restarts
+  it, and shows the sink reading 2 with deduplication off — then shows a
+  guard on the stable effect id absorbing the same duplicate, with the
+  sink reading 1. The state commit happens exactly once in both runs.
 - The activation fence protects the Solid Objects commit. It cannot revoke or
   undo network calls, files, emails, payments, or other external effects.
 - One identity processes one write operation at a time. This is the ordering

package/docs/operations.md

@@ -1,5 +1,12 @@
 # Operations
 
+`install()` prepares the database and starts nothing. A process serves
+background work only after `runtime.run(signal)` starts its roles. A process
+that registers actors, installs, and then waits never claims a ready message,
+and work enqueued with `send` stays ready until some process runs the roles.
+A direct call or an explicit `sync` needs no running role, because the caller's
+own path executes it.
+
 Runtime roles use durable polling as the correctness fallback. Consecutive
 empty passes double each role's wait from `pollingIntervalMilliseconds` to
 `idlePollingIntervalMilliseconds`, which defaults to one second. Processed

package/examples/at-least-once/actor.ts

@@ -0,0 +1,13 @@
+import { Actor } from "solid-objects"
+
+export class DeliveryCounter extends Actor {
+  static override readonly actorType = "DeliveryCounter"
+
+  count = 0
+
+  deliver(): number {
+    this.count += 1
+    this.emit("record", { arguments: {} })
+    return this.count
+  }
+}

package/examples/at-least-once/demo.ts

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict"
+import { fork, type ChildProcess } from "node:child_process"
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { createRuntime } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+import { DeliveryCounter } from "./actor.ts"
+import { readSink } from "./sink.ts"
+
+const directory = await mkdtemp(join(tmpdir(), "solid-objects-at-least-once-"))
+const databasePath = join(directory, "state.sqlite3")
+const runtime = createRuntime({
+  database: sqlite({ path: databasePath, timeoutMilliseconds: 2_000, lockRetryAttempts: 20 }),
+  leaseDurationMilliseconds: 250,
+  leaseRenewalIntervalMilliseconds: 50,
+  processHeartbeatIntervalMilliseconds: 75,
+  processAliveThresholdMilliseconds: 300,
+  workerCount: 1,
+  effectWorkerCount: 0,
+  reminderSchedulerCount: 0,
+  retentionIntervalMilliseconds: 0,
+  deadProcessCleanupIntervalMilliseconds: 0,
+  authorizeMessage: () => true,
+  authorizeQuery: () => true,
+  authorizeAdministration: () => true,
+})
+
+try {
+  runtime.register(DeliveryCounter)
+  await runtime.install()
+  const duplicate = await proveDuplicateAtSink()
+  const remedy = await proveDeduplicationAbsorbsIt()
+  process.stdout.write(`${JSON.stringify({ duplicate, remedy }, null, 2)}\n`)
+} finally {
+  await runtime.close()
+  await rm(directory, { recursive: true })
+}
+
+async function proveDuplicateAtSink(): Promise<{
+  stateCommits: number
+  sinkDeliveries: number
+  sameEffectId: boolean
+  attempts: number[]
+}> {
+  const sinkPath = join(directory, "sink-dedup-off.json")
+  await stageOneDelivery("dedup-off")
+  await crashThenRecover({ sinkPath, deduplicate: "off" })
+
+  const sink = await readSink(sinkPath)
+  const snapshot = await runtime.ref(DeliveryCounter, "dedup-off").snapshot()
+  assert.equal(snapshot.count, 1, "the state commit happened exactly once")
+  assert.equal(sink.deliveries.length, 2, "the sink observed the duplicate")
+  assert.equal(
+    sink.deliveries[0]?.effectId,
+    sink.deliveries[1]?.effectId,
+    "both deliveries carried the same stable effect id",
+  )
+  return {
+    stateCommits: snapshot.count,
+    sinkDeliveries: sink.deliveries.length,
+    sameEffectId: sink.deliveries[0]?.effectId === sink.deliveries[1]?.effectId,
+    attempts: sink.deliveries.map((delivery) => delivery.attempt),
+  }
+}
+
+async function proveDeduplicationAbsorbsIt(): Promise<{
+  stateCommits: number
+  sinkDeliveries: number
+}> {
+  const sinkPath = join(directory, "sink-dedup-on.json")
+  await stageOneDelivery("dedup-on")
+  await crashThenRecover({ sinkPath, deduplicate: "on" })
+
+  const sink = await readSink(sinkPath)
+  const snapshot = await runtime.ref(DeliveryCounter, "dedup-on").snapshot()
+  assert.equal(snapshot.count, 1, "the state commit happened exactly once")
+  assert.equal(sink.deliveries.length, 1, "the stable effect id absorbed the duplicate")
+  return { stateCommits: snapshot.count, sinkDeliveries: sink.deliveries.length }
+}
+
+async function stageOneDelivery(actorId: string): Promise<void> {
+  const message = await runtime.ref(DeliveryCounter, actorId).send.deliver()
+  const worker = runtime.worker()
+  try {
+    let processed = 0
+    for (let attempt = 0; attempt < 200 && processed === 0; attempt += 1) {
+      processed = await worker.runOnce({ activationRetention: "release" })
+      if (processed === 0) await new Promise((resolve) => setTimeout(resolve, 10))
+    }
+    assert.equal(processed, 1, "the actor turn committed and staged the effect")
+  } finally {
+    await worker.stop()
+  }
+  assert.equal(await message.status(), "completed")
+}
+
+async function crashThenRecover(options: {
+  sinkPath: string
+  deduplicate: "on" | "off"
+}): Promise<void> {
+  const crashing = spawnEffectWorker({ ...options, mode: "crash" })
+  const crashExit = await crashing.finished
+  assert.equal(crashExit, 1, "the first delivery crashed before acknowledgement")
+
+  await new Promise((resolve) => setTimeout(resolve, 400))
+
+  const recovering = spawnEffectWorker({ ...options, mode: "complete" })
+  const recoveryExit = await recovering.finished
+  assert.equal(recoveryExit, 0, "the second delivery completed and acknowledged")
+}
+
+function spawnEffectWorker(options: {
+  sinkPath: string
+  deduplicate: "on" | "off"
+  mode: "crash" | "complete"
+}): { child: ChildProcess; finished: Promise<number | null> } {
+  const child = fork(
+    fileURLToPath(new URL("./effect-worker.ts", import.meta.url)),
+    [databasePath, options.sinkPath, options.mode, options.deduplicate],
+    { stdio: ["ignore", "inherit", "inherit", "ipc"] },
+  )
+  const finished = new Promise<number | null>((resolve, reject) => {
+    child.once("exit", (code) => resolve(code))
+    child.once("error", reject)
+  })
+  return { child, finished }
+}

package/examples/at-least-once/effect-worker.ts

@@ -0,0 +1,62 @@
+import { createRuntime } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+import { DeliveryCounter } from "./actor.ts"
+import { recordDelivery } from "./sink.ts"
+
+const databasePath = requiredArgument(2)
+const sinkPath = requiredArgument(3)
+const mode = requiredArgument(4)
+const deduplicate = requiredArgument(5) === "on"
+
+const runtime = createRuntime({
+  database: sqlite({ path: databasePath, timeoutMilliseconds: 2_000, lockRetryAttempts: 20 }),
+  pollingIntervalMilliseconds: 10,
+  leaseDurationMilliseconds: 250,
+  leaseRenewalIntervalMilliseconds: 50,
+  processHeartbeatIntervalMilliseconds: 75,
+  processAliveThresholdMilliseconds: 300,
+  workerCount: 0,
+  effectWorkerCount: 1,
+  reminderSchedulerCount: 0,
+  retentionIntervalMilliseconds: 0,
+  deadProcessCleanupIntervalMilliseconds: 0,
+  authorizeMessage: () => true,
+  authorizeQuery: () => true,
+  authorizeAdministration: () => true,
+})
+
+runtime.register(DeliveryCounter)
+runtime.registerEffect("record", async (_argumentsValue, context) => {
+  const { applied } = await recordDelivery({
+    path: sinkPath,
+    effectId: context.id,
+    attempt: context.attempt,
+    deduplicate,
+  })
+  process.send?.({ event: "sink.recorded", effectId: context.id, applied })
+  if (mode === "crash") {
+    process.exit(1)
+  }
+  return null
+})
+await runtime.install()
+const effectWorker = runtime.effectWorker()
+
+try {
+  let processed = 0
+  for (let attempt = 0; attempt < 200 && processed === 0; attempt += 1) {
+    processed = await effectWorker.runOnce()
+    if (processed === 0) await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+  if (processed === 0) throw new Error("no effect became claimable")
+  process.send?.({ event: "effects.finished", processed })
+} finally {
+  await effectWorker.stop()
+  await runtime.close()
+}
+
+function requiredArgument(index: number): string {
+  const value = process.argv[index]
+  if (!value) throw new TypeError(`argument ${index - 1} is required`)
+  return value
+}

package/examples/at-least-once/sink.ts

@@ -0,0 +1,34 @@
+import { readFile, writeFile } from "node:fs/promises"
+
+export interface SinkDelivery {
+  effectId: string
+  attempt: number
+}
+
+export interface SinkState {
+  deliveries: SinkDelivery[]
+}
+
+export async function readSink(path: string): Promise<SinkState> {
+  try {
+    const parsed: SinkState = JSON.parse(await readFile(path, "utf-8"))
+    return parsed
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { deliveries: [] }
+    throw error
+  }
+}
+
+export async function recordDelivery(options: {
+  path: string
+  effectId: string
+  attempt: number
+  deduplicate: boolean
+}): Promise<{ applied: boolean }> {
+  const sink = await readSink(options.path)
+  const seen = sink.deliveries.some((delivery) => delivery.effectId === options.effectId)
+  if (options.deduplicate && seen) return { applied: false }
+  sink.deliveries.push({ effectId: options.effectId, attempt: options.attempt })
+  await writeFile(options.path, JSON.stringify(sink, null, 2))
+  return { applied: true }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-objects",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Race-free realtime state per application identity, backed by your SQL database",
   "type": "module",
   "license": "MIT",
@@ -107,6 +107,7 @@
     "test:mysql": "vitest run test/mysql.test.ts",
     "test:package": "node scripts/release-artifact-smoke.mjs",
     "test:recovery": "pnpm run build && node examples/failure-recovery/demo.ts",
+    "test:at-least-once": "pnpm run build && node examples/at-least-once/demo.ts",
     "test:redis": "vitest run test/redis-wake-up.test.ts",
     "test:watch": "vitest",
     "benchmark": "pnpm run build && node benchmarks/run.ts",