Projections, Checkpoints, and Cold Start

Conclusion: the event log owns truth; checkpoints and projections own timing and cost

The architecture is strongest when those layers remain distinct. A semantic checkpoint proves that earlier facts reached storage; a projection checkpoint merely remembers a fold; a watermark says how far a value has observed; a baseline is a transport cut; and a client row is disposable convergence state. Treating any one of them as the log itself creates exactly the recovery bugs the design is trying to avoid.

1. Six names for six different contracts

2. A semantic checkpoint is an awaited barrier, not a stored checkpoint object

append facts to the live Session
        ↓
sessions.flush(session)
        ├─ persistence listener drains write-behind
        ├─ any other scoped durability listener settles
        └─ first failure is thrown only after all listeners settle
        ↓
construct model stream or enter top-level tool body

SessionStore.flush() resolves the exact live Session's scoped listeners, invokes all of them, waits with Promise.allSettled, and then throws the first rejection if any. Its return value only says whether a durability listener participated. There is no durable “checkpoint record” produced by this API.

3. Write-behind separates hot-path admission from durable quiescence

Persistence and checkpoint scheduling are separate plugins. Loading a backend without the semantic policy is valid, but a crash may then lose events still inside the batching window or an outstanding write. The shipped base composition mounts both the JSONL persistence provider and the checkpoint policy explicitly.PROJ-SHIPPED-COMPOSITION

4. Projection units are synchronous folds over every committed event

ProjectionDefinition<K, S> = {
  key,
  schema,             // validates the wire-facing view
  init(): S,
  apply(S, event): S, // pure and synchronous
  view(S): Value,
  stateVersion
}

The synchronous requirement is load-bearing. A carrier can copy a Session's event snapshot and immediately call snapshot() in the same JavaScript turn, obtaining values whose shared asOfSeq is exactly session.seq - 1. An async unit would tear that cut.

5. Thirteen production keys share one framework but encode different lifecycles

This is a repository-wide inventory of production registrations at the pinned commit, not a promise that all thirteen keys are active in every deployment. Registration is composition-dependent, and the process-wide table also means a key mounted by one preset can appear in snapshots for Sessions whose own preset never produces a meaningful value.

6. A watermark advances on observation; a push occurs only on change

event seq N enters every unit
  ├─ apply returns same reference
  │    observedSeq = N
  │    no session/projection frame
  └─ apply returns new reference
       observedSeq = N
       schema.parse(view(state))
       emit { key, value, seq: N }

This distinction explains why imageLimits never emits a push yet still appears in a tail baseline, and why a quiet value in a full snapshot can legitimately be stamped at the log's current asOfSeq. The watermark means “observed through,” not “last changed at.”

7. The durable projection cache is a versioned shortcut, never a read authority

8. The implemented cold-cache ladder is not wired into shipped cold History

implemented SessionProjectionCache.coldSnapshot(id)
  cache rows → restoreFloor → persistence.readFrom(tail)
  → registry.restore → fail-soft refreshed write-back

shipped ordinary cold History
  persistence.inspect(full logical log)
  → registry.restore({}, all events, 0)

shipped Session list
  cachedSnapshot(header) only, zero log I/O

9. Inspect, prepare, and resume form a cold-start protocol, not three aliases

10. Browser cold open is deliberately not Agent resume

A cold Session must be listed by persistence and carry a project cwd to be Web-servable. History can still degrade to generic tool cards when the recorded preset no longer supplies a standing presenter scope. A real resume is stricter: it must pass format, continuity, ownership, preset composition, setup, and final publication checks.

11. Client convergence combines a full baseline, sparse pushes, and generation repair

history tail baseline { asOfSeq: N, values: all registered keys }
                       ↓ seed
resident ProjectionValueStore
                       ↑ apply only if frame.seq is greater
session/projection { key, value, seq }

new mux generation:
session/subscribed { lastSeq: D }
→ remove client rows with seq > D
→ refetch list and resync opened History windows

The mux and host feeds are independent streams with no shared total-order claim. events.mux({since}) also ignores since in v1. The supported convergence story is reopen the streams, refresh list state, refetch History, and repair each domain—not resume one globally linear stream offset.

12. Rebuild and invalidation operate at four different scopes

No live registry API hydrates its WeakMap cells from a persisted checkpoint. The cache's detached restore() path returns a snapshot and refreshed checkpoint, but a resumed live Session still lazily folds its in-memory event array on first registry touch. There is also no cache eviction or retention surface; records accumulate until out-of-band maintenance removes them.

13. Four documentation claims have drifted from current production control flow

14. Source-level risk: detach can briefly let the projection cache lead the log

Session detach
  1. remove Session from SessionStore
  2. emit contained, non-awaited session/disposed observers
       ├─ persistence starts asynchronous retirement flush
       └─ projection cache snapshots and writes
            live-entry check now fails → no sessions.flush()

coldSnapshot() could detect that overreach through its anchored floor, but no shipped caller uses it. The zero-I/O list read does not validate the stored log endpoint. A phantom list projection can consequently reach the client; a later lower-seq cold-History baseline loses under higher-seq-wins until a true resume emits session/subscribed and truncates the row, or the log advances beyond it.

15. Source-level risk: equal-seq replacement cannot cross a Host generation

imageLimits makes the scenario concrete. Its state is always null, its view reads the current boot's attachment configuration, and it intentionally never pushes. A browser that remains alive across a Host restart can retain old limits at seq N; subscribed keeps the row because it is not beyond N, and the fresh baseline at N loses as equal. The value converges only after another event advances the baseline, a full client reset, or a protocol that carries a generation/version dimension.

The same edge applies to a unit's view semantics changing at an unchanged log watermark, and to unload/reload of the same key. stateVersion protects the Host's persisted cache but is absent from the client wire row, so it cannot resolve this client-generation ambiguity.PROJ-IMAGE-LIMITS

16. Source-level risk: one optional unit can make ordinary History unavailable

This is not merely corrupt state inside the failing domain: the registry's process-wide all-unit fold lets an unrelated projection block the base transcript read. Whether fail-loud is desired needs an explicit product decision. Current carrier behavior is inconsistent.

17. Design assessment and verification status