Align durable handler contexts

Author: cardmagic

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Align effect and commit-action context with their durable source message and
+  activation fence, using immutable TypeScript contracts.
 - Bound runtime shutdown with a configurable deadline and report components
   that do not cooperate with cancellation or stop before it expires.
 - Separate generated request identity from caller-supplied idempotency keys and

README.md

@@ -405,6 +405,10 @@ runtime.registerEffect("chargePayment", async ({ paymentId }, context) => {
 })
 ```
 
+Effect context also exposes `attempt`, `sourceMessageId`, `actorType`, and
+`actorId`. The effect `id` is stable across retries and remains the external
+idempotency key.
+
 Success callbacks receive `{ effectId, result }`. Failure callbacks receive
 `{ effectId, error }`.
 
@@ -419,6 +423,10 @@ runtime.registerCommitAction("completeAttempt", async ({ attemptId }, context) =
 })
 ```
 
+Commit-action context includes the source message and request IDs, actor
+identity, mailbox sequence, activation generation, and the active transaction
+connection.
+
 Do not perform network I/O in a commit action. Use an effect when work cannot
 share the Solid Objects database transaction.
 

docs/parity.md

@@ -28,10 +28,10 @@ Reference: Ruby `solid_objects` 0.12.0 at commit `a01b6f5`.
 | 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.                                                                                                 |
 | 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 effect handlers with stable IDs and success/failure actor operations.                                                                                                                                |
+| Transactional effects and outcome operations                                                                  | Native  | At-least-once handlers receive immutable stable effect, attempt, source-message, and actor identity; success and failure return through actor operations.                                                          |
 | 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 the fenced transaction connection.                                                                                                                                                      |
+| Same-database commit actions                                                                                  | Native  | Registered actions receive source-message identity, mailbox sequence, activation generation, and the fenced transaction connection.                                                                                |
 | Ambient transaction rejection                                                                                 | Native  | Committed calls and message waits fail before blocking when the current async context already owns a transaction on the Solid Objects adapter.                                                                     |
 | Direct application-write isolation during actor code                                                          | Partial | `guardApplicationDatabase()` fails closed for operations, projections, and migrations, while registered commit actions remain writable. Unwrapped ORM pools and third-party clients cannot be intercepted.         |
 | Committed snapshots                                                                                           | Native  | `snapshot()` returns authorized committed state; realtime replay reads the explicit observable projection with instance ID and revision without creating mailbox history.                                          |

src/runtime.ts

@@ -1124,6 +1124,7 @@ export class SolidObjectsRuntime {
               messageId: turn.message.id,
               requestId: turn.message.request_id,
               sequence: BigInt(turn.message.sequence),
+              activationGeneration: turn.activationGeneration,
               connection,
             })
             this.emitInstrumentation("commit_action.completed", attributes)
@@ -1282,7 +1283,7 @@ export class SolidObjectsRuntime {
           attempt: Number(effect.attempt_count),
           actorType: effect.actor_type,
           actorId: effect.actor_id,
-          messageId: effect.message_id,
+          sourceMessageId: effect.message_id,
         })) ?? null,
         { maxBytes: this.settings.maxResultBytes },
       )

src/types.ts

@@ -48,20 +48,21 @@ export interface MessageContext {
 }
 
 export interface EffectContext {
-  id: string
-  attempt: number
-  actorType: string
-  actorId: string
-  messageId: string
+  readonly id: string
+  readonly attempt: number
+  readonly sourceMessageId: string
+  readonly actorType: string
+  readonly actorId: string
 }
 
 export interface CommitActionContext {
-  actorType: string
-  actorId: string
-  messageId: string
-  requestId: string
-  sequence: bigint
-  connection: DatabaseConnection
+  readonly actorType: string
+  readonly actorId: string
+  readonly messageId: string
+  readonly requestId: string
+  readonly sequence: bigint
+  readonly activationGeneration: bigint
+  readonly connection: DatabaseConnection
 }
 
 export type MessageStatus = "ready" | "claimed" | "completed" | "rejected" | "dead" | "unknown"

test/outboxes.test.ts

@@ -80,9 +80,19 @@ afterEach(async () => {
 describe("durable effects", () => {
   it("runs an effect and delivers its success message", async () => {
     runtime = configuredRuntime()
-    runtime.registerEffect("charge_payment", ({ paymentId }, context) => ({
-      receipt: `${paymentId}:${context.id}`,
-    }))
+    let effectContext:
+      | {
+          id: string
+          attempt: number
+          sourceMessageId: string
+          actorType: string
+          actorId: string
+        }
+      | undefined
+    runtime.registerEffect("charge_payment", ({ paymentId }, context) => {
+      effectContext = context
+      return { receipt: `${paymentId}:${context.id}` }
+    })
     await runtime.install()
     const checkout = Checkout.ref("order-1")
 
@@ -92,6 +102,12 @@ describe("durable effects", () => {
 
     expect(await checkout.status).toBe("paid")
     expect(await checkout.effectResult).toMatch(/^payment-1:/)
+    expect(effectContext).toMatchObject({
+      attempt: 1,
+      sourceMessageId: expect.any(String),
+      actorType: Checkout.actorType,
+      actorId: "order-1",
+    })
   })
 
   it("marks unknown effects dead and delivers the failure message", async () => {
@@ -140,7 +156,9 @@ describe("commit actions", () => {
     await runtime.settings.database.connection((connection) =>
       connection.run("CREATE TABLE application_records(id TEXT PRIMARY KEY) STRICT"),
     )
+    let activationGeneration: bigint | undefined
     runtime.registerCommitAction("write_record", async ({ recordId }, context) => {
+      activationGeneration = context.activationGeneration
       await context.connection.run("INSERT INTO application_records(id) VALUES (?)", [recordId])
     })
     const writer = DatabaseWriter.ref("writer")
@@ -154,6 +172,7 @@ describe("commit actions", () => {
       }>("SELECT id FROM application_records"),
     )
     expect(record?.id).toBe("record-1")
+    expect(activationGeneration).toBeGreaterThan(0n)
   })
 
   it("rolls actor state back when a commit action fails", async () => {

test/test-helper.test.ts

@@ -53,7 +53,7 @@ describe("public test helper", () => {
       },
     })
     runtime.registerEffect("recordHelperEffect", async (_arguments, context) => {
-      effects.push(context.messageId)
+      effects.push(context.sourceMessageId)
     })
     await runtime.install()
     const message = await HelperActor.ref("workflow").send.startWork()