feat(invariants): add package-owned service seam

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.

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"
   }
 }

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))

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]
+}

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/)
+    }
+  })
+})

packages/core/scope/tsconfig.json

@@ -13,6 +13,9 @@
     },
     {
       "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
     }
   ]
 }

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'] },
+  },
+])