fix(invariants): assert runtime relationships, not API shapes

packages/subagent/subagent/src/invariant.ts

@@ -1,30 +1,89 @@
-/** Package-owned runtime contract checks for `@deepseek-ai/dsh-subagent`. @module @deepseek-ai/dsh-subagent/invariant */
+/** Package-owned subagent registry and lifecycle invariants. @module @deepseek-ai/dsh-subagent/invariant */
 
 import type { Context } from 'cordis'
-import { observePluginInvariant, type InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { SubagentProvider } from './types.ts'
+import type { SubagentRunEndInfo, SubagentRunInfo } from './index.ts'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-subagent'
 
 /** Cordis companion plugin name. */
 export const name = 'subagent-invariant'
-/** Services required before the companion can register. */
+/** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** Install checks for this package's active plugin fibers. */
-const install: InvariantInstaller = (ctx, fail) => {
-  observePluginInvariant(ctx, fail, {
-    name: 'SubagentService',
-    effects: [
-      'ctx.provide("subagents")',
-    ],
-    services: [
-      'subagents',
-    ],
-  })
+/** Assert that a terminal lifecycle payload matches its start identity. */
+function validateRunEnd(start: SubagentRunInfo, end: SubagentRunEndInfo, fail: InvariantFailure): void {
+  if (start.provider !== end.provider || start.id !== end.id || start.local !== end.local) {
+    fail(`subagent/end identity diverges from subagent/start for run ${JSON.stringify(end.runId)}`)
+  }
 }
 
+/** Install provider-registry and start/end pairing checks. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  const providers = new Set(ctx.subagents.list())
+  const runs = new Map<string, SubagentRunInfo>()
+  const stagedProviders = new WeakSet<SubagentProvider>()
+  const stagedRemovals = new Set<string>()
+  const stagedStarts = new WeakSet<SubagentRunInfo>()
+  const stagedEnds = new WeakSet<SubagentRunEndInfo>()
+
+  ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName === 'subagent/provider-added') {
+      const provider = args[0] as SubagentProvider
+      if (provider.name.length === 0) fail('subagent provider names must be non-empty')
+      if (providers.has(provider.name)) fail(`subagent/provider-added repeated ${JSON.stringify(provider.name)}`)
+      stagedProviders.add(provider)
+      return
+    }
+    if (eventName === 'subagent/provider-removed') {
+      const providerName = args[0] as string
+      if (!providers.has(providerName)) fail(`subagent/provider-removed names unknown provider ${JSON.stringify(providerName)}`)
+      stagedRemovals.add(providerName)
+      return
+    }
+    if (eventName === 'subagent/start') {
+      const info = args[0] as SubagentRunInfo
+      if (!providers.has(info.provider)) fail(`subagent/start names inactive provider ${JSON.stringify(info.provider)}`)
+      if (String(info.runId).length === 0 || String(info.id).length === 0) {
+        fail('subagent/start runId and child id must be non-empty')
+      }
+      if (runs.has(info.runId)) fail(`subagent/start repeated run id ${JSON.stringify(info.runId)}`)
+      stagedStarts.add(info)
+      return
+    }
+    if (eventName !== 'subagent/end') return
+    const info = args[0] as SubagentRunEndInfo
+    const start = runs.get(info.runId)
+    if (start === undefined) fail(`subagent/end has no matching subagent/start for run ${JSON.stringify(info.runId)}`)
+    validateRunEnd(start, info, fail)
+    stagedEnds.add(info)
+  }, { global: true })
+
+  ctx.on('subagent/provider-added', (provider) => {
+    /* v8 ignore next -- internal/dispatch stages the same provider object */
+    if (!stagedProviders.delete(provider)) return
+    providers.add(provider.name)
+  }, { global: true })
+  ctx.on('subagent/provider-removed', (providerName) => {
+    /* v8 ignore next -- internal/dispatch stages the same provider name */
+    if (!stagedRemovals.delete(providerName)) return
+    providers.delete(providerName)
+  }, { global: true })
+  ctx.on('subagent/start', (info) => {
+    /* v8 ignore next -- internal/dispatch stages the same lifecycle object */
+    if (!stagedStarts.delete(info)) return
+    runs.set(info.runId, info)
+  }, { global: true })
+  ctx.on('subagent/end', (info) => {
+    /* v8 ignore next -- internal/dispatch stages the same lifecycle object */
+    if (!stagedEnds.delete(info)) return
+    runs.delete(info.runId)
+  }, { global: true })
+}, { inject: ['subagents'] })
+
 /**
- * Register this package's invariant companion.
+ * Register the subagent invariant companion.
  * @param ctx - Cordis context carrying the invariant service.
  * @returns the installed registration's disposer after setup succeeds.
  */

packages/subagent/subagent/tests/invariant.spec.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import SubagentService, { SubagentRunId } from '@deepseek-ai/dsh-subagent'
+import type {
+  SubagentProvider,
+  SubagentRunEndInfo,
+  SubagentRunInfo,
+} from '@deepseek-ai/dsh-subagent'
+import * as SubagentInvariant from '@deepseek-ai/dsh-subagent/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(SubagentInvariant)
+  return ctx
+}
+
+const provider = (name: string): SubagentProvider => ({
+  name,
+  capabilities: { outputSchema: false, depthLimit: false, toolFilter: false, persona: false },
+  inheritsParentContext: false,
+  start: async () => { throw new Error('not used') },
+})
+
+const start = (overrides: Partial<SubagentRunInfo> = {}): SubagentRunInfo => ({
+  runId: SubagentRunId('run-1'),
+  provider: 'mock',
+  id: SessionId('child-1'),
+  local: false,
+  ...overrides,
+})
+
+const end = (overrides: Partial<SubagentRunEndInfo> = {}): SubagentRunEndInfo => ({
+  ...start(),
+  stopReason: 'completed',
+  ...overrides,
+})
+
+function emitRun(ctx: Context, name: 'subagent/start', info: SubagentRunInfo): void
+function emitRun(ctx: Context, name: 'subagent/end', info: SubagentRunEndInfo): void
+function emitRun(ctx: Context, name: 'subagent/start' | 'subagent/end', info: SubagentRunInfo | SubagentRunEndInfo): void {
+  ctx.emit(scopeTarget(ctx.subagents, {}), name as 'subagent/start', info)
+}
+
+describe('subagent invariants', () => {
+  it('accepts provider and run lifecycle pairs', async () => {
+    const ctx = await setup()
+    const mock = provider('mock')
+    ctx.emit('subagent/provider-added', mock)
+    emitRun(ctx, 'subagent/start', start())
+    emitRun(ctx, 'subagent/end', end())
+    ctx.emit('subagent/provider-removed', 'mock')
+    ctx.emit('tools/change')
+  })
+
+  it('rejects malformed provider transitions', async () => {
+    const ctx = await setup()
+    expect(() => { ctx.emit('subagent/provider-added', provider('')) }).toThrow(/names must be non-empty/)
+    const mock = provider('mock')
+    ctx.emit('subagent/provider-added', mock)
+    expect(() => { ctx.emit('subagent/provider-added', mock) }).toThrow(/repeated "mock"/)
+    expect(() => { ctx.emit('subagent/provider-removed', 'missing') }).toThrow(/unknown provider/)
+  })
+
+  it('rejects malformed and unpaired run transitions', async () => {
+    const ctx = await setup()
+    expect(() => { emitRun(ctx, 'subagent/start', start()) }).toThrow(/inactive provider/)
+    ctx.emit('subagent/provider-added', provider('mock'))
+    expect(() => { emitRun(ctx, 'subagent/start', start({ runId: SubagentRunId('') })) })
+      .toThrow(/runId and child id must be non-empty/)
+    emitRun(ctx, 'subagent/start', start())
+    expect(() => { emitRun(ctx, 'subagent/start', start()) }).toThrow(/repeated run id/)
+    expect(() => { emitRun(ctx, 'subagent/end', end({ runId: SubagentRunId('missing') })) })
+      .toThrow(/no matching subagent\/start/)
+    expect(() => { emitRun(ctx, 'subagent/end', end({ id: SessionId('other') })) })
+      .toThrow(/identity diverges/)
+  })
+})