feat(invariants): add package-owned service seam

2026-07-19 19:19:57 +08:00
parent 38b7275eb1
commit 9d310ecc27
83 changed files with 2225 additions and 1557 deletions
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -27,6 +27,10 @@ The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loo

 `agents`, `sessions`, `llm`, `tools`, `systemPrompt` — all five interface services.

+### Invariant companion
+
+The optional `@deepseek-ai/dsh-agent-loop/invariant` companion registers request reconstruction with `ctx.invariants`. For each frozen loop-built request carrying a live session id, it independently rebuilds the message boundary and folded request header from the session log; direct one-shot calls remain outside this marker contract.
+
 ### Configuration (schemastery)

 ```ts
--- a/packages/core/agent-loop/package.json
+++ b/packages/core/agent-loop/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-scope": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
--- a/packages/core/agent-loop/src/invariant.ts
+++ b/packages/core/agent-loop/src/invariant.ts
@@ -0,0 +1,73 @@
+/**
+ * Package-owned request-reconstruction invariant for loop-built LLM calls.
+ * @module @deepseek-ai/dsh-agent-loop/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent-loop'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-loop-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants', 'sessions']
+
+/** Install the request-reconstruction contribution into its child registration fiber. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  // Prepend prevents a short-circuiting replay listener from silencing the
+  // check; correctness itself comes from the sequence-bounded reconstruction.
+  ctx.on('llm/stream', (options: GenerateOptions, next) => {
+    if (options.sessionId === undefined || !Object.isFrozen(options)) return next()
+    const session = ctx.sessions.get(options.sessionId)
+    if (!session) return next()
+    if (!Object.isFrozen(options.messages)) {
+      fail('a loop-built request must carry a frozen messages array')
+    }
+
+    const events = session.events
+    let boundary = -1
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      if (events[index]?.type === 'step/start') {
+        boundary = index
+        break
+      }
+    }
+    if (boundary === -1) {
+      return fail('a loop-built request with no step/start in its session log')
+    }
+    const header = foldRequestHeader(events)
+    if (header === undefined) {
+      return fail('a loop-built request with no request/header event in its session log')
+    }
+    const rebuilt = new Session(
+      SessionId(`${String(session.id)}-invariant-rebuild`),
+      structuredClone(events.slice(0, boundary)),
+    )
+    const expected = [...header.messagePrefix ?? [], ...rebuilt.deriveMessages()]
+    if (JSON.stringify(options.messages) !== JSON.stringify(expected)) {
+      fail(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`)
+    }
+
+    const headerMatches = options.model === header.config.model
+      && options.system === header.system
+      && options.temperature === header.config.temperature
+      && options.maxTokens === header.config.maxTokens
+      && JSON.stringify(options.stop) === JSON.stringify(header.config.stop)
+      && JSON.stringify(options.tools ?? []) === JSON.stringify(header.tools ?? [])
+    if (!headerMatches) {
+      fail(`llm request for session "${String(session.id)}" diverges from the folded request header`)
+    }
+    return next()
+  }, { global: true, prepend: true })
+}, { inject: ['sessions'] })
+
+/**
+ * Register the agent-loop invariant companion.
+ * @param ctx - Cordis context carrying the invariant and session services.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -7,9 +7,19 @@ import ToolRegistry, { defineTool, type PostToolDecision } from '@deepseek-ai/ds
 import AgentRegistry, { type Agent, type ContinuationDecision } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
 import { prepareReactLoopAgent } from '../src/agent.ts'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
 import { maxTokensResponse, MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'

+async function mountInvariants(ctx: Context): Promise<void> {
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(SessionInvariant)
+  await ctx.plugin(AgentInvariant)
+  await ctx.plugin(AgentLoopInvariant)
+}
+
 function driverDone(agent: Agent): Promise<void> {
  return (agent as Agent & { done: Promise<void> }).done
 }
@@ -144,7 +154,7 @@ describe('successful provider completion survives agent/step-result failure', ()
  ): Promise<void> {
    const adapter = new MockAdapter([response])
    const ctx = await harness(adapter)
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
    const agent = ctx.agentLoop.create(SessionId(id), { provider: 'mock', model: 'mock' })
    const failure = new Error(`${id} result processing failed`)
    const reported: Error[] = []
@@ -1014,7 +1024,7 @@ describe('step boundary publication order', () => {
 })

 describe('turn and step boundary recovery', () => {
-  // The invariants plugin makes an unbalanced log fail the test.
+  // The session invariant companion makes an unbalanced log fail the test.
  async function balancedHarness(adapter: MockAdapter) {
    const ctx = new Context()
    await ctx.plugin(LlmService)
@@ -1023,7 +1033,7 @@ describe('turn and step boundary recovery', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
    ctx.llm.registerAdapter(['mock'], adapter)
    return ctx
  }
@@ -1437,7 +1447,7 @@ describe('surface: assistant/message records exact empty provenance when no chun
    // stream from legacy events whose provenance was not recorded.
    const adapter = new MockAdapter([[]])
    const ctx = await harness(adapter)
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })

    ctx.on('agent/step-result', async (_agent, _turn, _step, _message, _next) => ({
@@ -1474,7 +1484,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
    ctx.llm.registerAdapter(['mock'], adapter)

    // Parent-owned listener survives agent-fiber disposal.
@@ -1525,7 +1535,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
    ctx.llm.registerAdapter(['mock'], adapter)

    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
@@ -1580,7 +1590,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
    ctx.llm.registerAdapter(['mock'], adapter)

    ctx.on('agent/pre-step', async () => {
@@ -1631,7 +1641,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
    ctx.llm.registerAdapter(['mock'], adapter)

    ctx.on('agent/pre-step', async () => {
@@ -1680,7 +1690,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants)
+    await mountInvariants(ctx)
    ctx.llm.registerAdapter(['mock'], adapter)

    ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
--- a/packages/core/agent-loop/tests/invariant.spec.ts
+++ b/packages/core/agent-loop/tests/invariant.spec.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(AgentLoopInvariant)
+  return ctx
+}
+
+function dispatch(ctx: Context, options: unknown): void {
+  void ctx.waterfall('llm/stream', options as never, () => (async function* () {})() as never)
+}
+
+async function requestSetup() {
+  const ctx = await setup()
+  const session = ctx.sessions.create(SessionId('req-check'))
+  session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+  session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+  const boundary = session.deriveMessages()
+  session.append('step/start', { turn: 1, step: 1 })
+  session.append('request/header', { header: { config: { provider: 'mock', model: 'm' } }, reason: 'initial' })
+  return { ctx, session, boundary }
+}
+
+describe('request-reconstruction invariant', () => {
+  it('accepts a frozen request equal to the boundary derivation and folded header', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    const options = Object.freeze({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
+    expect(() => { dispatch(ctx, options) }).not.toThrow()
+  })
+
+  it('uses the step boundary rather than content appended afterward', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    session.append('context/message', { content: [{ type: 'text', text: '[late]' }], source: { kind: 'plugin', plugin: 'x' } }, { surfaceOp: 'append' })
+    const options = Object.freeze({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
+    expect(() => { dispatch(ctx, options) }).not.toThrow()
+  })
+
+  it('requires the folded session prefix ahead of derived history', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    const prefix = { role: 'user' as const, content: [{ type: 'text' as const, text: '<system-reminder>catalog</system-reminder>' }] }
+    session.append('request/header', { header: { config: { provider: 'mock', model: 'm' }, messagePrefix: [prefix] }, reason: 'change' })
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([prefix, ...boundary]), sessionId: session.id })) })
+      .not.toThrow()
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([...boundary]), sessionId: session.id })) })
+      .toThrow(/diverges from the boundary derivation/)
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([...boundary, prefix]), sessionId: session.id })) })
+      .toThrow(/diverges from the boundary derivation/)
+  })
+
+  it('rejects message and header divergence', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    const divergent = [...boundary, { role: 'user', content: [{ type: 'text', text: 'phantom' }] }]
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze(divergent), sessionId: session.id })) })
+      .toThrow(/diverges from the boundary derivation/)
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'other', messages: Object.freeze(boundary), sessionId: session.id })) })
+      .toThrow(/diverges from the folded request header/)
+  })
+
+  it('rejects loop requests with no boundary or header', async () => {
+    const ctx = await setup()
+    const session = ctx.sessions.create(SessionId('req-bare'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const bare = Object.freeze({ model: 'm', messages: Object.freeze([]), sessionId: session.id })
+    expect(() => { dispatch(ctx, bare) }).toThrow(/no step\/start/)
+    session.append('step/start', { turn: 1, step: 1 })
+    expect(() => { dispatch(ctx, bare) }).toThrow(/no request\/header event/)
+  })
+
+  it('rejects an unfrozen messages array but skips requests outside the loop contract', async () => {
+    const { ctx, session, boundary } = await requestSetup()
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: [...boundary], sessionId: session.id })) })
+      .toThrow(/frozen messages array/)
+    expect(() => { dispatch(ctx, { model: 'summarizer', messages: [], sessionId: session.id }) }).not.toThrow()
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([]) })) }).not.toThrow()
+    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([]), sessionId: SessionId('ghost') })) })
+      .not.toThrow()
+  })
+
+  it('prepends ahead of a short-circuiting stream listener', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    ctx.on('llm/stream', () => (async function* () {})() as never)
+    await ctx.plugin(InvariantService)
+    await ctx.plugin(AgentLoopInvariant)
+    const session = ctx.sessions.create(SessionId('prepend-check'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    session.append('step/start', { turn: 1, step: 1 })
+    session.append('request/header', { header: { config: { provider: 'mock', model: 'm' } }, reason: 'initial' })
+    const divergent = Object.freeze({
+      model: 'm',
+      messages: Object.freeze([{ role: 'user', content: [{ type: 'text', text: 'phantom' }] }]),
+      sessionId: session.id,
+    })
+    expect(() => { dispatch(ctx, divergent) }).toThrow(/diverges from the boundary derivation/)
+  })
+})
--- a/packages/core/agent-loop/tests/turn-stop.spec.ts
+++ b/packages/core/agent-loop/tests/turn-stop.spec.ts
@@ -7,9 +7,19 @@ import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent, type ContinuationStop } from '@deepseek-ai/dsh-agent'

 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'

+async function mountInvariants(ctx: Context): Promise<void> {
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(SessionInvariant)
+  await ctx.plugin(AgentInvariant)
+  await ctx.plugin(AgentLoopInvariant)
+}
+
 async function harness(adapter: MockAdapter): Promise<Context> {
  const ctx = new Context()
  await ctx.plugin(LlmService)
@@ -17,7 +27,7 @@ async function harness(adapter: MockAdapter): Promise<Context> {
  await ctx.plugin(SystemPrompt)
  await ctx.plugin(ToolRegistry)
  await ctx.plugin(AgentRegistry)
-  await ctx.plugin(Invariants)
+  await mountInvariants(ctx)
  await ctx.plugin(AgentLoop, { agents: [] })
  ctx.llm.registerAdapter(['mock'], adapter)
  return ctx
--- a/packages/core/agent-loop/tsconfig.json
+++ b/packages/core/agent-loop/tsconfig.json
@@ -37,6 +37,9 @@
    },
    {
      "path": "../../core/scope"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/core/agent-loop/tsdown.config.ts
+++ b/packages/core/agent-loop/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -2,6 +2,8 @@

 Agent interface, registry, process-local initiator scope, and `agent/*` event vocabulary. Every plugin (UI, hooks, orchestrators) programs against the `Agent` handle defined here — it has zero loop dependency, so the loop is swappable.

+The optional `@deepseek-ai/dsh-agent/invariant` companion registers this package's agent-status transition checks with `ctx.invariants`. The root agent service does not load diagnostics implicitly.
+
 ## Service: `AgentRegistry` (ctx key: `agents`)

 Tracks live agents and carries the initiating Agent through asynchronous driver work without importing the concrete loop package.
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/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,6 +28,7 @@
  "license": "BSD-3-Clause",
  "peerDependencies": {
    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-scope": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
@@ -31,6 +37,7 @@
  },
  "devDependencies": {
    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-scope": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
--- a/packages/core/agent/src/invariant.ts
+++ b/packages/core/agent/src/invariant.ts
@@ -0,0 +1,35 @@
+/** Package-owned agent lifecycle invariants. @module @deepseek-ai/dsh-agent/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Install the agent contribution into its child registration fiber. */
+const install: InvariantInstaller = (ctx, fail) => {
+  const lastStatus = new WeakMap<Agent, AgentStatus>()
+  ctx.on('agent/status', (agent, status) => {
+    const previous = lastStatus.get(agent)
+    if (previous === status) {
+      fail(`agent/status repeated ${status} (no-op transition)`)
+    }
+    if (previous === 'disposed') {
+      fail(`agent/status left terminal state disposed → ${status}`)
+    }
+    lastStatus.set(agent, status)
+  }, { global: true })
+}
+
+/**
+ * Register the agent 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))
--- a/packages/core/agent/tests/invariant.spec.ts
+++ b/packages/core/agent/tests/invariant.spec.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(AgentInvariant)
+  return ctx
+}
+
+function mockAgent(id: string): Agent {
+  return { id } as unknown as Agent
+}
+
+describe('agent status invariants', () => {
+  it('accepts lifecycle transitions through idle, running, and disposed', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('a1')
+    expect(() => {
+      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle')
+      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running')
+      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle')
+      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'disposed')
+    }).not.toThrow()
+
+    const running = mockAgent('a2')
+    ctx.emit(scopeTarget(running, running), 'agent/status', running, 'running')
+    expect(() => { ctx.emit(scopeTarget(running, running), 'agent/status', running, 'disposed') }).not.toThrow()
+  })
+
+  it('rejects a no-op transition', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('a3')
+    ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running')
+    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running') })
+      .toThrow(/no-op transition/)
+  })
+
+  it('rejects leaving the terminal disposed state', async () => {
+    const ctx = await setup()
+    const agent = mockAgent('a4')
+    ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'disposed')
+    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle') })
+      .toThrow(/left terminal state disposed/)
+  })
+
+  it('tracks agents independently', async () => {
+    const ctx = await setup()
+    const a = mockAgent('a5')
+    const b = mockAgent('b5')
+    ctx.emit(scopeTarget(a, a), 'agent/status', a, 'running')
+    expect(() => { ctx.emit(scopeTarget(b, b), 'agent/status', b, 'running') }).not.toThrow()
+  })
+})
--- a/packages/core/agent/tsconfig.json
+++ b/packages/core/agent/tsconfig.json
@@ -28,6 +28,9 @@
    },
    {
      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/core/agent/tsdown.config.ts
+++ b/packages/core/agent/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])
--- a/packages/core/scope/README.md
+++ b/packages/core/scope/README.md
@@ -13,6 +13,8 @@ Scoped registration primitive. `createScope(ctx, key)` creates a tagged Cordis c
 - `Scoped<T>` The compile-time opaque carrier brand: scope-filtered events demand it as their `this` type, so dispatching with a bare subject is a compile error. The type parameter records the subject type but does not expose its properties.
 - `isScopeCarrier(value)` / `carrierKeyOf(value)` Runtime carrier marks, used by the dev invariants to assert every scope-filtered dispatch carries a carrier keyed to the subject its arguments name.

+The optional `@deepseek-ai/dsh-scope/invariant` companion owns that runtime assertion. It uses the generated `scoped-events.generated.ts` resolver map to require a carrier for every declared scoped event and, when the payload exposes its routing subject, require identity with the carrier key. The Program-backed generator derives the map from event declarations and real `scopeTarget(base, key)` calls.
+
 ## Design contract

 The registration context determines both visibility and ownership, preventing a registration from being visible in one scope but disposed with another. Scopes route trusted same-process plugins; they are not sandboxes or authority boundaries. See the [agent-scope RFC](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals) for rationale and security non-goals.
--- a/packages/core/scope/package.json
+++ b/packages/core/scope/package.json
@@ -11,20 +11,27 @@
      "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",
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/core/scope/src/invariant.ts
+++ b/packages/core/scope/src/invariant.ts
@@ -0,0 +1,41 @@
+/** Package-owned scoped-dispatch invariants. @module @deepseek-ai/dsh-scope/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { carrierKeyOf, isScopeCarrier } from '@deepseek-ai/dsh-scope'
+import { scopedSubjectResolverFor } from './scoped-events.generated.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-scope'
+
+/** Cordis companion plugin name. */
+export const name = 'scope-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Install the scoped-dispatch contribution into its child registration fiber. */
+const install: InvariantInstaller = (ctx, fail) => {
+  ctx.on('internal/dispatch', (_mode, eventName, args, thisArg) => {
+    const subjectOf = scopedSubjectResolverFor(eventName)
+    if (subjectOf === undefined) return
+    if (!isScopeCarrier(thisArg)) {
+      fail(
+        `"${eventName}" is a scope-filtered event but was dispatched without a scope carrier — `
+        + 'pass scopeTarget(base, subject) as the dispatch thisArg (agent events: use agentEvents(ctx, agent))',
+      )
+    }
+    if (subjectOf !== null && carrierKeyOf(thisArg) !== subjectOf(args)) {
+      fail(
+        `"${eventName}" was dispatched with a scope carrier keyed to a DIFFERENT subject than its arguments name — `
+        + 'the carrier key and the event\'s subject must be the same object (use agentEvents(ctx, agent))',
+      )
+    }
+  }, { global: true })
+}
+
+/**
+ * Register the scope 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))
--- a/packages/core/scope/src/scoped-events.generated.ts
+++ b/packages/core/scope/src/scoped-events.generated.ts
@@ -0,0 +1,50 @@
+/**
+ * Generated scoped-event routing-subject resolvers for dsh-scope invariants.
+ * Do not edit by hand; run `pnpm run gen-scoped-events`.
+ *
+ * @module @deepseek-ai/dsh-scope/scoped-events.generated
+ */
+
+type ScopedSubjectResolver = (args: readonly unknown[]) => unknown
+
+const scopedSubjectResolvers: Readonly<Record<string, ScopedSubjectResolver | null>> = Object.freeze({
+  'agent/created': args => args[0],
+  'agent/disposed': args => args[0],
+  'agent/error': args => args[0],
+  'agent/post-step': args => args[0],
+  'agent/pre-step': args => args[0],
+  'agent/prompt-submit': args => args[0],
+  'agent/queued': args => args[0],
+  'agent/request': args => args[0],
+  'agent/request-error': args => args[0],
+  'agent/session-prefix': args => args[0],
+  'agent/session-start': args => args[0],
+  'agent/status': args => args[0],
+  'agent/step-result': args => args[0],
+  'agent/turn-continuation': args => args[0],
+  'agent/turn-stop': args => args[0],
+  'approval/request': args => (args[0] as Record<string, unknown>)['agent'],
+  'session/created': null,
+  'session/disposed': null,
+  'session/event': null,
+  'session/flush': null,
+  'subagent/end': null,
+  'subagent/start': null,
+  'system-prompt/assemble': args => (args[1] as Record<string, unknown>)['scope'],
+  'tools/execute': args => (args[0] as Record<string, unknown>)['agent'],
+  'tools/post-execute': args => (args[0] as Record<string, unknown>)['agent'],
+  'tools/pre-execute': args => (args[0] as Record<string, unknown>)['agent'],
+  'tools/result': args => (args[0] as Record<string, unknown>)['agent'],
+})
+
+/**
+ * Resolve the routing key named by one scoped event payload. A null
+ * resolver means the payload cannot expose its external routing key, so the
+ * invariant checks carrier presence only.
+ * @param event - runtime Cordis event name.
+ * @returns the generated subject resolver, null for presence-only,
+ *   or undefined when the event is not scope-filtered.
+ */
+export function scopedSubjectResolverFor(event: string): ScopedSubjectResolver | null | undefined {
+  return scopedSubjectResolvers[event]
+}
--- a/packages/core/scope/tests/invariant.spec.ts
+++ b/packages/core/scope/tests/invariant.spec.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import * as ScopeInvariant from '@deepseek-ai/dsh-scope/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(ScopeInvariant)
+  return ctx
+}
+
+function emit(ctx: Context, receiver: object | undefined, event: string, args: unknown[]): void {
+  const dispatch = ctx.emit.bind(ctx) as (...values: unknown[]) => void
+  if (receiver === undefined) dispatch(event, ...args)
+  else dispatch(receiver, event, ...args)
+}
+
+describe('scoped-dispatch invariants', () => {
+  it('ignores ordinary events and rejects a scoped dispatch without a carrier', async () => {
+    const ctx = await setup()
+    expect(() => { emit(ctx, undefined, 'ordinary/event', []) }).not.toThrow()
+    const agent = { id: 'a1' }
+    expect(() => { emit(ctx, undefined, 'agent/error', [agent, 1, 0, new Error('x')]) })
+      .toThrow(/dispatched without a scope carrier/)
+  })
+
+  it('checks every generated subject resolver against the carrier key', async () => {
+    const ctx = await setup()
+    const agent = { id: 'a1' }
+    const other = { id: 'a2' }
+    const rows: Array<[string, unknown[]]> = [
+      ['agent/created', [agent]],
+      ['agent/disposed', [agent]],
+      ['agent/error', [agent, 1, 0, new Error('x')]],
+      ['agent/post-step', [agent, 1, 1]],
+      ['agent/pre-step', [agent, 1, 1, new AbortController().signal]],
+      ['agent/prompt-submit', [agent, [], { kind: 'user' }, () => Promise.resolve({ kind: 'allow' })]],
+      ['agent/queued', [agent, [], { source: { kind: 'user' }, steering: false }]],
+      ['agent/request', [agent, 1, 1, { model: 'm' }, () => Promise.resolve({ model: 'm' })]],
+      ['agent/request-error', [agent, 1, 1, new Error('x')]],
+      ['agent/session-prefix', [agent, [], new AbortController().signal, () => Promise.resolve([])]],
+      ['agent/session-start', [agent, 'startup']],
+      ['agent/status', [agent, 'idle']],
+      ['agent/step-result', [agent, 1, 1, { role: 'assistant', content: [] }, () => Promise.resolve({ role: 'assistant', content: [] })]],
+      ['agent/turn-continuation', [agent, 1, { action: 'stop' }, () => Promise.resolve({ action: 'stop' })]],
+      ['agent/turn-stop', [agent, 1]],
+      ['approval/request', [{ agent, toolName: 'echo' }, () => Promise.resolve('unavailable')]],
+      ['system-prompt/assemble', [[], { scope: agent }]],
+      ['tools/execute', [{ callId: 'c', name: 't', arguments: {}, agent }, () => Promise.resolve({ content: [], isError: false })]],
+      ['tools/post-execute', [{ callId: 'c', name: 't', arguments: {}, agent }, { content: [], isError: false }, () => Promise.resolve({ kind: 'accept' })]],
+      ['tools/pre-execute', [{ callId: 'c', name: 't', arguments: {}, agent }, () => Promise.resolve({ kind: 'allow' })]],
+      ['tools/result', [{ callId: 'c', name: 't', arguments: {}, agent }, { content: [], isError: false }]],
+    ]
+
+    for (const [event, args] of rows) {
+      expect(() => { emit(ctx, scopeTarget(agent, agent), event, args) }, `${event} matching`).not.toThrow()
+      expect(() => { emit(ctx, scopeTarget(agent, other), event, args) }, `${event} mismatched`)
+        .toThrow(/DIFFERENT subject/)
+    }
+  })
+
+  it('requires carriers for generated presence-only scoped events without comparing a payload subject', async () => {
+    const ctx = await setup()
+    const agent = { id: 'a1' }
+    const rows: Array<[string, unknown[]]> = [
+      ['session/created', [{}]],
+      ['session/disposed', [{}]],
+      ['session/event', [{}, {}]],
+      ['session/flush', [{}]],
+      ['subagent/end', [{}]],
+      ['subagent/start', [{}]],
+    ]
+    for (const [event, args] of rows) {
+      expect(() => { emit(ctx, scopeTarget(agent, agent), event, args) }, `${event} carrier`).not.toThrow()
+      expect(() => { emit(ctx, undefined, event, args) }, `${event} no carrier`)
+        .toThrow(/dispatched without a scope carrier/)
+    }
+  })
+})
--- a/packages/core/scope/tsconfig.json
+++ b/packages/core/scope/tsconfig.json
@@ -13,6 +13,9 @@
    },
    {
      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/core/scope/tsdown.config.ts
+++ b/packages/core/scope/tsdown.config.ts
@@ -0,0 +1,27 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+    // Preserve the root entry's carrier WeakMap identity across bundles.
+    deps: { neverBundle: ['@deepseek-ai/dsh-scope'] },
+  },
+])
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -2,6 +2,8 @@

 Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (an ordered projection of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.

+The optional `@deepseek-ai/dsh-session/invariant` companion registers this package's relational trace checks with `ctx.invariants`: monotonic sequence numbers, turn/step enclosure, and same-step tool call/result pairing. It replays existing sessions when loaded or reloaded; storage validation, snapshotting, freezing, provenance, and surface acceptance remain always-on responsibilities of the root session package.
+
 ## Service: `SessionStore` (ctx key: `sessions`)

 Creates and holds event-sourced `Session` instances. Persistence is intentionally not implemented here — plugins subscribe to `session/event`, flush on `session/flush`, and may mirror the paired `session/created`/`session/disposed` lifecycle.
@@ -34,7 +36,7 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.

 - `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, and complete replacement coverage, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
 - `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback.
- `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and invariants.
+- `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and request checks.
 - `session.surface` exposes the readonly `SessionSurface` view owned by the session's single incremental surface manager; `replaceGeneration` changes on every committed rewrite.
 - `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
 - `session.seq`, `session.id` — current sequence and readonly typed identity.
--- a/packages/core/session/package.json
+++ b/packages/core/session/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,12 +28,14 @@
  "license": "BSD-3-Clause",
  "peerDependencies": {
    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-scope": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-scope": "workspace:^",
    "cordis": "^4.0.0-rc.7"
--- a/packages/core/session/src/invariant.ts
+++ b/packages/core/session/src/invariant.ts
@@ -0,0 +1,230 @@
+/**
+ * Package-owned relational invariants for the session event log. Load this
+ * companion beside `@deepseek-ai/dsh-invariants` to enable the checks.
+ *
+ * @module @deepseek-ai/dsh-session/invariant
+ */
+
+import type { Context } from 'cordis'
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import type { CallId } from '@deepseek-ai/dsh-llm'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session'
+
+/** Cordis companion plugin name. */
+export const name = 'session-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants', 'sessions']
+
+/** Per-session bookkeeping for relational log checks. */
+interface SessionTrace {
+  lastSeq: number
+  openTurn: number | null
+  openStep: number | null
+  nextTurn: number
+  nextStep: number
+  pendingCalls: Set<CallId>
+}
+
+/** One accepted event's deferred mutation of a committed session trace. */
+interface SessionTraceTransition {
+  scalars: Pick<SessionTrace, 'lastSeq' | 'openTurn' | 'openStep' | 'nextTurn' | 'nextStep'>
+  pendingCalls:
+    | { kind: 'none' }
+    | { kind: 'add' | 'delete'; callId: CallId }
+    | { kind: 'clear' }
+}
+
+/** Assert that a step-scoped event names the currently open turn and step. */
+function requireOpenStep(
+  trace: SessionTrace,
+  kind: string,
+  turn: number,
+  step: number,
+  fail: InvariantFailure,
+): void {
+  if (trace.openTurn !== turn || trace.openStep !== step) {
+    fail(`${kind} names turn ${turn}/step ${step} but open is turn ${trace.openTurn}/step ${trace.openStep}`)
+  }
+}
+
+/** Validate one candidate event without mutating the committed trace. */
+function validateEvent(
+  trace: SessionTrace,
+  event: SessionEvent,
+  fail: InvariantFailure,
+): SessionTraceTransition {
+  if (event.seq <= trace.lastSeq) {
+    fail(`seq must strictly increase: saw ${event.seq} after ${trace.lastSeq}`)
+  }
+  let openTurn = trace.openTurn
+  let openStep = trace.openStep
+  let nextTurn = trace.nextTurn
+  let nextStep = trace.nextStep
+  let pendingCalls: SessionTraceTransition['pendingCalls'] = { kind: 'none' }
+
+  // SessionEventMap is merge-extensible, so the default enforces turn
+  // enclosure for package-added events as well as the built-in variants.
+  switch (event.type) {
+    case 'turn/start': {
+      if (trace.openTurn !== null) {
+        fail(`turn/start ${event.data.turn} while turn ${trace.openTurn} is still open`)
+      }
+      if (event.data.turn !== trace.nextTurn) {
+        fail(`turn/start expected turn ${trace.nextTurn}, got ${event.data.turn}`)
+      }
+      openTurn = event.data.turn
+      nextStep = 1
+      break
+    }
+    case 'turn/end': {
+      if (trace.openTurn !== event.data.turn) {
+        fail(`turn/end ${event.data.turn} does not match open turn ${trace.openTurn}`)
+      }
+      if (trace.openStep !== null) {
+        fail(`turn/end ${event.data.turn} while step ${trace.openStep} is still open`)
+      }
+      openTurn = null
+      nextTurn += 1
+      break
+    }
+    case 'step/start': {
+      if (trace.openTurn !== event.data.turn) {
+        fail(`step/start in turn ${event.data.turn} but open turn is ${trace.openTurn}`)
+      }
+      if (trace.openStep !== null) {
+        fail(`step/start ${event.data.step} while step ${trace.openStep} is still open`)
+      }
+      if (event.data.step !== trace.nextStep) {
+        fail(`step/start expected step ${trace.nextStep} in turn ${event.data.turn}, got ${event.data.step}`)
+      }
+      openStep = event.data.step
+      break
+    }
+    case 'step/end': {
+      requireOpenStep(trace, 'step/end', event.data.turn, event.data.step, fail)
+      pendingCalls = { kind: 'clear' }
+      openStep = null
+      nextStep += 1
+      break
+    }
+    case 'assistant/chunk': {
+      requireOpenStep(trace, 'assistant/chunk', event.data.turn, event.data.step, fail)
+      break
+    }
+    case 'assistant/message': {
+      requireOpenStep(trace, 'assistant/message', event.data.turn, event.data.step, fail)
+      break
+    }
+    case 'tool/call': {
+      requireOpenStep(trace, 'tool/call', event.data.turn, event.data.step, fail)
+      pendingCalls = { kind: 'add', callId: event.data.callId }
+      break
+    }
+    case 'tool/result': {
+      requireOpenStep(trace, 'tool/result', event.data.turn, event.data.step, fail)
+      const syntheticInterrupted = event.data.isError && event.data.error?.code === 'interrupted'
+      if (!trace.pendingCalls.has(event.data.callId) && !syntheticInterrupted) {
+        fail(`tool/result for ${event.data.callId} with no prior tool/call in this step`)
+      }
+      pendingCalls = { kind: 'delete', callId: event.data.callId }
+      break
+    }
+    default: {
+      if (trace.openTurn === null) {
+        fail(`${event.type} appended outside any open turn (every event must be turn-enclosed)`)
+      }
+      break
+    }
+  }
+  return {
+    scalars: { lastSeq: event.seq, openTurn, openStep, nextTurn, nextStep },
+    pendingCalls,
+  }
+}
+
+/** Apply one already-validated transition after its event commits. */
+function applyTransition(trace: SessionTrace, transition: SessionTraceTransition): void {
+  Object.assign(trace, transition.scalars)
+  switch (transition.pendingCalls.kind) {
+    case 'none':
+      break
+    case 'add':
+      trace.pendingCalls.add(transition.pendingCalls.callId)
+      break
+    case 'delete':
+      trace.pendingCalls.delete(transition.pendingCalls.callId)
+      break
+    case 'clear':
+      trace.pendingCalls.clear()
+      break
+    /* v8 ignore next -- validateEvent produces this closed transition union */
+    default:
+      assertNever(transition.pendingCalls, 'session trace pending-call transition')
+  }
+}
+
+/** Install the session contribution into its child registration fiber. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  const traces = new WeakMap<Session, SessionTrace>()
+  const stagedTransitions = new WeakMap<SessionEvent, {
+    session: Session
+    trace: SessionTrace
+    transition: SessionTraceTransition
+  }>()
+
+  const freshTrace = (): SessionTrace => ({
+    lastSeq: -1,
+    openTurn: null,
+    openStep: null,
+    nextTurn: 1,
+    nextStep: 1,
+    pendingCalls: new Set(),
+  })
+
+  const seedSession = (session: Session): SessionTrace => {
+    const trace = freshTrace()
+    traces.set(session, trace)
+    for (const event of session.events) {
+      applyTransition(trace, validateEvent(trace, event, fail))
+    }
+    return trace
+  }
+
+  /* v8 ignore next -- session/event always follows list() or session/created seeding */
+  const traceFor = (session: Session): SessionTrace => traces.get(session) ?? seedSession(session)
+
+  for (const session of ctx.sessions.list()) seedSession(session)
+
+  ctx.on('session/created', (session) => { seedSession(session) }, { global: true })
+
+  ctx.on('session/event', (session, event) => {
+    const staged = stagedTransitions.get(event)
+    /* v8 ignore next 2 -- internal/dispatch stages the exact callback arguments */
+    if (staged === undefined || staged.session !== session) {
+      return fail('session/event reached publication without matching pre-commit validation')
+    }
+    stagedTransitions.delete(event)
+    applyTransition(staged.trace, staged.transition)
+  }, { global: true })
+
+  ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName !== 'session/event') return
+    const [session, event] = args as [Session, SessionEvent]
+    const trace = traceFor(session)
+    const transition = validateEvent(trace, event, fail)
+    // A later dispatch listener may veto. Validation is pure, so abandoning
+    // this weakly keyed transition does not advance or retain the session.
+    stagedTransitions.set(event, { session, trace, transition })
+  }, { global: true })
+}, { inject: ['sessions'] })
+
+/**
+ * Register the session invariant companion.
+ * @param ctx - Cordis context carrying the invariant and session services.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
--- a/packages/core/session/tests/invariant.spec.ts
+++ b/packages/core/session/tests/invariant.spec.ts
@@ -0,0 +1,268 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { createScope, scopeTarget } from '@deepseek-ai/dsh-scope'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import InvariantService, { InvariantError } from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise<{ ctx: Context; fiber: Awaited<ReturnType<Context['plugin']>> }> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(InvariantService)
+  const fiber = await ctx.plugin(SessionInvariant)
+  return { ctx, fiber }
+}
+
+describe('session-log invariants', () => {
+  it('keeps registration global when the companion is mounted under a scope', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(InvariantService)
+    let scopedCtx!: Context
+    await ctx.plugin(Object.assign((inner: Context) => {
+      scopedCtx = createScope(inner, {}).ctx
+    }, { inject: ['sessions', 'invariants'] }))
+    await scopedCtx.plugin(SessionInvariant)
+    const session = ctx.sessions.create(SessionId('global-under-scoped-invariants'))
+    expect(() => {
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    }).not.toThrow()
+  })
+
+  it('accepts a well-formed turn, step, and tool sequence', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    expect(() => {
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+      session.append('step/start', { turn: 1, step: 1 })
+      session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } })
+      session.append('assistant/message', {
+        provenance: { provider: 'mock', model: 'mock' },
+        turn: 1,
+        step: 1,
+        content: [{ type: 'tool-call', id: CallId('c1'), name: 'echo', arguments: '{}' }],
+      }, { surfaceOp: 'append' })
+      session.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' })
+      session.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [], isError: false }, { surfaceOp: 'append' })
+      session.append('step/end', { turn: 1, step: 1 })
+      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    }).not.toThrow()
+  })
+
+  it('does not advance committed trace state when a later dispatch listener vetoes', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create(SessionId('dispatch-veto-rollback'))
+    let veto = true
+    ctx.on('internal/dispatch', (_mode, name) => {
+      if (name !== 'session/event' || !veto) return
+      veto = false
+      throw new Error('later dispatch veto')
+    })
+    expect(() => session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })).toThrow('later dispatch veto')
+    expect(session.events).toEqual([])
+    expect(() => {
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    }).not.toThrow()
+  })
+
+  it('applies the committed transition after another postcommit observer throws', async () => {
+    const { ctx } = await setup()
+    const warnings: string[] = []
+    ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
+    const session = ctx.sessions.create(SessionId('postcommit-peer'))
+    ctx.on('session/event', () => { throw new Error('hostile observer') }, { prepend: true })
+    expect(() => {
+      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    }).not.toThrow()
+    expect(warnings).toHaveLength(2)
+  })
+
+  it('rejects non-monotonic event sequence numbers', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    ctx.emit(scopeTarget(session, undefined), 'session/event', session, {
+      type: 'turn/start',
+      seq: 0,
+      time: 1,
+      data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+    } as never)
+    expect(() => { ctx.emit(scopeTarget(session, undefined), 'session/event', session, {
+      type: 'turn/end',
+      seq: 0,
+      time: 2,
+      data: { turn: 1, reason: { kind: 'completed' } },
+    } as never) }).toThrow(/seq must strictly increase/)
+  })
+
+  it('enforces turn numbering and enclosure', async () => {
+    const first = await setup()
+    const open = first.ctx.sessions.create()
+    open.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(() => open.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }))
+      .toThrow(/turn 1 is still open/)
+    expect(() => open.append('turn/end', { turn: 2, reason: { kind: 'completed' } }))
+      .toThrow(/does not match open turn 1/)
+
+    const second = (await setup()).ctx.sessions.create()
+    second.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    second.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    expect(() => second.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } }))
+      .toThrow(/expected turn 2, got 3/)
+
+    const outside = (await setup()).ctx.sessions.create()
+    expect(() => outside.append('user/message', {
+      content: [{ type: 'text', text: 'hi' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })).toThrow(/outside any open turn/)
+    expect(() => outside.append('steering/message', {
+      turn: 1,
+      content: [{ type: 'text', text: 'go' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })).toThrow(/outside any open turn/)
+    // Merge-extensible session events use the same default enclosure branch.
+    const appendUnknown = outside.append.bind(outside) as (type: string, data: unknown) => unknown
+    expect(() => { appendUnknown('plugin/marker', {}) }).toThrow(/outside any open turn/)
+  })
+
+  it('enforces open-step identity and numbering', async () => {
+    const wrongTurn = (await setup()).ctx.sessions.create()
+    wrongTurn.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(() => wrongTurn.append('step/start', { turn: 2, step: 1 })).toThrow(/open turn is 1/)
+
+    const nested = (await setup()).ctx.sessions.create()
+    nested.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    nested.append('step/start', { turn: 1, step: 1 })
+    expect(() => nested.append('step/start', { turn: 1, step: 2 })).toThrow(/while step 1 is still open/)
+    expect(() => nested.append('turn/end', { turn: 1, reason: { kind: 'completed' } }))
+      .toThrow(/while step 1 is still open/)
+    expect(() => nested.append('step/end', { turn: 1, step: 2 })).toThrow(/open is turn 1\/step 1/)
+    expect(() => nested.append('assistant/message', {
+      provenance: { provider: 'mock', model: 'mock' },
+      turn: 1,
+      step: 2,
+      content: [],
+    }, { surfaceOp: 'append' })).toThrow(/open is turn 1\/step 1/)
+
+    const skipped = (await setup()).ctx.sessions.create()
+    skipped.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    skipped.append('step/start', { turn: 1, step: 1 })
+    skipped.append('step/end', { turn: 1, step: 1 })
+    expect(() => skipped.append('step/start', { turn: 1, step: 3 }))
+      .toThrow(/expected step 2 in turn 1, got 3/)
+  })
+
+  it('requires step-scoped stream and tool events to name the open step', async () => {
+    const chunk = (await setup()).ctx.sessions.create()
+    chunk.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(() => chunk.append('assistant/chunk', {
+      turn: 1,
+      step: 1,
+      chunk: { type: 'text-delta', index: 0, text: 'x' },
+    })).toThrow(/open is turn 1\/step null/)
+
+    const tool = (await setup()).ctx.sessions.create()
+    tool.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    tool.append('step/start', { turn: 1, step: 1 })
+    expect(() => tool.append('tool/result', {
+      turn: 1,
+      step: 1,
+      callId: CallId('ghost'),
+      content: [],
+      isError: false,
+    }, { surfaceOp: 'append' })).toThrow(/no prior tool\/call/)
+  })
+
+  it('allows interrupted repair results and unresolved calls at step end', async () => {
+    const repaired = (await setup()).ctx.sessions.create()
+    expect(() => {
+      repaired.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      repaired.append('step/start', { turn: 1, step: 1 })
+      repaired.append('tool/result', {
+        turn: 1,
+        step: 1,
+        callId: CallId('crashed'),
+        content: [],
+        isError: true,
+        error: { name: 'InterruptedError', code: 'interrupted' },
+      }, { surfaceOp: 'append' })
+      repaired.append('step/end', { turn: 1, step: 1 })
+      repaired.append('turn/end', { turn: 1, reason: { kind: 'interrupted' } })
+    }).not.toThrow()
+
+    const unresolved = (await setup()).ctx.sessions.create()
+    expect(() => {
+      unresolved.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+      unresolved.append('step/start', { turn: 1, step: 1 })
+      unresolved.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' })
+      unresolved.append('step/end', { turn: 1, step: 1 })
+      unresolved.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'boom' } })
+    }).not.toThrow()
+  })
+
+  it('does not let a result in a later step satisfy an earlier call', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
+    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' })
+    session.append('step/end', { turn: 1, step: 1 })
+    session.append('step/start', { turn: 1, step: 2 })
+    expect(() => session.append('tool/result', {
+      turn: 1,
+      step: 2,
+      callId: CallId('c1'),
+      content: [],
+      isError: false,
+    }, { surfaceOp: 'append' })).toThrow(/no prior tool\/call in this step/)
+  })
+
+  it('replays seeded sessions and tracks each session independently', async () => {
+    const { ctx } = await setup()
+    const badSeed = [
+      { type: 'turn/start' as const, seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
+      { type: 'turn/start' as const, seq: 1, time: 0, data: { turn: 2, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
+    ]
+    expect(() => ctx.sessions.create(undefined, { seed: badSeed })).toThrow(InvariantError)
+
+    const a = ctx.sessions.create(SessionId('a'))
+    const b = ctx.sessions.create(SessionId('b'))
+    a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(() => b.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }))
+      .not.toThrow()
+  })
+
+  it('rebuilds trace state for sessions that exist when the companion reloads', async () => {
+    const { ctx, fiber } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
+    await fiber.dispose()
+    await ctx.plugin(SessionInvariant)
+    expect(() => session.append('assistant/chunk', {
+      turn: 1,
+      step: 1,
+      chunk: { type: 'text-delta', index: 0, text: 'h' },
+    })).not.toThrow()
+    expect(() => session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }))
+      .toThrow(/turn 1 is still open/)
+  })
+
+  it('removes all listeners when the companion is disposed', async () => {
+    const { ctx, fiber } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    await fiber.dispose()
+    expect(() => session.append('turn/start', {
+      turn: 2,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })).not.toThrow()
+  })
+})
--- a/packages/core/session/tsconfig.json
+++ b/packages/core/session/tsconfig.json
@@ -22,6 +22,9 @@
    },
    {
      "path": "../../core/scope"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/core/session/tsdown.config.ts
+++ b/packages/core/session/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+  },
+])