@earendil-works/chord 1.2.0 → 1.3.0

package/dist/host.js

@@ -1,42 +1,48 @@
 import { ChildReloads, reconcileChild, runClusterReload } from "./cluster.js";
 import { Connection } from "./connection.js";
-import { bind, } from "./contract.js";
+import { bind, contractFromDescription, placedOn, placementText, resolveHost, } from "./contract.js";
 import { ChordError, invalid, runAll } from "./errors.js";
+import { awaitReady, CtxImpl, hostLifetime, makeService, ObjectImpl, RefImpl, } from "./object.js";
 import { enqueue } from "./publish.js";
-import { CtxImpl, HandleImpl, makeService, RecordImpl, } from "./record.js";
 import { runReload } from "./reload.js";
-import { RemoteHandle } from "./remote.js";
+import { RemoteBinding, RemoteRef } from "./remote.js";
 import { canonicalIdentity, canonicalJson, deepEqual, normalize } from "./schema.js";
-/** The principal of in-host code. */
-export const hostPrincipal = Object.freeze({ host: true });
+/** `defineFacet<P>(…)`: an app passes its principal type, so factories and contexts see `P`. */
 export const defineFacet = (setup, options = {}) => ({ setup, uses: options.uses });
 const isFacet = (ref) => typeof ref === "object" && !(ref instanceof URL);
 const EMPTY_TABLE = new Map();
-export function createHost(options = {}) {
+/** A host whose principals are `P` (the app's type; `unknown` if not given). */
+export function createHost(options) {
     return new HostImpl(options);
 }
 export class HostImpl {
     name;
     dev;
-    principal = hostPrincipal;
+    principal;
     inFactory = 0;
     failed;
-    records = new Map();
-    epochs = new Map();
+    objects = new Map();
+    codeVersions = new Map();
     facets = new Map();
-    eager = new Map();
+    /** The host's own references to its `lifetime: "host"` objects, by type name. */
+    hostObjects = new Map();
     kind;
     connections = new Set();
     upstream;
-    /** Remote handles this host holds (re-held after an upstream reconnect). */
-    remotes = new Set();
+    /** Shared bindings of this host's remote references, by key (re-held after an upstream reconnect). */
+    bindings = new Map();
+    /** Bindings without references that linger, least recently released first. */
+    #lingering = new Map();
+    #lingerTypes;
+    #lingerCap;
+    #originSeq = 0;
     #routes = new Map();
     #childReloads = new ChildReloads(this);
     /** Child facet modules by host-name prefix, from every committed cluster reload (for reconciling children). */
     remoteModules = {};
     /** Removal tombstones also reconcile children that connected during a transaction. */
     remoteRemoved = {};
-    /** Highest epoch the parent has retired. */
+    /** Highest code version the parent has retired. */
     #retireAllowed = 0;
     /** Roots that came over a link, by the link they came from. */
     /** Foreign roots (started on another host), by the links they came over. */
@@ -48,46 +54,75 @@ export class HostImpl {
     #rootLinks = new Map();
     current;
     previous;
-    /** The epoch a running reload will commit; new types activated during prepare install their behavior for it. */
+    /** The code version a running reload will commit; new types activated during prepare install their implementation for it. */
     pending;
     /** Activations of these types wait (reload gate). */
-    /** Types behind a reload gate: new records of these types are rejected `upgrade_conflict` until commit/abort. */
+    /** Types behind a reload gate: new objects of these types are rejected `upgrade_conflict` until commit/abort. */
     gating;
     reloading = false;
-    retired = () => { };
+    taskStopDeadline;
+    readyTimeout;
     #principalKey;
+    /** `principalKey(self)`: an equal principal is the host's own, whatever object carries it. */
+    #selfKey;
+    /** Called when a root ends, the parent allows a retirement, or the previous code version retires. */
+    #retirementWatchers = new Set();
+    /** Child hosts whose hello arrived while a reload ran: synced or reconciled once it ends. */
+    #deferredHellos = new Map();
+    /** Resolved when the running reload ends. */
+    #reloadWaiters = [];
+    /** Aborted when the installed run of a facet (by name) is replaced, removed, or the host closes. */
+    #facetRuns = new Map();
     #onError;
     #loader;
     #dying = new Map();
     #touches = new Map();
     #order = new Map();
     #subscribers = new Map();
-    #epochSeq = 1;
+    #codeVersionSeq = 1;
     #rootSeq = 0;
     constructor(options) {
         this.name = options.name ?? "host";
         this.dev = options.dev ?? false;
+        if (!("self" in options))
+            throw new TypeError("createHost needs `self`: the principal of the host's own code");
+        this.principal = options.self;
         this.#principalKey = options.principalKey ?? canonicalJson;
+        this.#selfKey = this.#principalKey(options.self);
         this.#onError = options.onError ?? ((error) => console.error("chord:", error));
         this.#loader = options.loader;
-        this.current = { id: this.#epochSeq, services: new Map(), tables: new Map(), roots: new Map() };
-        this.epochs.set(this.current.id, this.current);
+        this.taskStopDeadline = options.taskStopDeadline ?? 5000;
+        this.readyTimeout = options.readyTimeout ?? 60_000;
+        this.#lingerTypes = options.linger?.types ?? {};
+        this.#lingerCap = options.linger?.cap ?? 4;
+        this.current = {
+            id: this.#codeVersionSeq,
+            services: new Map(),
+            tables: new Map(),
+            roots: new Map(),
+            abort: new AbortController(),
+        };
+        this.codeVersions.set(this.current.id, this.current);
         this.kind = options.kind ?? "host";
         if (options.upstream !== undefined)
-            this.connect(options.upstream, options.upstreamOptions);
+            this.connect(options.upstream.link, options.upstream);
+    }
+    /** Whether `principal` is the host's own: the same key as `self`. */
+    isSelf(principal) {
+        return principal === this.principal || this.#principalKey(principal) === this.#selfKey;
     }
-    get epoch() {
+    get codeVersion() {
         return this.current.id;
     }
-    get previousEpoch() {
+    get previousCodeVersion() {
         return this.previous?.id;
     }
-    /** Allocates the next epoch id, or adopts one issued by the coordinating server. */
-    nextEpochId(given) {
+    /** Allocates the next code version id, or adopts one issued by the coordinating server. */
+    nextCodeVersionId(given) {
         if (given !== undefined && given <= this.current.id)
-            throw new Error(`epoch ${given} is not newer than ${this.current.id}`);
-        this.#epochSeq = given ?? this.#epochSeq + 1;
-        return this.#epochSeq;
+            throw new Error(`code version ${given} is not newer than ${this.current.id}`);
+        this.#codeVersionSeq = given ?? this.#codeVersionSeq + 1;
+        return this.#codeVersionSeq;
     }
     report(error) {
         this.#onError(error);
@@ -97,8 +132,8 @@ export class HostImpl {
         if (this.reloading)
             throw new Error("host.serve during a reload; serve from a facet passed to reload()");
         this.serveInto(this.current.services, makeService(type, factory, options, ""));
-        if (options.eager)
-            this.startEager(this.current.services.get(type.name));
+        if (options.lifetime === "host")
+            this.startHostObject(this.current.services.get(type.name));
     });
     install(facet, options = {}) {
         if (this.reloading)
@@ -106,25 +141,33 @@ export class HostImpl {
         if (this.facets.has(facet.name))
             throw new Error(`facet ${facet.name} is already installed; use reload()`);
         const added = [];
-        facet.setup(this.facetApi(((type, factory, options = {}) => {
-            const service = makeService(type, factory, options, facet.name);
-            this.serveInto(this.current.services, service);
-            added.push(service);
-        })));
+        const run = new AbortController();
+        try {
+            facet.setup(this.facetApi(((type, factory, options = {}) => {
+                const service = makeService(type, factory, options, facet.name);
+                this.serveInto(this.current.services, service);
+                added.push(service);
+            }), run.signal));
+        }
+        catch (error) {
+            run.abort(error);
+            throw error;
+        }
         this.facets.set(facet.name, facet);
-        const holds = added.filter((service) => service.options.eager).map((service) => this.startEager(service));
-        return options.awaitEager === false ? Promise.resolve() : this.#eagerReady(holds);
+        this.facetRunChanged(facet.name, run);
+        const refs = added.filter(hostLifetime).map((service) => this.startHostObject(service));
+        return options.awaitHostObjects === false ? Promise.resolve() : this.#hostObjectsReady(refs);
     }
     async load(plugins, options = {}) {
         const facets = await this.resolve(plugins);
-        // No await between installs: an eager factory may consume a type served by a later facet.
+        // No await between installs: a host object's factory may consume a type served by a later facet.
         await Promise.all(facets.map((facet) => this.install(facet, options)));
     }
     ready() {
-        return this.#eagerReady(this.eager.values());
+        return this.#hostObjectsReady(this.hostObjects.values());
     }
-    #eagerReady(holds) {
-        const ready = Promise.all([...holds].map((hold) => hold.ready)).then(() => { });
+    #hostObjectsReady(refs) {
+        const ready = Promise.all([...refs].map((ref) => ref.ready)).then(() => { });
         // Ignoring install's return still reports through onError without an unhandled rejection.
         ready.catch(() => { });
         return ready;
@@ -138,128 +181,183 @@ export class HostImpl {
         const loaded = modules.length > 0 && this.#loader !== undefined ? await this.#loader(modules) : [];
         return plugins.map((ref) => (isFacet(ref) ? ref : loaded.shift()));
     }
-    facetApi(serve) {
+    facetApi(serve, signal) {
         return {
             serve,
             name: this.name,
             root: (fn, options) => this.root(fn, options),
             registry: (registry) => this.registry(registry),
+            signal,
         };
     }
+    /** The installed run of facet `name` is now `run` (or none): the run it replaces is aborted. */
+    facetRunChanged(name, run) {
+        const replaced = this.#facetRuns.get(name);
+        if (run === undefined)
+            this.#facetRuns.delete(name);
+        else
+            this.#facetRuns.set(name, run);
+        if (replaced !== run)
+            replaced?.abort(new ChordError("gone", `facet ${name} was replaced or removed`));
+    }
     serveInto(services, service) {
         if (services.has(service.contract.name))
             throw new Error(`${service.contract.name} is already served`);
+        const placement = service.contract.description.host;
+        if (placement !== undefined && !placedOn(placement, this.name)) {
+            throw new TypeError(`${service.contract.name} is declared for ${placementText(placement)}, but ${this.name} serves it`);
+        }
         services.set(service.contract.name, service);
     }
-    startEager(service) {
-        const eager = service.options.eager;
-        const input = typeof eager === "object" ? eager.input : {};
-        const handle = this.acquire(service.contract, input, undefined, "host");
-        this.eager.set(service.contract.name, handle);
-        handle.ready.catch((error) => this.report(error));
-        return handle;
+    startHostObject(service) {
+        const ref = this.acquire(service.contract, {}, undefined, "host");
+        this.hostObjects.set(service.contract.name, ref);
+        ref.ready.catch((error) => this.report(error));
+        return ref;
     }
     // ─── HostCore ───
-    currentEpoch() {
+    currentCodeVersion() {
         return this.current.id;
     }
-    hasEpoch(epoch) {
-        return this.epochs.has(epoch);
+    hasCodeVersion(codeVersion) {
+        return this.codeVersions.has(codeVersion);
     }
-    *retainedEpochs() {
-        for (const [id, state] of this.epochs)
+    *retainedCodeVersions() {
+        for (const [id, state] of this.codeVersions)
             yield [id, state.services];
         if (this.pending !== undefined)
             yield [this.pending.id, this.pending.services];
     }
-    pendingEpoch() {
+    pendingCodeVersion() {
         return this.pending?.id;
     }
-    /** The current code for a type; a type a running reload adds is served from the pending epoch. */
+    /** The current code for a type; a type a running reload adds is served from the pending code version. */
     service(typeName) {
         return this.current.services.get(typeName) ?? this.pending?.services.get(typeName);
     }
-    addressOf(type, input, principal, at, candidate = false) {
-        if (at !== undefined && at !== this.name)
-            return remoteAddress(at, type, input, principal === this.principal ? undefined : principal);
+    addressOf(type, input, principal, candidate = false) {
+        const elsewhere = this.#elsewhere(type, input);
+        if (elsewhere !== undefined)
+            return this.#remoteKey(type, elsewhere.input, principal);
         const service = this.#bindingService(type.name, candidate);
         if (service === undefined)
             throw unknownType(type.name, this.name);
-        const normalized = normalize(service.contract.input, input, `${type.name} input`);
-        return this.#address(service, normalized, principal);
+        return this.#locate(service, input, principal).address;
     }
-    #address(service, normalized, principal) {
-        const key = principal === this.principal ? "host" : `p:${this.#principalKey(principal)}`;
-        return `${service.contract.name}\u0000${canonicalIdentity(service.contract.input, normalized)}\u0000${key}`;
+    /**
+     * Where an object of a remote type lives when that is another host: its name and the input normalized with the
+     * caller's contract (the placement is read from it). `undefined`: here (and every local type).
+     */
+    #elsewhere(type, input) {
+        const placement = type.description.host;
+        if (type.scope !== "remote" || placement === undefined)
+            return undefined;
+        const normalized = normalize(type.input, input, `${type.name} input`);
+        const at = resolveHost(type.name, placement, normalized);
+        return at === this.name ? undefined : { at, input: normalized };
+    }
+    /**
+     * The address of `input` for `principal`, normalized. A `lifetime: "host"` type has one object: the empty input, for
+     * the host principal, whoever asks; another input is invalid.
+     */
+    #locate(service, input, principal) {
+        const { name, input: schema } = service.contract;
+        const normalized = normalize(schema, input, `${name} input`);
+        const identity = canonicalIdentity(schema, normalized);
+        if (hostLifetime(service)) {
+            if (identity !== canonicalIdentity(schema, normalize(schema, {}, `${name} input`)))
+                throw invalid("input", `${name} has lifetime "host": its one object has the empty input`);
+            principal = this.principal;
+        }
+        return { address: `${name}\u0000${identity}\u0000${this.#principalPart(principal)}`, normalized, principal };
+    }
+    #principalPart(principal) {
+        return this.isSelf(principal) ? "host" : `p:${this.#principalKey(principal)}`;
+    }
+    /**
+     * The key of a remote binding: type, input identity (fields equal to their defaults omitted, as for local objects),
+     * principal key and the consumer's contract fingerprint. No host name: the type and the input decide where it lives.
+     */
+    #remoteKey(type, normalized, principal) {
+        const identity = canonicalIdentity(type.input, normalized);
+        return `@${type.name}\u0000${identity}\u0000${this.#principalPart(principal)}\u0000${type.fingerprint}`;
     }
     acquire(type, input, options, owner, from, candidate = false) {
-        if (options?.at !== undefined && options.at !== this.name)
-            return this.#acquireRemote(type, input, options, owner);
+        const elsewhere = this.#elsewhere(type, input);
+        if (elsewhere !== undefined)
+            return this.#acquireRemote(type, elsewhere.at, elsewhere.input, options, owner);
         const service = this.#bindingService(type.name, candidate);
         if (service === undefined)
             throw unknownType(type.name, this.name);
         bind(service.contract, service.options.accepts, type);
-        const principal = options?.principal ?? this.principal;
-        const normalized = normalize(service.contract.input, input, `${type.name} input`);
-        const address = this.#address(service, normalized, principal);
-        let record = this.records.get(address);
-        if (from !== undefined && record !== undefined && (record === from || reaches(record, from))) {
-            throw invalid("cycle", `${from.address} -> ${address} would create a hold cycle`);
-        }
-        if (record === undefined) {
+        const { address, normalized, principal } = this.#locate(service, input, options?.principal ?? this.principal);
+        // The provider's own placement decides, never where a request says it is going (a client picks that).
+        const placement = service.contract.description.host;
+        if (placement !== undefined && resolveHost(type.name, placement, normalized) !== this.name) {
+            throw invalid("placement", `${type.name} with this input lives on ${resolveHost(type.name, placement, normalized)}, not ${this.name}`);
+        }
+        let object = this.objects.get(address);
+        if (from !== undefined && object !== undefined && (object === from || reaches(object, from))) {
+            throw invalid("cycle", `${from.address} -> ${address} would create a ref cycle`);
+        }
+        if (object === undefined) {
             if (this.gating?.has(type.name)) {
                 throw new ChordError("upgrade_conflict", `${type.name} is being upgraded; retry`, { reason: "gate" });
             }
             const dying = this.#dying.get(address);
             if (dying?.status === "disposed")
                 this.#dying.delete(address);
-            record = new RecordImpl(this, {
+            object = new ObjectImpl(this, {
                 address,
                 typeName: type.name,
                 input: normalized,
                 principal,
-                eager: service.options.eager !== undefined && service.options.eager !== false && principal === this.principal,
+                hostLifetime: hostLifetime(service),
             });
-            this.records.set(address, record);
-            // A new record for an address still being disposed waits for that cleanup (exclusive resources).
-            record.start(dying?.status === "disposing" ? dying.dispose(false) : undefined);
+            this.objects.set(address, object);
+            // A new object for an address still being disposed waits for that cleanup (exclusive resources).
+            object.start(dying?.status === "disposing" ? dying.dispose(false) : undefined);
         }
-        const handle = new HandleImpl(record, type, owner);
-        record.addHold(handle);
-        return handle;
+        const ref = new RefImpl(object, type, owner);
+        object.addRef(ref);
+        return ref;
+    }
+    forget(object) {
+        if (this.objects.get(object.address) === object)
+            this.objects.delete(object.address);
+        if (object.status === "disposing")
+            this.#dying.set(object.address, object);
     }
-    forget(record) {
-        if (this.records.get(record.address) === record)
-            this.records.delete(record.address);
-        if (record.status === "disposing")
-            this.#dying.set(record.address, record);
+    disposed(object) {
+        if (this.#dying.get(object.address) === object)
+            this.#dying.delete(object.address);
     }
-    touch(rootId, record) {
+    touch(rootId, object) {
         let touched = this.#touches.get(rootId);
         if (touched === undefined) {
             touched = new Set();
             this.#touches.set(rootId, touched);
         }
-        touched.add(record);
+        touched.add(object);
     }
     // ─── roots ───
     async root(fn, options = {}) {
         // The incarnation keeps root ids unique across restarts of a host with the same name.
         const rootId = `${this.name}#${this.#incarnation}:${++this.#rootSeq}`;
         this.#local.add(rootId);
-        return this.joinRoot(rootId, options.epoch ?? this.current.id, fn, options);
+        return this.joinRoot(rootId, options.codeVersion ?? this.current.id, fn, options);
     }
     /**
-     * Runs `fn` inside root `rootId` of `epoch`. A root counts as running here (for retirement) while any of its calls
-     * runs here. A root that started here ends when its last call here settles, even if it went out and came back
-     * over a link meanwhile. A foreign root (started elsewhere, arriving `from` a link) keeps its leases on records
+     * Runs `fn` inside root `rootId` of `codeVersion`. A root counts as running here (for retirement) while any of its
+     * calls runs here. A root that started here ends when its last call here settles, even if it went out and came back
+     * over a link meanwhile. A foreign root (started elsewhere, arriving `from` a link) keeps its leases on objects
      * until every link it came over announced its end (`root_end`) or closed, so its re-entry stays grandfathered.
      */
-    async joinRoot(rootId, epochId, fn, options = {}) {
-        const epoch = this.epochs.get(epochId);
-        if (epoch === undefined) {
+    async joinRoot(rootId, codeVersionId, fn, options = {}) {
+        const codeVersion = this.codeVersions.get(codeVersionId);
+        if (codeVersion === undefined) {
             this.#local.delete(rootId);
-            throw new ChordError("superseded", `epoch ${epochId} is not retained by ${this.name}`);
+            throw new ChordError("superseded", `code version ${codeVersionId} is not retained by ${this.name}`);
         }
         if (options.from !== undefined && !this.#local.has(rootId)) {
             let links = this.#foreign.get(rootId);
@@ -269,11 +367,12 @@ export class HostImpl {
             }
             links.add(options.from);
         }
-        epoch.roots.set(rootId, (epoch.roots.get(rootId) ?? 0) + 1);
+        codeVersion.roots.set(rootId, (codeVersion.roots.get(rootId) ?? 0) + 1);
         const ctx = new CtxImpl(this, {
-            signal: options.signal ?? new AbortController().signal,
+            // Forced retirement aborts what still runs on a code version before closing what only it used.
+            signals: options.signal === undefined ? [codeVersion.abort.signal] : [options.signal, codeVersion.abort.signal],
             rootId,
-            epoch: epoch.id,
+            codeVersion: codeVersion.id,
             principal: options.principal ?? this.principal,
         });
         try {
@@ -281,14 +380,15 @@ export class HostImpl {
         }
         finally {
             ctx.close();
-            const count = (epoch.roots.get(rootId) ?? 1) - 1;
+            const count = (codeVersion.roots.get(rootId) ?? 1) - 1;
             if (count > 0)
-                epoch.roots.set(rootId, count);
+                codeVersion.roots.set(rootId, count);
             else {
-                epoch.roots.delete(rootId);
+                codeVersion.roots.delete(rootId);
                 if (!this.#foreign.has(rootId))
                     this.endRoot(rootId);
                 this.maybeRetire();
+                this.#retirementChanged();
             }
         }
     }
@@ -305,8 +405,8 @@ export class HostImpl {
     endRoot(rootId) {
         this.#local.delete(rootId);
         this.#foreign.delete(rootId);
-        for (const record of this.#touches.get(rootId) ?? [])
-            record.rootEnded(rootId);
+        for (const object of this.#touches.get(rootId) ?? [])
+            object.rootEnded(rootId);
         this.#touches.delete(rootId);
         for (const connection of this.#rootLinks.get(rootId) ?? [])
             connection.send({ t: "root_end", rootId });
@@ -320,7 +420,7 @@ export class HostImpl {
         const links = this.#foreign.get(rootId);
         if (links === undefined || !links.delete(from) || links.size > 0)
             return;
-        const running = [...this.epochs.values()].some((epoch) => epoch.roots.has(rootId));
+        const running = [...this.codeVersions.values()].some((codeVersion) => codeVersion.roots.has(rootId));
         // Still running here (a call in flight): the lease ends when it settles.
         if (running)
             this.#foreign.delete(rootId);
@@ -328,48 +428,71 @@ export class HostImpl {
             this.endRoot(rootId);
     }
     /**
-     * Retires the previous epoch once no local roots of it remain. A child also waits for its parent to retire it:
-     * roots span hosts, and an old root on the server may still call in.
+     * Retires the previous code version once no local roots of it remain. A child also waits for its parent to retire
+     * it: roots span hosts, and an old root on the server may still call in.
      */
     maybeRetire() {
+        if (this.retirable())
+            this.retire();
+    }
+    /** The previous code version has no roots left here and, on a child host, the parent has retired it. */
+    retirable() {
         const previous = this.previous;
         if (previous === undefined || previous.roots.size > 0)
-            return;
-        if (this.kind !== "client" && this.upstream !== undefined && previous.id > this.#retireAllowed)
-            return;
-        this.retire();
+            return false;
+        return this.kind === "client" || this.upstream === undefined || previous.id <= this.#retireAllowed;
     }
-    allowRetire(epoch) {
-        this.#retireAllowed = Math.max(this.#retireAllowed, epoch);
+    allowRetire(codeVersion) {
+        this.#retireAllowed = Math.max(this.#retireAllowed, codeVersion);
         this.maybeRetire();
+        this.#retirementChanged();
+    }
+    /** Calls `watcher` whenever a root ends, the parent allows a retirement, or a code version retires. */
+    watchRetirement(watcher) {
+        this.#retirementWatchers.add(watcher);
+        return () => this.#retirementWatchers.delete(watcher);
+    }
+    #retirementChanged() {
+        for (const watcher of [...this.#retirementWatchers])
+            watcher();
+    }
+    /**
+     * Tells a child that is now in step which code versions this host retired before: every id below the oldest one it
+     * retains (ids only grow). Without it, a child reconciled after those retirements would never hear a `retire` frame for
+     * its own previous code version and would wait for the retire deadline at every reload.
+     */
+    announceRetired(connection) {
+        const retired = (this.previous ?? this.current).id - 1;
+        if (retired > 0)
+            connection.send({ t: "retire", codeVersion: retired });
     }
-    /** Drops the previous epoch: its behaviors and the declarations only it used. */
+    /** Drops the previous code version: its implementations and the declarations only it used. */
     retire() {
         const previous = this.previous;
         if (previous === undefined)
             return;
         this.previous = undefined;
-        this.epochs.delete(previous.id);
-        for (const record of [...this.records.values()])
-            this.retireBehavior(record, previous.id);
+        this.codeVersions.delete(previous.id);
+        for (const object of [...this.objects.values()])
+            this.retireImplementation(object, previous.id);
         for (const connection of this.connections) {
             if (connection.role === "downstream" && connection.peer?.kind === "host")
-                connection.send({ t: "retire", epoch: previous.id });
+                connection.send({ t: "retire", codeVersion: previous.id });
         }
-        this.retired();
+        this.#retirementChanged();
     }
     /**
-     * Drops a record's behavior for `epoch` and what only that behavior declared, in disposal order: resources close
-     * (reverse open order) before its holds are released.
+     * Drops an object's implementation for `codeVersion` and what only that implementation declared, in disposal order:
+     * resources close (reverse open order) before its references are released.
      */
-    retireBehavior(record, epoch) {
-        const installed = record.behaviors.get(epoch);
-        record.behaviors.delete(epoch);
-        if (installed === undefined || installed.decls === record.decls)
+    retireImplementation(object, codeVersion) {
+        const installed = object.implementations.get(codeVersion);
+        object.implementations.delete(codeVersion);
+        if (installed === undefined || installed.decls === object.decls)
             return;
-        const kept = record.allDecls();
+        const kept = object.allDecls();
         const keep = (pick) => new Set([...kept].flatMap((decls) => [...pick(decls)]));
-        const holds = keep((decls) => decls.holds.values());
+        const refs = keep((decls) => decls.refs.values());
         const resources = keep((decls) => decls.resources.values());
         const derives = keep((decls) => decls.derives.values());
         for (const derived of installed.decls.derives.values())
@@ -377,21 +500,21 @@ export class HostImpl {
                 derived.detach();
         const closing = [...installed.decls.resources.values()]
             .filter((resource) => !resources.has(resource))
-            .sort((a, b) => record.openOrder.indexOf(b) - record.openOrder.indexOf(a));
-        const releasing = [...installed.decls.holds.values()].filter((hold) => !holds.has(hold));
-        record.refreshSchemas();
+            .sort((a, b) => object.openOrder.indexOf(b) - object.openOrder.indexOf(a));
+        const releasing = [...installed.decls.refs.values()].filter((ref) => !refs.has(ref));
+        object.refreshSchemas();
         runAll([
-            ...closing.map((resource) => () => resource.close(record.openOrder)),
-            ...releasing.map((hold) => () => hold.release()),
-        ], `${record.address}: retiring epoch ${epoch} failed`).catch((error) => this.report(error));
+            ...closing.map((resource) => () => resource.close(object.openOrder)),
+            ...releasing.map((ref) => () => ref.release()),
+        ], `${object.address}: retiring code version ${codeVersion} failed`).catch((error) => this.report(error));
     }
     // ─── registries ───
     registry(registry) {
         const table = (ctx) => {
-            const epoch = ctx === undefined ? this.current : this.epochs.get(ctx.epoch);
-            if (epoch === undefined)
-                throw new ChordError("superseded", `epoch ${ctx?.epoch} is retired`);
-            return (epoch.tables.get(registry.name) ?? EMPTY_TABLE);
+            const codeVersion = ctx === undefined ? this.current : this.codeVersions.get(ctx.codeVersion);
+            if (codeVersion === undefined)
+                throw new ChordError("superseded", `code version ${ctx?.codeVersion} is retired`);
+            return (codeVersion.tables.get(registry.name) ?? EMPTY_TABLE);
         };
         return {
             table,
@@ -409,10 +532,10 @@ export class HostImpl {
             },
         };
     }
-    /** Builds registry tables from (record, declarations) pairs. Throws registry_conflict. */
+    /** Builds registry tables from (object, declarations) pairs. Throws registry_conflict. */
     buildTables(entries) {
         const byRegistry = new Map();
-        for (const [record, decls] of entries) {
+        for (const [object, decls] of entries) {
             for (const { registry, key, value } of decls.registrations.values()) {
                 let entries = byRegistry.get(registry.name);
                 if (entries === undefined) {
@@ -420,10 +543,10 @@ export class HostImpl {
                     byRegistry.set(registry.name, entries);
                 }
                 const existing = entries.get(key);
-                if (existing !== undefined && existing.record !== record && registry.conflict === "error") {
-                    throw invalid("registry_conflict", `${registry.name}: ${key} registered by ${existing.record.address} and ${record.address}`);
+                if (existing !== undefined && existing.object !== object && registry.conflict === "error") {
+                    throw invalid("registry_conflict", `${registry.name}: ${key} registered by ${existing.object.address} and ${object.address}`);
                 }
-                entries.set(key, { value, record });
+                entries.set(key, { value, object });
                 let order = this.#order.get(registry.name);
                 if (order === undefined) {
                     order = new Map();
@@ -442,25 +565,25 @@ export class HostImpl {
         return tables;
     }
     /**
-     * The service a hold binds against: the current one, or for a prepare rerun (`candidate`) the running reload's
+     * The service a reference binds against: the current one, or for a prepare rerun (`candidate`) the running reload's
      * pending one, so consumer and provider of a breaking change can reload in one batch.
      */
     #bindingService(typeName, candidate) {
         return (candidate ? this.pending?.services.get(typeName) : undefined) ?? this.service(typeName);
     }
-    /** Live records with their current declarations; records waiting for a reload's commit only with `candidates`. */
+    /** Live objects with their current declarations; objects waiting for a reload's commit only with `candidates`. */
     liveDecls(candidates = false) {
-        return [...this.records.values()]
-            .filter((record) => record.status === "live" && (candidates || !record.deferredRuntime))
-            .map((record) => [record, record.decls]);
+        return [...this.objects.values()]
+            .filter((object) => object.status === "live" && (candidates || !object.deferredRuntime))
+            .map((object) => [object, object.decls]);
     }
-    checkRegistrations(record, decls) {
+    checkRegistrations(object, decls) {
         if (decls.registrations.size === 0)
             return;
-        this.buildTables([...this.liveDecls().filter(([other]) => other !== record), [record, decls]]);
+        this.buildTables([...this.liveDecls().filter(([other]) => other !== object), [object, decls]]);
     }
     registriesChanged(including) {
-        const entries = this.liveDecls().filter(([record]) => record !== including);
+        const entries = this.liveDecls().filter(([object]) => object !== including);
         if (including !== undefined)
             entries.push([including, including.decls]);
         this.installTables(this.current, this.buildTables(entries));
@@ -470,11 +593,11 @@ export class HostImpl {
         this.failed ??= error;
         this.report(error);
     }
-    /** Installs tables for `epoch`; subscribers hear about changed tables of the current epoch (all tables when `all`). */
-    installTables(epoch, tables, all = false) {
-        const before = epoch.tables;
-        epoch.tables = tables;
-        if (epoch !== this.current)
+    /** Installs tables for `codeVersion`; subscribers hear about changed tables of the current code version (all tables when `all`). */
+    installTables(codeVersion, tables, all = false) {
+        const before = codeVersion.tables;
+        codeVersion.tables = tables;
+        if (codeVersion !== this.current)
             return;
         for (const [name, listeners] of this.#subscribers) {
             const next = tables.get(name) ?? EMPTY_TABLE;
@@ -484,7 +607,7 @@ export class HostImpl {
             enqueue(() => {
                 for (const listener of current) {
                     try {
-                        listener(next, epoch.id);
+                        listener(next, codeVersion.id);
                     }
                     catch (error) {
                         this.report(error);
@@ -494,7 +617,12 @@ export class HostImpl {
         }
     }
     // ─── public API ───
-    get(type, input, options) {
+    async get(type, input, options) {
+        const ref = this.acquire(type, input, options, "external");
+        await awaitReady(ref, options?.signal === undefined ? [] : [options.signal], this.readyTimeout);
+        return ref.proxy;
+    }
+    hold(type, input, options) {
         return this.acquire(type, input, options, "external").proxy;
     }
     async invalidatePrincipal(match) {
@@ -507,7 +635,7 @@ export class HostImpl {
             // Relays under the old principal close at once, including those still resolving their route.
             connection.revoke(connection.restamp?.(connection.principal));
         }
-        // Patterns propagate to child hosts, which dispose their own matching records (e.g. relayed guests).
+        // Patterns propagate to child hosts, which dispose their own matching objects (e.g. relayed guests).
         if (typeof match !== "function") {
             for (const connection of this.connections) {
                 if (connection.role === "downstream" && connection.peer.kind === "host") {
@@ -515,7 +643,7 @@ export class HostImpl {
                 }
             }
         }
-        const matching = [...this.records.values()].filter((record) => record.principal !== this.principal && matches(record.principal));
+        const matching = [...this.objects.values()].filter((object) => !this.isSelf(object.principal) && matches(object.principal));
         await disposeHoldersFirst(matching, reason, "invalidatePrincipal: disposal failed");
     }
     // ─── links ───
@@ -528,54 +656,93 @@ export class HostImpl {
             role: "downstream",
             principal: options.principal,
             peer: { kind, name: kind === "host" ? options.name : undefined },
+            // Holds over a client link carry its id as their origin (also when relayed), so hosts can tell clients apart.
+            ...(kind === "client" ? { originId: `${this.#incarnation}:${++this.#originSeq}` } : {}),
         });
     }
-    connect(link, options = {}) {
+    connect(link, options) {
+        if (!("principal" in options))
+            throw new TypeError("connect needs `principal`: what the parent's own requests act as");
         if (this.upstream?.open)
             this.upstream.link.close("replaced");
         const connection = this.#addConnection(link, {
             ...options,
             role: "upstream",
-            principal: undefined,
+            principal: options.principal,
             peer: { kind: "host", name: undefined },
         });
         this.upstream = connection;
-        // Remote handles that lost their link re-hold over the new one; state subscribers get a reset.
-        for (const handle of this.remotes)
-            if (handle.binding === undefined)
-                connection.hold(handle);
+        // Bindings that lost their link re-hold over the new one (`again`: they keep their values meanwhile).
+        for (const binding of this.bindings.values())
+            if (binding.hold === undefined && !binding.ended)
+                connection.hold(binding, binding.applied);
     }
     #addConnection(link, config) {
         const connection = new Connection(this, link, config);
-        this.connections.add(connection);
+        // A link that was already closed closed the connection in its constructor: keeping it would route to it forever.
+        if (connection.open)
+            this.connections.add(connection);
         return connection;
     }
     route(prefix, route) {
+        if (typeof route.principal !== "function")
+            throw new TypeError(`route ${prefix} needs \`principal\`: what the routed hosts act as when they call back`);
         this.#routes.set(prefix, route);
     }
     /**
-     * A child host announced its epoch. In step: usable. Behind: fenced (nothing is routed to it) and reconciled by a
-     * reload of its modules to this host's epoch, never by renumbering what it runs. Ahead: impossible, refused.
+     * A child host announced its code version. In step: usable. Behind: fenced (nothing is routed to it) and reconciled
+     * by a reload of its modules to this host's code version, never by renumbering what it runs. Ahead: impossible,
+     * refused.
      */
-    peerHello(connection, epoch) {
-        if (epoch === this.current.id) {
-            connection.markSynced(epoch);
+    peerHello(connection, codeVersion) {
+        if (codeVersion > this.current.id) {
+            this.report(new ChordError("invalid", `${connection.name} runs code version ${codeVersion}, ahead of ${this.current.id}`));
+            connection.link.close("code version ahead of parent");
             return;
         }
-        if (epoch > this.current.id) {
-            this.report(new ChordError("invalid", `${connection.name} runs epoch ${epoch}, ahead of ${this.current.id}`));
-            connection.link.close("epoch ahead of parent");
+        if (this.reloading) {
+            // Not a participant of the running reload (participants are fixed when it starts): in step now, it would miss
+            // the commit. Decided when the reload ends. A child already behind is fenced now, so the calls its roots make
+            // meanwhile are admitted in this host's code version (never relabeled) instead of being `superseded`.
+            connection.peerCodeVersion = codeVersion;
+            if (codeVersion < this.current.id)
+                connection.fencedCodeVersions.add(codeVersion);
+            this.#deferredHellos.set(connection, codeVersion);
             return;
         }
-        connection.peerEpoch = epoch;
-        connection.fencedEpochs.add(epoch);
+        if (codeVersion === this.current.id) {
+            connection.markSynced(codeVersion);
+            this.announceRetired(connection);
+            return;
+        }
+        connection.peerCodeVersion = codeVersion;
+        connection.fencedCodeVersions.add(codeVersion);
         reconcileChild(this, connection).catch((error) => {
             this.report(error);
             connection.link.close("reconciliation failed");
         });
     }
+    /** The host's reload slot was freed: children that said hello meanwhile are synced or reconciled now. */
+    reloadEnded() {
+        this.reloading = false;
+        const deferred = [...this.#deferredHellos];
+        this.#deferredHellos.clear();
+        for (const [connection, codeVersion] of deferred)
+            if (connection.open)
+                this.peerHello(connection, codeVersion);
+        for (const resolve of this.#reloadWaiters.splice(0))
+            resolve();
+        this.maybeRetire();
+    }
+    /** Resolves once no reload runs on this host. */
+    whenReloadEnded() {
+        if (!this.reloading)
+            return Promise.resolve();
+        return new Promise((resolve) => this.#reloadWaiters.push(resolve));
+    }
     connectionClosed(connection) {
         this.connections.delete(connection);
+        this.#deferredHellos.delete(connection);
         // Foreign roots that came over this link will never announce their end over it.
         for (const [rootId, links] of [...this.#foreign])
             if (links.has(connection))
@@ -587,46 +754,78 @@ export class HostImpl {
             this.#childReloads.parentLost();
         }
     }
-    forgetRemote(handle) {
-        this.remotes.delete(handle);
+    /** The last reference to `binding` was released: it lingers if its type does (`HostOptions.linger`), else closes. */
+    bindingIdle(binding) {
+        const ms = Object.hasOwn(this.#lingerTypes, binding.contract.name)
+            ? this.#lingerTypes[binding.contract.name]
+            : 0;
+        // A binding that never had a shape has nothing worth keeping.
+        if (ms <= 0 || binding.ended || !binding.applied || this.#lingerCap <= 0) {
+            binding.close();
+            return;
+        }
+        binding.lingerTimer = setTimeout(() => binding.close(), ms);
+        binding.lingerTimer.unref?.();
+        this.#lingering.set(binding.key, binding);
+        for (const oldest of this.#lingering.values()) {
+            if (this.#lingering.size <= this.#lingerCap)
+                break;
+            oldest.close();
+        }
+    }
+    forgetBinding(binding) {
+        if (this.bindings.get(binding.key) === binding)
+            this.bindings.delete(binding.key);
+        if (this.#lingering.get(binding.key) === binding)
+            this.#lingering.delete(binding.key);
     }
     /** A downstream host connection by its configured name (never by what a peer announced). */
     #childNamed(name) {
-        return [...this.connections].find((connection) => connection.role === "downstream" && connection.peer.kind === "host" && connection.peer.name === name);
-    }
-    #acquireRemote(type, input, options, owner) {
-        const at = options.at;
-        if (type.scope !== "remote")
-            throw invalid("local", `${type.name} is local and cannot be reached at ${at}`);
-        const principal = options.principal === undefined || options.principal === this.principal ? undefined : options.principal;
-        const handle = new RemoteHandle(this, {
-            contract: type,
-            at,
-            input,
-            principal,
-            owner,
-            address: remoteAddress(at, type, input, principal),
-        });
-        this.remotes.add(handle);
+        return [...this.connections].find((connection) => connection.open &&
+            connection.role === "downstream" &&
+            connection.peer.kind === "host" &&
+            connection.peer.name === name);
+    }
+    /**
+     * A reference to an object on host `at`: a view onto the binding for its key, created (and held) if there is none.
+     * `input` is normalized with `type` (the hold carries it so).
+     */
+    #acquireRemote(type, at, input, options, owner) {
+        const principal = options?.principal === undefined || this.isSelf(options.principal) ? undefined : options.principal;
+        const key = this.#remoteKey(type, input, principal ?? this.principal);
+        let binding = this.bindings.get(key);
+        const fresh = binding === undefined || binding.ended;
+        if (binding === undefined || binding.ended) {
+            binding = new RemoteBinding(this, { key, contract: type, at, input, principal });
+            this.bindings.set(key, binding);
+        }
+        const ref = new RemoteRef(binding, owner, options?.state !== false);
+        this.#lingering.delete(key);
+        binding.addView(ref);
+        if (fresh)
+            this.#hold(binding);
+        return ref;
+    }
+    /** Holds `binding` over the link to its host: the parent's, a child's, or one a route resolves. */
+    #hold(binding) {
         const bindWhenSynced = (connection) => {
             connection.then((target) => {
-                if (handle.status === "loading" && handle.binding === undefined)
-                    target.hold(handle);
-            }, (error) => handle.gone(error));
+                if (!binding.ended && binding.hold === undefined)
+                    target.hold(binding, false);
+            }, (error) => binding.gone(error));
         };
-        const direct = this.#childNamed(at);
+        const direct = this.#childNamed(binding.at);
         if (this.upstream !== undefined)
-            this.upstream.hold(handle);
+            this.upstream.hold(binding, false);
         else if (direct !== undefined)
             bindWhenSynced(direct.whenSynced().then(() => direct));
         else {
-            const route = this.#routeFor(at);
+            const route = this.#routeFor(binding.at);
             if (route === undefined)
-                handle.gone(new ChordError("unavailable", `no route to ${at}`));
+                binding.gone(new ChordError("unavailable", `no route to ${binding.at}`));
             else
-                bindWhenSynced(this.#resolve(route, at, principal ?? this.principal));
+                bindWhenSynced(this.#resolve(route, binding.at, binding.principal ?? this.principal));
         }
-        return handle;
     }
     #routeFor(hostName) {
         let best;
@@ -654,7 +853,7 @@ export class HostImpl {
         let connection = [...this.connections].find((candidate) => candidate.link === link);
         connection ??= this.#addConnection(link, {
             role: "downstream",
-            principal: route.principal?.(hostName) ?? { host: hostName },
+            principal: route.principal(hostName),
             peer: { kind: "host", name: hostName },
         });
         await connection.whenSynced();
@@ -663,12 +862,16 @@ export class HostImpl {
         return connection;
     }
     /**
-     * Relays a hold from `relay.origin` to the host it names. Relaying needs a route: it is where authorization
+     * Relays a reference from `relay.origin` to the host it names. Relaying needs a route: it is where authorization
      * lives. The origin's authorization generation is re-checked after every await and right before forwarding, so a
      * revocation during resolution wins.
      */
     async relay(relay) {
         const at = relay.frame.at;
+        // The hold names its target; its contract token says where the type lives. They must agree.
+        const placement = contractFromDescription(relay.frame.token).description.host;
+        if (placement === undefined || resolveHost(relay.frame.token.name, placement, relay.frame.input) !== at)
+            throw invalid("placement", `${relay.frame.token.name} with this input does not live on ${at}`);
         const route = this.#routeFor(at);
         if (route === undefined) {
             throw this.#childNamed(at) === undefined
@@ -681,7 +884,7 @@ export class HostImpl {
         relay.open(down);
     }
     reload(plugins, options = {}) {
-        // Client-local facet epochs never cross the parent link; only child hosts require cluster coordination.
+        // Client-local facet code versions never cross the parent link; only child hosts require cluster coordination.
         if (this.kind !== "client" && this.upstream !== undefined) {
             return Promise.reject(new ChordError("unavailable", "reloads are coordinated by the server", { reason: "not_coordinator" }));
         }
@@ -701,19 +904,23 @@ export class HostImpl {
             this.remoteRemoved[prefix] = [...new Set([...(this.remoteRemoved[prefix] ?? []), ...removed])].filter((module) => !modules.includes(module));
         }
     }
-    /** The epoch id the next reload would commit. */
-    peekNextEpoch() {
-        return this.#epochSeq + 1;
+    /** The code version id the next reload would commit. */
+    peekNextCodeVersion() {
+        return this.#codeVersionSeq + 1;
     }
     /**
-     * Disposes every record, holders before what they hold (a resource's `close` may still use the objects its record
-     * holds, local or remote), then closes the links.
+     * Disposes every object, holders before what they reference (a resource's `close` may still use the objects its object
+     * references, local or remote), then closes the links.
      */
     async close() {
-        this.eager.clear();
+        for (const binding of [...this.#lingering.values()])
+            binding.close();
+        this.hostObjects.clear();
+        for (const name of [...this.#facetRuns.keys()])
+            this.facetRunChanged(name, undefined);
         const reason = new ChordError("gone", `host ${this.name} closed`);
         try {
-            await disposeHoldersFirst([...this.records.values()], reason, "host close: disposal failed");
+            await disposeHoldersFirst([...this.objects.values()], reason, "host close: disposal failed");
         }
         finally {
             for (const connection of [...this.connections])
@@ -722,35 +929,35 @@ export class HostImpl {
     }
 }
 /**
- * Force-disposes `records` in waves: a record goes once no record of the set that holds it is left, so holders are
- * disposed (and their resources closed) while what they hold is still live. In-host holds are acyclic. Errors of
+ * Force-disposes `objects` in waves: an object goes once no object of the set that references it is left, so holders are
+ * disposed (and their resources closed) while what they reference is still live. In-host references are acyclic. Errors of
  * every disposal are collected.
  */
-async function disposeHoldersFirst(records, reason, message) {
-    const remaining = new Set(records);
-    const held = (record) => {
+async function disposeHoldersFirst(objects, reason, message) {
+    const remaining = new Set(objects);
+    const held = (object) => {
         const result = new Set();
-        for (const decls of record.allDecls()) {
-            for (const hold of decls.holds.values())
-                if (hold.record !== undefined)
-                    result.add(hold.record);
+        for (const decls of object.allDecls()) {
+            for (const ref of decls.refs.values())
+                if (ref.object !== undefined)
+                    result.add(ref.object);
         }
         return result;
     };
-    const holds = new Map(records.map((record) => [record, held(record)]));
+    const refs = new Map(objects.map((object) => [object, held(object)]));
     const errors = [];
     while (remaining.size > 0) {
         const heldByRemaining = new Set();
-        for (const record of remaining)
-            for (const target of holds.get(record) ?? [])
+        for (const object of remaining)
+            for (const target of refs.get(object) ?? [])
                 heldByRemaining.add(target);
-        let wave = [...remaining].filter((record) => !heldByRemaining.has(record));
+        let wave = [...remaining].filter((object) => !heldByRemaining.has(object));
         // A cycle cannot happen in-host; dispose the rest together rather than loop.
         if (wave.length === 0)
             wave = [...remaining];
-        for (const record of wave)
-            remaining.delete(record);
-        const results = await Promise.allSettled(wave.map((record) => record.dispose(true, reason)));
+        for (const object of wave)
+            remaining.delete(object);
+        const results = await Promise.allSettled(wave.map((object) => object.dispose(true, reason)));
         for (const result of results)
             if (result.status === "rejected")
                 errors.push(result.reason);
@@ -769,25 +976,23 @@ function sameTable(a, b) {
 const matchesPattern = (pattern, principal) => principal !== null &&
     typeof principal === "object" &&
     Object.entries(pattern).every(([key, value]) => deepEqual(principal[key], value));
-/** Address of a remote hold, as the consumer sees it (the provider normalizes the input). */
-const remoteAddress = (at, type, input, principal) => `@${at}\u0000${type.name}\u0000${canonicalJson(input)}\u0000${principal === undefined ? "host" : canonicalJson(principal)}`;
 const unknownType = (type, host) => new ChordError("unavailable", `${type} is not served by ${host}`, { reason: "unknown_type" });
-/** True if `from` holds `to`, directly or transitively, through record-owned holds on this host. */
+/** True if `from` references `to`, directly or transitively, through object-owned references on this host. */
 function reaches(from, to) {
     const seen = new Set();
     const stack = [from];
     while (stack.length > 0) {
-        const record = stack.pop();
-        if (record === to)
+        const object = stack.pop();
+        if (object === to)
             return true;
-        if (seen.has(record))
+        if (seen.has(object))
             continue;
-        seen.add(record);
-        // Remote holds have no record here: cycles across hosts are avoided by convention.
-        for (const decls of record.allDecls()) {
-            for (const hold of decls.holds.values())
-                if (hold.record !== undefined)
-                    stack.push(hold.record);
+        seen.add(object);
+        // Remote references have no object here: cycles across hosts are avoided by convention.
+        for (const decls of object.allDecls()) {
+            for (const ref of decls.refs.values())
+                if (ref.object !== undefined)
+                    stack.push(ref.object);
         }
     }
     return false;