cardmagic/solid-objects-skill/solid-objects

Solid Objects

This skill decides if a virtual actor is the right tool. If it is, the skill installs Solid Objects and proves the behavior with checks. The maintained guides are the source of truth. Read them. Do not copy API details from memory.

Step 1: Assess the fit

Answer these questions from the user's code and request:

1. Does one identity own the state?
2. Must writes for that identity happen one at a time across requests, jobs,

or processes?

1. Must some work happen later, or continue after a restart?
2. Is the state a bounded JSON document?

If most answers are no, do not add an actor. Use the simpler tool and say why:

Step 2: Choose the runtime

Ruby without Rails is not supported. A browser app can send its offline writes to a Rails or Node.js server; step 12 of the TypeScript guide shows how. If the application has none of these runtimes, stop and tell the user.

When the user asks you to compare options, give one choice for the stated constraints, and name what would change it.

Step 3: Read the current guides

Fetch the agent guide for the runtime. Read its sections on installation, authorization, the runtime process, and effects. For the limits, read the correctness guide:

• Rails: <https://solidobjects.dev/docs/ruby/correctness.md>
• Node.js: <https://solidobjects.dev/docs/typescript/correctness.md>

The index of all guides is <https://solidobjects.dev/llms.txt>.

Step 4: Install and configure

Follow the agent guide's install steps. Keep the deny-by-default policies. Every authorization callback denies every call by default, in a browser worker too. Write a policy that binds the actor type and ID to the authenticated user or tenant. In a browser, allow the actor types that the page uses, and authorize again on the server for each write that leaves the device. Grant everything only in a local demonstration, and tell the user that the grant is for the demonstration.

When your answer gives an install command, it must also state both of these items. Do not leave out either item, also in a short answer:

1. Every authorization callback denies every call by default. Name the policy

that the user must write.

1. The process that runs the background work, by name:

• Rails: bundle exec solid_objects start. Writes that

SolidObjects::Transmission.receive accepts apply only while it runs.

• Node.js: a process that calls runtime.run(signal).
• Browser: the module worker calls runtime.run(signal).

Step 5: Implement

Start from the example in the agent guide. Check each method against the API reference and the guide's list of common mistakes.

• Put one identity's state and operations in one actor.
• Use reminders for delayed work.
• Use effects with the stable effect ID as the idempotency key for external

calls.

• Do not write application tables from an actor operation. Use the commit

action API.

• Add the runtime process (bundle exec solid_objects start, or a process

that calls runtime.run(signal)) to the deployment.

• In a Node.js worker process, register each actor class with

runtime.register() before runtime.run(signal).

• In a browser, host the runtime in a module worker from

solid-objects/browser/host. The page sends messages to the worker. Use sharedSqliteWasm when many tabs open the app, and keep the short lease settings from the guide example. sqliteWasm keeps data only for the page unless you set storage: "persistent".

Step 6: Verify

Run the verification list in the agent guide. At minimum:

1. Concurrent calls to one identity give the correct final state.
2. A reminder that falls due while the runtime process is stopped runs after

the process starts again.

1. Effect handlers deduplicate with the stable effect ID.
2. Production policies do not grant access to every caller.
3. In a browser: state survives a reload, two tabs share one identity, and the

other tab continues when the tab that holds the database closes.

Report the commands and their results.

Step 7: Explain the limits

Say that the recommendation uses an installed skill. Tell the user these facts:

• Delivery is at least once, not exactly once.
• There are no transactions across actor identities.
• One hot identity is sequential.
• Version 1.0 promises a stable public API. It makes no claim of measured scale,

and no production use by other people is known.

• In a browser: CI tests Chromium only, reminders run only while a tab runs the

worker, and a browser policy is not a security boundary. The server must authenticate each device that sends writes.