Merge branch 'master' into worktree/routed-model-compaction-policy

# Conflicts:
#	docs/event-producer-consumer.md

packages/llm/llm-deepseek/package.json

@@ -11,17 +11,23 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.7"

packages/llm/llm-deepseek/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-llm-deepseek`.
+ * @module @deepseek-ai/dsh-llm-deepseek/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm-deepseek'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-deepseek-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/llm/llm-deepseek/tsconfig.json

@@ -20,6 +20,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../support/invariants"
+    },
     {
       "path": "../../util/timeout"
     }

packages/llm/llm-pi-ai/package.json

@@ -11,17 +11,23 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
@@ -31,6 +37,7 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",

packages/llm/llm-pi-ai/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-llm-pi-ai`.
+ * @module @deepseek-ai/dsh-llm-pi-ai/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm-pi-ai'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-pi-ai-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/llm/llm-pi-ai/tsconfig.json

@@ -20,6 +20,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../support/invariants"
+    },
     {
       "path": "../../util/timeout"
     }

packages/llm/llm-retry/README.md

@@ -6,6 +6,8 @@ The default policy permits two retries for `RATE_LIMIT`, `SERVER`, `TIMEOUT`, an
 
 Before waiting, the plugin appends a non-surface `llm/retry` event with the failure and scheduled delay. Cancellation and plugin disposal abort the wait; disposal drains the plugin's active backoffs, and a callback captured before disposal fails closed if invoked afterward.
 
+The separately published `./invariant` companion checks that every retry record names the current open turn and its latest closed step, has a unique step record and increasing retry number, and carries a positive bounded retry budget and non-negative bounded timer delay. Full jitter may schedule zero milliseconds at its lower boundary.
+
 ```yaml
 - name: '@deepseek-ai/dsh-llm-retry'
   config:

packages/llm/llm-retry/package.json

@@ -11,10 +11,15 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
@@ -22,6 +27,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-timeout": "^0.0.1",
@@ -35,6 +41,7 @@
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",

packages/llm/llm-retry/src/invariant.ts

@@ -0,0 +1,97 @@
+/** Package-owned durable retry-event invariants. @module @deepseek-ai/dsh-llm-retry/invariant */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type {} from './index.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm-retry'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-retry-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Validate one retry record against the open turn and most recently closed step. */
+function validateRetry(
+  history: readonly SessionEvent[],
+  event: SessionEvent<'llm/retry'>,
+  fail: InvariantFailure,
+): void {
+  const { turn, step, retry, maxRetries, delayMs } = event.data
+  if (!Number.isSafeInteger(retry) || retry < 1) {
+    fail('llm/retry retry must be a positive safe integer')
+  }
+  if (!Number.isSafeInteger(maxRetries) || maxRetries < 1 || retry > maxRetries) {
+    fail(`llm/retry retry ${retry} must not exceed a positive safe maxRetries ${maxRetries}`)
+  }
+  if (!(delayMs >= 0 && delayMs <= MAX_TIMER_DELAY_MS)) {
+    fail(`llm/retry delayMs must be within 0..${MAX_TIMER_DELAY_MS}`)
+  }
+
+  const currentTurnEvents: SessionEvent[] = []
+  let openTurn: number | undefined
+  for (const prior of history.slice().reverse()) {
+    if (prior.type === 'turn/end') fail('llm/retry must be appended inside an open turn')
+    if (prior.type === 'turn/start') {
+      openTurn = prior.data.turn
+      break
+    }
+    currentTurnEvents.push(prior)
+  }
+  if (openTurn === undefined) fail('llm/retry must be appended inside an open turn')
+  if (turn !== openTurn) {
+    fail(`llm/retry names turn ${turn}, but the open turn is ${openTurn}`)
+  }
+
+  let closedStep: number | undefined
+  for (const prior of currentTurnEvents) {
+    if (prior.type === 'step/start') {
+      fail(`llm/retry must follow step/end, but step ${prior.data.step} is still open`)
+    }
+    if (prior.type === 'step/end') {
+      closedStep = prior.data.step
+      break
+    }
+  }
+  if (closedStep === undefined || step !== closedStep) {
+    fail(`llm/retry names step ${step}, but the latest closed step is ${String(closedStep)}`)
+  }
+
+  const priorRetries = currentTurnEvents
+    .filter((prior): prior is SessionEvent<'llm/retry'> => prior.type === 'llm/retry')
+  if (priorRetries.some(prior => prior.data.step === step)) {
+    fail(`llm/retry duplicates the retry record for turn ${turn}/step ${step}`)
+  }
+  const priorRetry = priorRetries[0]
+  if (priorRetry !== undefined && retry <= priorRetry.data.retry) {
+    fail(`llm/retry retry ${retry} must increase after retry ${priorRetry.data.retry}`)
+  }
+}
+
+/** Validate every retry record already present in one loaded session. */
+function validateSession(session: Session, fail: InvariantFailure): void {
+  for (const [index, event] of session.events.entries()) {
+    if (event.type === 'llm/retry') validateRetry(session.events.slice(0, index), event, fail)
+  }
+}
+
+/** Install validation for loaded and newly appended retry records. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  for (const session of ctx.sessions.list()) validateSession(session, fail)
+  ctx.on('session/created', (session) => { validateSession(session, fail) }, { global: true })
+  ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName !== 'session/event') return
+    const [session, event] = args as [Session, SessionEvent]
+    if (event.type === 'llm/retry') validateRetry(session.events, event, fail)
+  }, { global: true })
+}, { inject: ['sessions'] })
+
+/**
+ * Register the LLM retry invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/llm/llm-retry/tests/invariant.spec.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(RetryInvariant)
+  return ctx
+}
+
+function closeStep(ctx: Context, id: string, turn = 1, step = 1) {
+  const session = ctx.sessions.create(SessionId(id))
+  session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
+  session.append('step/start', { turn, step })
+  session.append('step/end', { turn, step })
+  return session
+}
+
+const failure = { message: 'provider busy', code: 'RATE_LIMIT', status: 429 }
+
+describe('llm-retry invariants', () => {
+  it('accepts increasing retry records for successive closed steps and ignores unrelated events', async () => {
+    const ctx = await setup()
+    const session = closeStep(ctx, 'retry-invariant-valid')
+    expect(() => {
+      session.append('llm/retry', {
+        turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 500, failure,
+      })
+      session.append('step/start', { turn: 1, step: 2 })
+      session.append('step/end', { turn: 1, step: 2 })
+      session.append('llm/retry', {
+        turn: 1, step: 2, retry: 2, maxRetries: 2, delayMs: 1_000, failure,
+      })
+      const zeroDelay = closeStep(ctx, 'retry-invariant-zero-delay')
+      zeroDelay.append('llm/retry', {
+        turn: 1, step: 1, retry: 1, maxRetries: 1, delayMs: 0, failure,
+      })
+    }).not.toThrow()
+    expect(() => { ctx.emit('tools/change') }).not.toThrow()
+  })
+
+  it.each([
+    [{ retry: 0, maxRetries: 2, delayMs: 1 }, /positive safe integer/],
+    [{ retry: 1.5, maxRetries: 2, delayMs: 1 }, /positive safe integer/],
+    [{ retry: 1, maxRetries: 0, delayMs: 1 }, /positive safe maxRetries/],
+    [{ retry: 1, maxRetries: 1.5, delayMs: 1 }, /positive safe maxRetries/],
+    [{ retry: 3, maxRetries: 2, delayMs: 1 }, /must not exceed/],
+    [{ retry: 1, maxRetries: 2, delayMs: -1 }, /delayMs/],
+    [{ retry: 1, maxRetries: 2, delayMs: MAX_TIMER_DELAY_MS + 1 }, /delayMs/],
+  ])('rejects invalid retry bounds %#', async (data, message) => {
+    const ctx = await setup()
+    const session = closeStep(ctx, `retry-invariant-bounds-${data.retry}-${data.maxRetries}-${data.delayMs}`)
+    expect(() => {
+      session.append('llm/retry', { turn: 1, step: 1, ...data, failure })
+    }).toThrow(message)
+  })
+
+  it('rejects retry records outside the matching closed-step boundary', async () => {
+    const ctx = await setup()
+    const absent = ctx.sessions.create(SessionId('retry-invariant-no-turn'))
+    expect(() => {
+      absent.append('llm/retry', {
+        turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+      })
+    }).toThrow(/inside an open turn/)
+
+    const wrongTurn = closeStep(ctx, 'retry-invariant-wrong-turn')
+    expect(() => {
+      wrongTurn.append('llm/retry', {
+        turn: 2, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+      })
+    }).toThrow(/open turn is 1/)
+
+    const openStep = ctx.sessions.create(SessionId('retry-invariant-open-step'))
+    openStep.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    openStep.append('step/start', { turn: 1, step: 1 })
+    expect(() => {
+      openStep.append('llm/retry', {
+        turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+      })
+    }).toThrow(/step 1 is still open/)
+
+    const noStep = ctx.sessions.create(SessionId('retry-invariant-no-step'))
+    noStep.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(() => {
+      noStep.append('llm/retry', {
+        turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+      })
+    }).toThrow(/latest closed step is undefined/)
+
+    const wrongStep = closeStep(ctx, 'retry-invariant-wrong-step')
+    expect(() => {
+      wrongStep.append('llm/retry', {
+        turn: 1, step: 2, retry: 1, maxRetries: 2, delayMs: 1, failure,
+      })
+    }).toThrow(/latest closed step is 1/)
+
+    const closedTurn = closeStep(ctx, 'retry-invariant-closed-turn')
+    closedTurn.append('turn/end', { turn: 1, reason: { kind: 'aborted', reason: 'cancelled' } })
+    expect(() => {
+      closedTurn.append('llm/retry', {
+        turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+      })
+    }).toThrow(/inside an open turn/)
+  })
+
+  it('rejects duplicate and non-increasing retry records', async () => {
+    const ctx = await setup()
+    const duplicate = closeStep(ctx, 'retry-invariant-duplicate')
+    duplicate.append('llm/retry', {
+      turn: 1, step: 1, retry: 1, maxRetries: 3, delayMs: 1, failure,
+    })
+    expect(() => {
+      duplicate.append('llm/retry', {
+        turn: 1, step: 1, retry: 2, maxRetries: 3, delayMs: 1, failure,
+      })
+    }).toThrow(/duplicates the retry record/)
+
+    const nonIncreasing = closeStep(ctx, 'retry-invariant-non-increasing')
+    nonIncreasing.append('llm/retry', {
+      turn: 1, step: 1, retry: 1, maxRetries: 3, delayMs: 1, failure,
+    })
+    nonIncreasing.append('step/start', { turn: 1, step: 2 })
+    nonIncreasing.append('step/end', { turn: 1, step: 2 })
+    expect(() => {
+      nonIncreasing.append('llm/retry', {
+        turn: 1, step: 2, retry: 1, maxRetries: 3, delayMs: 1, failure,
+      })
+    }).toThrow(/must increase/)
+  })
+
+  it('validates existing histories on late registration', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const session = ctx.sessions.create(SessionId('retry-invariant-late'))
+    session.append('step/end', { turn: 1, step: 1 })
+    session.append('llm/retry', {
+      turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+    })
+    await ctx.plugin(InvariantService)
+    await expect(ctx.plugin(RetryInvariant)).rejects.toThrow(/inside an open turn/)
+  })
+})

packages/llm/llm-retry/tests/retry.spec.ts

@@ -232,6 +232,29 @@ describe('bounded transient retry policy', () => {
     })
   })
 
+  it('accepts the zero-delay lower jitter bound', async () => {
+    vi.useFakeTimers()
+    const adapter = new ScriptedAdapter([
+      new LlmError('busy', 'SERVER'),
+      textResponse('done'),
+    ])
+    ;({ ctx: context } = await harness(adapter, {
+      initialDelayMs: 1,
+      maxDelayMs: 1,
+      jitterRatio: 1,
+    }, undefined, { random: () => 0 }))
+    const agent = context.agentLoop.create(SessionId('retry-zero-delay'), { provider: 'mock', model: 'mock' })
+    const scheduled = waitForRetry(context, agent, 1)
+
+    agent.send([{ type: 'text', text: 'go' }])
+    expect((await scheduled).data.delayMs).toBe(0)
+
+    const idle = waitForIdle(context, agent)
+    await vi.runAllTimersAsync()
+    await idle
+    expect(adapter.requests).toHaveLength(2)
+  })
+
   it('uses a bounded provider Retry-After verbatim and delegates an over-cap instruction', async () => {
     vi.useFakeTimers()
     const accepted = new ScriptedAdapter([

packages/llm/llm-retry/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../support/invariants"
+    },
     {
       "path": "../../util/timeout"
     }

packages/llm/llm/package.json

@@ -11,11 +11,16 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
@@ -23,10 +28,12 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/llm/llm/src/invariant.ts

@@ -0,0 +1,95 @@
+/** Package-owned LLM stream-protocol invariants. @module @deepseek-ai/dsh-llm/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { ContentBlockType, StreamChunk } from './types.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Require one chunk index to be a non-negative safe integer. */
+function validateIndex(index: number, fail: InvariantFailure): void {
+  if (!Number.isSafeInteger(index) || index < 0) {
+    fail(`LLM stream block index must be a non-negative safe integer, got ${index}`)
+  }
+}
+
+/** Require a delta to address an open block of its matching type. */
+function validateDelta(
+  open: ReadonlyMap<number, ContentBlockType>,
+  index: number,
+  expected: ContentBlockType,
+  fail: InvariantFailure,
+): void {
+  validateIndex(index, fail)
+  const actual = open.get(index)
+  if (actual !== expected) {
+    fail(`${expected} delta at index ${index} requires an open ${expected} block, got ${String(actual)}`)
+  }
+}
+
+/** Wrap one provider stream and enforce its grammar as chunks are consumed. */
+async function* validateStream(
+  source: AsyncIterable<StreamChunk>,
+  fail: InvariantFailure,
+): AsyncIterable<StreamChunk> {
+  const open = new Map<number, ContentBlockType>()
+  let usageSeen = false
+  let finished = false
+  for await (const chunk of source) {
+    if (finished) fail(`LLM stream emitted ${chunk.type} after terminal finish`)
+    switch (chunk.type) {
+      case 'block-start':
+        validateIndex(chunk.index, fail)
+        if (open.has(chunk.index)) fail(`LLM stream repeated block-start index ${chunk.index}`)
+        open.set(chunk.index, chunk.blockType)
+        break
+      case 'text-delta':
+        validateDelta(open, chunk.index, 'text', fail)
+        break
+      case 'reasoning-delta':
+        validateDelta(open, chunk.index, 'reasoning', fail)
+        break
+      case 'tool-call-delta':
+        validateDelta(open, chunk.index, 'tool-call', fail)
+        break
+      case 'block-end': {
+        validateIndex(chunk.index, fail)
+        const blockType = open.get(chunk.index)
+        if (blockType === undefined) fail(`LLM stream block-end index ${chunk.index} has no open block`)
+        if (chunk.block.type !== blockType) {
+          fail(`LLM stream block-end index ${chunk.index} closes ${chunk.block.type}, expected ${blockType}`)
+        }
+        open.delete(chunk.index)
+        break
+      }
+      case 'usage':
+        if (usageSeen) fail('LLM stream emitted usage more than once')
+        usageSeen = true
+        break
+      case 'finish':
+        if (open.size > 0) fail(`LLM stream finished with ${open.size} open block(s)`)
+        finished = true
+        break
+    }
+    yield chunk
+  }
+  if (!finished) fail('LLM stream ended without a terminal finish chunk')
+}
+
+/** Install validation around every provider stream. */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.on('llm/stream', (_options, next) => validateStream(next(), fail), { global: true, prepend: true })
+}
+
+/**
+ * Register the LLM invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/llm/llm/tests/invariant.spec.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import * as LlmInvariant from '@deepseek-ai/dsh-llm/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(LlmInvariant)
+  return ctx
+}
+
+const options: GenerateOptions = { provider: 'mock', model: 'mock', messages: [] }
+
+async function* source(chunks: readonly StreamChunk[]): AsyncIterable<StreamChunk> {
+  yield* chunks
+}
+
+async function consume(ctx: Context, chunks: readonly StreamChunk[]): Promise<StreamChunk[]> {
+  const stream = ctx.waterfall(ctx as never, 'llm/stream', options, () => source(chunks))
+  const consumed: StreamChunk[] = []
+  for await (const chunk of stream) consumed.push(chunk)
+  return consumed
+}
+
+const finish: StreamChunk = { type: 'finish', reason: { kind: 'stop' } }
+
+describe('LLM stream invariants', () => {
+  it('accepts a complete interleaved stream grammar', async () => {
+    const ctx = await setup()
+    const chunks: StreamChunk[] = [
+      { type: 'block-start', index: 0, blockType: 'text' },
+      { type: 'text-delta', index: 0, text: 'a' },
+      { type: 'block-start', index: 1, blockType: 'reasoning' },
+      { type: 'reasoning-delta', index: 1, text: 'b' },
+      { type: 'block-end', index: 1, block: { type: 'reasoning', text: 'b' } },
+      { type: 'block-end', index: 0, block: { type: 'text', text: 'a' } },
+      { type: 'block-start', index: 2, blockType: 'tool-call' },
+      { type: 'tool-call-delta', index: 2, id: CallId('c1'), name: 'echo', argumentsDelta: '{}' },
+      { type: 'block-end', index: 2, block: { type: 'tool-call', id: CallId('c1'), name: 'echo', arguments: '{}' } },
+      { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } },
+      finish,
+    ]
+    await expect(consume(ctx, chunks)).resolves.toEqual(chunks)
+  })
+
+  it.each([
+    [[{ type: 'block-start', index: -1, blockType: 'text' }, finish], /non-negative safe integer/],
+    [[
+      { type: 'block-start', index: 0, blockType: 'text' },
+      { type: 'block-start', index: 0, blockType: 'text' },
+    ], /repeated block-start/],
+    [[{ type: 'text-delta', index: 0, text: 'x' }], /requires an open text block/],
+    [[
+      { type: 'block-start', index: 0, blockType: 'reasoning' },
+      { type: 'text-delta', index: 0, text: 'x' },
+    ], /got reasoning/],
+    [[{ type: 'block-end', index: 0, block: { type: 'text', text: '' } }], /has no open block/],
+    [[
+      { type: 'block-start', index: 0, blockType: 'text' },
+      { type: 'block-end', index: 0, block: { type: 'reasoning', text: '' } },
+    ], /closes reasoning, expected text/],
+    [[
+      { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } },
+      { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } },
+    ], /usage more than once/],
+    [[{ type: 'block-start', index: 0, blockType: 'text' }, finish], /finished with 1 open block/],
+    [[finish, { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } }], /usage after terminal finish/],
+    [[], /ended without a terminal finish/],
+  ] as Array<[StreamChunk[], RegExp]>)('rejects malformed stream %#', async (chunks, message) => {
+    const ctx = await setup()
+    await expect(consume(ctx, chunks)).rejects.toThrow(message)
+  })
+
+  it('preserves provider exceptions without inventing a missing-finish failure', async () => {
+    const ctx = await setup()
+    const stream = ctx.waterfall(ctx as never, 'llm/stream', options, async function* () {
+      throw new Error('provider failed')
+    })
+    await expect((async () => {
+      for await (const _chunk of stream) { /* consume */ }
+    })()).rejects.toThrow('provider failed')
+  })
+})

packages/llm/llm/tests/service.spec.ts

@@ -72,6 +72,7 @@ class CatalogAdapter extends ScriptedAdapter {
 const SCRIPT: StreamChunk[] = [
   { type: 'block-start', index: 0, blockType: 'text' },
   { type: 'text-delta', index: 0, text: 'hi' },
+  { type: 'block-end', index: 0, block: { type: 'text', text: 'hi' } },
   { type: 'finish', reason: { kind: 'stop' } },
 ]
 
@@ -736,13 +737,14 @@ describe('LlmService', () => {
       const inner = next()
       return (async function * () {
         yield { type: 'block-start', index: 99, blockType: 'text' } satisfies StreamChunk
+        yield { type: 'block-end', index: 99, block: { type: 'text', text: '' } } satisfies StreamChunk
         yield * inner
       })()
     })
 
     const chunks: StreamChunk[] = []
     for await (const chunk of ctx.llm.stream({ provider: 'test-model', model: 'dynamic-model', messages: [] })) chunks.push(chunk)
-    expect(chunks).toHaveLength(4)
+    expect(chunks).toHaveLength(6)
     expect(chunks[0]).toMatchObject({ index: 99 })
   })
 

packages/llm/llm/tsconfig.json

@@ -16,6 +16,9 @@
     },
     {
       "path": "../../util/brand"
+    },
+    {
+      "path": "../../support/invariants"
     }
   ]
 }

packages/llm/token-meter/package.json

@@ -11,17 +11,23 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "cordis": "^4.0.0-rc.7"

packages/llm/token-meter/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-token-meter`.
+ * @module @deepseek-ai/dsh-token-meter/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-token-meter'
+
+/** Cordis companion plugin name. */
+export const name = 'token-meter-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: token estimates are per-call outputs and the private session cache is
+ * invalidated at its event mutation boundary; neither exposes an independent observation stream.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/llm/token-meter/tests/token-meter.spec.ts

@@ -620,19 +620,24 @@ describe('malformed replay and listener lifecycle', () => {
     })
     const firstFiber = await ctx.plugin(TokenMeterService)
     activeMeter = ctx.tokenMeter
-    const session = ctx.sessions.create(SessionId('listener-order'))
+    const session = ctx.sessions.create(SessionId('listener-order'), { seed: [{
+      type: 'turn/start',
+      seq: 0,
+      time: 1,
+      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+    }] })
     activeMeter.measure(session)
     session.append('user/message', {
       content: [{ type: 'text', text: 'one' }],
       source: { kind: 'user' },
     }, { surfaceOp: 'append' })
-    expect(revisions).toEqual([1])
-    expect(activeMeter.measure(session).logRevision).toBe(1)
+    expect(revisions).toEqual([2])
+    expect(activeMeter.measure(session).logRevision).toBe(2)
 
     await firstFiber.dispose()
     const secondFiber = await ctx.plugin(TokenMeterService)
     activeMeter = ctx.tokenMeter
-    expect(activeMeter.measure(session).logRevision).toBe(1)
+    expect(activeMeter.measure(session).logRevision).toBe(2)
     await secondFiber.dispose()
   })
 })

packages/llm/token-meter/tsconfig.json

@@ -22,6 +22,9 @@
     },
     {
       "path": "../../core/session"
+    },
+    {
+      "path": "../../support/invariants"
     }
   ]
 }