fix(runtime): preserve provider generation context

[Upd4ting]

Summary

• capture and restore the complete provider ModuleExecutionContext for async and registering callbacks, including replay and unregister paths
• key automatic proxy, registration, and event cleanup by explicit owner generation while preserving the existing module-ID lifecycle event
• publish provider selection metadata through InterfaceConnection and enforce runtime protocol v3 across physical package copies
• add source-level and packed-package consumer regressions for provider context, generations, cross-copy behavior, and metadata

This supplies the minimal public interface-core contract needed by AntelopeJS/antelopejs#101 without including any core changes.

Public contract

ModuleExecutionContext adds optional owner, a unique lifecycle generation ID:

interface ModuleExecutionContext {
  module: string;
  owner?: string;
  provider?: string;
  providerRoutes?: Readonly<Record<string, string>>;
}

A loader that can overlap an old module instance with its replacement should assign a distinct owner to each generation and emit the existing Events.ModuleDestroyed(moduleId) event inside that generation's RunWithModuleContext. Without owner, behavior remains module-scoped for compatibility.

InterfaceConnection is now exported from the package root and includes:

interface InterfaceConnection {
  id?: string;
  path: string;
  provider: string;
  selected: boolean;
}

Proxy attachments continue to return generation-guarded leases. Provider callbacks now execute under the context captured at attachment, across nested calls and awaits. Invocation after owner invalidation fails with ModuleContextInvalidatedError rather than running stale code.

Compatibility and migration

• Direct single-provider use remains unchanged; owner is optional and defaults to module.
• The ModuleDestroyed event payload remains the module ID.
• Existing split onRegister / onUnregister attachment remains supported, including manual routes.
• Runtime protocol increases from 2 to 3 because older and newer copies cannot safely share the same global runtime shape. Mixed versions in one Node realm fail immediately with a clear incompatibility error rather than corrupting shared state.
• Anonymous proxy identity binding is intentionally not added: package-consumer coverage after proxy canonicalization does not demonstrate a remaining need.

Recommended release: 0.0.11, subject to maintainers confirming the current release sequence.

Verification

• corepack pnpm install --frozen-lockfile
• corepack pnpm run lint
• corepack pnpm run build
• corepack pnpm dlx @antelopejs/core module test . — 71 passing
• corepack pnpm run test:package
• git diff --check

The package-consumer test builds and packs the real tarball, installs it in an isolated project, executes the provider-context/generation/metadata contract, and compiles the public types. The standalone explanatory HTML is a review artifact and is not included in the package: https://t-03gpgyh60w6e7a0062f1i9lal-p28351.onamp.dev/interface-core-provider-context.html

Greptile Summary

The PR preserves complete provider execution context across asynchronous and registering callbacks while introducing generation-specific ownership and cleanup.

• Adds owner-generation tracking to module contexts, registrations, events, and callback leases.
• Exposes provider-selection metadata through InterfaceConnection and advances the shared runtime protocol to version 3.
• Adds source-level and packed-package regression coverage for context propagation, generation cleanup, metadata, and cross-copy runtime behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/internal.ts	Introduces owner-generation context tokens, context capture and restoration helpers, richer connection metadata, and runtime protocol version 3.
src/modules.ts	Resolves lifecycle cleanup through the active owner generation while retaining the module-ID event payload.
src/proxies.ts	Captures provider contexts, tracks registrations and events by owner, and independently preserves and cleans split registering callbacks.
src/tests/generation-cleanup.test.ts	Covers overlapping generations, both split-callback attachment orders, and owner-specific registration and event cleanup.
src/tests/provider-context.test.ts	Verifies provider context restoration across awaits, replay, direct operations, nested calls, and invalidation.
test/package-consumer.mjs	Validates the packaged runtime and public type contracts from an isolated consumer project.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Provider attaches callback] --> B[Capture module context and owner]
  B --> C[Create generation-guarded attachment lease]
  C --> D[Consumer invokes proxy]
  D --> E[Restore captured provider context]
  E --> F[Execute callback across nested calls and awaits]
  G[ModuleDestroyed within owner context] --> H[Invalidate owner token]
  H --> I[Detach only matching owner-generation leases]

Loading

_{Reviews (3): Last reviewed commit: "address greptile review feedback (greplo..." | Re-trigger Greptile}

[Upd4ting]

@greptile review

[Upd4ting]

@greptile review

[Upd4ting]

@greptile review