solid-objects 0.14.7 → 0.14.9

package/docs/api.md

@@ -54,8 +54,11 @@ authorization, capability boundaries, and release validation.
 - `reference.live`: read-only live signals for an actor, enabled by the
   `solid-objects/signals` entry point documented below.
 - `ActorClass`, `ActorReference`, `ActorMessageSender`, `ActorSnapshot`,
-  `ActorOperationNames`, `ActorQueryNames`, `StagedOperations`, and
-  `ScheduledOperations`: inferred actor-class and fluent-dispatch types.
+  `ActorOperationNames`, `ActorQueryNames`, `StagedOperations`,
+  `ScheduledOperationsFor`, and `ScheduledOperations`: inferred actor-class and
+  fluent-dispatch types, plus the legacy dynamic scheduling map.
+- `EffectOptions`: effect arguments and independently checked success/failure
+  callback names. Effect names themselves belong to the runtime's global registry.
 - `SnapshotWithIncarnation`: the `{ snapshot, instanceId, revision,
 createdAtMs }` shape returned by `SolidObjectsRuntime.snapshotWithIncarnation`.
 - `MessageReference`: immutable durable message identity with `id`,
@@ -69,6 +72,10 @@ createdAtMs }` shape returned by `SolidObjectsRuntime.snapshotWithIncarnation`.
 `PayloadBroadcasts`, and `PayloadBroadcastValue` describe actor-declared
 transactional work and typed personalized projections.
 
+`EffectFailurePayload<Arguments>`, `EffectSuccessPayload<Arguments, Result>`,
+and `SerializedError` describe effect callback messages. They are also exported
+from the browser-safe `solid-objects/core` entry point.
+
 `observables()` returns a flat object. Unwrapped values are invalidation-only:
 their real values participate in change detection, but only their names enter
 the durable envelope. Use an explicit marker when wire behavior matters:
@@ -126,7 +133,7 @@ operation. If you arm one alarm per queued item, only the last one remains:
 // Wrong. Every entry overwrites the previous entry's alarm.
 add({ entry }: { entry: Entry }): void {
   this.entries = [...this.entries, entry]
-  this.schedule({ at: new Date(entry.waitUntil) }).deliver!()
+  this.schedule({ at: new Date(entry.waitUntil) }).deliver()
 }
 ```
 
@@ -136,7 +143,7 @@ own identifier for the item and names that item's alarm, so each item gets one:
 ```typescript
 add({ entry }: { entry: Entry }): void {
   this.entries = [...this.entries, entry]
-  this.schedule({ at: new Date(entry.waitUntil), key: entry.id }).deliver!()
+  this.schedule({ at: new Date(entry.waitUntil), key: entry.id }).deliver()
 }
 ```
 
@@ -155,6 +162,115 @@ row per item. It also cannot strand an entry when the runtime coalesces an
 occurrence. Prefer it for a large queue of interchangeable items. Prefer `key`
 when one item needs an alarm that you can move on its own.
 
+### Typing your onFailure handler
+
+An effect callback is an ordinary actor operation. Its payload always includes
+the stable `effectId` and the original serialized `arguments`, including `{}`
+when the effect was emitted without arguments. Use the exported types when a
+watchdog or failure handler needs to correlate work with the current generation:
+
+```typescript
+import { Actor, type EffectFailurePayload, type EffectSuccessPayload } from "solid-objects"
+
+type RunArguments = { generation: number }
+
+class ChatRun extends Actor {
+  static override readonly actorType = "ChatRun"
+  generation = 0
+  status = "idle"
+  reply = ""
+
+  start(): void {
+    this.emit("run_model", {
+      arguments: { generation: ++this.generation },
+      onSuccess: "finishTurn",
+      onFailure: "failTurn",
+    })
+  }
+
+  failTurn({ arguments: original, error }: EffectFailurePayload<RunArguments>): void {
+    if (original.generation !== this.generation) return
+    this.status = `${error.name}: ${error.message}`
+  }
+
+  finishTurn({
+    arguments: original,
+    result,
+  }: EffectSuccessPayload<RunArguments, { reply: string }>): void {
+    if (original.generation !== this.generation) return
+    this.status = "finished"
+    this.reply = result.reply
+  }
+}
+```
+
+Failure payloads contain `error: SerializedError`, with string `name` and
+`message` fields. They do not include a stack or cause. Success payloads contain
+`result`, which can be any JSON value; an undefined effect return becomes
+`null`. The default argument type is `JsonObject` and the default success result
+type is `JsonValue`. Declare argument shapes with a JSON-compatible type alias.
+
+These types describe the SQL and Cloudflare callback envelopes. Error messages
+for non-Error throws retain each backend's existing serialization behavior.
+The generic parameters express your application's contract; they do not add
+runtime validation or infer types from `registerEffect()`. Keep registered
+effect results and the handler's declared argument/result types in agreement.
+
+### Typed operation references
+
+`schedule` and `transmit` infer this actor's operation names and arguments, including
+inside actor methods and for inherited application operations. The returned
+`ScheduledOperationsFor<ActorType>` values return `void` and preserve required,
+optional, and zero-argument operation signatures. No non-null assertion is needed:
+
+```typescript
+class ChatRun extends Actor {
+  generation = 0
+  status = "idle"
+
+  start({ generation }: { generation: number }): void {
+    this.generation = generation
+    this.schedule({ at: new Date(Date.now() + 60_000), key: "watchdog" }).recoverIfStuck({
+      generation,
+    })
+    this.emit("run_model", { arguments: { generation }, onFailure: "failTurn" })
+  }
+
+  recoverIfStuck({ generation }: { generation: number }): void {
+    if (generation !== this.generation) return
+    this.status = "recovering"
+  }
+
+  failTurn({ error }: { error: { message: string } }): void {
+    this.status = error.message
+  }
+}
+```
+
+Misspelled operations/callbacks, state properties, queries, and Actor infrastructure
+are rejected. `emit` checks each callback independently: widening one callback to
+`string` does not disable literal checking of the other. A deliberately widened
+`string` callback retains runtime validation. Object properties can also widen to
+`string`; preserve literals with `as const` or specialize `EffectOptions` to keep
+static checking when options are stored in a variable. Effect and commit-action names remain
+strings because their registries are runtime-wide; inferring registered names needs
+a separate registry typing design.
+
+For deliberately dynamic scheduling, retain the exported legacy map explicitly:
+
+```typescript
+const dynamicActor: Actor = this
+const operations: ScheduledOperations = dynamicActor.schedule({ at: deadline })
+operations[operationName]!({ generation })
+```
+
+This opts out of operation-name and argument inference and retains the existing
+runtime operation checks. Direct calls, queries, and `sendTo` keep their inference.
+Subclasses that override `schedule` or `transmit` with an explicit legacy
+`ScheduledOperations` return annotation must update their override signatures to
+match the generic Actor methods. This is a compile-time compatibility change;
+runtime scheduling and transmission behavior are unchanged.
+
 ### Runtime managers
 
 Every manager below is available as a property on `SolidObjectsRuntime`; the

package/docs/parity.md

@@ -29,6 +29,13 @@ such boundary between a gem and its dependents.
 
 ## Status vocabulary
 
+Operation-reference typing is runtime-specific: TypeScript infers scheduled and
+transmitted operations from the concrete receiver, and checks literal effect
+callback names. Ruby offers opt-in RBS generation from declared application types
+in [solid-objects-ruby#66](https://github.com/cardmagic/solid-objects-ruby/pull/66).
+Both preserve runtime operation validation and global effect/commit-action names;
+this does not imply automatic TypeScript-style inference in Ruby.
+
 - **Native**: the TypeScript runtime provides the capability in a Node-native
   shape.
 - **Partial**: the core exists, but an important Ruby guarantee or operational
@@ -48,13 +55,13 @@ is needed for the JavaScript stale-result race fix.
 | ------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Actor registry, durable identity, JSON state, and adjacent state migrations                                   | Native  | Ordinary classes, static actor types, inferred state, explicit migrations, and isolated runtime context across every actor-instance callback.                                                                                                                                                                                          |
 | Fluent committed calls and background delivery                                                                | Native  | `await reference.operation()` and `reference.send.operation()`.                                                                                                                                                                                                                                                                        |
-| Ordered mailbox, sequence allocation, idempotency, retries, dead letters, leases, renewal, and fenced commits | Native  | Relational ready/claimed membership tables, distinct generated request IDs and caller idempotency keys, durable history, and adapter-appropriate sequence locking.                                                                                                                                                                     |
+| Ordered mailbox, sequence allocation, idempotency, retries, dead letters, leases, renewal, and fenced commits | Native  | Relational ready/claimed membership tables, distinct generated request IDs and caller idempotency keys, durable history, adapter-appropriate sequence locking, and PostgreSQL/MySQL row locks held from fence validation through commit.                                                                                               |
 | Domain rejection and strict poison ordering                                                                   | Native  | Rejections accept JavaScript identifier-style codes and roll back without retry; invalid codes fail terminally, while retryable failures block later operations until completion or dead-lettering.                                                                                                                                    |
 | Bounded activation passes and hot-actor fairness                                                              | Native  | Configurable turn-count and elapsed-time budgets bound each pass, then move only that actor's already-due memberships behind actors already waiting.                                                                                                                                                                                   |
 | Bounded claim candidate scan                                                                                  | Native  | A configurable ordered scan continues to another ready actor when a worker loses the first candidate's lease race.                                                                                                                                                                                                                     |
 | Backpressure and payload caps                                                                                 | Partial | Serialization enforces a shared maximum JSON nesting depth, raising `InvalidPayload`, and an optional caller-supplied `maxBytes` limit, raising `PayloadTooLarge`; reminder names are bounded to 255 characters. Distributed per-actor rate limits and global admission control do not exist yet, matching the open Ruby roadmap item. |
 | Idle activation cache                                                                                         | Native  | Long-running workers retain hydrated actors under renewable fenced leases, restore public state after failed turns, and release on timeout, fairness yield, lease loss, or shutdown.                                                                                                                                                   |
-| Transactional effects and outcome operations                                                                  | Native  | At-least-once handlers receive immutable stable effect, attempt, source-message, and actor identity; success and failure operations also receive the originally staged arguments for correlation.                                                                                                                                      |
+| Transactional effects and outcome operations                                                                  | Native  | At-least-once handlers receive immutable stable effect, attempt, source-message, and actor identity; success and failure operations also receive the originally staged arguments for correlation. Typed callback envelopes are exported.                                                                                               |
 | Actor-to-actor delivery                                                                                       | Native  | `sendTo(reference).operation()` stages delivery in the source actor commit.                                                                                                                                                                                                                                                            |
 | One-shot and recurring reminders                                                                              | Native  | Scheduling, replacement events, catch-up policy, stale-claim recovery, pausing, authorized inspection, and idempotent resume are implemented.                                                                                                                                                                                          |
 | Same-database commit actions                                                                                  | Native  | Registered actions receive source-message identity, mailbox sequence, activation generation, and the fenced transaction connection.                                                                                                                                                                                                    |
@@ -65,6 +72,11 @@ is needed for the JavaScript stale-result race fix.
 | Result recovery and sync timeout diagnostics                                                                  | Native  | Status, result, and wait reauthorize the stored operation; terminal failure raises structured `MessageFailed`; whole-call adapter deadlines distinguish enqueue, wait, database, activation, and mailbox blockers.                                                                                                                     |
 | Result lookup by request ID                                                                                   | Planned | This is also an open Ruby roadmap item and will be implemented in both runtimes when its authorization shape is settled.                                                                                                                                                                                                               |
 
+Effect callback envelopes are typed with `EffectFailurePayload`,
+`EffectSuccessPayload`, and `SerializedError` in both SQL and Cloudflare.
+Ruby RBS contracts are tracked in cardmagic/solid-objects-ruby#64 and preserve
+Ruby field names; this does not change runtime delivery semantics.
+
 ## Operations
 
 | Capability                                                                    | Status | TypeScript shape or remaining work                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-objects",
-  "version": "0.14.7",
+  "version": "0.14.9",
   "description": "Race-free realtime state per application identity, backed by your SQL database",
   "type": "module",
   "license": "MIT",
@@ -136,14 +136,14 @@
     "@types/node": "^24.0.0",
     "@types/pg": "^8.21.0",
     "@types/ws": "^8.18.1",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.11",
     "mysql2": "^3.23.3",
     "pg": "^8.23.0",
     "prettier": "^3.9.6",
     "redis": "^6.2.1",
     "signal-polyfill": "^0.2.2",
     "typescript": "^5.9.0",
-    "vitest": "^4.1.10",
+    "vitest": "^4.1.11",
     "wrangler": "^4.129.0",
     "ws": "^8.21.3"
   },