Merge origin/master into worktree/web-multimodal-image-input

# Conflicts: # docs/architecture.i18n.yaml # docs/architecture.md # docs/architecture.zh.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/llm-streaming.i18n.yaml # docs/event-producer-consumer.md # docs/module-graph.md # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # packages/client/connection/src/client/fixture.ts # packages/client/connection/tests/node-half.spec.ts # packages/client/ui-conversation/README.i18n.yaml # packages/client/ui-conversation/README.md # packages/client/ui-conversation/README.zh.md # packages/compact/compact-basic/README.i18n.yaml # packages/llm/llm/README.i18n.yaml # scripts/test-invariants.ts
2026-07-31 17:39:06 +08:00
parent 8b00482d7c 7e07d0179d
commit 481d3c7076
400 changed files with 79356 additions and 4154 deletions
--- a/scripts/test-invariants.ts
+++ b/scripts/test-invariants.ts
@@ -6,7 +6,7 @@
 */

 import { expect } from 'vitest'
-import { RegistryService } from 'cordis'
+import { FiberState, Inject, RegistryService } from 'cordis'
 import type { Context, Plugin } from 'cordis'
 import { AttachmentStore } from '@deepseek-ai/dsh-attachment'
 import type {
@@ -32,6 +32,9 @@ export interface TestInvariantCompanion {
  apply(ctx: Context): Promise<() => void>
 }

+/** Private service dependency that holds ordinary root plugins until invariant startup completes. */
+export const TEST_INVARIANT_READY_SERVICE = 'testInvariantReady'
+
 /**
 * Every package companion as a lazy loader keyed by glob path. Ordinary tests
 * load only their owner's module; the exhaustive topology test loads and
@@ -50,10 +53,12 @@ const MANUAL_INVARIANT_TEST_EXCEPTIONS = [

 interface InvariantHost {
  readonly byCallback: ReadonlyMap<unknown, PluginFiber>
+  readonly barrierOwners: WeakSet<Context['fiber']>
  readonly ready: Promise<void>
 }

 type PluginFiber = ReturnType<RegistryService['plugin']>
+type PluginCallback = Plugin.Function | Plugin.Constructor

 const hosts = new WeakMap<Context, InvariantHost>()
 // oxlint-disable-next-line typescript/unbound-method -- every call below supplies its RegistryService receiver explicitly.
@@ -68,14 +73,28 @@ RegistryService.prototype.plugin = function(plugin: Plugin, config?: unknown, ge
  const callback = this.resolve(plugin)
  const existing = callback === undefined ? undefined : host.byCallback.get(callback)
  if (existing !== undefined) {
-    return this.ctx === root ? joinInvariantStartup(existing, host.ready) : existing
+    return hasBarrierOwner(host, this.ctx) ? existing : joinInvariantStartup(existing, host.ready)
  }

-  const fiber = originalPlugin.call(this, plugin, config, getOuterStack)
-  // A root-level await is the test's composition boundary. Nested plugin
-  // fibers must not await their own companion parent through the global host.
-  if (this.ctx !== root) return fiber
-  return joinInvariantStartup(fiber, host.ready)
+  // Causal descendants of a gated target have already crossed the barrier.
+  // Host service and companion descendants also bypass it so their own startup
+  // cannot depend on the readiness they are responsible for providing.
+  if (hasBarrierOwner(host, this.ctx)) {
+    return originalPlugin.call(this, plugin, config, getOuterStack)
+  }
+  if (callback === undefined) {
+    return originalPlugin.call(this, plugin, config, getOuterStack)
+  }
+
+  const fiber = originalPlugin.call(
+    this,
+    withInvariantReadiness(plugin, callback as PluginCallback),
+    config,
+    getOuterStack,
+  )
+  const initiallyPending = fiber.ctx.fiber.state === FiberState.PENDING
+  host.barrierOwners.add(fiber.ctx.fiber)
+  return joinInvariantStartup(fiber, host.ready, initiallyPending)
 }

 /**
@@ -138,11 +157,13 @@ export function testInvariantCompanionPaths(testPath: string): string[] {

 function startInvariantHost(root: Context): InvariantHost {
  const byCallback = new Map<unknown, PluginFiber>()
+  const barrierOwners = new WeakSet<Context['fiber']>()
  const mount = (plugin: Plugin, config?: unknown): PluginFiber => {
    const fiber = originalPlugin.call(root.registry, plugin, config)
    const callback = root.registry.resolve(plugin)
    if (callback === undefined) throw new Error('test invariants: companion is not a valid Cordis plugin')
    byCallback.set(callback, fiber)
+    barrierOwners.add(fiber.ctx.fiber)
    return fiber
  }

@@ -156,11 +177,11 @@ function startInvariantHost(root: Context): InvariantHost {
  const serviceFiber = mount(InvariantService, { enabled: true })
  const testPath = expect.getState().testPath ?? ''
  const companionPaths = testInvariantCompanionPaths(testPath)
-  const ready = serviceFiber.await().then(async () => {
+  const ready = requireActive(serviceFiber, 'invariant service').then(async () => {
    const attachmentFiber = companionPaths.includes(ATTACHMENT_COMPANION)
      ? mount(TestAttachmentStore)
      : undefined
-    const companionFibers = await Promise.all(companionPaths.map(async (path) => {
+    const companions = await Promise.all(companionPaths.map(async (path) => {
      const load = testInvariantCompanions[path]
      if (load === undefined) {
        throw new Error(`test invariants: selected companion vanished at ${path}`)
@@ -169,23 +190,80 @@ function startInvariantHost(root: Context): InvariantHost {
      if (!companion.inject.includes('invariants')) {
        throw new Error(`test invariants: ${path} must inject the invariant service`)
      }
-      return mount(companion)
+      return { companion, path }
+    }))
+    const companionFibers = companions.map(({ companion, path }) => ({
+      fiber: mount(companion),
+      path,
    }))
    await Promise.all([
-      ...(attachmentFiber === undefined ? [] : [attachmentFiber.await()]),
-      ...companionFibers.map(fiber => fiber.await()),
+      ...(attachmentFiber === undefined
+        ? []
+        : [requireActive(attachmentFiber, 'test attachment store')]),
+      ...companionFibers.map(({ fiber, path }) => requireActive(fiber, path)),
    ])
+    root.provide(TEST_INVARIANT_READY_SERVICE, true)
  })
-  const host = { byCallback, ready }
+  const host = { byCallback, barrierOwners, ready }
  hosts.set(root, host)
  return host
 }

-function joinInvariantStartup(fiber: PluginFiber, invariantReady: Promise<void>): PluginFiber {
-  const readiness = fiber.await().then(async (loaded) => {
-    await invariantReady
-    return loaded
-  })
+function hasBarrierOwner(host: InvariantHost, ctx: Context): boolean {
+  let fiber = ctx.fiber
+  while (true) {
+    if (
+      host.barrierOwners.has(fiber)
+      && (fiber.state === FiberState.LOADING || fiber.state === FiberState.ACTIVE)
+    ) {
+      return true
+    }
+    const parent = fiber.parent.fiber
+    if (parent === fiber) return false
+    fiber = parent
+  }
+}
+
+async function requireActive(fiber: PluginFiber, label: string): Promise<void> {
+  await fiber.await()
+  if (fiber.state !== FiberState.ACTIVE) {
+    throw new Error(`test invariants: ${label} settled without becoming active`)
+  }
+}
+
+function withInvariantReadiness(plugin: Plugin, callback: PluginCallback): Plugin.Object {
+  return {
+    apply: callback as Plugin.Function,
+    inject: {
+      ...Inject.resolve(plugin.inject),
+      [TEST_INVARIANT_READY_SERVICE]: null,
+    },
+    ...(plugin.name === undefined ? {} : { name: plugin.name }),
+    ...(plugin.Config === undefined ? {} : { Config: plugin.Config }),
+    ...(plugin.provide === undefined ? {} : { provide: plugin.provide }),
+    ...(plugin.intercept === undefined ? {} : { intercept: plugin.intercept }),
+  }
+}
+
+function joinInvariantStartup(
+  fiber: PluginFiber,
+  invariantReady: Promise<void>,
+  disposeInitialFailure = false,
+): PluginFiber {
+  // RegistryService returns a thenable wrapper whose context still points to
+  // the raw Fiber. Calling inherited await() on the wrapper would return and
+  // assimilate that thenable, accidentally following later plugin startup.
+  const rawFiber = fiber.ctx.fiber
+  const initialized = disposeInitialFailure
+    ? rawFiber.await().catch(async (error: unknown) => {
+      // Config validation is the only failure recorded while a gated fiber
+      // is initially PENDING. Dispose it even if queued readiness publication
+      // changes its state before this rejection handler runs.
+      await rawFiber.dispose()
+      throw error
+    })
+    : Promise.resolve()
+  const readiness = initialized.then(() => invariantReady).then(() => rawFiber.await())
  const joined = Object.create(fiber) as PluginFiber
  joined.then = readiness.then.bind(readiness)
  return joined