Merge remote-tracking branch 'origin/master' into session-fork

# Conflicts:
#	docs/architecture.md
#	docs/cordis-catalog/services.md

packages/core/session/tests/derived-cache.spec.ts

@@ -0,0 +1,112 @@
+/**
+ * Derived-message cache tests: the session projects each surface node exactly
+ * once (O(new nodes) per call), rebuilds on a surface rewrite (replace /
+ * invalidate — the replaceGeneration signal), returns a fresh array snapshot
+ * per call over shared frozen messages, and stays deep-equal to a from-scratch
+ * replay derivation at every step — the incremental==scratch property the
+ * reconstructability RFC's invariant enforces in dev at request time.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+
+function userText(session: Session, text: string): void {
+  session.append('user/message', { content: [{ type: 'text', text }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+}
+
+/** From-scratch oracle: replay the log into a fresh session and derive. */
+function scratch(session: Session): unknown {
+  return new Session(SessionId(`${session.id}-scratch-${session.seq}`), [...session.events]).deriveMessages()
+}
+
+describe('derived-message cache', () => {
+  it('stays deep-equal to a from-scratch replay derivation as the log grows', () => {
+    const session = new Session(SessionId('cache-grow'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    userText(session, 'one')
+    expect(session.deriveMessages()).toEqual(scratch(session))
+    userText(session, 'two')
+    session.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'reply' }] }, { surfaceOp: 'append' })
+    expect(session.deriveMessages()).toEqual(scratch(session))
+    // An empty-content assistant/message (usage host) projects to nothing.
+    session.append('assistant/message', { turn: 1, step: 2, content: [], usage: { inputTokens: 1, outputTokens: 0 } }, { surfaceOp: 'append' })
+    expect(session.deriveMessages()).toEqual(scratch(session))
+  })
+
+  it('rebuilds on a surface replace and still matches scratch', () => {
+    const session = new Session(SessionId('cache-replace'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    userText(session, 'one')
+    userText(session, 'two')
+    const beforeReplace = session.deriveMessages()
+    expect(beforeReplace).toHaveLength(2)
+
+    const nodes = session.surface.nodes
+    session.append('context/message', {
+      content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' },
+    }, { surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq }, sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq] })
+
+    expect(session.deriveMessages()).toHaveLength(1)
+    expect(session.deriveMessages()).toEqual(scratch(session))
+    // The array a caller took before the replace is untouched.
+    expect(beforeReplace).toHaveLength(2)
+  })
+
+  it('returns a fresh array per call: later appends never grow a held snapshot', () => {
+    const session = new Session(SessionId('cache-snapshot'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    userText(session, 'one')
+    const first = session.deriveMessages()
+    userText(session, 'two')
+    const second = session.deriveMessages()
+    expect(first).toHaveLength(1)
+    expect(second).toHaveLength(2)
+    // Shared projection objects: the same frozen message instance, once ever.
+    expect(second[0]).toBe(first[0])
+    expect(Object.isFrozen(first[0])).toBe(true)
+  })
+
+  it('rebuilds after surface.invalidate() (the generation covers wholesale rebuilds too)', () => {
+    const session = new Session(SessionId('cache-invalidate'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    userText(session, 'one')
+    const before = session.deriveMessages()
+    session.surface.invalidate()
+    const after = session.deriveMessages()
+    expect(after).toEqual(before)
+    // A rebuild re-projects: fresh objects, same values.
+    expect(after[0]).not.toBe(before[0])
+  })
+})
+
+describe('Session.deriveEventMessage — the per-event projection', () => {
+  it('projects one appended event exactly as the full derivation projects its node', () => {
+    const session = new Session(SessionId('per-event'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const event = session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    // The fold path (deriveMessages) and the per-event path share the
+    // projection, so an external reconstructor cannot disagree with the cache.
+    expect(session.deriveEventMessage(event)).toEqual(session.deriveMessages().at(-1))
+  })
+
+  it('clones content off the log: the projection never aliases the logged event', () => {
+    const session = new Session(SessionId('per-event-clone'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const event = session.append('user/message', { content: [{ type: 'text', text: 'orig' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const message = session.deriveEventMessage(event)!
+    expect(message.content).not.toBe(event.data.content)
+    // deriveEventMessage returns an unfrozen clone (the cache freezes ITS
+    // copies); mutating it must not reach the log.
+    ;(message.content[0] as { text: string }).text = 'mutated'
+    expect(session.deriveMessages().at(-1)!.content).toEqual([{ type: 'text', text: 'orig' }])
+  })
+
+  it('projects null for events that produce no message (boundaries, empty assistant)', () => {
+    const session = new Session(SessionId('per-event-null'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const boundary = session.append('step/start', { turn: 1, step: 1 })
+    expect(session.deriveEventMessage(boundary)).toBeNull()
+    const empty = session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append' })
+    expect(session.deriveEventMessage(empty)).toBeNull()
+  })
+})

packages/core/session/tests/properties.spec.ts

@@ -109,15 +109,17 @@ describe('Session properties', () => {
     ))
   })
 
-  it('every derived message has a known role and decoupled content', () => {
+  it('every derived message has a known role and is frozen (append-only contract)', () => {
     fc.assert(fc.property(logArb, (events) => {
       const session = build(events)
       const messages = session.deriveMessages()
       const before = structuredClone(session.events)
       for (const m of messages) {
         expect(['user', 'assistant', 'system']).toContain(m.role)
-        // Mutating derived content must not touch the log (append-only).
-        m.content.push({ type: 'text', text: 'mutation' })
+        // Derived messages are frozen shared projections: mutation THROWS
+        // (strict mode) instead of relying on per-call clones for isolation.
+        expect(Object.isFrozen(m)).toBe(true)
+        expect(() => { m.content.push({ type: 'text', text: 'mutation' }) }).toThrow(TypeError)
       }
       expect(session.events).toEqual(before)
     }))

packages/core/session/tests/request-header.spec.ts

@@ -0,0 +1,140 @@
+/**
+ * Request-header utility tests: canonical form, the system line-diff
+ * (prefix/suffix trim), the name-keyed tools delta, config replacement, the
+ * round-trip contract (including the reorder case the encoding cannot
+ * express), and the log fold. These pin the reconstruction algebra: for every
+ * logged delta, apply(prev, delta) === next, and folding a log prefix yields
+ * the header its next request was built under.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Session, SessionId, applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader } from '@deepseek-ai/dsh-session'
+import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+
+const CONFIG = { model: 'm' }
+
+function tool(name: string, description = 'd'): ToolSchema {
+  return { name, description, parameters: { type: 'object' } }
+}
+
+/** Round-trip helper: diff must reproduce `next` from `prev` exactly. */
+function roundTrip(prev: EpochHeader, next: EpochHeader): ReturnType<typeof diffHeader> {
+  const delta = diffHeader(prev, next)
+  if (delta !== undefined) {
+    expect(applyHeaderDelta(prev, delta)).toEqual(canonicalHeader(next))
+  }
+  return delta
+}
+
+describe('canonicalHeader', () => {
+  it('normalizes empty system and empty tools to absent fields', () => {
+    expect(canonicalHeader({ config: CONFIG, system: '', tools: [] })).toEqual({ config: CONFIG })
+    const full = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')] })
+    expect(full.system).toBe('s')
+    expect(full.tools).toHaveLength(1)
+  })
+})
+
+describe('diffHeader / applyHeaderDelta', () => {
+  it('returns undefined for equal headers', () => {
+    const header = canonicalHeader({ config: CONFIG, system: 'a\nb', tools: [tool('t')] })
+    expect(diffHeader(header, header)).toBeUndefined()
+  })
+
+  it('encodes a mid-prompt line change as a prefix/suffix trim', () => {
+    const prev = canonicalHeader({ config: CONFIG, system: 'keep1\nold\nkeep2\nkeep3' })
+    const next = canonicalHeader({ config: CONFIG, system: 'keep1\nnew A\nnew B\nkeep2\nkeep3' })
+    const delta = roundTrip(prev, next)
+    expect(delta?.system).toEqual({ keepStart: 1, keepEnd: 2, insert: ['new A', 'new B'] })
+    expect(delta?.tools).toBeUndefined()
+    expect(delta?.config).toBeUndefined()
+  })
+
+  it('degenerates to a full replacement when nothing is shared, and round-trips absence transitions', () => {
+    const none = canonicalHeader({ config: CONFIG })
+    const some = canonicalHeader({ config: CONFIG, system: 'x\ny' })
+    const gained = roundTrip(none, some)
+    expect(gained?.system).toEqual({ keepStart: 0, keepEnd: 0, insert: ['x', 'y'] })
+    const lost = roundTrip(some, none)
+    expect(lost?.system).toEqual({ keepStart: 0, keepEnd: 0, insert: [] })
+  })
+
+  it('does not double-count overlapping prefix and suffix (repeated lines)', () => {
+    const prev = canonicalHeader({ config: CONFIG, system: 'a\na' })
+    const next = canonicalHeader({ config: CONFIG, system: 'a\na\na' })
+    roundTrip(prev, next)
+  })
+
+  it('encodes tool addition, removal, and in-place schema change by name', () => {
+    const prev = canonicalHeader({ config: CONFIG, tools: [tool('keep'), tool('drop'), tool('edit', 'before')] })
+    const next = canonicalHeader({ config: CONFIG, tools: [tool('keep'), tool('edit', 'after'), tool('new')] })
+    const delta = roundTrip(prev, next)
+    expect(delta?.tools?.added.map(t => t.name)).toEqual(['new'])
+    expect(delta?.tools?.removed).toEqual(['drop'])
+    expect(delta?.tools?.changed.map(t => t.name)).toEqual(['edit'])
+  })
+
+  it('round-trips a tool set gained from a tool-less header and lost back to one', () => {
+    const none = canonicalHeader({ config: CONFIG })
+    const some = canonicalHeader({ config: CONFIG, tools: [tool('t')] })
+    const gained = roundTrip(none, some)
+    expect(gained?.tools?.added.map(t => t.name)).toEqual(['t'])
+    const lost = roundTrip(some, none)
+    expect(lost?.tools?.removed).toEqual(['t'])
+  })
+
+  it('cannot express a pure reordering — the writer detects it via the round-trip check', () => {
+    const prev = canonicalHeader({ config: CONFIG, tools: [tool('a'), tool('b')] })
+    const next = canonicalHeader({ config: CONFIG, tools: [tool('b'), tool('a')] })
+    const delta = diffHeader(prev, next)
+    // A delta IS produced (the lists differ)…
+    expect(delta).toBeDefined()
+    // …but applying it cannot reproduce the new order — exactly the case the
+    // writer's guard turns into a 'fallback' snapshot.
+    expect(applyHeaderDelta(prev, delta!)).not.toEqual(next)
+  })
+
+  it('replaces the config whole and leaves untouched parts alone', () => {
+    const prev = canonicalHeader({ config: { model: 'm' }, system: 's', tools: [tool('t')] })
+    const next = canonicalHeader({ config: { model: 'm2', temperature: 0.1 }, system: 's', tools: [tool('t')] })
+    const delta = roundTrip(prev, next)
+    expect(delta).toEqual({ config: { model: 'm2', temperature: 0.1 } })
+  })
+})
+
+describe('foldRequestHeader', () => {
+  function headerEvents(session: Session): readonly SessionEvent[] {
+    return session.events
+  }
+
+  it('returns undefined on a log with no header events', () => {
+    const session = new Session(SessionId('fold-none'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(foldRequestHeader(headerEvents(session))).toBeUndefined()
+  })
+
+  it('folds snapshot then deltas into the header in force, skipping unrelated events', () => {
+    const session = new Session(SessionId('fold'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const first = canonicalHeader({ config: { model: 'm' }, system: 'a\nb', tools: [tool('t')] })
+    session.append('request/header', { header: first, reason: 'initial' })
+    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+
+    const second = canonicalHeader({ config: { model: 'm' }, system: 'a\nc', tools: [tool('t')] })
+    session.append('request/header-delta', diffHeader(first, second)!)
+    expect(foldRequestHeader(headerEvents(session))).toEqual(second)
+
+    // A later snapshot replaces the state wholesale (the 'resume'/'fallback' anchor).
+    const third = canonicalHeader({ config: { model: 'other' } })
+    session.append('request/header', { header: third, reason: 'resume' })
+    expect(foldRequestHeader(headerEvents(session))).toEqual(third)
+  })
+
+  it('throws on a delta before any snapshot (corrupt log)', () => {
+    const session = new Session(SessionId('fold-corrupt'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('request/header-delta', { config: { model: 'x' } })
+    expect(() => foldRequestHeader(headerEvents(session))).toThrow(/before any request\/header snapshot/)
+  })
+})

packages/core/session/tests/session.spec.ts

@@ -80,19 +80,25 @@ describe('Session', () => {
     }, { surfaceOp: 'append' })
     const before = structuredClone(session.events)
 
-    // A request middleware / adapter mutates the messages it was handed.
+    // A misbehaving consumer tries to mutate the messages it was handed.
+    // Derived messages are frozen shared projections (cloned once off the
+    // log, then deep-frozen): every mutation attempt THROWS in strict mode —
+    // isolation by unrepresentability, not by per-call cloning.
     const messages = session.deriveMessages()
     const userBlock = messages[0]!.content[0]!
-    if (userBlock.type === 'text') userBlock.text = 'HACKED'
+    expect(() => { if (userBlock.type === 'text') userBlock.text = 'HACKED' }).toThrow(TypeError)
     const toolBlock = messages[1]!.content[0]!
-    if (toolBlock.type === 'tool-result') {
-      toolBlock.content.push({ type: 'text', text: 'injected' })
-    }
-    messages[0]!.content.push({ type: 'text', text: 'extra' })
+    expect(() => {
+      if (toolBlock.type === 'tool-result') toolBlock.content.push({ type: 'text', text: 'injected' })
+    }).toThrow(TypeError)
+    expect(() => { messages[0]!.content.push({ type: 'text', text: 'extra' }) }).toThrow(TypeError)
+    // The returned ARRAY is the caller's own snapshot, though — reordering it
+    // is the caller's business and never reaches the cache or the log.
+    messages.reverse()
 
     // The log is unchanged: deep-equal to the snapshot taken before mutation.
     expect(session.events).toEqual(before)
-    // And a fresh derivation still reflects the original content.
+    // And a fresh derivation still reflects the original content and order.
     expect(session.deriveMessages()[0]!.content).toEqual([{ type: 'text', text: 'original' }])
   })
 

packages/core/session/tests/surface.spec.ts

@@ -334,3 +334,26 @@ describe('surface type guards', () => {
     expect(isSurfaceEvent(markerless)).toBe(false)
   })
 })
+
+describe('SurfaceManager.replaceGeneration', () => {
+  it('folds the pending log delta on access and counts replaces and invalidations', () => {
+    const s = new Session(SessionId('gen'))
+    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    s.append('user/message', { content: [{ type: 'text', text: 'one' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    s.append('user/message', { content: [{ type: 'text', text: 'two' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    // Read the generation FIRST — before nodes — so the getter itself folds
+    // the pending delta rather than piggybacking on a nodes read.
+    expect(s.surface.replaceGeneration).toBe(0)
+
+    const nodes = s.surface.nodes
+    s.append('context/message', {
+      content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' },
+    }, { surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq }, sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq] })
+    expect(s.surface.replaceGeneration).toBe(1)
+
+    // invalidate() is a rewrite too: the generation moves forward (and the
+    // refold re-counts the replace), never backwards.
+    s.surface.invalidate()
+    expect(s.surface.replaceGeneration).toBeGreaterThan(1)
+  })
+})