Align typed snapshot values

Author: cardmagic

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Make typed snapshots return persisted fields and getter values from one
+  committed state image, rejecting getters that mutate state or stage work.
 - Probe configured authorization policies with a neutral context in the doctor
   and warn when sensitive access is open or a policy cannot evaluate safely.
 - Align effect and commit-action context with their durable source message and

README.md

@@ -809,7 +809,9 @@ IDs and observable values are not authorization.
 - Failed turns roll state and staged intents back and block later work until
   retry or dead-letter completion.
 - Effects can execute more than once.
-- Results and snapshots are deeply frozen copies.
+- Results and snapshots are deeply frozen copies. A snapshot contains every
+  persisted field and getter from one committed state image; snapshot getters
+  must not mutate state or stage durable work.
 
 Override protected `onActivate()` and `onDeactivate()` methods when an actor
 needs a process-local resource during that window. Hooks may be asynchronous,

docs/correctness.md

@@ -33,6 +33,9 @@
   permits only `SELECT` through row-returning methods; commit actions remain the
   fenced write path. The guarantee applies only to clients passed through the
   facade.
+- Snapshots hydrate one committed state image and evaluate every inferred getter
+  against it. Getter mutation or staged durable work rejects the whole snapshot;
+  successful snapshots and their nested JSON values are frozen copies.
 - Personalized payloads hydrate committed state separately for every payload
   name and subscriber. Each projection is read-only, size bounded, and fenced
   independently by actor incarnation and revision. One denied, mutating, or

docs/parity.md

@@ -34,7 +34,7 @@ Reference: Ruby `solid_objects` 0.12.0 at commit `a01b6f5`.
 | 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.                                          |
+| Committed snapshots                                                                                           | Native  | `snapshot()` returns authorized persisted fields and inferred getters from one read-only committed state image; realtime replay reads explicit observables without mailbox history.                                |
 | Actor destruction and incarnation fencing                                                                     | Native  | Authorized cascading deletion creates a fresh instance ID on recreation; an authorized waiter receives `ActorDestroyed` when that incarnation disappears.                                                          |
 | 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.                                                                                           |

src/reference.ts

@@ -30,7 +30,7 @@ export type ActorQueryNames<ActorType extends Actor> = Exclude<
 >
 
 export type ActorSnapshot<ActorType extends Actor> = {
-  readonly [Key in ActorQueryNames<ActorType>]: DeepReadonly<ActorType[Key]>
+  readonly [Key in ActorQueryNames<ActorType>]: DeepReadonly<Awaited<ActorType[Key]>>
 }
 
 type MethodResult<Method> = Method extends (...argumentsValue: any[]) => infer Result

src/runtime.ts

@@ -683,7 +683,30 @@ export class SolidObjectsRuntime {
           storedState: jsonObject(JSON.parse(instance.state)),
         })
       : initialStateFor(registered.definition)
-    return readonlyCopy(state) as ActorSnapshot<ActorType>
+    const actor = hydrateActor({
+      definition: registered.definition,
+      actorId: reference.actorId,
+      state,
+    })
+    const stateBefore = stableJson(actorState(actor, registered.definition.stateKeys))
+    const intentCount = actor.intentCount()
+    const snapshot: Record<string, JsonValue> = { ...state }
+    await withActorProjection({ actor, runtime: this }, async () => {
+      for (const query of registered.definition.queries) {
+        if (registered.definition.stateKeys.includes(query)) continue
+        const value = await (actor as unknown as Record<string, unknown>)[query]
+        snapshot[query] = normalizeJson(value === undefined ? null : value, {
+          maxBytes: this.settings.maxResultBytes,
+        })
+      }
+    })
+    if (
+      stableJson(actorState(actor, registered.definition.stateKeys)) !== stateBefore ||
+      actor.intentCount() !== intentCount
+    ) {
+      throw new QueryMutatedState("snapshot getters must not mutate actor state or stage work")
+    }
+    return readonlyCopy(snapshot) as ActorSnapshot<ActorType>
   }
 
   async subscriptionSnapshot(options: {

test/correctness.test.ts

@@ -5,6 +5,7 @@ import {
   ActorDestroyed,
   IdempotencyConflict,
   MessageFailed,
+  QueryMutatedState,
   Rejected,
   SyncInsideTransaction,
   Unauthorized,
@@ -324,6 +325,14 @@ describe("durable invocation correctness", () => {
     expect(effect).toBeUndefined()
   })
 
+  it("rejects snapshot getters that mutate state", async () => {
+    runtime = configuredRuntime()
+    await runtime.install()
+
+    await expect(MutatingQuery.ref("snapshot").snapshot()).rejects.toBeInstanceOf(QueryMutatedState)
+    expect(await MutatingQuery.ref("snapshot").count).toBe(0)
+  })
+
   it("rejects observables that mutate state or stage durable work", async () => {
     runtime = configuredRuntime({ maxAttempts: 1 })
     await runtime.install()

test/runtime.test.ts

@@ -142,9 +142,13 @@ describe("typed actor references", () => {
     expect(await counter.increment({ amount: 3 })).toBe(3)
     expect(await counter.count).toBe(3)
     expect(await counter.doubled).toBe(6)
+    const snapshot = await counter.snapshot()
+    expect(snapshot).toEqual({ count: 3, lastAuthorizationContext: null, doubled: 6 })
+    expect(Object.isFrozen(snapshot)).toBe(true)
 
     expectTypeOf(counter.increment).returns.toEqualTypeOf<Promise<number>>()
     expectTypeOf(counter).toHaveProperty("count").toEqualTypeOf<Promise<number>>()
+    expectTypeOf(snapshot.doubled).toEqualTypeOf<number>()
     expectTypeOf(counter).not.toHaveProperty("async")
     expectTypeOf(counter).not.toHaveProperty("sync")
   })