solid-objects 0.13.1 → 0.13.3

package/examples/failure-recovery/demo.ts

@@ -8,6 +8,11 @@ import { fork, type ChildProcess } from "node:child_process"
 import { createRuntime, type ActorReference, type MessageReference } from "solid-objects"
 import { sqlite } from "solid-objects/database/sqlite"
 import { RecoveryCounter } from "./actor.ts"
+import {
+  assertSerializedExecution,
+  parseSerializationEvent,
+  type SerializationProof,
+} from "./serialization.ts"
 
 interface WorkerMessage {
   event: string
@@ -15,12 +20,6 @@ interface WorkerMessage {
   processed?: number
 }
 
-interface SerializationEvent {
-  event: "start" | "finish"
-  messageId: string
-  at: number
-}
-
 interface ExternalEffectEvent {
   messageId: string
   attempt: number
@@ -59,7 +58,7 @@ try {
 
 assert.equal(existsSync(directory), false)
 
-async function proveSerialization(): Promise<{ finalState: number; overlap: false }> {
+async function proveSerialization(): Promise<SerializationProof & { finalState: number }> {
   const controlDirectory = join(directory, "serialization")
   await mkdir(controlDirectory)
   const reference = runtime.ref(RecoveryCounter, "serialized")
@@ -74,15 +73,10 @@ async function proveSerialization(): Promise<{ finalState: number; overlap: fals
     join(controlDirectory, "serialization.jsonl"),
     parseSerializationEvent,
   )
-  assert.equal(events.length, 4)
-  const starts = events.filter((event) => event.event === "start")
-  const finishes = events.filter((event) => event.event === "finish")
-  assert.equal(starts.length, 2)
-  assert.equal(finishes.length, 2)
-  assert(Number(starts[1]?.at) >= Number(finishes[0]?.at))
+  const proof = assertSerializedExecution(events, { messageCount: 2 })
   const snapshot = await reference.snapshot()
   assert.equal(snapshot.count, 2)
-  return { finalState: snapshot.count, overlap: false }
+  return { ...proof, finalState: snapshot.count }
 }
 
 async function proveCrashRecovery(): Promise<{
@@ -200,18 +194,6 @@ async function readJsonLines<Value>(
   return (await readFile(path, "utf8")).trim().split("\n").filter(Boolean).map(parse)
 }
 
-function parseSerializationEvent(line: string): SerializationEvent {
-  const event = JSON.parse(line) as Partial<SerializationEvent>
-  if (
-    (event.event !== "start" && event.event !== "finish") ||
-    typeof event.messageId !== "string" ||
-    typeof event.at !== "number"
-  ) {
-    throw new TypeError("invalid serialization event")
-  }
-  return { event: event.event, messageId: event.messageId, at: event.at }
-}
-
 function parseExternalEffectEvent(line: string): ExternalEffectEvent {
   const event = JSON.parse(line) as Partial<ExternalEffectEvent>
   if (

package/examples/failure-recovery/serialization.ts

@@ -0,0 +1,133 @@
+import assert from "node:assert/strict"
+
+export interface SerializationEvent {
+  event: "start" | "finish"
+  messageId: string
+  attempt: number
+  processId: number
+  at: number
+}
+
+export interface SerializationProof {
+  executions: number
+  retried: boolean
+  supersededOverlap: boolean
+}
+
+interface Execution {
+  messageId: string
+  attempt: number
+  processId: number
+  startedAt: number
+  finishedAt: number
+}
+
+export function parseSerializationEvent(line: string): SerializationEvent {
+  const event = JSON.parse(line) as Partial<SerializationEvent>
+  if (
+    (event.event !== "start" && event.event !== "finish") ||
+    typeof event.messageId !== "string" ||
+    typeof event.attempt !== "number" ||
+    typeof event.processId !== "number" ||
+    typeof event.at !== "number"
+  ) {
+    throw new TypeError("invalid serialization event")
+  }
+  return {
+    event: event.event,
+    messageId: event.messageId,
+    attempt: event.attempt,
+    processId: event.processId,
+    at: event.at,
+  }
+}
+
+// One identity commits one state transition at a time. The control file is
+// written outside the transaction, so it records execution attempts rather than
+// commits: a worker that loses its lease keeps running until it notices, and its
+// replacement executes the same message under a higher attempt. The superseded
+// attempt may therefore overlap anything, because its write is fenced out and
+// the committed state is what proves it.
+//
+// Each event carries its attempt and process, so a start pairs with its own
+// finish rather than with whichever finish arrived next. Without that, a
+// superseded attempt finishing late reads as its replacement finishing, and a
+// second message could then overlap a replacement that is still running.
+export function assertSerializedExecution(
+  events: readonly SerializationEvent[],
+  options: { messageCount: number },
+): SerializationProof {
+  const executions = pairExecutions(events)
+
+  const messageIds = new Set(executions.map((execution) => execution.messageId))
+  assert.equal(
+    messageIds.size,
+    options.messageCount,
+    `expected ${options.messageCount} messages to run, saw ${messageIds.size}`,
+  )
+
+  const survivingAttempt = new Map<string, number>()
+  for (const execution of executions) {
+    const highest = survivingAttempt.get(execution.messageId) ?? 0
+    if (execution.attempt > highest) survivingAttempt.set(execution.messageId, execution.attempt)
+  }
+  const surviving = executions.filter(
+    (execution) => survivingAttempt.get(execution.messageId) === execution.attempt,
+  )
+
+  for (const [index, execution] of surviving.entries()) {
+    for (const other of surviving.slice(index + 1)) {
+      assert(
+        !overlaps(execution, other),
+        `${describe(execution)} and ${describe(other)} overlap, and neither was superseded`,
+      )
+    }
+  }
+
+  const supersededOverlap = executions.some((execution) =>
+    executions.some((other) => other !== execution && overlaps(execution, other)),
+  )
+
+  return {
+    executions: executions.length,
+    retried: executions.length > options.messageCount,
+    supersededOverlap,
+  }
+}
+
+function pairExecutions(events: readonly SerializationEvent[]): Execution[] {
+  const started = new Map<string, SerializationEvent>()
+  const executions: Execution[] = []
+
+  for (const event of [...events].sort((left, right) => left.at - right.at)) {
+    const key = `${event.messageId}#${event.attempt}#${event.processId}`
+    if (event.event === "start") {
+      assert(!started.has(key), `${describe(event)} started twice`)
+      started.set(key, event)
+      continue
+    }
+    const start = started.get(key)
+    assert(start !== undefined, `${describe(event)} finished with no matching start`)
+    started.delete(key)
+    executions.push({
+      messageId: event.messageId,
+      attempt: event.attempt,
+      processId: event.processId,
+      startedAt: start.at,
+      finishedAt: event.at,
+    })
+  }
+
+  const unfinished = [...started.values()].map(describe)
+  assert.equal(unfinished.length, 0, `${unfinished.join(", ")} never wrote a finish`)
+
+  return executions
+}
+
+function overlaps(left: Execution, right: Execution): boolean {
+  return left.startedAt < right.finishedAt && right.startedAt < left.finishedAt
+}
+
+function describe(execution: { messageId: string; attempt: number }): string {
+  return `${execution.messageId} attempt ${execution.attempt}`
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-objects",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Race-free realtime state per application identity, backed by your SQL database",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
     "url": "git+https://github.com/cardmagic/solid-objects-js.git"
   },
   "engines": {
-    "node": ">=24.15.0"
+    "node": ">=24.4.0"
   },
   "packageManager": "pnpm@11.11.0",
   "bin": {