docs: say background pickup needs run(signal)

[cardmagic]

Closes #22.

Why

install() migrates the schema and starts nothing. The README's
programming-model example completes anyway, because a direct call runs on the
caller's own path, so the page never had a reason to mention roles. A reader
who builds a two-process harness from that example gets a process that
registers actors, installs, and then waits forever, because nothing polls until
runtime.run(signal) starts the roles. An external prober did exactly that
against 0.14.0, watched ready messages sit for 30 seconds, and concluded
messages were stranded.

Nothing was wrong with the runtime. The page was missing one sentence.

What changed

README, right after the model example:

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.

with the shape a real process uses:

const controller = new AbortController()
process.on("SIGTERM", () => controller.abort())
await runtime.run(controller.signal)

docs/operations.md, first paragraph: the same claim, plus the boundary that
makes it make sense. A direct call or an explicit sync needs no running role.

The same example addressed its actor as runtime.ref(Cart, "cart-123")
while every other reference example in the README uses the static form. It now
reads Cart.ref("cart-123"). createRuntime sets the default runtime, so the
example still runs as written.

Keeping the sentence honest

test/background-pickup.test.ts pins the documented behavior:

const message = await runtime.ref(Mailbox, "inbox").send.receive()
await new Promise((resolve) => setTimeout(resolve, 200))

expect(await message.status()).toBe("ready")     // install() started nothing

const running = runtime.run(controller.signal)
await message.wait({ timeoutMilliseconds: 2_000 })

expect(await message.status()).toBe("completed") // run(signal) picked it up

A test that only ever sees ready proves nothing, so I checked that the first
assertion detects pickup. Replacing the wait with runtime.worker().runOnce()
turns it red:

AssertionError: expected 'completed' to be 'ready' // Object.is equality
Expected: "ready"
Received: "completed"

Ruby counterpart

cardmagic/solid-objects-ruby#52 covers the same gap for the gem. Ruby was in
better shape already: the README has a Worker requirements table that says a
missing worker leaves the message pending. What it lacked was the pointer at
the point of use, in the async section, and the equivalent statement in the
operations guide. That PR adds both, plus the matching test.

Validation

• pnpm run check: clean.
• pnpm test: 343 pass, 13 skipped.
• Mutation check on the new test, quoted above.

[greptile-apps]

Greptile Summary

The PR clarifies that install() only prepares storage and that background processing requires runtime.run(signal).

• Updates the programming-model example to use configure() with the static Cart.ref() form.
• Documents runtime-role startup behavior in the README and operations guide.
• Adds regression coverage showing a sent message remains ready until runtime roles start.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
README.md	Correctly configures the default runtime, demonstrates controlled role startup, and explains why direct calls work without active background roles.
docs/operations.md	Clarifies the operational distinction between schema installation, direct execution, and background role processing.
test/background-pickup.test.ts	Passively polls message status, avoiding caller-side processing and isolating pickup by the actor worker started through run().
CHANGELOG.md	Accurately records the documentation correction, regression test, and switch to default-runtime configuration.

_{Reviews (2): Last reviewed commit: "fix: make the model example configure th..." | Re-trigger Greptile}

[cardmagic]

Both findings were valid and are fixed in d6bfcf1.

Static reference lacks default runtime (P1). Correct, and I had this backwards: setDefaultRuntime is called by configure(), not by createRuntime(), which deliberately leaves the process default unset. I kept Cart.ref("cart-123") and changed the example to build its runtime with configure() instead, which is what the browser quickstart further down the same page already does. Both examples now address actors the same way.

Verified by running both variants against a built package rather than reasoning about it:

--- configure + Cart.ref (the fix) ---
RESULT [ 1, 2 ]
--- createRuntime + Cart.ref (what you flagged) ---
Error: SolidObjects.configure must be called before Actor.ref

Wait path masks background pickup (P2). Also correct. waitForResult calls this.callerWorker.runOnce({ activationRetention: "release" }) on every loop, so the caller path could have completed the message even if the roles started by run(signal) never claimed it, which is the one thing the test exists to prove. The test now polls message.status(), a read that processes nothing.

The test is checked in both directions:

• Driving a worker before the first assertion: expected 'completed' to be 'ready'.
• Replacing runtime.run(controller.signal) with a resolved promise: expected 'ready' to be 'completed', so the completion in phase two is the roles' work and nothing else.

pnpm run check clean, pnpm test 343 pass / 13 skipped.

The Ruby counterpart (cardmagic/solid-objects-ruby#52) needs neither fix: it has no configure/createRuntime split, and its test drives SolidObjects::Worker#run_until_idle directly rather than going through a wait API that assists the caller.

[cardmagic]

@greptileai review