fix(core): enforce agent-scoped ownership boundaries

packages/core/scope/src/index.ts

@@ -22,7 +22,7 @@
  * @module @deepseek-ai/dsh-scope
  */
 
-import type { Context } from 'cordis'
+import type { Context, Fiber } from 'cordis'
 import { Context as CordisContext } from 'cordis'
 
 /**
@@ -78,21 +78,30 @@ export interface Scope {
   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).
+   * registration disposer. Idempotent and always awaitable: repeat and racing
+   * calls share one completion even though the underlying Cordis disposer is
+   * single-shot and returns undefined after its first invocation.
    * After disposal the scoped context is inert — a further registration
    * through it throws Cordis's INACTIVE_EFFECT.
    * @returns for the call that initiates teardown: resolves when every
-   *   registration's disposer has settled. A repeat/racing call resolves
-   *   immediately WITHOUT awaiting the in-flight teardown (the underlying
-   *   Cordis disposer is single-shot) — a caller needing a shared quiescence
-   *   boundary across racing disposers keeps its own completion promise (the
-   *   agent factory's pattern).
+   *   registration's disposer has settled. Every repeat/racing call awaits
+   *   that same quiescence boundary, including when {@link rawDispose} claimed
+   *   the underlying single-shot Cordis disposer first.
    */
   dispose(): Promise<void>
 }
 
+/**
+ * Dispose a Cordis fiber and await its lifecycle inertia even when some other
+ * caller claimed the single-shot raw disposer first. `Fiber.dispose()` returns
+ * `undefined` on a repeat call, but the fiber's `inertia` remains the
+ * authoritative promise while its async unload is running.
+ */
+async function quiesceFiber(fiber: Fiber): Promise<void> {
+  await Promise.resolve(fiber.dispose())
+  while (fiber.inertia !== undefined) await fiber.inertia
+}
+
 /**
  * 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
@@ -127,21 +136,22 @@ 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)')
+  if ((typeof key !== 'object' && typeof key !== 'function') || key === null) {
+    throw new TypeError('createScope: key must be a non-null object or function (scope keys are identity-compared)')
   }
   const fiber = ctx.plugin(scope)
   const scoped: Context = fiber.ctx.extend({ [kScope]: key })
+  let disposing: Promise<void> | undefined
   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()),
+    // Memoize the public boundary and explicitly follow fiber inertia: the raw
+    // disposer must remain the exact Cordis function for ordered composition,
+    // so it cannot itself be wrapped to record a raw-first invocation.
+    dispose: () => (disposing ??= quiesceFiber(fiber)),
   }
 }
 
@@ -293,8 +303,10 @@ export interface ScopeHost {
   mint(key: ScopeKey): Scope
   /**
    * Dispose the host fiber and with it every scope minted through it.
-   * @returns resolves when all collected disposers have settled (first call;
-   *   a repeat call resolves immediately — single-shot, like Scope.dispose).
+   * Every racing/repeat caller observes the same completion, including when a
+   * child's raw disposer started before host disposal.
+   * @returns resolves when the host and every minted scope have reached
+   *   quiescence.
    */
   dispose(): Promise<void>
 }
@@ -334,8 +346,33 @@ export async function scopeHost(ctx: Context, services: string[]): Promise<Scope
     throw new Error(`scopeHost: service${missing.length === 1 ? '' : 's'} ${named} not available on this context — load the providing plugin(s) before minting scopes`)
   }
   const host = hostCtx
+  const scopes = new Set<Scope>()
+  let disposing: Promise<void> | undefined
+  const dispose = async (): Promise<void> => {
+    // Start every boundary before awaiting any one of them. A child whose raw
+    // disposer already ran is still followed through Scope.dispose(); a child
+    // the host unload claims first is followed through the same fiber inertia.
+    const tasks = [quiesceFiber(fiber), ...[...scopes].map(scope => scope.dispose())]
+    const results = await Promise.allSettled(tasks)
+    scopes.clear()
+    const errors = results.flatMap(result => result.status === 'rejected' ? [result.reason as unknown] : [])
+    if (errors.length === 1) throw errors[0]
+    if (errors.length > 1) throw new AggregateError(errors, 'scopeHost: disposal failed')
+  }
   return {
-    mint: (key: ScopeKey) => createScope(host, key),
-    dispose: () => Promise.resolve(fiber.dispose()),
+    mint: (key: ScopeKey) => {
+      const minted = createScope(host, key)
+      let disposing: Promise<void> | undefined
+      const tracked: Scope = {
+        ctx: minted.ctx,
+        // Preserve the exact Cordis identity: only the public shared boundary
+        // is wrapped to retire this child from the host's tracking set.
+        rawDispose: minted.rawDispose,
+        dispose: () => (disposing ??= minted.dispose().finally(() => { scopes.delete(tracked) })),
+      }
+      scopes.add(tracked)
+      return tracked
+    },
+    dispose: () => (disposing ??= dispose()),
   }
 }

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

@@ -30,14 +30,19 @@ async function mintScope(ctx: Context, key: object): Promise<Scope> {
 }
 
 describe('createScope', () => {
-  it('rejects a primitive key at runtime (identity-compared keys must be objects)', () => {
+  it('rejects primitive keys but accepts callable objects (matching ScopeKey)', async () => {
     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/)
+      expect(() => createScope(ctx, bad as ScopeKey)).toThrow(/must be a non-null object or function/)
     }
+
+    const callable = Object.assign(() => {}, { nameForTest: 'callable-key' })
+    const scope = await mintScope(ctx, callable)
+    expect(scopeOf(scope.ctx)).toBe(callable)
+    await scope.dispose()
   })
 
   it('tags the scoped context, readable through derivations (nearest tag wins)', async () => {
@@ -91,6 +96,29 @@ describe('createScope', () => {
     expect(() => scope.ctx.effect(() => () => {})).toThrow(/inactive context/)
   })
 
+  it('dispose() follows a rawDispose-first race through async quiescence', async () => {
+    const ctx = new Context()
+    const scope = await mintScope(ctx, { name: 'raw-first' })
+    const gate = Promise.withResolvers<undefined>()
+    let cleanupFinished = false
+    scope.ctx.effect(() => async () => {
+      await gate.promise
+      cleanupFinished = true
+    })
+
+    const raw = Promise.resolve(scope.rawDispose())
+    let publicSettled = false
+    const publicDispose = scope.dispose().then(() => { publicSettled = true })
+    await Promise.resolve()
+    expect(publicSettled).toBe(false)
+    expect(cleanupFinished).toBe(false)
+
+    gate.resolve(undefined)
+    await Promise.all([raw, publicDispose])
+    expect(cleanupFinished).toBe(true)
+    await expect(scope.dispose()).resolves.toBeUndefined()
+  })
+
   it('rawDispose is the exact cordis disposer: yielding it nests the scope at its position', async () => {
     const ctx = new Context()
     const order: string[] = []
@@ -287,6 +315,52 @@ describe('scopeHost', () => {
     expect(() => scope.ctx.effect(() => () => {})).toThrow(/inactive context/)
   })
 
+  it('dispose waits for a child whose raw disposer won the race', async () => {
+    const ctx = new Context()
+    ctx.provide('answers', { value: 42 })
+    const host = await scopeHost(ctx, ['answers'])
+    const scope = host.mint({ name: 'raw-first-child' })
+    const gate = Promise.withResolvers<undefined>()
+    let cleanupFinished = false
+    scope.ctx.effect(() => async () => {
+      await gate.promise
+      cleanupFinished = true
+    })
+
+    const raw = Promise.resolve(scope.rawDispose())
+    let hostSettled = false
+    const hostDispose = host.dispose().then(() => { hostSettled = true })
+    await Promise.resolve()
+    expect(hostSettled).toBe(false)
+
+    gate.resolve(undefined)
+    await Promise.all([raw, hostDispose])
+    expect(cleanupFinished).toBe(true)
+    await expect(host.dispose()).resolves.toBeUndefined()
+  })
+
+  it('reaches every child before surfacing one or multiple disposal failures', async () => {
+    const oneCtx = new Context()
+    oneCtx.provide('answers', { value: 42 })
+    const oneHost = await scopeHost(oneCtx, ['answers'])
+    const one = oneHost.mint({ name: 'one' })
+    one.dispose = () => Promise.reject(new Error('one failed'))
+    await expect(oneHost.dispose()).rejects.toThrow('one failed')
+
+    const manyCtx = new Context()
+    manyCtx.provide('answers', { value: 42 })
+    const manyHost = await scopeHost(manyCtx, ['answers'])
+    const a = manyHost.mint({ name: 'a' })
+    const b = manyHost.mint({ name: 'b' })
+    a.dispose = () => Promise.reject(new Error('a failed'))
+    b.dispose = () => Promise.reject(new Error('b failed'))
+    await expect(manyHost.dispose()).rejects.toMatchObject({
+      name: 'AggregateError',
+      message: 'scopeHost: disposal failed',
+      errors: [expect.objectContaining({ message: 'a failed' }), expect.objectContaining({ message: 'b failed' })],
+    })
+  })
+
   it('fails LOUD naming absent services instead of resolving as a silent no-op host', async () => {
     const ctx = new Context()
     await expect(scopeHost(ctx, ['tools', 'systemPrompt']))