feat: session/projection push frame; tail block reads the watermark snapshot

packages/host/apiproxy/src/api-proxy.ts

@@ -299,25 +299,18 @@ function backscanTodos(events: readonly SessionEvent[]): TodoItem[] | undefined
 }
 
 /**
- * Compute the projection baseline for one history tail page: read the
- * session's next-event seq, then walk every registered provider — one fully
- * synchronous pass (no await anywhere), so all values and `asOfSeq` form a
- * single consistent cut and `asOfSeq` equals the window tail seq. Each value
- * passes through its provider's own schema before leaving the host (the
- * carrier holds zero domain knowledge; a provider returning an invalid value —
- * including an accidental Promise from a non-synchronous `get` — fails loud
- * here). An absent registry means the deployment has no projection seam: the
- * whole block is absent and clients treat every key as capability-absent.
+ * The projection baseline for one history tail page: the registry's
+ * watermark-cache snapshot — one fully synchronous read (no await between the
+ * page slice and this), so all values and `asOfSeq` form a single consistent
+ * cut and `asOfSeq` equals the window tail event seq. The carrier holds zero
+ * domain knowledge (each value passed its unit's own schema inside the
+ * registry). An absent registry means the deployment has no projection seam:
+ * the whole block is absent and clients treat every key as capability-absent.
  */
 function projectionsFor(ctx: Context, agent: Agent): SessionProjectionsBlock | undefined {
   const registry = ctx.get('sessionProjections')
   if (registry === undefined) return undefined
-  const asOfSeq = agent.session.seq
-  const values: Record<string, unknown> = {}
-  for (const provider of registry.entries()) {
-    values[provider.key] = provider.schema.parse(provider.get(agent))
-  }
-  return { asOfSeq, values: values as SessionProjectionsBlock['values'] }
+  return registry.snapshot(agent.session)
 }
 
 /**
@@ -400,6 +393,16 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     for (const queue of muxQueues) queue.push(envelope)
   }
 
+  // Projection change feed → session/projection push frames. The carrier
+  // mints the wire frame (the seam package holds no wire vocabulary); the
+  // child activates only when a projection registry is composed, and the
+  // subscription unwinds with this gateway's fiber.
+  ctx.inject(['sessionProjections'], (projectionCtx) => {
+    projectionCtx.sessionProjections.onChanged((session, key, value, seq) => {
+      broadcast({ type: 'session/projection', sessionId: session.id, key, value, seq })
+    })
+  })
+
   /**
    * Per-session inbox mirror serving the mux-open queue snapshot (the same
    * refresh-recovery baseline as pending questions). Keyed by the stable

packages/host/apiproxy/src/api/events.schema.ts

@@ -37,6 +37,9 @@ export const muxFrameSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('question/resolved'), sessionId: sessionIdSchema, questionRpcId: rpcIdSchema, outcome: z.union([z.literal('answered'), z.literal('cancelled')]) }),
   // content/source reuse the wide passthroughs (both are merge-extensible in core).
   z.object({ type: z.literal('session/queued'), sessionId: sessionIdSchema, content: z.array(contentBlockSchema), source: z.looseObject({ kind: z.string() }), steering: z.boolean() }),
+  // value stays wide: it already passed its unit's own schema on the host,
+  // and deep-validating here would import every domain's schema into the carrier.
+  z.object({ type: z.literal('session/projection'), sessionId: sessionIdSchema, key: z.string().min(1), value: z.unknown(), seq: z.number().int().nonnegative() }),
   z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
 ]) as unknown as z.ZodType<MuxFrame>
 

packages/host/apiproxy/src/api/events.ts

@@ -75,6 +75,15 @@ export type MuxFrame =
    * reconciliation key).
    */
   | { type: 'session/queued'; sessionId: SessionId; content: ContentBlock[]; source: MessageSource; steering: boolean }
+  /**
+   * One projection unit's finished value changed (session-projection RFC).
+   * Live push state, never logged — replay recomputes on the host (the
+   * tool-view posture). `value` is the unit's schema-validated view output;
+   * `seq` is the unit's watermark at emission. Clients keep one generic
+   * per-session value store under higher-seq-wins, seeded by the history
+   * tail page's projections block.
+   */
+  | { type: 'session/projection'; sessionId: SessionId; key: string; value: unknown; seq: number }
   | { type: 'stream/error'; error: RpcError }
 
 /**

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -105,7 +105,8 @@ export const todoItemSchema = z.object({
  * deep-validating here would import every domain's schema into the carrier.
  */
 export const sessionProjectionsBlockSchema = z.object({
-  asOfSeq: z.number().int().nonnegative(),
+  // -1 = empty log (the lastSeq convention of session/subscribed).
+  asOfSeq: z.number().int().min(-1),
   values: z.record(z.string(), z.unknown()),
 }) as unknown as z.ZodType<SessionProjectionsBlock>
 

packages/host/apiproxy/src/api/sessions.ts

@@ -37,13 +37,16 @@ export interface HistoryEntry {
 
 /**
  * The projection baseline riding the history tail page: one synchronous cut
- * over every registered projection provider. `asOfSeq` equals the window tail
- * seq (the session's next-event seq at slice time) because the handler reads
- * it and every value with no await in between. A key absent from `values`
- * means the capability is absent (its domain plugin is unmounted).
+ * over every registered projection unit, read from the registry's watermark
+ * cache. `asOfSeq` is the seq of the last committed event every value
+ * reflects — the window tail event seq (`-1` for an empty log, mirroring
+ * `session/subscribed.lastSeq`), directly comparable with
+ * `session/projection` frame seqs under the client's higher-seq-wins rule. A
+ * key absent from `values` means the capability is absent (its domain plugin
+ * is unmounted).
  */
 export interface SessionProjectionsBlock {
-  /** The session seq the values are consistent with (window tail seq). */
+  /** Seq of the last event the values reflect; -1 for an empty log. */
   asOfSeq: number
   /** Whole current value per registered projection key. */
   values: Partial<SessionProjectionMap>