operon-agents 0.1.0-alpha.0

package/dist/extensions/services.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Process-level service registry with handle indirection — the substrate for hot-swapping
+ * shared instances (design: docs/architecture.md §5.5).
+ *
+ * Consumers never hold a service instance. `handle()` returns a stable Proxy that resolves
+ * the CURRENT table entry on every method call and holds a lease for exactly that call, so
+ * replacing a provider is a registry-local act — swap the entry, drain the old instance's
+ * leases, dispose it — with no session participation at all. The invariant this file exists
+ * to keep: at any moment only one generation of a service is being handed out.
+ *
+ * Handles expose METHODS ONLY. A method's return value must not carry the instance (no
+ * `return this`, no objects closing over it) — that is the one leak the Proxy cannot stop.
+ */
+export type ServiceUnavailableReason = "missing" | "draining";
+export declare class ServiceUnavailableError extends Error {
+    readonly serviceName: string;
+    readonly reason: ServiceUnavailableReason;
+    constructor(serviceName: string, reason: ServiceUnavailableReason);
+}
+export interface ServiceOptions {
+    /** Absent/false = `replace()` rejects; swapping this service means restarting the process. */
+    readonly replaceable?: boolean;
+    /** Called once the old instance has drained. Default: call `instance.close()` when present. */
+    readonly dispose?: (instance: unknown) => void | Promise<void>;
+}
+export declare class ServiceRegistry {
+    private readonly table;
+    private readonly handles;
+    /** Per-name op chain: concurrent replace/unregister serialize instead of interleaving. */
+    private readonly ops;
+    private readonly warn;
+    constructor(options?: {
+        readonly warn?: (message: string) => void;
+    });
+    /** Register a service under a unique name. Duplicate names fail closed — an extension that
+     *  wants to take over an existing name must go through `replace`, never shadow. */
+    register(name: string, instance: unknown, options?: ServiceOptions): void;
+    has(name: string): boolean;
+    /**
+     * The stable handle for a service — safe to take before the service is registered and to
+     * keep across replaces. Property access requires a method (a non-function property throws:
+     * replaceable services expose methods only); availability is judged at CALL time, so a
+     * handle taken during early setup never explodes on mere property access.
+     */
+    handle<T = unknown>(name: string): T;
+    /**
+     * Swap the provider behind a name. Atomic from the consumers' side: the very next handle
+     * call lands on `next`; calls already in flight finish on the old instance, which is
+     * disposed once its leases drain (or after `drainTimeoutMs`, logged, default 10s).
+     *
+     * `force` skips the `replaceable` gate. It exists for ONE caller — `harness.replaceExtension`,
+     * where the extension that OWNS this service is being replaced along with it, inside the
+     * barrier's quiet moment. The gate guards the other case (a host swapping an instance under a
+     * live owner that never agreed to it), which is why it stays closed by default.
+     */
+    replace(name: string, next: unknown, options?: {
+        readonly drainTimeoutMs?: number;
+        readonly force?: boolean;
+    }): Promise<void>;
+    /**
+     * Remove a service entirely (extension unload). Unlike `replace`, callers see "draining"
+     * during the drain and "missing" after — there is deliberately no replaceable gate here:
+     * unload is the host/loader tearing an extension's service down, not swapping code under consumers.
+     */
+    unregister(name: string, options?: {
+        readonly drainTimeoutMs?: number;
+    }): Promise<void>;
+    private invoke;
+    private enqueueOp;
+    private retire;
+    private drainLeases;
+    private disposeOf;
+}
+/** A handle whose every call throws "missing" — handed to detached extensions and to
+ *  extensions on hosts that expose no services, mirroring the actions revocation collar. */
+export declare function deadServiceHandle<T = unknown>(name: string): T;
+/**
+ * Properties a proxy must NEVER intercept with a throw or a fake method — the probe surface
+ * generic JS pokes at (await → `then`, JSON.stringify → `toJSON` via the absent-property rule,
+ * class checks → `prototype`/`constructor`, test/inspect utilities → `_`-prefixed, serializers →
+ * numeric indices, symbols everywhere). Cordis's reflect layer converged on this exact list
+ * over years of proxy bugs (`isSpecialProperty`); we adopt it wholesale.
+ */
+export declare function isProbeProperty(prop: string | symbol): boolean;
+//# sourceMappingURL=services.d.ts.map

package/dist/extensions/services.js

@@ -0,0 +1,265 @@
+/**
+ * Process-level service registry with handle indirection — the substrate for hot-swapping
+ * shared instances (design: docs/architecture.md §5.5).
+ *
+ * Consumers never hold a service instance. `handle()` returns a stable Proxy that resolves
+ * the CURRENT table entry on every method call and holds a lease for exactly that call, so
+ * replacing a provider is a registry-local act — swap the entry, drain the old instance's
+ * leases, dispose it — with no session participation at all. The invariant this file exists
+ * to keep: at any moment only one generation of a service is being handed out.
+ *
+ * Handles expose METHODS ONLY. A method's return value must not carry the instance (no
+ * `return this`, no objects closing over it) — that is the one leak the Proxy cannot stop.
+ */
+export class ServiceUnavailableError extends Error {
+    serviceName;
+    reason;
+    constructor(serviceName, reason) {
+        super(reason === "missing"
+            ? `service "${serviceName}" is not registered`
+            : `service "${serviceName}" is shutting down`);
+        this.name = "ServiceUnavailableError";
+        this.serviceName = serviceName;
+        this.reason = reason;
+    }
+}
+const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
+export class ServiceRegistry {
+    table = new Map();
+    handles = new Map();
+    /** Per-name op chain: concurrent replace/unregister serialize instead of interleaving. */
+    ops = new Map();
+    warn;
+    constructor(options = {}) {
+        this.warn = options.warn ?? ((message) => console.warn(`[services] ${message}`));
+    }
+    /** Register a service under a unique name. Duplicate names fail closed — an extension that
+     *  wants to take over an existing name must go through `replace`, never shadow. */
+    register(name, instance, options = {}) {
+        if (name.length === 0)
+            throw new Error("service name must be non-empty");
+        if (this.table.has(name))
+            throw new Error(`service "${name}" is already registered`);
+        this.table.set(name, {
+            instance,
+            generation: 1,
+            leases: 0,
+            draining: false,
+            replaceable: options.replaceable === true,
+            ...(options.dispose !== undefined ? { dispose: options.dispose } : {}),
+        });
+    }
+    has(name) {
+        const entry = this.table.get(name);
+        return entry !== undefined && !entry.draining;
+    }
+    /**
+     * The stable handle for a service — safe to take before the service is registered and to
+     * keep across replaces. Property access requires a method (a non-function property throws:
+     * replaceable services expose methods only); availability is judged at CALL time, so a
+     * handle taken during early setup never explodes on mere property access.
+     */
+    handle(name) {
+        const cached = this.handles.get(name);
+        if (cached !== undefined)
+            return cached;
+        const registry = this;
+        const proxy = new Proxy(Object.create(null), {
+            get(_target, prop) {
+                // Probe surface reads as undefined (await, JSON.stringify, inspect, test utilities —
+                // see isProbeProperty): probes must never throw or receive a fake method.
+                if (isProbeProperty(prop))
+                    return undefined;
+                const key = prop; // symbols were filtered by the probe check
+                const entry = registry.table.get(name);
+                if (entry !== undefined) {
+                    const value = entry.instance[key];
+                    // Absent entirely → undefined (probe-safe, and a typo'd method fails naturally at
+                    // the call site). Present but NOT a method → the discipline throw: field access is
+                    // the one real violation ("replaceable services expose methods only").
+                    if (value === undefined && !(key in entry.instance))
+                        return undefined;
+                    if (typeof value !== "function") {
+                        throw new TypeError(`service "${name}": "${key}" is not a method — replaceable services expose methods only`);
+                    }
+                }
+                return (...args) => registry.invoke(name, key, args);
+            },
+            has(_target, prop) {
+                const entry = registry.table.get(name);
+                return (entry !== undefined &&
+                    typeof prop === "string" &&
+                    typeof entry.instance[prop] === "function");
+            },
+        });
+        this.handles.set(name, proxy);
+        return proxy;
+    }
+    /**
+     * Swap the provider behind a name. Atomic from the consumers' side: the very next handle
+     * call lands on `next`; calls already in flight finish on the old instance, which is
+     * disposed once its leases drain (or after `drainTimeoutMs`, logged, default 10s).
+     *
+     * `force` skips the `replaceable` gate. It exists for ONE caller — `harness.replaceExtension`,
+     * where the extension that OWNS this service is being replaced along with it, inside the
+     * barrier's quiet moment. The gate guards the other case (a host swapping an instance under a
+     * live owner that never agreed to it), which is why it stays closed by default.
+     */
+    replace(name, next, options = {}) {
+        return this.enqueueOp(name, async () => {
+            const old = this.table.get(name);
+            if (old === undefined)
+                throw new Error(`cannot replace service "${name}": not registered`);
+            if (!old.replaceable && options.force !== true) {
+                throw new Error(`service "${name}" is not replaceable — register it with { replaceable: true }, or restart the process to change it`);
+            }
+            this.table.set(name, {
+                instance: next,
+                generation: old.generation + 1,
+                leases: 0,
+                draining: false,
+                replaceable: old.replaceable,
+                ...(old.dispose !== undefined ? { dispose: old.dispose } : {}),
+            });
+            await this.retire(old, name, options.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS);
+        });
+    }
+    /**
+     * Remove a service entirely (extension unload). Unlike `replace`, callers see "draining"
+     * during the drain and "missing" after — there is deliberately no replaceable gate here:
+     * unload is the host/loader tearing an extension's service down, not swapping code under consumers.
+     */
+    unregister(name, options = {}) {
+        return this.enqueueOp(name, async () => {
+            const entry = this.table.get(name);
+            if (entry === undefined)
+                return;
+            entry.draining = true;
+            await this.drainLeases(entry, name, options.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS);
+            this.table.delete(name);
+            await this.disposeOf(entry, name);
+        });
+    }
+    invoke(name, prop, args) {
+        const entry = this.table.get(name);
+        if (entry === undefined || entry.draining) {
+            throw new ServiceUnavailableError(name, entry === undefined ? "missing" : "draining");
+        }
+        const fn = entry.instance[prop];
+        if (typeof fn !== "function") {
+            throw new TypeError(`service "${name}": "${prop}" is not a method — replaceable services expose methods only`);
+        }
+        // The lease covers exactly this call. Resolve-at-call is what makes a swap between two
+        // calls land the next call on the new instance with zero consumer cooperation.
+        entry.leases += 1;
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            entry.leases -= 1;
+            if (entry.leases === 0 && entry.draining)
+                entry.onDrained?.();
+        };
+        let result;
+        try {
+            result = fn.apply(entry.instance, args);
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+        if (isPromiseLike(result))
+            return Promise.resolve(result).finally(release);
+        release();
+        return result;
+    }
+    enqueueOp(name, run) {
+        const prev = this.ops.get(name) ?? Promise.resolve();
+        const next = prev.then(() => run(), () => run());
+        // The chain must survive a rejected op; the rejection still reaches that op's caller.
+        this.ops.set(name, next.catch(() => undefined));
+        return next;
+    }
+    async retire(old, name, drainTimeoutMs) {
+        old.draining = true;
+        await this.drainLeases(old, name, drainTimeoutMs);
+        await this.disposeOf(old, name);
+    }
+    async drainLeases(entry, name, timeoutMs) {
+        if (entry.leases === 0)
+            return;
+        const drained = new Promise((resolve) => {
+            entry.onDrained = resolve;
+        });
+        // Re-check after wiring the callback: the last lease may have released in between.
+        if (entry.leases === 0)
+            return;
+        let timer;
+        const timedOut = await Promise.race([
+            drained.then(() => false),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(true), timeoutMs);
+            }),
+        ]);
+        clearTimeout(timer);
+        if (timedOut) {
+            this.warn(`service "${name}": disposing with ${entry.leases} lease(s) still outstanding after ${timeoutMs}ms drain timeout`);
+        }
+    }
+    async disposeOf(entry, name) {
+        try {
+            if (entry.dispose !== undefined) {
+                await entry.dispose(entry.instance);
+            }
+            else {
+                const close = entry.instance?.close;
+                if (typeof close === "function")
+                    await close.call(entry.instance);
+            }
+        }
+        catch (error) {
+            this.warn(`service "${name}": dispose failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+/** A handle whose every call throws "missing" — handed to detached extensions and to
+ *  extensions on hosts that expose no services, mirroring the actions revocation collar. */
+export function deadServiceHandle(name) {
+    return new Proxy(Object.create(null), {
+        get(_target, prop) {
+            if (isProbeProperty(prop))
+                return undefined;
+            return () => {
+                throw new ServiceUnavailableError(name, "missing");
+            };
+        },
+        // `in` is the registration probe (thin shells use it to fall back to a direct instance);
+        // a dead handle answers no to everything.
+        has() {
+            return false;
+        },
+    });
+}
+/**
+ * Properties a proxy must NEVER intercept with a throw or a fake method — the probe surface
+ * generic JS pokes at (await → `then`, JSON.stringify → `toJSON` via the absent-property rule,
+ * class checks → `prototype`/`constructor`, test/inspect utilities → `_`-prefixed, serializers →
+ * numeric indices, symbols everywhere). Cordis's reflect layer converged on this exact list
+ * over years of proxy bugs (`isSpecialProperty`); we adopt it wholesale.
+ */
+export function isProbeProperty(prop) {
+    return (typeof prop === "symbol" ||
+        prop === "then" ||
+        prop === "toJSON" ||
+        prop === "prototype" ||
+        prop === "constructor" ||
+        String(parseInt(prop, 10)) === prop ||
+        prop.startsWith("_"));
+}
+function isPromiseLike(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        typeof value.then === "function");
+}
+//# sourceMappingURL=services.js.map