feat(scope): dsh-scope scoped-context registration primitive

createScope(ctx, key) mints a tagged context over a synchronously-usable
no-op-plugin fiber (one fact drives visibility AND lifetime); scopeOf reads
the tag through the prototype chain; scopeTarget(base, key) builds the
scope-filtered dispatch carrier over cordis Context.filter, composing the
base's own filter, branded Scoped<T> and runtime-marked for the dev
invariants. Scope.rawDispose exposes the exact cordis disposer so a
composite effect can nest the scope's teardown at its yield position.

docs/config-catalog.md

@@ -815,4 +815,5 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
+- `@deepseek-ai/dsh-scope` ([`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts))
 - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))

docs/module-graph.md

@@ -19,6 +19,7 @@ flowchart TD
     pkg_agent["agent"]
     pkg_agent_core["agent-core"]
     pkg_agent_loop["agent-loop"]
+    pkg_scope["scope"]
     pkg_session["session"]
     pkg_system_prompt["system-prompt"]
     pkg_tools["tools"]
@@ -211,6 +212,7 @@ flowchart TD
 | Package | Group | Depends on |
 | --- | --- | --- |
 | [`brand`](../packages/util/brand) | `util` | — |
+| [`scope`](../packages/core/scope) | `core` | — |
 | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | — |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | — |
 | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — |

packages/core/scope/README.md

@@ -0,0 +1,20 @@
+# dsh-scope
+
+Scoped-context registration primitive. `createScope(ctx, key)` mints a Cordis context that TAGS everything registered through it with an opaque `ScopeKey` and OWNS those registrations' lifetime (one backing fiber drives both facts); `scopeOf(ctx)` reads the tag; `scopeTarget(base, key)` builds the dispatch carrier that makes an event scope-filtered — listeners registered through a scoped context fire only for their key's subject, while plain plugin listeners keep firing for every subject. The agent loop is the one scope minter today (one scope per live agent, key = the `Agent` object — the `Agent.ctx` contract in `dsh-agent`), but the mechanism is key-agnostic so packages below the agent layer (`dsh-session`, `dsh-system-prompt`) depend on it without a dependency cycle.
+
+## Public API
+
+- `createScope(ctx: Context, key: ScopeKey): Scope` Mint a scope under `ctx`'s fiber. Usable synchronously (effect collection is uid-gated; service resolution falls through to the minting plugin's dependency surface). Throws on a primitive key, or when `ctx`'s fiber is disposing (`INACTIVE_EFFECT`).
+- `Scope.ctx` The tagged context: registrations through it are scope-visible AND scope-lifetime. Derived contexts (an `extend`, a fiber mounted under it) inherit the tag; nested scopes shadow (nearest tag wins).
+- `Scope.rawDispose` The EXACT Cordis disposer for the backing fiber — a composite (generator) effect yields THIS function to nest the scope's teardown at that yield position (Cordis dedupes nested effects by function identity; yielding a wrapper leaves the scope disposing as a concurrent sibling).
+- `Scope.dispose(): Promise<void>` Idempotent, always-awaitable teardown of every registration made through the scope.
+- `scopeOf(ctx: Context): ScopeKey | undefined` The tag a context (or any context derived from it) carries; `undefined` = context-global.
+- `scopeTarget(base: T, key?: ScopeKey): Scoped<T>` Build the dispatch `thisArg` for a scope-filtered event: composes `base`'s own `Context.filter` with the scope predicate (untagged listener ⇒ admitted; tagged ⇒ admitted iff tag === key; `key === undefined` ⇒ untagged only). Listener `this` stays `base`-shaped. `{ global: true }` listeners bypass filtering (Cordis semantics).
+- `Scoped<T>` The compile-time carrier brand: scope-filtered events demand it as their `this` type, so dispatching with a bare subject is a compile error.
+- `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.
+
+## Design contract
+
+Ownership and visibility derive from ONE fact — which context a registration went through. An explicit `{ scope }` registration parameter could express "visible to X, disposed with Y", which is almost always a bug; the scoped context makes it unrepresentable. Rationale and alternatives: the agent-scoped-registration RFC (`docs/rfc/implemented/architecture/2026-07-08-agent-scoped-registration.md`, landing with this change set).
+
+Handing out a scoped context hands out the minting plugin's service-resolution capability (resolution walks the minting fiber's dependency chain, not the holder's) — mint scopes from a plugin whose `inject` surface is what scope holders should reach.

packages/core/scope/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@deepseek-ai/dsh-scope",
+  "description": "Scoped-context registration primitive (scope tags, scope-filtered event dispatch) for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/core/scope/src/index.ts

@@ -0,0 +1,237 @@
+/**
+ * Scoped-context primitive: mint a Cordis context that TAGS everything
+ * registered through it with an opaque {@link ScopeKey}, and dispatch events so
+ * listeners registered through such a context fire only for their key's
+ * subject. Scope-aware registries (`ctx.tools`, `ctx.systemPrompt`) read the
+ * tag via {@link scopeOf} to file a registration in the right layer; the agent
+ * loop is the one scope MINTER today (one scope per live agent, key = the
+ * `Agent` object — see `Agent.ctx` in `@deepseek-ai/dsh-agent`), but the
+ * mechanism is key-agnostic by design so packages below the agent layer
+ * (`dsh-session`, `dsh-system-prompt`) can depend on it without a dependency
+ * cycle.
+ *
+ * Ownership and visibility derive from ONE fact — which context a registration
+ * went through: the scope's fiber owns the disposal (a `ctx.effect()`/
+ * `ctx.on()`/registry call through the scoped context unwinds on
+ * {@link Scope.dispose}, because Cordis routes a service method's `this.ctx`
+ * to the ACCESSING context), and the tag decides who sees it. Splitting those
+ * two — an explicit `{ scope }` registration parameter — would let a caller
+ * express "visible to X, disposed with Y", which is almost always a bug; the
+ * scoped context makes it unrepresentable.
+ *
+ * @module @deepseek-ai/dsh-scope
+ */
+
+import type { Context } from 'cordis'
+import { Context as CordisContext, withProps } from 'cordis'
+
+/**
+ * The identity a scope is keyed by. Opaque and compared by object identity —
+ * never inspected. The harness convention: a live `Agent` is the key of its
+ * own scope, so seam vocabularies that already carry the agent
+ * (`ToolExecution.agent`, `AssembleContext.scope`) name the layer directly.
+ */
+export type ScopeKey = object
+
+/** The context tag {@link createScope} writes and {@link scopeOf} reads (module-private). */
+const kScope = Symbol('dsh.scope')
+
+/** The carrier mark {@link scopeTarget} writes and {@link carrierKeyOf} reads (module-private). */
+const kCarrier = Symbol('dsh.scope.carrier')
+
+declare const ScopedBrand: unique symbol
+
+/**
+ * A dispatch carrier built by {@link scopeTarget}: structurally the `base` it
+ * overlays, branded so scope-filtered events can DEMAND a carrier as their
+ * `this` type — passing a bare subject where a `Scoped<T>` is required is a
+ * compile error, which is what makes "forgot the carrier" unrepresentable at
+ * dispatch sites. The brand is compile-time only; {@link isScopeCarrier} is
+ * the runtime counterpart (used by the dev invariants).
+ */
+export type Scoped<T> = T & { readonly [ScopedBrand]: 'dsh.scope.carrier' }
+
+/**
+ * A minted scope: the tagged context to register through, plus the disposers
+ * that unwind every registration made through it.
+ */
+export interface Scope {
+  /**
+   * The scoped context. Registrations through it are tagged with the scope's
+   * key (scope-aware registries file them in that key's layer; `ctx.on`
+   * listeners fire only for dispatches targeted at that key) and owned by the
+   * scope's fiber (disposed together on {@link dispose}). Contexts DERIVED
+   * from it — an `extend`, a fiber mounted under it — inherit the tag through
+   * the prototype chain.
+   */
+  ctx: Context
+  /**
+   * The EXACT disposer Cordis registered on the minting fiber for the scope's
+   * backing fiber. A composite (generator) effect that owns the scope's
+   * position in an ordered teardown must yield THIS function: Cordis dedupes a
+   * nested effect out of the parent's concurrent disposal list by function
+   * identity, so yielding a wrapper would leave the scope disposing as an
+   * unordered sibling. Callers outside a composite effect use {@link dispose}.
+   * @returns the backing fiber's teardown promise (undefined on a repeat call
+   *   — Cordis effect disposers are single-shot).
+   */
+  rawDispose: () => Promise<void> | void
+  /**
+   * Unwind the scope: dispose the backing fiber, running every collected
+   * registration disposer. Idempotent and always awaitable — a repeat call
+   * resolves immediately (the underlying Cordis disposer is single-shot and
+   * returns undefined the second time; this wrapper Promise-normalizes it).
+   * After disposal the scoped context is inert — a further registration
+   * through it throws Cordis's INACTIVE_EFFECT.
+   * @returns resolves when every registration's disposer has settled.
+   */
+  dispose(): Promise<void>
+}
+
+/**
+ * The shared no-op plugin every scope fiber mounts: named so diagnostics read
+ * `scope` and shared so all scopes join ONE plugin runtime (Cordis deletes the
+ * runtime record when its last fiber disposes, so idle deployments carry no
+ * residue).
+ */
+function scope(): void {}
+
+/**
+ * Mint a registration scope for `key` under `ctx`.
+ *
+ * Mounts a runtime fiber (`ctx.plugin`) and tags a child of its context with
+ * `key`. The fiber is usable synchronously — Cordis activates it on a
+ * microtask, but effect collection is uid-gated (not state-gated) and service
+ * resolution falls through the pending fiber to the MINTING plugin's
+ * dependency surface, so a caller may register through {@link Scope.ctx} the
+ * moment this returns.
+ *
+ * Service resolution through the scoped context flows through the minting
+ * plugin's dependency chain (the fiber walk), regardless of what the eventual
+ * holder's own fiber injected — handing out the scoped context hands out that
+ * capability; see `Agent.ctx` in `@deepseek-ai/dsh-agent` for the harness's
+ * contract.
+ * @param ctx - the context to mount the scope under; its fiber must be active
+ *   (a disposing owner throws Cordis's INACTIVE_EFFECT), and its plugin's
+ *   `inject` surface is what the scoped context resolves services against.
+ * @param key - the scope's identity ({@link ScopeKey}); must be an object
+ *   (identity-compared), else this throws.
+ * @returns the tagged context plus its disposers ({@link Scope}).
+ */
+export function createScope(ctx: Context, key: ScopeKey): Scope {
+  // Runtime guard behind the ScopeKey type: callers outside the typechecker
+  // (yml-configured plugins, JS consumers) can still pass a primitive.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (typeof key !== 'object' || key === null) {
+    throw new TypeError('createScope: key must be an object (scope keys are identity-compared)')
+  }
+  const fiber = ctx.plugin(scope)
+  const scoped: Context = fiber.ctx.extend({ [kScope]: key })
+  return {
+    ctx: scoped,
+    // fiber.dispose IS the disposer Cordis pushed onto the minting fiber's
+    // disposable list — the identity a composite effect must yield (see
+    // Scope.rawDispose).
+    rawDispose: fiber.dispose,
+    // Promise.resolve-normalized: a cordis fiber's dispose returns undefined
+    // on a repeat call (the epoch is already cleared), and Scope.dispose
+    // promises an awaitable on every call.
+    dispose: () => Promise.resolve(fiber.dispose()),
+  }
+}
+
+/**
+ * Read the scope key a context is tagged with, or `undefined` for an untagged
+ * (context-global) context. Walks the prototype chain, so any context DERIVED
+ * from a scoped context — service shadows, `extend`s, fibers mounted under it
+ * — reads as that scope; with nested scopes the nearest tag wins.
+ * @param ctx - the context to inspect (typically a registry method's
+ *   `this.ctx`, i.e. the ACCESSING context).
+ * @returns the key given to {@link createScope}, or `undefined` when the
+ *   context is not derived from any scope.
+ */
+export function scopeOf(ctx: Context): ScopeKey | undefined {
+  // A plain (possibly proxied) property read: symbols bypass the Cordis
+  // context proxy's service resolution, and Reflect walks the prototype chain.
+  return (ctx as Context & { [kScope]?: ScopeKey })[kScope]
+}
+
+/**
+ * Build the dispatch carrier for a scope-filtered event: `base` overlaid with
+ * a `Context.filter` that admits a listener iff
+ *
+ * - its registering context is UNTAGGED (a context-global listener — the
+ *   compatibility default: plain plugin listeners see every subject), or
+ * - its tag IS `key` (a scoped listener seeing exactly its own subject),
+ *
+ * AND `base`'s own filter (a Cordis `Service`'s isolation check) also admits
+ * it. Dispatching with `key === undefined` — a subject-less dispatch, e.g. a
+ * tool call with no calling agent or a bare (agent-less) session's events —
+ * admits only untagged listeners: a scoped listener never fires for someone
+ * else's (or nobody's) subject. Listeners registered `{ global: true }`
+ * bypass all filtering (Cordis semantics).
+ *
+ * Use it as the `thisArg` of the dispatch:
+ * `ctx.waterfall(scopeTarget(this, exec.agent), 'tools/pre-execute', …)`. The
+ * carrier is a proxy over `base` — listener `this` stays `base`-shaped, but
+ * identity-comparing `this` against the subject is not supported; the subject
+ * always travels in the event's arguments. The returned carrier is branded
+ * {@link Scoped} and runtime-marked ({@link isScopeCarrier} /
+ * {@link carrierKeyOf}) so both the type system and the dev invariants can
+ * tell a carrier from a bare subject.
+ * @param base - the object the event is dispatched on behalf of (the owning
+ *   service, or the subject agent itself); its own `Context.filter` is
+ *   preserved and composed.
+ * @param key - the subject's scope key, or `undefined` for a subject-less
+ *   dispatch.
+ * @returns the carrier to pass as the dispatch `thisArg`.
+ */
+export function scopeTarget<T extends object>(base: T, key: ScopeKey | undefined): Scoped<T> {
+  const baseFilter = (base as { [CordisContext.filter]?: (ctx: Context) => boolean })[CordisContext.filter]
+  const filter = (ctx: Context): boolean => {
+    if (baseFilter && !baseFilter.call(base, ctx)) return false
+    const tag = scopeOf(ctx)
+    return tag === undefined || tag === key
+  }
+  // withProps overlays own-property reads; the symbol-keyed props have no
+  // structural overlap with T. withProps is typed `any` upstream (a generic
+  // proxy helper); the carrier is structurally the same T it overlays plus
+  // the compile-time brand, so pin the type via the return annotation.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  return withProps(base, {
+    [CordisContext.filter]: filter,
+    [kCarrier]: { key },
+  })
+}
+
+/**
+ * Whether `value` is a carrier built by {@link scopeTarget} — the runtime
+ * counterpart of the {@link Scoped} brand, used by the dev invariants to
+ * assert that a scope-filtered event was dispatched with a carrier and not a
+ * bare subject.
+ * @param value - the dispatch `thisArg` to test.
+ * @returns true iff `value` came from {@link scopeTarget}.
+ */
+export function isScopeCarrier(value: unknown): value is Scoped<object> {
+  if (typeof value !== 'object' || value === null) return false
+  // A property READ, not an `in` check: withProps overlays props via get/set
+  // traps only (no `has` trap), so `kCarrier in carrier` would fall through to
+  // the wrapped base and always answer false.
+  return (value as { [kCarrier]?: { key: ScopeKey | undefined } })[kCarrier] !== undefined
+}
+
+/**
+ * The scope key a carrier was built for — `undefined` for a subject-less
+ * carrier, and also `undefined` for a non-carrier (pair with
+ * {@link isScopeCarrier} when the distinction matters). The dev invariants
+ * use it to assert the carrier's key IS the subject the event's arguments
+ * name.
+ * @param value - the dispatch `thisArg` to read.
+ * @returns the `key` given to {@link scopeTarget}, or `undefined`.
+ */
+export function carrierKeyOf(value: unknown): ScopeKey | undefined {
+  if (!isScopeCarrier(value)) return undefined
+  // Optional-prop cast: the guard proves the mark is present at runtime, but
+  // the Scoped<> brand carries no structural kCarrier member to narrow from.
+  return (value as { [kCarrier]?: { key: ScopeKey | undefined } })[kCarrier]?.key
+}

packages/core/scope/tests/scope.spec.ts

@@ -0,0 +1,209 @@
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { Context } from 'cordis'
+import { carrierKeyOf, createScope, isScopeCarrier, scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope'
+import type { Scope, ScopeKey, Scoped } from '@deepseek-ai/dsh-scope'
+
+declare module 'cordis' {
+  interface Events {
+    /**
+     * Test-only event for exercising scope-filtered dispatch.
+     * @param value - opaque payload recorded by listeners.
+     * @mode emit
+     */
+    'scope-test/ping'(value: string): void
+    /**
+     * Test-only waterfall for exercising carrier `this` shape.
+     * @param value - seed value listeners may wrap.
+     * @mode waterfall
+     */
+    'scope-test/echo'(value: string, next: () => string): string
+  }
+}
+
+/** Mount a host plugin and mint a scope inside it, returning both. */
+async function mintScope(ctx: Context, key: object): Promise<Scope> {
+  let scope!: Scope
+  await ctx.plugin((inner: Context) => {
+    scope = createScope(inner, key)
+  })
+  return scope
+}
+
+describe('createScope', () => {
+  it('rejects a primitive key at runtime (identity-compared keys must be objects)', () => {
+    const ctx = new Context()
+    // Typed through `unknown` so the ScopeKey type cannot argue the assertion
+    // away: this test exercises exactly the callers the typechecker misses.
+    const badKeys: unknown[] = ['k', null]
+    for (const bad of badKeys) {
+      expect(() => createScope(ctx, bad as ScopeKey)).toThrow(/must be an object/)
+    }
+  })
+
+  it('tags the scoped context, readable through derivations (nearest tag wins)', async () => {
+    const ctx = new Context()
+    const key = { name: 'a' }
+    const inner = { name: 'a.inner' }
+    const scope = await mintScope(ctx, key)
+
+    expect(scopeOf(scope.ctx)).toBe(key)
+    // An extend of the scoped context inherits the tag through the prototype chain.
+    expect(scopeOf(scope.ctx.extend({}))).toBe(key)
+    // A plain context carries no tag.
+    expect(scopeOf(ctx)).toBeUndefined()
+    // A fiber mounted UNDER the scoped context reads as that scope…
+    let mountedCtx!: Context
+    await scope.ctx.plugin((c: Context) => { mountedCtx = c })
+    expect(scopeOf(mountedCtx)).toBe(key)
+    // …and a nested scope shadows the outer tag (nearest wins).
+    const nested = createScope(scope.ctx, inner)
+    expect(scopeOf(nested.ctx)).toBe(inner)
+  })
+
+  it('is usable synchronously: registrations land before the fiber activates', async () => {
+    const ctx = new Context()
+    const events: string[] = []
+    await ctx.plugin((inner: Context) => {
+      const scope = createScope(inner, { name: 'sync' })
+      // Same tick as createScope — no await between mint and use.
+      scope.ctx.effect(() => () => void events.push('effect-disposed'))
+      scope.ctx.on('scope-test/ping', value => void events.push(`heard:${value}`))
+      events.push('registered')
+    })
+    ctx.emit(scopeTarget(ctx, undefined), 'scope-test/ping', 'nobody')
+    expect(events).toEqual(['registered'])
+  })
+
+  it('dispose() unwinds registrations, is idempotent, and inerts the context', async () => {
+    const ctx = new Context()
+    const scope = await mintScope(ctx, { name: 'd' })
+    const order: string[] = []
+    scope.ctx.effect(() => () => void order.push('a'))
+    scope.ctx.effect(() => () => void order.push('b'))
+
+    await scope.dispose()
+    expect(order).toEqual(['b', 'a']) // LIFO within the scope fiber
+
+    // Repeat dispose: the underlying cordis disposer returns undefined; the
+    // wrapper still resolves.
+    await expect(scope.dispose()).resolves.toBeUndefined()
+    // Registration through a disposed scope throws INACTIVE_EFFECT.
+    expect(() => scope.ctx.effect(() => () => {})).toThrow(/inactive context/)
+  })
+
+  it('rawDispose is the exact cordis disposer: yielding it nests the scope at its position', async () => {
+    const ctx = new Context()
+    const order: string[] = []
+    let composite!: () => Promise<void> | void
+    await ctx.plugin((inner: Context) => {
+      composite = inner.effect(function* () {
+        yield () => void order.push('outermost') // disposed LAST
+        const scope = createScope(inner, { name: 'nested' })
+        scope.ctx.effect(() => () => void order.push('scope-registration'))
+        yield scope.rawDispose // disposed SECOND — nested by identity
+        yield () => void order.push('innermost') // disposed FIRST
+      })
+    })
+    await composite()
+    // The scope disposed exactly at its yield position (between the two
+    // neighbours), not as a concurrent sibling of the composite.
+    expect(order).toEqual(['innermost', 'scope-registration', 'outermost'])
+  })
+})
+
+describe('scopeTarget dispatch filtering', () => {
+  it('scoped listeners hear only their key; untagged listeners hear everything', async () => {
+    const ctx = new Context()
+    const keyA = { name: 'A' }
+    const keyB = { name: 'B' }
+    const scopeA = await mintScope(ctx, keyA)
+    const scopeB = await mintScope(ctx, keyB)
+
+    const heard: string[] = []
+    ctx.on('scope-test/ping', value => void heard.push(`global:${value}`))
+    scopeA.ctx.on('scope-test/ping', value => void heard.push(`A:${value}`))
+    scopeB.ctx.on('scope-test/ping', value => void heard.push(`B:${value}`))
+
+    ctx.emit(scopeTarget(ctx, keyA), 'scope-test/ping', 'to-A')
+    ctx.emit(scopeTarget(ctx, keyB), 'scope-test/ping', 'to-B')
+    ctx.emit(scopeTarget(ctx, undefined), 'scope-test/ping', 'to-nobody')
+
+    expect(heard).toEqual([
+      'global:to-A', 'A:to-A',
+      'global:to-B', 'B:to-B',
+      'global:to-nobody',
+    ])
+  })
+
+  it('{ global: true } listeners bypass scope filtering entirely', async () => {
+    const ctx = new Context()
+    const keyA = { name: 'A' }
+    const scopeA = await mintScope(ctx, keyA)
+    const heard: string[] = []
+    scopeA.ctx.on('scope-test/ping', value => void heard.push(`escape:${value}`), { global: true })
+
+    ctx.emit(scopeTarget(ctx, { name: 'other' }), 'scope-test/ping', 'foreign')
+    ctx.emit(scopeTarget(ctx, undefined), 'scope-test/ping', 'nobody')
+    expect(heard).toEqual(['escape:foreign', 'escape:nobody'])
+  })
+
+  it("composes the base's own Context.filter (a rejecting base filter wins)", async () => {
+    const ctx = new Context()
+    const keyA = { name: 'A' }
+    const scopeA = await mintScope(ctx, keyA)
+    const heard: string[] = []
+    ctx.on('scope-test/ping', value => void heard.push(`global:${value}`))
+    scopeA.ctx.on('scope-test/ping', value => void heard.push(`A:${value}`))
+
+    // A base whose own filter rejects every listener context: nothing fires,
+    // scoped or not — the scope predicate never overrides the base's veto.
+    const vetoBase = { [Context.filter]: () => false }
+    ctx.emit(scopeTarget(vetoBase, keyA), 'scope-test/ping', 'vetoed')
+    expect(heard).toEqual([])
+
+    // A base whose filter accepts delegates to the scope predicate.
+    const openBase = { [Context.filter]: () => true }
+    ctx.emit(scopeTarget(openBase, keyA), 'scope-test/ping', 'open')
+    expect(heard).toEqual(['global:open', 'A:open'])
+  })
+
+  it('keeps listener `this` base-shaped through the carrier (waterfall)', async () => {
+    const ctx = new Context()
+    const base = { label: 'the-base' }
+    let seenLabel: string | undefined
+    ctx.on('scope-test/echo', function (this: { label: string }, value, next) {
+      seenLabel = this.label
+      return `${next()}+${value}`
+    })
+    const result = ctx.waterfall(scopeTarget(base, undefined), 'scope-test/echo', 'v', () => 'seed')
+    expect(result).toBe('seed+v')
+    expect(seenLabel).toBe('the-base')
+  })
+})
+
+describe('carrier marks', () => {
+  it('isScopeCarrier / carrierKeyOf distinguish carriers, keys, and bare subjects', () => {
+    const base = { name: 'base' }
+    const key = { name: 'key' }
+    const keyed = scopeTarget(base, key)
+    const subjectless = scopeTarget(base, undefined)
+
+    expect(isScopeCarrier(keyed)).toBe(true)
+    expect(carrierKeyOf(keyed)).toBe(key)
+    expect(isScopeCarrier(subjectless)).toBe(true)
+    expect(carrierKeyOf(subjectless)).toBeUndefined()
+
+    expect(isScopeCarrier(base)).toBe(false)
+    expect(carrierKeyOf(base)).toBeUndefined()
+    expect(isScopeCarrier(null)).toBe(false)
+    expect(isScopeCarrier('x')).toBe(false)
+  })
+
+  it('brands the carrier type (compile-time)', () => {
+    const base = { name: 'base' }
+    const carrier = scopeTarget(base, undefined)
+    expectTypeOf(carrier).toExtend<Scoped<{ name: string }>>()
+    // A bare subject is NOT assignable where a carrier is demanded.
+    expectTypeOf(base).not.toExtend<Scoped<{ name: string }>>()
+  })
+})

packages/core/scope/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    }
+  ]
+}

pnpm-lock.yaml

@@ -264,6 +264,12 @@ importers:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
 
+  packages/core/scope:
+    devDependencies:
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
   packages/core/session:
     devDependencies:
       '@deepseek-ai/dsh-brand':

tsconfig.build.json

@@ -13,6 +13,7 @@
     { "path": "./packages/util/brand" },
     { "path": "./packages/llm/llm" },
     { "path": "./packages/core/session" },
+    { "path": "./packages/core/scope" },
     { "path": "./packages/session-persistence/session-persistence" },
     { "path": "./packages/session-persistence/session-persistence-jsonl" },
     { "path": "./packages/session-persistence/session-persistence-sqlite" },

tsconfig.json

@@ -24,6 +24,7 @@
     { "path": "./packages/util/brand" },
     { "path": "./packages/llm/llm" },
     { "path": "./packages/core/session" },
+    { "path": "./packages/core/scope" },
     { "path": "./packages/session-persistence/session-persistence" },
     { "path": "./packages/session-persistence/session-persistence-jsonl" },
     { "path": "./packages/session-persistence/session-persistence-sqlite" },