fix(vnext): enforce exact disposal hooks

Author: Light2Dark

docs/adr/0005-parser-independent-relation-completion.md

@@ -488,7 +488,8 @@ The combined search coordinator also installs one package-owned disposal
 target. Epoch self-quarantine makes the outer coordinator inert before
 subscription cleanup continues, so search work cannot outlive its epoch
 authority. The target is receiver-free, invoked at most once, and its failure
-cannot reopen disposal.
+cannot reopen disposal. It is synchronously exact-return and must return
+`undefined`; any other runtime result is detached and rejection-drained.
 
 A search that discovers a higher epoch supersedes itself instead of publishing
 against its older captured revision. Pages and cache entries from different

src/vnext/__tests__/relation-catalog-epoch-coordinator.test.ts

@@ -236,7 +236,7 @@ describe("catalog epoch coordinator construction and membership", () => {
     expect(reads).toBe(0);
   });
 
-  it("validates and invokes the package disposal target exactly once", () => {
+  it("validates, drains, and invokes the package disposal target exactly once", async () => {
     expect(
       Reflect.apply(createSqlCatalogEpochCoordinator, undefined, [
         capturedProvider(),
@@ -266,6 +266,26 @@ describe("catalog epoch coordinator construction and membership", () => {
       created.coordinator.dispose();
     }).not.toThrow();
     expect(disposalCalls).toBe(1);
+
+    const invalidReturn = Promise.reject(
+      new Error("invalid async package disposal"),
+    );
+    const withInvalidReturn = Reflect.apply(
+      createSqlCatalogEpochCoordinator,
+      undefined,
+      [
+        capturedProvider(),
+        undefined,
+        () => invalidReturn,
+      ],
+    );
+    expect(withInvalidReturn.status).toBe("created");
+    if (withInvalidReturn.status !== "created") {
+      throw new Error("Expected a coordinator fixture");
+    }
+    withInvalidReturn.coordinator.dispose();
+    await Promise.resolve();
+    await Promise.resolve();
   });
 
   it("validates exact bounded well-formed scopes without raw errors", () => {

src/vnext/relation-catalog-epoch-coordinator.ts

@@ -158,7 +158,7 @@ interface CoordinatorState {
   readonly commands: EpochCommand[];
   readonly deferredCleanup: Set<SubscriptionState>;
   readonly memberships: Set<MembershipState>;
-  onDispose: ((this: void) => void) | null;
+  onDispose: ((this: void) => undefined) | null;
   prepareEpochTransition: Function | null;
   readonly providerId: string;
   readonly scopes: Map<string, ScopeEntry>;
@@ -1277,7 +1277,10 @@ function disposeCoordinator(state: CoordinatorState): void {
   }
   if (onDispose) {
     try {
-      Reflect.apply(onDispose, undefined, []);
+      const result = Reflect.apply(onDispose, undefined, []);
+      if (result !== undefined) {
+        drainDetachedSettlement(result);
+      }
     } catch {
       // Disposal remains authoritative if its package owner fails.
     }
@@ -1316,7 +1319,7 @@ function createCoordinatorHandle(
 export function createSqlCatalogEpochCoordinator(
   capturedProvider: unknown,
   prepareEpochTransition?: SqlCatalogEpochTransitionTarget,
-  onDispose?: (this: void) => void,
+  onDispose?: (this: void) => undefined,
 ): SqlCatalogEpochCoordinatorResult {
   const provider = resolveSqlRelationCatalogProvider(
     capturedProvider,

src/vnext/relation-catalog-search-work.ts

@@ -1835,8 +1835,9 @@ export function createSqlCatalogSearchWorkCoordinator(
     provider,
     (scope): (() => undefined) | null =>
       state ? prepareTransition(state, scope) : null,
-    (): void => {
+    (): undefined => {
       if (state) disposeCoordinatorState(state);
+      return undefined;
     },
   );
   if (epochResult.status !== "created") {

test/vnext-types/relation-catalog-search-work.test-d.ts

@@ -5,6 +5,9 @@ import type {
 import type {
   SqlCatalogRevisionTarget,
 } from "../../src/vnext/relation-catalog-epoch-coordinator.js";
+import {
+  createSqlCatalogEpochCoordinator,
+} from "../../src/vnext/relation-catalog-epoch-coordinator.js";
 import type {
   SqlCatalogSearchWorkCoordinator,
   SqlCatalogSearchWorkInput,
@@ -94,7 +97,6 @@ const invalidRequestReceiver: SqlCatalogSearchWorkOwner["request"] =
 const receiverDependentPrepareOwner = function (
   this: { readonly active: boolean },
   _scope: unknown,
-  _dialectId: unknown,
   _dialect: unknown,
   _target: SqlCatalogRevisionTarget,
 ): SqlCatalogSearchWorkOwnerResult {
@@ -105,6 +107,15 @@ const receiverDependentPrepareOwner = function (
 const invalidPrepareOwnerReceiver: SqlCatalogSearchWorkCoordinator["prepareOwner"] =
   receiverDependentPrepareOwner;
 
+const asyncDisposalTarget = async (): Promise<void> => {};
+type EpochDisposalTarget = NonNullable<
+  Parameters<typeof createSqlCatalogEpochCoordinator>[2]
+>;
+// @ts-expect-error package disposal targets are synchronously exact-undefined
+const invalidAsyncDisposalTarget: EpochDisposalTarget =
+  asyncDisposalTarget;
+void invalidAsyncDisposalTarget;
+
 const receiverDependentActivate = function (
   this: { readonly active: boolean },
 ): ReturnType<SqlCatalogSearchWorkOwner["activate"]> {