@antelopejs/interface-core 0.2.3 → 0.2.5

package/dist/tests/ownership-call-chain.test.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const modules_1 = require("../modules");
+const __1 = require("..");
+function inModule(module, owner, callback) {
+    return (0, modules_1.RunWithModuleContext)({ module, owner }, callback);
+}
+function destroy(module, owner) {
+    inModule(module, owner, () => modules_1.Events.ModuleDestroyed.emit(module));
+}
+function attachRegistry(proxy, entries, module, owner) {
+    inModule(module, owner, () => proxy.onHandlers((id) => entries.add(id), (id) => entries.delete(id)));
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}
+function outcomeOf(promise) {
+    return promise.then(() => "resolved", (error) => error);
+}
+describe("call chain: a module serving a call owns what it registers", () => {
+    it("keeps a registration made by B's provider when A is destroyed, and drops it with B", async () => {
+        const b = new __1.AsyncProxy();
+        const c = new __1.RegisteringProxy();
+        const entries = new Set();
+        attachRegistry(c, entries, "c", "c#1");
+        inModule("b", "b#1", () => b.onCall(() => c.register("from-b")));
+        await inModule("a", "a#1", () => b.call());
+        destroy("a", "a#1");
+        (0, chai_1.expect)([...entries]).to.deep.equal(["from-b"]);
+        destroy("b", "b#1");
+        (0, chai_1.expect)([...entries]).to.deep.equal([]);
+    });
+    it("forwards A's registration through B, replays it to B's next generation, and removes it with A", () => {
+        const b = new __1.RegisteringProxy();
+        const c = new __1.RegisteringProxy();
+        const entries = new Set();
+        attachRegistry(c, entries, "c", "c#2");
+        const attachForwarder = (owner) => inModule("b", owner, () => b.onHandlers((id) => c.register(`c:${id}`), (id) => c.unregister(`c:${id}`)));
+        attachForwarder("b#2");
+        inModule("a", "a#2", () => b.register("x"));
+        (0, chai_1.expect)([...entries]).to.deep.equal(["c:x"]);
+        destroy("b", "b#2");
+        (0, chai_1.expect)([...entries]).to.deep.equal([]);
+        attachForwarder("b#3");
+        (0, chai_1.expect)([...entries]).to.deep.equal(["c:x"]);
+        destroy("a", "a#2");
+        (0, chai_1.expect)([...entries]).to.deep.equal([]);
+    });
+});
+describe("call chain: queued calls", () => {
+    it("runs a call queued before the provider attached in the provider's context", async () => {
+        const proxy = new __1.AsyncProxy();
+        const pending = inModule("a", "a#3", () => proxy.call());
+        inModule("b", "b#4", () => proxy.onCall(() => (0, __1.GetResponsibleModule)()));
+        (0, chai_1.expect)(await pending).to.equal("b");
+    });
+    it("rejects a queued call whose caller was destroyed before the provider attached", async () => {
+        const proxy = new __1.AsyncProxy();
+        let served = 0;
+        const pending = outcomeOf(inModule("a", "a#4", () => proxy.call()));
+        destroy("a", "a#4");
+        inModule("b", "b#5", () => proxy.onCall(() => {
+            served += 1;
+            return "served";
+        }));
+        (0, chai_1.expect)(await pending).to.be.instanceOf(__1.ModuleContextInvalidatedError);
+        (0, chai_1.expect)(served).to.equal(0);
+    });
+});
+describe("call chain: context at each crossing", () => {
+    it("runs a provider callback in the provider's context, across an await", async () => {
+        const proxy = new __1.AsyncProxy();
+        inModule("b", "b#6", () => proxy.onCall(async () => {
+            const before = (0, __1.GetResponsibleModule)();
+            await Promise.resolve();
+            return [before, (0, __1.GetResponsibleModule)()];
+        }));
+        const seen = await inModule("a", "a#5", () => proxy.call());
+        (0, chai_1.expect)(seen).to.deep.equal(["b", "b"]);
+    });
+    it("runs register, unregister and replay handlers in the provider's context", () => {
+        const proxy = new __1.RegisteringProxy();
+        const seen = [];
+        const attach = (owner) => inModule("b", owner, () => proxy.onHandlers(() => seen.push((0, modules_1.GetModuleContext)()?.owner), () => seen.push((0, modules_1.GetModuleContext)()?.owner)));
+        attach("b#7");
+        inModule("a", "a#6", () => proxy.register("x"));
+        attach("b#8");
+        inModule("a", "a#6", () => proxy.unregister("x"));
+        (0, chai_1.expect)(seen).to.deep.equal(["b#7", "b#8", "b#8"]);
+    });
+    it("runs an event handler in the context it was registered in", () => {
+        const event = new __1.EventProxy();
+        const seen = [];
+        inModule("a", "a#7", () => event.register(() => seen.push((0, __1.GetResponsibleModule)())));
+        inModule("emitter", "emitter#1", () => event.emit());
+        (0, chai_1.expect)(seen).to.deep.equal(["a"]);
+    });
+    it("runs a handler registered outside any context in the emitter's context", () => {
+        const event = new __1.EventProxy();
+        const seen = [];
+        event.register(() => seen.push((0, __1.GetResponsibleModule)()));
+        inModule("emitter", "emitter#2", () => event.emit());
+        (0, chai_1.expect)(seen).to.deep.equal(["emitter"]);
+    });
+    it("lets an unregister handler schedule work that enters a module context during the registrant's release", async () => {
+        const proxy = new __1.RegisteringProxy();
+        let scheduled;
+        inModule("d", "d#1", () => proxy.onHandlers(() => undefined, () => {
+            scheduled = new Promise((resolve) => {
+                setImmediate(() => {
+                    try {
+                        (0, modules_1.RunWithModuleContext)({ module: "d-sync" }, () => undefined);
+                        resolve("entered");
+                    }
+                    catch (error) {
+                        resolve(error);
+                    }
+                });
+            });
+        }));
+        inModule("a", "a#8", () => proxy.register("page"));
+        destroy("a", "a#8");
+        (0, chai_1.expect)(await scheduled).to.equal("entered");
+    });
+});
+describe("call chain: an interface's own context", () => {
+    const INTERFACE = {
+        module: "interface-x",
+        owner: "interface-x@p#instance",
+        kind: "interface",
+    };
+    it("keeps the interface's context for its own timers and event handlers", async () => {
+        const event = new __1.EventProxy();
+        const handled = [];
+        const timer = (0, modules_1.RunWithModuleContext)(INTERFACE, () => {
+            event.register(() => handled.push((0, __1.GetResponsibleModule)()));
+            return new Promise((resolve) => {
+                setTimeout(() => resolve((0, modules_1.GetModuleContext)()?.owner), 0);
+            });
+        });
+        inModule("emitter", "emitter#3", () => event.emit());
+        (0, chai_1.expect)(await timer).to.equal(INTERFACE.owner);
+        (0, chai_1.expect)(handled).to.deep.equal(["interface-x"]);
+    });
+    it("runs callbacks it attaches in the caller's context, so what they forward is the caller's", async () => {
+        const call = new __1.AsyncProxy();
+        const handlers = new __1.RegisteringProxy();
+        const c = new __1.RegisteringProxy();
+        const entries = new Set();
+        attachRegistry(c, entries, "c", "c#3");
+        (0, modules_1.RunWithModuleContext)({ ...INTERFACE, owner: "interface-y#instance" }, () => {
+            call.onCall(() => (0, __1.GetResponsibleModule)());
+            handlers.onHandlers((id) => c.register(`c:${id}`), (id) => c.unregister(`c:${id}`));
+        });
+        (0, chai_1.expect)(await inModule("a", "a#9", () => call.call())).to.equal("a");
+        inModule("a", "a#9", () => handlers.register("x"));
+        (0, chai_1.expect)([...entries]).to.deep.equal(["c:x"]);
+        destroy("a", "a#9");
+        (0, chai_1.expect)([...entries]).to.deep.equal([]);
+    });
+    it("replays a call queued before it attaches in the caller's context, so what it forwards is the caller's", async () => {
+        const call = new __1.AsyncProxy();
+        const c = new __1.RegisteringProxy();
+        const entries = new Set();
+        attachRegistry(c, entries, "c", "c#5");
+        const pending = inModule("a", "a#16", () => call.call());
+        (0, modules_1.RunWithModuleContext)({ ...INTERFACE, owner: "interface-q#instance" }, () => call.onCall(() => {
+            c.register("queued");
+            return (0, __1.GetResponsibleModule)();
+        }));
+        (0, chai_1.expect)(await pending).to.equal("a");
+        (0, chai_1.expect)([...entries]).to.deep.equal(["queued"]);
+        destroy("a", "a#16");
+        (0, chai_1.expect)([...entries]).to.deep.equal([]);
+    });
+    it("replays a call queued outside any context with no context", async () => {
+        const call = new __1.AsyncProxy();
+        const pending = call.call();
+        (0, modules_1.RunWithModuleContext)({ ...INTERFACE, owner: "interface-r#instance" }, () => call.onCall(() => (0, __1.GetResponsibleModule)()));
+        (0, chai_1.expect)(await pending).to.equal(undefined);
+    });
+    it("releases only the interface's own work when its owner is released", () => {
+        const own = new __1.RegisteringProxy();
+        const handlers = new __1.RegisteringProxy();
+        const ownEntries = new Set();
+        const forwarded = new Set();
+        const owner = "interface-z#instance";
+        attachRegistry(own, ownEntries, "c", "c#4");
+        attachRegistry(handlers, forwarded, "c", "c#4");
+        (0, modules_1.RunWithModuleContext)({ ...INTERFACE, owner }, () => own.register("interface-entry"));
+        inModule("a", "a#10", () => handlers.register("a-entry"));
+        (0, modules_1.ReleaseOwner)(owner);
+        (0, chai_1.expect)([...ownEntries]).to.deep.equal([]);
+        (0, chai_1.expect)([...forwarded]).to.deep.equal(["a-entry"]);
+    });
+});
+describe("call chain: values cross unchanged", () => {
+    class Value {
+    }
+    const handler = () => undefined;
+    const object = { handler };
+    const array = [handler];
+    const values = [Value, handler, object, array];
+    it("hands call arguments to the provider as the very same values", async () => {
+        const proxy = new __1.AsyncProxy();
+        inModule("b", "b#9", () => proxy.onCall((...received) => received));
+        const received = await inModule("a", "a#11", () => proxy.call(...values));
+        received.forEach((value, index) => (0, chai_1.expect)(value).to.equal(values[index]));
+    });
+    it("hands register arguments to the provider as the very same values", () => {
+        const proxy = new __1.RegisteringProxy();
+        let received = [];
+        inModule("b", "b#10", () => proxy.onHandlers((_id, ...args) => {
+            received = args;
+        }, () => undefined));
+        inModule("a", "a#12", () => proxy.register("x", ...values));
+        received.forEach((value, index) => (0, chai_1.expect)(value).to.equal(values[index]));
+    });
+    it("unregisters an event handler by the reference it was registered with", () => {
+        const event = new __1.EventProxy();
+        const received = [];
+        const listener = (value) => received.push(value);
+        inModule("a", "a#13", () => event.register(listener));
+        event.emit(object);
+        inModule("a", "a#13", () => event.unregister(listener));
+        event.emit(object);
+        (0, chai_1.expect)(received).to.have.length(1);
+        (0, chai_1.expect)(received[0]).to.equal(object);
+    });
+});
+describe("call chain: fence on a destroyed generation", () => {
+    it("rejects a call made from a destroyed generation without throwing", async () => {
+        const proxy = new __1.AsyncProxy();
+        inModule("b", "b#11", () => proxy.onCall(() => "served"));
+        const gate = deferred();
+        const outcome = inModule("a", "a#14", async () => {
+            await gate.promise;
+            return outcomeOf(proxy.call());
+        });
+        destroy("a", "a#14");
+        gate.resolve();
+        (0, chai_1.expect)(await outcome).to.be.instanceOf(__1.ModuleContextInvalidatedError);
+    });
+    it("throws on a register made from a destroyed generation", async () => {
+        const proxy = new __1.RegisteringProxy();
+        const gate = deferred();
+        const outcome = inModule("a", "a#15", async () => {
+            await gate.promise;
+            proxy.register("late");
+        });
+        destroy("a", "a#15");
+        gate.resolve();
+        (0, chai_1.expect)(await outcomeOf(outcome)).to.be.instanceOf(__1.ModuleContextInvalidatedError);
+    });
+});
+//# sourceMappingURL=ownership-call-chain.test.js.map

package/dist/tests/ownership-call-chain.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership-call-chain.test.js","sourceRoot":"","sources":["../../src/tests/ownership-call-chain.test.ts"],"names":[],"mappings":"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"}

package/docs/1.introduction.md

@@ -1,8 +1,21 @@
-# Interface Core Documentation
+# Connect modules through interfaces
 
 ## Overview
 
-`@antelopejs/interface-core` provides the foundational building blocks for the AntelopeJS interface system. It defines the core primitives that enable type-safe, module-aware communication between decoupled components.
+`@antelopejs/interface-core` lets one module call a contract implemented by another. The caller imports the interface rather than the provider, so the runtime can connect modules and replace a provider without changing the caller's imports.
+
+If you only need application logs, start with [logging](./6.logging.md). If you are using HTTP routes or authentication, start with those interfaces; you do not need to build a proxy first.
+
+## Start with your role
+
+| You are…                      | Start here                                                                                                         | You own…                                              |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
+| Calling an existing interface | Its package documentation, then [connection lookup](./2.proxies.md#getinterfaceinstances-and-getinterfaceinstance) | The consuming module and its provider binding.        |
+| Defining a new contract       | [How interfaces work](#how-interfaces-work), then [proxies](./2.proxies.md)                                        | Typed declarations shared by consumers and providers. |
+| Implementing a contract       | [`ImplementInterface`](./2.proxies.md#implementinterface)                                                          | Every declared function and registration callback.    |
+| Integrating a module loader   | [Runtime](./8.runtime.md) and [module lifecycle](./5.modules.md)                                                   | Ownership contexts, generations, and cleanup.         |
+
+Application modules normally import an existing interface rather than construct proxies themselves. The AntelopeJS runtime supplies module context and connections; these primitives do not configure a project or choose a provider for you.
 
 The package exports several key categories of functionality:
 
@@ -70,7 +83,17 @@ ImplementInterface(UserInterface, {
 });
 ```
 
-The proxy system ensures that calls to `GetUser` before the implementation is attached are automatically queued and resolved once the implementation becomes available. When the implementing module is unloaded, the proxy detaches and resumes queuing.
+The proxy queues calls to `GetUser` until an implementation attaches. When the implementing module unloads, the proxy detaches and queues new calls again. The queue is bounded (1,000 pending calls by default), and test stub mode rejects missing providers instead of waiting. See [proxy failure modes](./2.proxies.md#other-public-errors) before relying on this behavior during startup.
+
+## Choose a communication primitive
+
+| Need                                       | Primitive                          | Without an attached provider or listener                  |
+| ------------------------------------------ | ---------------------------------- | --------------------------------------------------------- |
+| Ask for a result                           | `InterfaceFunction` / `AsyncProxy` | Calls queue, subject to the queue limit and stub mode.    |
+| Notify current listeners                   | `EventProxy`                       | Emissions are not retained for future listeners.          |
+| Keep declarations available across reloads | `RegisteringProxy`                 | Entries remain available for replay when handlers attach. |
+
+Do not use an event for a registration that a replacement provider must recover. Use the registering proxy's paired `onHandlers` attachment when replay needs both registration and unregistration callbacks.
 
 ## Next steps
 
@@ -78,3 +101,6 @@ The proxy system ensures that calls to `GetUser` before the implementation is at
 - [Decorators](./3.decorators.md) - Build type-safe decorator factories
 - [Modules](./5.modules.md) - Understand module lifecycle events
 - [Logging](./6.logging.md) - Use the structured logging system
+- [Metadata](./4.metadata.md) - Read inherited metadata
+- [Configuration](./7.configuration.md) - Define project configuration
+- [Runtime](./8.runtime.md) - Integrate ownership and loader behavior

package/docs/2.proxies.md

@@ -2,9 +2,23 @@
 
 ## Overview
 
-Proxies are the backbone of cross-module communication in AntelopeJS. They provide module-aware abstractions for function calls, event handling, and registration patterns. Each proxy type automatically tracks the module that attaches callbacks and detaches them when that module is unloaded, preventing memory leaks and dangling references.
+Choose a proxy by what must survive a provider change: a pending call, nothing from a past event, or a retained registration. The proxy tracks module ownership so the runtime can remove that module's callbacks and registrations when it is destroyed. You still own resources such as sockets and timers created by those callbacks.
 
-A proxy has a single provider and keeps its state on the proxy object itself. When a project has several providers of one interface, the core evaluates a separate instance of the interface package for each provider, so each instance's proxies reach exactly one provider; no call selects a provider at run time.
+An async or registering proxy has one provider attachment; an event proxy has multiple listeners. State lives on each proxy object. When a project has several providers of one interface, the core evaluates a separate instance of the interface package for each provider, so each instance's calls reach one provider; no call selects a provider at run time.
+
+For an ordinary request/response contract, start with [`InterfaceFunction`](#interfacefunction) and [`ImplementInterface`](#implementinterface). Direct attachment, leases, and ownership contexts below are for provider or loader authors who need lifecycle control.
+
+## Read the lifecycle before choosing a proxy
+
+![Async calls wait for a provider, events reach only current listeners, and registrations remain available for replay after provider replacement.](./assets/proxy-lifecycles.svg){width="480"}
+
+| Situation          | Async call             | Event                                   | Registration                                                         |
+| ------------------ | ---------------------- | --------------------------------------- | -------------------------------------------------------------------- |
+| No attachment      | Queues up to the limit | No listener receives it                 | Entry is retained                                                    |
+| Attachment arrives | Pending calls run      | Future emissions reach listeners        | Stored entries replay                                                |
+| Attachment leaves  | New calls queue again  | Removed listener stops receiving events | Entries remain until explicitly removed or their owner is cleaned up |
+
+This table describes normal runtime behavior. [Test stub mode](#missingprovidererror) rejects missing providers. Detaching an async callback does not cancel work already running; detaching registration callbacks does not release provider resources.
 
 ## `AsyncProxy`
 
@@ -20,7 +34,7 @@ const proxy = new AsyncProxy<(name: string) => string>();
 // Calls made before attachment are queued
 const result = proxy.call("Alice"); // returns Promise<string>
 
-// Attach an implementation - queued calls resolve immediately
+// Attach an implementation - queued calls now invoke it
 proxy.onCall((name: string) => {
   return `Hello, ${name}!`;
 });
@@ -33,23 +47,41 @@ const greeting = await proxy.call("Bob"); // "Hello, Bob!"
 
 Attaches the provider's callback to the proxy, replacing any callback attached before, so a provider's new generation takes over from the old one. The proxy automatically tracks the calling module and detaches the callback when that module is unloaded; releasing an older generation never detaches a newer one. Pass `manualDetach: true` to disable automatic cleanup.
 
-When attachment occurs inside `RunWithModuleContext`, calls execute in the captured provider context rather than the consumer context. The captured module and owner generation remain available across nested calls and `await`. Calls reject with `ModuleContextInvalidatedError` if the captured owner has been destroyed.
+The callback runs in the context it was attached in, the provider's, whichever module calls: `GetModuleContext` reports the provider, across nested calls and `await`, and what the callback registers belongs to the provider. A callback attached in an interface package's own context runs in the caller's context instead (see [Ownership](#ownership)).
 
 ```ts
 // Automatic cleanup (default) - detaches when the module unloads
 proxy.onCall(myHandler);
 
-// Manual cleanup - you are responsible for calling detach()
-proxy.onCall(myHandler, true);
+// Manual cleanup - retain the lease for generation-safe detachment
+const lease = proxy.onCall(myHandler, true);
+// Later:
+proxy.detach(lease);
 ```
 
+`onCall` returns an `AttachmentLease` with `owner: string` and `generation: number`. Keep this handle unchanged and pass it to `detach(lease)` to remove only that attachment. A stale lease cannot detach a replacement provider. Import the type from `@antelopejs/interface-core/proxies`; it is not re-exported from the package root.
+
+```ts docs-check
+import { AsyncProxy } from "@antelopejs/interface-core";
+import type { AttachmentLease } from "@antelopejs/interface-core/proxies";
+
+const proxy = new AsyncProxy<() => string>("greeting");
+const oldLease: AttachmentLease = proxy.onCall(() => "old", true);
+const currentLease = proxy.onCall(() => "current", true);
+proxy.detach(oldLease); // The current provider stays attached.
+const greeting: string = await proxy.call(); // "current"
+proxy.detach(currentLease);
+```
+
+Manual detachment disables automatic attachment cleanup only. A callback attached by a generation that is later destroyed still runs when invoked, in that generation's context, so reading the module context or registering from inside it throws `ModuleContextInvalidatedError`.
+
 ### `call(...args)`
 
-Invokes the attached callback. If no callback is attached, the call returns a `Promise` that resolves once a callback is provided. In test stub mode, unattached calls reject with a [`MissingProviderError`](#missingprovidererror).
+Invokes the attached callback. If no callback is attached, the call returns a `Promise` that resolves once a callback is provided; the queued call then runs as if it had just been made, and rejects with `ModuleContextInvalidatedError` if the caller's generation was destroyed in the meantime. A call made from a destroyed generation rejects with `ModuleContextInvalidatedError`. In test stub mode, unattached calls reject with a [`MissingProviderError`](#missingprovidererror).
 
 ### `detach()`
 
-Manually removes the attached callback. After detaching, subsequent calls are queued again.
+`detach()` removes the current callback unconditionally; `detach(lease)` removes it only when the lease matches. After detaching, subsequent calls are queued again. Detaching does not cancel calls already executing.
 
 ## `InterfaceFunction`
 
@@ -66,7 +98,9 @@ const GetUser =
 const user = await GetUser("user-123");
 ```
 
-The returned function has a `.proxy` property that exposes the underlying `AsyncProxy` for direct access when needed.
+The typed return value is `(...args: Parameters<T>) => Promise<R>`, where `R` defaults to `Awaited<ReturnType<T>>`. Supply an optional identity string as `InterfaceFunction<T>("name")` for diagnostics.
+
+The implementation attaches a `.proxy` property at runtime, but the declared return type does not expose it. Use `ImplementInterface({ GetUser }, { GetUser: handler })` for typed provider wiring. When you need direct attachment and lease control, construct an `AsyncProxy` as shown above instead of accessing `.proxy` on an interface function.
 
 ## `EventProxy`
 
@@ -90,11 +124,11 @@ onUserCreated.emit("u-1", "Alice");
 
 ### `register(func)`
 
-Registers a handler for the event. Duplicate handlers (same function reference) are ignored. The proxy tracks the calling module and removes the handler when that module is unloaded. The handler runs in the context of the module that registered it, whichever module emits the event.
+Registers a handler for the event. Duplicate handlers (same function reference) are ignored. The proxy tracks the calling module and removes the handler when that module is unloaded. The handler runs in the context it was registered in, whichever module emits the event. A handler registered outside any context runs in the emitter's context.
 
 ### `emit(...args)`
 
-Calls all registered handlers with the provided arguments.
+Calls all registered handlers synchronously with the provided arguments. Synchronous exceptions are reported through the runtime's error reporter without preventing later handlers from running. Emission does not await returned promises; asynchronous handlers must handle their own rejections.
 
 ### `unregister(func)`
 
@@ -117,51 +151,72 @@ const routeRegistry = new RegisteringProxy<
 routeRegistry.register("home", "/", homeHandler);
 routeRegistry.register("about", "/about", aboutHandler);
 
-// Attach callbacks - queued registrations replay immediately
-routeRegistry.onRegister((id, path, handler) => {
-  router.addRoute(path, handler);
-});
-
-routeRegistry.onUnregister((id) => {
-  router.removeRoute(id);
-});
+// Install both callbacks before replaying stored registrations.
+const lease = routeRegistry.onHandlers(
+  (id, path, handler) => router.addRoute(path, handler),
+  (id) => router.removeRoute(id),
+);
 
 // Unregister by ID
 routeRegistry.unregister("about");
 ```
 
+### `onHandlers(register, unregister, manualDetach?)`
+
+Attaches both callbacks under one lease before replaying stored registrations. Prefer this operation when replacing a provider: replay can safely call `unregister` because the matching unregister callback is already installed. It returns an `AttachmentLease` for both callbacks. `ImplementInterface` uses this operation for registering proxies.
+
+Replay reports synchronous registration failures and continues to the next stored entry. This is not a transaction or a rollback of provider side effects. Direct `register` calls propagate synchronous callback failures to the caller.
+
 ### `onRegister(callback, manualDetach?)`
 
-Attaches the register callback. Any previously registered entries replay through this callback immediately. Automatic module-aware detachment applies unless `manualDetach` is `true`.
+Attaches only the register callback and returns its own lease. Any previously registered entries replay through this callback immediately. Automatic module-aware detachment applies unless `manualDetach` is `true`. An existing unregister callback remains attached.
 
-Register replay and direct registration execute in the provider context captured when the callback attaches.
+Direct registration and replay run in the context the callback was attached in, the provider's.
 
 ### `onUnregister(callback)`
 
-Attaches the unregister callback. This callback is detached at the same time as the register callback.
+Attaches only the unregister callback and returns a separate lease. It shares the owner and manual-detach setting of an existing attachment belonging to the active owner when available. Without an explicit context, it uses the existing unregister attachment, then the register attachment, if present. Otherwise it resolves ownership normally and enables automatic cleanup. It does not replay registrations or replace the register callback.
 
-Unregistration executes in the context captured when this callback attaches.
+Unregistration runs in the context this callback was attached in, also when it is triggered by the release of the module that registered the entry.
 
 ### `register(id, ...args)`
 
-Registers an entry with the given identifier. If a register callback is attached, it executes immediately. Otherwise, the entry is stored and replayed when a callback is attached. The calling module is tracked for automatic cleanup.
+Registers an entry with the given identifier. If a register callback is attached, it executes immediately. Otherwise, the entry is stored and replayed when a callback is attached. The calling module is tracked for automatic cleanup. Registering the same ID replaces the stored arguments and ownership and calls the register callback again; it does not first call unregister. Registering from a destroyed generation throws `ModuleContextInvalidatedError`.
 
 ### `unregister(id)`
 
-Removes the entry with the given identifier and calls the unregister callback if one is attached.
+Removes the entry with the given identifier and calls the unregister callback if one is attached. Unknown IDs are ignored. The stored entry is removed even if the callback throws.
 
 ### `detach()`
 
-Manually removes both the register and unregister callbacks. Registered entries remain stored.
+`detach()` removes both callbacks. `detach(lease)` removes only callbacks matching the lease: both for `onHandlers`, or one for separate `onRegister`/`onUnregister` attachments. Registered entries remain stored for replay; detaching callbacks does not unregister provider resources.
+
+### Ownership cleanup
+
+`RegisteringProxy` and `EventProxy` expose `unregisterModule(module)` and `unregisterOwner(owner)` to remove entries for a whole module or one generation. Normal module destruction invokes owner cleanup automatically; application consumers usually need only `unregister(id)` or `unregister(handler)`.
+
+## Proxy identity helpers
+
+All three proxy constructors accept an optional identity string. `GetInterfaceProxyIdentity(proxy)` returns a diagnostic identity prefixed by the proxy kind, for example `"async:greeting"`. Without an explicit name, the runtime generates an anonymous identity. Non-proxy values return `undefined`.
+
+`IsInterfaceProxy(value, kind?)` checks the shared runtime protocol brand, optionally restricted to `"async"`, `"registering"`, or `"event"`. It works across compatible package copies where `instanceof` is unreliable, but returns a boolean rather than narrowing a TypeScript type. Both helpers operate on proxy objects, not on the callable return value of `InterfaceFunction`.
 
-## Functions passed through a proxy
+## Ownership
 
-A function a module hands to a proxy runs as that module's work, whoever invokes it later:
+Proxies track ownership so that hot reload can detach and unregister everything a module generation left behind. The owner of an attachment, a registration or an event handler is the nearest module in the chain of work that made it, read from the async module context:
 
-- an event handler runs in the context of the module that registered it;
-- a function passed as an argument to `AsyncProxy.call` or `RegisteringProxy.register`, or held in a plain object or array passed that way, runs in the context of the module that made the call.
+- **A module owns its own work**, including what it registers while serving another module's call. A provider callback runs in the provider's context, so when module A calls B and B's provider registers on C, the entry on C is B's: reloading B removes it, destroying A does not.
+- **A module that forwards registrations declares a `RegisteringProxy`.** When A registers on B and B's provider forwards to C, B's next generation receives A's entry again through replay and forwards it again. When A is destroyed, its entry on B is unregistered and B's unregister callback removes the one on C.
+- **Interface package code is never an owner.** Functions an interface package exports run in their caller's context, so what they forward is the caller's.
+- **An interface package owns what it needs in order to work.** The core evaluates each interface package in a context of its own, of kind `"interface"`, whose owner is released only when the core discards that interface instance, never on a module reload. Code at the package's top level, and the timers, promises and event handlers it creates, run in that context. A provider callback attached there is the exception: it only carries calls and registrations forward on a caller's behalf, so it runs in the caller's context.
 
-Inside such a function, `GetModuleContext` and `GetResponsibleModule` report the module that passed it, and what it registers is owned by that module. Once that module's generation is destroyed, invoking the function throws `ModuleContextInvalidatedError`. Plain data, classes, class instances and proxies cross unchanged, so a class keeps the identity its metadata and registries are keyed by; a function passed twice reaches the provider as the same value, and a function passed on by another module keeps its original context.
+Values cross unchanged: arguments to `AsyncProxy.call`, `RegisteringProxy.register` and `EventProxy.emit` reach the other side as the very same values, so a class keeps the identity its metadata and registries are keyed by, and a function can be unregistered by reference.
+
+### Limits
+
+- A function passed as an argument and invoked later by the provider runs in the context of whoever invokes it, and what it registers belongs to that module. Callbacks that outlive the call belong in a `RegisteringProxy` entry, not in `AsyncProxy.call` arguments.
+- Work an interface package starts lazily, from inside a function it exports rather than from its top level, belongs to the module that called first.
+- The core enters an interface package's context only for packages loaded through `require()`. A package reached through an ECMAScript `import` is evaluated in its importer's context, so its top-level work belongs to that importer.
 
 ## `ImplementInterface`
 
@@ -200,6 +255,8 @@ ImplementInterface(ItemInterface, {
 
 `EventProxy` entries in the declaration are skipped during implementation wiring, as they are emitted from the declaring side, not implemented.
 
+The synchronous overload returns `{ declaration, implementation }`. Every declared async proxy needs a function, and every registering proxy needs both `register` and `unregister`, even though the implementation type permits optional keys. Missing or malformed handlers, non-object arguments, and object cycles throw `TypeError`. Validation happens before attachment, but provider callback effects during attachment are not rolled back. Promise-like arguments use a deprecated asynchronous overload; prefer the synchronous form.
+
 ## `MissingProviderError`
 
 In test stub mode, using a proxy that has no provider attached fails with a `MissingProviderError`: `AsyncProxy.call` rejects with it and `RegisteringProxy.register` throws it.
@@ -222,6 +279,16 @@ try {
 
 Prefer the `isMissingProviderError` guard over `instanceof`: it checks the `code` property, so detection keeps working across realm boundaries and duplicated copies of the package where `instanceof` fails.
 
+## Other public errors
+
+Errors are exported from the package root. Use their stable `code` values rather than parsing messages.
+
+| Error                           | Code constant                     | Code value                       | When it applies                                                                                                                                     |
+| ------------------------------- | --------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ProviderQueueFullError`        | `PROVIDER_QUEUE_FULL_CODE`        | `ERR_PROVIDER_QUEUE_FULL`        | An unattached async proxy reaches its pending-call limit (1,000 by default).                                                                        |
+| `ModuleContextInvalidatedError` | `MODULE_CONTEXT_INVALIDATED_CODE` | `ERR_MODULE_CONTEXT_INVALIDATED` | Work tries to use a destroyed ownership context.                                                                                                    |
+| `AmbiguousProviderError`        | `AMBIGUOUS_PROVIDER_CODE`         | `ERR_AMBIGUOUS_PROVIDER`         | Exported to represent ambiguous provider routing. The current single-provider proxy classes do not themselves throw it or select between providers. |
+
 ## `GetInterfaceInstances` and `GetInterfaceInstance`
 
 These functions retrieve information about active interface connections for the current module.
@@ -254,7 +321,7 @@ Requiring a connection's `path` (or a subpath of it) gives the interface bound t
 
 ## `GetResponsibleModule`
 
-`GetResponsibleModule` inspects the call stack to determine which module is responsible for the current execution. The proxy classes use this internally for automatic cleanup tracking.
+`GetResponsibleModule` returns the module of the active async module context, or `undefined` outside any context. It never inspects the call stack.
 
 ```ts
 import { GetResponsibleModule } from "@antelopejs/interface-core";
@@ -262,11 +329,9 @@ import { GetResponsibleModule } from "@antelopejs/interface-core";
 const moduleId = GetResponsibleModule();
 ```
 
-> **Warning:** Calling `GetResponsibleModule` from within an async context (such as `setTimeout` or `setInterval`) without explicit ownership breaks hot reloading. The system logs an error when this is detected.
-
 ## `RunWithResponsibleModule`
 
-`RunWithResponsibleModule` sets the responsible module explicitly for synchronous and asynchronous work. Proxy registrations made in the callback use this module directly instead of capturing and walking a stack. Nested contexts restore their parent when they complete, including when a callback throws.
+`RunWithResponsibleModule` sets the responsible module explicitly for synchronous and asynchronous work. Proxy registrations made in the callback are owned by this module. Nested contexts restore their parent when they complete, including when a callback throws.
 
 ```ts
 import { RunWithResponsibleModule } from "@antelopejs/interface-core";
@@ -277,7 +342,7 @@ await RunWithResponsibleModule("my-module", async () => {
 });
 ```
 
-The module loader should wrap known module-owned entry points, including module evaluation and lifecycle hooks. Existing callers need no migration: outside an explicit context, `GetResponsibleModule` retains stack-based resolution as a backward-compatible fallback. Automatic proxy detachment and registration cleanup use the resolved module in both paths.
+The module loader wraps every module-owned entry point, including module evaluation and lifecycle hooks. Work done outside any context has no owner: its attachments belong to a default owner that no module release removes, and its registrations are never released by owner.
 
 Ownership contexts are scoped to a loaded module generation. Loaders that can overlap old and replacement instances should use `RunWithModuleContext` and provide a unique `owner` for every generation. `ModuleDestroyed` invalidates and cleans only the active event context's owner while preserving the existing module ID event contract. Detached asynchronous work from that owner then receives a `ModuleContextInvalidatedError`.