Merge remote-tracking branch 'origin/master' into xtr/identified-immutable-messages

# Conflicts:
#	docs/event-producer-consumer.md
#	packages/client/connection/src/client/fixture.ts
#	packages/goal/command-goal/tests/command-goal.spec.ts
#	packages/host/apiproxy/src/api-proxy.ts
#	packages/host/apiproxy/src/api/events.schema.ts
#	packages/host/apiproxy/src/api/events.ts
#	packages/host/apiproxy/tests/api-proxy-view.spec.ts
#	packages/host/apiproxy/tests/rpc-schemas.spec.ts
#	tsconfig.base.json

packages/session-title/session-title/package.json

@@ -15,12 +15,21 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/types/client.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
@@ -31,10 +40,12 @@
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-projection": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
-    "schemastery": "^3.18.0"
+    "schemastery": "^3.18.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
@@ -43,6 +54,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/session-title/session-title/src/client.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the title domain: a pure re-export of the package's
+ * types outlet. Client code imports ONLY the client namespace (repo
+ * discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ *
+ * @module @deepseek-ai/dsh-session-title/client
+ */
+
+export type * from './types.ts'

packages/session-title/session-title/src/index.ts

@@ -5,6 +5,7 @@
 
 import { Context, FiberState, Service, type Fiber } from 'cordis'
 import z from 'schemastery'
+import { z as zod } from 'zod'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import { deepFreeze, isAgentLoopRequest } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
@@ -12,6 +13,13 @@ import type {
   Session,
   SessionEvent,
 } from '@deepseek-ai/dsh-session'
+// Type-only: resolves ctx.sessionProjections for the optional unit child.
+import type {} from '@deepseek-ai/dsh-session-projection'
+// The `title` projection-key declaration lives in src/types.ts (its one home);
+// this re-export projects the type face onto the package root AND keeps the
+// module edge in the emitted index.d.ts, so aggregate programs consuming the
+// declarations still receive the SessionProjectionMap merge.
+export type * from './types.ts'
 import { fallbackSessionTitle, normalizeSessionTitle } from './normalize.ts'
 
 export { fallbackSessionTitle, normalizeSessionTitle, truncateTitleUtf8 } from './normalize.ts'
@@ -272,6 +280,21 @@ export class SessionTitleService extends Service {
       this.work.clear()
     }, 'sessionTitle lifecycle')
 
+    // The title projection unit: pure last-wins fold of session/title events
+    // (the same events foldSessionTitle consumes), serving the plain title
+    // string clients list rows read. The unit child activates only when a
+    // projection registry is composed (headless assemblies stay unaffected).
+    ctx.inject(['sessionProjections'], (projectionCtx) => {
+      projectionCtx.sessionProjections.register<'title', string | null>({
+        key: 'title',
+        schema: zod.union([zod.string().min(1), zod.null()]),
+        init: () => null,
+        apply: (state, event) => (event.type === 'session/title' ? event.data.title : state),
+        view: state => state,
+        stateVersion: 1,
+      })
+    })
+
     ctx.on('session/event', (session, event) => {
       switch (event.type) {
         case 'user/message':

packages/session-title/session-title/src/types.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure types of the title domain: the ONE home of the `title` projection-key
+ * declaration, free of this package's host-side value imports (cordis
+ * service, schemastery, the llm seam). Two namespace projections serve it —
+ * `./types` for host consumers, `./client/types` (the browser half-entry's
+ * re-export) for client aggregates — with zero content duplication.
+ *
+ * @module @deepseek-ai/dsh-session-title/types
+ */
+
+// Marks this file a module so the declaration below AUGMENTS the projection
+// table instead of declaring an ambient module.
+export {}
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    /**
+     * The session's current normalized title — the latest `session/title`
+     * event's text (last-wins), or `null` before the first title lands. A
+     * plain string: the shape the client list rows consume.
+     */
+    title: string | null
+  }
+}

packages/session-title/session-title/tests/projection.spec.ts

@@ -0,0 +1,76 @@
+/**
+ * The `title` projection unit: mounting the title service beside the
+ * projection registry serves the current normalized title (last-wins over
+ * session/title events, the same events foldSessionTitle consumes) — null
+ * before the first title — through the registry snapshot and the change
+ * feed; compositions without the registry are unaffected; unmounting the
+ * service removes the key (HMR safety). The bespoke session/title mux frame
+ * is untouched by this unit (its retirement is the client value-store
+ * migration's concern).
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import SessionTitleService from '@deepseek-ai/dsh-session-title'
+
+const CONFIG = { fallbackMaxWords: 8, fallbackMaxBytes: 64, maxTitleBytes: 256 }
+
+async function harness(withTitleService: boolean): Promise<{ ctx: Context; session: Session }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionProjectionRegistry)
+  if (withTitleService) await ctx.plugin(SessionTitleService, CONFIG)
+  return { ctx, session: ctx.sessions.create(SessionId('titled')) }
+}
+
+/** Append one session/title event directly (the replay-plane shape the unit folds). */
+function appendTitle(session: Session, title: string): number {
+  return session.append('session/title', { title, messageSeqs: [1], source: { kind: 'fallback' } }).seq
+}
+
+describe('title projection unit', () => {
+  it('serves null before the first title event', async () => {
+    const { ctx, session } = await harness(true)
+    const snapshot = ctx.sessionProjections.snapshot(session)
+    expect(snapshot.values.title).toBeNull()
+  })
+
+  it('serves the latest title last-wins and notifies the change feed with the causing seq', async () => {
+    const { ctx, session } = await harness(true)
+    const changes: { key: string; value: unknown; seq: number }[] = []
+    ctx.sessionProjections.onChanged((_session, key, value, seq) => {
+      changes.push({ key, value, seq })
+    })
+    const firstSeq = appendTitle(session, 'First title')
+    const secondSeq = appendTitle(session, 'Second title')
+    // Unrelated event: same-reference apply, no notification.
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(changes).toEqual([
+      { key: 'title', value: 'First title', seq: firstSeq },
+      { key: 'title', value: 'Second title', seq: secondSeq },
+    ])
+    const snapshot = ctx.sessionProjections.snapshot(session)
+    expect(snapshot.values.title).toBe('Second title')
+    expect(snapshot.asOfSeq).toBe(session.seq - 1)
+  })
+
+  it('folds titles already in the log when the service mounts late (lazy cell build)', async () => {
+    const { ctx, session } = await harness(false)
+    appendTitle(session, 'Pre-mount title')
+    await ctx.plugin(SessionTitleService, CONFIG)
+    expect(ctx.sessionProjections.snapshot(session).values.title).toBe('Pre-mount title')
+  })
+
+  it('has no title key without the title service, and drops it when the service unloads (HMR safety)', async () => {
+    const { ctx, session } = await harness(false)
+    expect('title' in ctx.sessionProjections.snapshot(session).values).toBe(false)
+    const fiber = await ctx.plugin(SessionTitleService, CONFIG)
+    appendTitle(session, 'Ephemeral')
+    expect(ctx.sessionProjections.snapshot(session).values.title).toBe('Ephemeral')
+    await fiber.dispose()
+    expect('title' in ctx.sessionProjections.snapshot(session).values).toBe(false)
+  })
+})

packages/session-title/session-title/tsconfig.json

@@ -28,6 +28,9 @@
     },
     {
       "path": "../../core/session"
+    },
+    {
+      "path": "../../session-projection/session-projection"
     }
   ]
 }