@cortexkit/aft-bridge 0.49.3 → 0.49.4

package/dist/lifecycle-registry.d.ts

@@ -0,0 +1,196 @@
+/** A canonical project root. The registry never derives identity by parsing it. */
+declare const canonicalRootPathBrand: unique symbol;
+export type CanonicalRootPath = string & {
+    readonly [canonicalRootPathBrand]: "CanonicalRootPath";
+};
+/** A pool-lifetime root generation. Generations are strictly increasing per root. */
+declare const rootGenerationBrand: unique symbol;
+export type RootGeneration = number & {
+    readonly [rootGenerationBrand]: "RootGeneration";
+};
+/** A realm-local concrete pool identity. IDs are never reused by a registry. */
+declare const concretePoolIdBrand: unique symbol;
+export type ConcretePoolId = string & {
+    readonly [concretePoolIdBrand]: "ConcretePoolId";
+};
+/**
+ * Immutable provenance for one registration handle. The object identity is the
+ * deregistration authority; the serial fields make the provenance inspectable
+ * without treating a pool object as a registration token.
+ */
+export interface RegistrationIdentity {
+    readonly concretePoolId: ConcretePoolId;
+    readonly registrationSequence: number;
+}
+export declare function asCanonicalRootPath(root: string): CanonicalRootPath;
+export declare function asRootGeneration(generation: number): RootGeneration;
+export declare function asConcretePoolId(id: string): ConcretePoolId;
+export type LifecycleCloseCause = "sweep" | "explicit";
+export type LifecycleRootState = "live" | "reaping" | "tombstoned";
+/** Counts returned by a concrete pool after it has detached its indexed records. */
+export interface LifecycleTeardownResult {
+    readonly tornDownSessionCount?: number;
+    readonly tornDownFacadeCount?: number;
+}
+/** The concrete-pool portion of the lifecycle contract. */
+export interface LifecyclePool {
+    closeProjectRoot(root: CanonicalRootPath, generation: RootGeneration): unknown;
+}
+export interface LifecyclePoolRegistrationOptions {
+    readonly reapingEnabled: boolean;
+    readonly evictOuterFacade: (root: CanonicalRootPath, generation: RootGeneration) => void;
+}
+export interface LifecyclePoolRegistration {
+    readonly concretePoolId: ConcretePoolId;
+    readonly reapingEnabled: boolean;
+    readonly registrationIdentity: RegistrationIdentity;
+    /** Short alias for callers that refer to the provenance token as identity. */
+    readonly identity: RegistrationIdentity;
+    deregister(): void;
+}
+export type LifecycleStatResult = boolean | {
+    readonly exists?: boolean;
+} | unknown;
+export type LifecycleStat = (root: CanonicalRootPath, concretePoolId: ConcretePoolId, generation: RootGeneration) => LifecycleStatResult | Promise<LifecycleStatResult>;
+export type LifecycleDemandCheck = (root: CanonicalRootPath, concretePoolId: ConcretePoolId) => boolean | {
+    readonly exists?: boolean;
+} | Promise<boolean | {
+    readonly exists?: boolean;
+}>;
+export interface LifecycleTimerSeam {
+    setInterval(callback: () => void, delayMs: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+export interface RootReapedLifecycleEvent {
+    readonly type: "subc_root_reaped";
+    readonly realm: string;
+    readonly concretePoolId: ConcretePoolId;
+    readonly canonicalRoot: CanonicalRootPath;
+    readonly generation: RootGeneration;
+    readonly consecutiveAbsenceCount: number;
+    readonly tornDownSessionCount: number;
+    readonly tornDownFacadeCount: number;
+    readonly cause: LifecycleCloseCause;
+}
+export interface RootGenerationRejectedLifecycleEvent {
+    readonly type: "subc_root_generation_rejected";
+    readonly realm: string;
+    readonly concretePoolId: ConcretePoolId;
+    readonly canonicalRoot: CanonicalRootPath;
+    readonly expectedGeneration: RootGeneration;
+    readonly currentGeneration?: RootGeneration;
+    readonly boundary: string;
+}
+export type LifecycleEvent = RootReapedLifecycleEvent | RootGenerationRejectedLifecycleEvent;
+export interface LifecycleRegistryOptions {
+    /** Label attached to realm-local metrics and lifecycle events. */
+    readonly realm?: string;
+    /** Production cadence. Tests normally replace the timer and use a short value. */
+    readonly intervalMs?: number;
+    readonly timer?: LifecycleTimerSeam;
+    readonly setInterval?: LifecycleTimerSeam["setInterval"];
+    readonly clearInterval?: LifecycleTimerSeam["clearInterval"];
+    /** A stat that resolves for an existing root and rejects with ENOENT when absent. */
+    readonly stat?: LifecycleStat;
+    /** Positive demand is the only signal that permits an initial or successor root. */
+    readonly demandCheck?: LifecycleDemandCheck;
+    readonly onEvent?: (event: LifecycleEvent) => void;
+}
+export interface LifecycleRootSnapshot {
+    readonly concretePoolId: ConcretePoolId;
+    readonly registrationIdentity: RegistrationIdentity;
+    readonly canonicalRoot: CanonicalRootPath;
+    readonly generation: RootGeneration;
+    readonly state: LifecycleRootState;
+    readonly consecutiveAbsences: number;
+}
+export interface LifecycleRegistrationSnapshot {
+    readonly concretePoolId: ConcretePoolId;
+    readonly reapingEnabled: boolean;
+    readonly roots: readonly LifecycleRootSnapshot[];
+}
+export interface LifecycleRegistrySnapshot {
+    readonly realm: string;
+    readonly intervalMs: number;
+    readonly timerActive: boolean;
+    readonly registrations: readonly LifecycleRegistrationSnapshot[];
+}
+export declare const DEFAULT_LIFECYCLE_INTERVAL_MS: number;
+/**
+ * One lifecycle registry per JavaScript module realm.
+ *
+ * The registry deliberately knows only the concrete pool's root-close seam. It
+ * owns root generations, absence observations, and transition ownership, while
+ * the concrete pool remains responsible for indexed session and route cleanup.
+ */
+export declare class LifecycleRegistry {
+    readonly realm: string;
+    readonly intervalMs: number;
+    private readonly registrations;
+    private readonly registrationByPool;
+    private readonly nextGenerationByRoot;
+    private nextConcretePoolNumber;
+    private nextRegistrationSequence;
+    private readonly timer;
+    private readonly statRoot;
+    private readonly demand;
+    private readonly onEvent?;
+    private intervalHandle;
+    private sweepInFlight;
+    constructor(options?: LifecycleRegistryOptions);
+    /** Register an unregistered concrete pool and permanently bind its reapingEnabled setting. */
+    registerLifecyclePool(pool: LifecyclePool, options: LifecyclePoolRegistrationOptions): LifecyclePoolRegistration;
+    /** Functional form used by construction sites that keep a registry instance. */
+    registerPool(pool: LifecyclePool, options: LifecyclePoolRegistrationOptions): LifecyclePoolRegistration;
+    /** Register a root before its facade is exposed. Repeated live registration is idempotent. */
+    registerRoot(poolId: ConcretePoolId, root: CanonicalRootPath): RootGeneration;
+    /**
+     * Get an existing live generation without creating one. This is the only
+     * non-creating lookup used by status and background paths.
+     */
+    currentGeneration(poolId: ConcretePoolId, root: CanonicalRootPath): RootGeneration | undefined;
+    isTombstoned(poolId: ConcretePoolId, root: CanonicalRootPath, generation: RootGeneration): boolean;
+    isCurrentRegistration(identity: RegistrationIdentity): boolean;
+    isCurrentLiveGeneration(poolId: ConcretePoolId, root: CanonicalRootPath, generation: RootGeneration): boolean;
+    getRootSnapshot(poolId: ConcretePoolId, root: CanonicalRootPath): LifecycleRootSnapshot | undefined;
+    /** Return only roots visible to lifecycle operations; tombstones are retained until close settles. */
+    rootSnapshots(poolId?: ConcretePoolId): LifecycleRootSnapshot[];
+    snapshot(): LifecycleRegistrySnapshot;
+    /** Alias for callers that use status terminology. */
+    status(): LifecycleRegistrySnapshot;
+    /**
+     * Demand gate for initial and successor creation. A live root is returned
+     * without repeating the filesystem check; absent roots require a fresh positive
+     * result and then receive exactly one greater generation.
+     */
+    ensureRootForDemand(poolId: ConcretePoolId, root: CanonicalRootPath): Promise<RootGeneration | undefined>;
+    demandRoot(poolId: ConcretePoolId, root: CanonicalRootPath): Promise<RootGeneration | undefined>;
+    getBridgeDemand(poolId: ConcretePoolId, root: CanonicalRootPath): Promise<RootGeneration | undefined>;
+    /**
+     * Coordinate one generation's close. The live-to-reaping transition, tombstone,
+     * outer eviction, and concrete close invocation all happen before the returned
+     * promise can yield. Concurrent requests coalesce on the same close promise.
+     */
+    requestProjectRootClose(poolId: ConcretePoolId, root: CanonicalRootPath, expectedGeneration: RootGeneration, cause?: LifecycleCloseCause): Promise<void>;
+    /** Coalesce concurrent ticks and observe only enabled, live registrations. */
+    sweep(): Promise<void>;
+    /** Alias used by timer seams and tests. */
+    sweepNow(): Promise<void>;
+    /** Emit a generation-rejection event when a lifecycle boundary refuses the expected generation. */
+    recordGenerationRejection(poolId: ConcretePoolId, root: CanonicalRootPath, expectedGeneration: RootGeneration, boundary: string): void;
+    rejectGeneration(poolId: ConcretePoolId, root: CanonicalRootPath, expectedGeneration: RootGeneration, boundary: string): void;
+    private runSweep;
+    private currentRegistration;
+    private currentRoot;
+    private snapshotRoot;
+    private finishRootClose;
+    private deregisterInternal;
+    private refreshTimer;
+    private emit;
+}
+/** Create a lifecycle registry for callers that do not inject one; use getLifecycleRegistry() for the shared default. */
+export declare function createLifecycleRegistry(options?: LifecycleRegistryOptions): LifecycleRegistry;
+export declare function getLifecycleRegistry(): LifecycleRegistry;
+export { LifecycleRegistry as SubcLifecycleRegistry };
+export declare function registerLifecyclePool(pool: LifecyclePool, options: LifecyclePoolRegistrationOptions): LifecyclePoolRegistration;
+//# sourceMappingURL=lifecycle-registry.d.ts.map

package/dist/lifecycle-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-registry.d.ts","sourceRoot":"","sources":["../src/lifecycle-registry.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle-registry.js

@@ -0,0 +1,471 @@
+import { lstat } from "node:fs/promises";
+export function asCanonicalRootPath(root) {
+    return root;
+}
+export function asRootGeneration(generation) {
+    if (!Number.isSafeInteger(generation) || generation < 1) {
+        throw new RangeError("root generations must be positive safe integers");
+    }
+    return generation;
+}
+export function asConcretePoolId(id) {
+    return id;
+}
+export const DEFAULT_LIFECYCLE_INTERVAL_MS = 5 * 60 * 1000;
+const DEFAULT_REALM = "default";
+function rootKey(root) {
+    return root;
+}
+function resultMeansPresent(result) {
+    if (typeof result === "boolean")
+        return result;
+    if (typeof result === "object" && result !== null && "exists" in result) {
+        return result.exists !== false;
+    }
+    return true;
+}
+function isEnoent(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function closeCounts(result) {
+    const teardown = typeof result === "object" && result !== null ? result : undefined;
+    const sessions = teardown?.tornDownSessionCount;
+    const facades = teardown?.tornDownFacadeCount;
+    return {
+        sessions: typeof sessions === "number" && Number.isFinite(sessions) ? Math.max(0, sessions) : 0,
+        facades: typeof facades === "number" && Number.isFinite(facades) ? Math.max(0, facades) : 0,
+    };
+}
+function defaultTimer() {
+    return {
+        setInterval(callback, delayMs) {
+            const handle = setInterval(callback, delayMs);
+            const maybeUnref = handle;
+            maybeUnref.unref?.();
+            return handle;
+        },
+        clearInterval(handle) {
+            clearInterval(handle);
+        },
+    };
+}
+/**
+ * One lifecycle registry per JavaScript module realm.
+ *
+ * The registry deliberately knows only the concrete pool's root-close seam. It
+ * owns root generations, absence observations, and transition ownership, while
+ * the concrete pool remains responsible for indexed session and route cleanup.
+ */
+export class LifecycleRegistry {
+    realm;
+    intervalMs;
+    registrations = new Map();
+    registrationByPool = new WeakMap();
+    nextGenerationByRoot = new Map();
+    nextConcretePoolNumber = 1;
+    nextRegistrationSequence = 1;
+    timer;
+    statRoot;
+    demand;
+    onEvent;
+    intervalHandle = null;
+    sweepInFlight = null;
+    constructor(options = {}) {
+        this.realm = options.realm ?? DEFAULT_REALM;
+        this.intervalMs = options.intervalMs ?? DEFAULT_LIFECYCLE_INTERVAL_MS;
+        if (!Number.isFinite(this.intervalMs) || this.intervalMs <= 0) {
+            throw new RangeError("lifecycle interval must be a positive finite number");
+        }
+        const nativeTimer = defaultTimer();
+        this.timer =
+            options.timer ??
+                (options.setInterval || options.clearInterval
+                    ? {
+                        setInterval: options.setInterval ?? nativeTimer.setInterval,
+                        clearInterval: options.clearInterval ?? nativeTimer.clearInterval,
+                    }
+                    : nativeTimer);
+        this.statRoot = options.stat ?? ((root) => lstat(root));
+        this.demand = options.demandCheck ?? (() => false);
+        this.onEvent = options.onEvent;
+    }
+    /** Register an unregistered concrete pool and permanently bind its reapingEnabled setting. */
+    registerLifecyclePool(pool, options) {
+        if (!pool || typeof pool.closeProjectRoot !== "function") {
+            throw new TypeError("a lifecycle pool must provide closeProjectRoot");
+        }
+        if (typeof options?.evictOuterFacade !== "function") {
+            throw new TypeError("lifecycle registration requires evictOuterFacade");
+        }
+        if (typeof options.reapingEnabled !== "boolean") {
+            throw new TypeError("reapingEnabled must be a boolean");
+        }
+        const previous = this.registrationByPool.get(pool);
+        if (previous?.active)
+            this.deregisterInternal(previous);
+        const concretePoolId = asConcretePoolId(`pool-${this.nextConcretePoolNumber++}`);
+        const registrationIdentity = Object.freeze({
+            concretePoolId,
+            registrationSequence: this.nextRegistrationSequence++,
+        });
+        const internal = {
+            pool,
+            concretePoolId,
+            registrationIdentity,
+            reapingEnabled: options.reapingEnabled,
+            evictOuterFacade: options.evictOuterFacade,
+            roots: new Map(),
+            handle: undefined,
+            active: true,
+        };
+        const handle = {
+            registrationIdentity,
+            identity: registrationIdentity,
+            get concretePoolId() {
+                return concretePoolId;
+            },
+            get reapingEnabled() {
+                return internal.reapingEnabled;
+            },
+            deregister: () => {
+                this.deregisterInternal(internal);
+            },
+        };
+        internal.handle = handle;
+        this.registrations.set(concretePoolId, internal);
+        this.registrationByPool.set(pool, internal);
+        this.refreshTimer();
+        return handle;
+    }
+    /** Functional form used by construction sites that keep a registry instance. */
+    registerPool(pool, options) {
+        return this.registerLifecyclePool(pool, options);
+    }
+    /** Register a root before its facade is exposed. Repeated live registration is idempotent. */
+    registerRoot(poolId, root) {
+        const registration = this.currentRegistration(poolId);
+        if (!registration)
+            throw new Error(`unknown lifecycle pool ${poolId}`);
+        const key = rootKey(root);
+        const existing = registration.roots.get(key);
+        if (existing?.state === "live")
+            return existing.generation;
+        if (existing && !existing.synchronousPhaseComplete) {
+            // This is only reachable through re-entrant code in the synchronous close
+            // phase. Exposing the old generation would permit resurrection, so callers
+            // must wait until that phase has finished and ask again.
+            throw new Error("root registration raced its synchronous close phase");
+        }
+        const next = (this.nextGenerationByRoot.get(`${poolId}\u0000${key}`) ?? 0) + 1;
+        this.nextGenerationByRoot.set(`${poolId}\u0000${key}`, next);
+        const entry = {
+            registration,
+            canonicalRoot: root,
+            generation: asRootGeneration(next),
+            state: "live",
+            consecutiveAbsences: 0,
+            tombstoned: false,
+            synchronousPhaseComplete: true,
+            closePromise: null,
+            eventEmitted: false,
+            cause: null,
+        };
+        registration.roots.set(key, entry);
+        return entry.generation;
+    }
+    /**
+     * Get an existing live generation without creating one. This is the only
+     * non-creating lookup used by status and background paths.
+     */
+    currentGeneration(poolId, root) {
+        return this.currentRoot(poolId, root)?.generation;
+    }
+    isTombstoned(poolId, root, generation) {
+        const entry = this.currentRoot(poolId, root);
+        return entry?.generation === generation && entry.tombstoned;
+    }
+    isCurrentRegistration(identity) {
+        const registration = this.registrations.get(identity.concretePoolId);
+        return registration?.active === true && registration.registrationIdentity === identity;
+    }
+    isCurrentLiveGeneration(poolId, root, generation) {
+        const entry = this.currentRoot(poolId, root);
+        return entry?.generation === generation && entry.state === "live";
+    }
+    getRootSnapshot(poolId, root) {
+        const entry = this.currentRoot(poolId, root);
+        return entry ? this.snapshotRoot(entry) : undefined;
+    }
+    /** Return only roots visible to lifecycle operations; tombstones are retained until close settles. */
+    rootSnapshots(poolId) {
+        const entries = poolId
+            ? [this.currentRegistration(poolId)].filter((registration) => registration != null)
+            : [...this.registrations.values()];
+        return entries.flatMap((registration) => [...registration.roots.values()].map((entry) => this.snapshotRoot(entry)));
+    }
+    snapshot() {
+        return {
+            realm: this.realm,
+            intervalMs: this.intervalMs,
+            timerActive: this.intervalHandle !== null,
+            registrations: [...this.registrations.values()].map((registration) => ({
+                concretePoolId: registration.concretePoolId,
+                reapingEnabled: registration.reapingEnabled,
+                roots: [...registration.roots.values()].map((entry) => this.snapshotRoot(entry)),
+            })),
+        };
+    }
+    /** Alias for callers that use status terminology. */
+    status() {
+        return this.snapshot();
+    }
+    /**
+     * Demand gate for initial and successor creation. A live root is returned
+     * without repeating the filesystem check; absent roots require a fresh positive
+     * result and then receive exactly one greater generation.
+     */
+    async ensureRootForDemand(poolId, root) {
+        const registration = this.currentRegistration(poolId);
+        if (!registration)
+            return undefined;
+        const existing = registration.roots.get(rootKey(root));
+        if (existing?.state === "live")
+            return existing.generation;
+        if (existing && !existing.synchronousPhaseComplete)
+            return undefined;
+        let result;
+        try {
+            result = await this.demand(root, poolId);
+        }
+        catch {
+            return undefined;
+        }
+        if (!resultMeansPresent(result))
+            return undefined;
+        const stillCurrent = this.currentRegistration(poolId);
+        if (stillCurrent !== registration)
+            return undefined;
+        const afterCheck = registration.roots.get(rootKey(root));
+        if (afterCheck?.state === "live")
+            return afterCheck.generation;
+        if (afterCheck && !afterCheck.synchronousPhaseComplete)
+            return undefined;
+        return this.registerRoot(poolId, root);
+    }
+    demandRoot(poolId, root) {
+        return this.ensureRootForDemand(poolId, root);
+    }
+    getBridgeDemand(poolId, root) {
+        return this.ensureRootForDemand(poolId, root);
+    }
+    /**
+     * Coordinate one generation's close. The live-to-reaping transition, tombstone,
+     * outer eviction, and concrete close invocation all happen before the returned
+     * promise can yield. Concurrent requests coalesce on the same close promise.
+     */
+    requestProjectRootClose(poolId, root, expectedGeneration, cause = "explicit") {
+        const registration = this.currentRegistration(poolId);
+        if (!registration)
+            return Promise.resolve();
+        const entry = registration.roots.get(rootKey(root));
+        if (!entry || entry.generation !== expectedGeneration)
+            return Promise.resolve();
+        if (entry.state === "reaping")
+            return entry.closePromise ?? Promise.resolve();
+        if (entry.state === "tombstoned")
+            return entry.closePromise ?? Promise.resolve();
+        entry.state = "reaping";
+        entry.tombstoned = true;
+        entry.cause = cause;
+        let closeResult;
+        try {
+            registration.evictOuterFacade(entry.canonicalRoot, entry.generation);
+            closeResult = registration.pool.closeProjectRoot(entry.canonicalRoot, entry.generation);
+            entry.synchronousPhaseComplete = true;
+            entry.state = "tombstoned";
+        }
+        catch (error) {
+            entry.synchronousPhaseComplete = true;
+            entry.state = "tombstoned";
+            const failed = Promise.reject(error);
+            entry.closePromise = failed.then(() => undefined, (failure) => {
+                this.finishRootClose(entry, undefined);
+                throw failure;
+            });
+            return entry.closePromise;
+        }
+        entry.closePromise = Promise.resolve(closeResult).then((result) => {
+            const counts = closeCounts(result);
+            this.finishRootClose(entry, counts);
+        }, (error) => {
+            this.finishRootClose(entry, undefined);
+            throw error;
+        });
+        return entry.closePromise;
+    }
+    /** Coalesce concurrent ticks and observe only enabled, live registrations. */
+    sweep() {
+        if (this.sweepInFlight)
+            return this.sweepInFlight;
+        const sweep = this.runSweep();
+        this.sweepInFlight = sweep;
+        sweep.then(() => {
+            if (this.sweepInFlight === sweep)
+                this.sweepInFlight = null;
+        }, () => {
+            if (this.sweepInFlight === sweep)
+                this.sweepInFlight = null;
+        });
+        return sweep;
+    }
+    /** Alias used by timer seams and tests. */
+    sweepNow() {
+        return this.sweep();
+    }
+    /** Emit a generation-rejection event when a lifecycle boundary refuses the expected generation. */
+    recordGenerationRejection(poolId, root, expectedGeneration, boundary) {
+        const currentGeneration = this.currentGeneration(poolId, root);
+        this.emit({
+            type: "subc_root_generation_rejected",
+            realm: this.realm,
+            concretePoolId: poolId,
+            canonicalRoot: root,
+            expectedGeneration,
+            currentGeneration,
+            boundary,
+        });
+    }
+    rejectGeneration(poolId, root, expectedGeneration, boundary) {
+        this.recordGenerationRejection(poolId, root, expectedGeneration, boundary);
+    }
+    async runSweep() {
+        const snapshots = [...this.registrations.values()]
+            .filter((registration) => registration.active && registration.reapingEnabled)
+            .flatMap((registration) => [...registration.roots.values()]
+            .filter((entry) => entry.state === "live")
+            .map((entry) => ({
+            concretePoolId: registration.concretePoolId,
+            canonicalRoot: entry.canonicalRoot,
+            generation: entry.generation,
+        })));
+        const closes = [];
+        await Promise.all(snapshots.map(async (snapshot) => {
+            let present = false;
+            try {
+                const result = await this.statRoot(snapshot.canonicalRoot, snapshot.concretePoolId, snapshot.generation);
+                present = resultMeansPresent(result);
+            }
+            catch (error) {
+                if (!isEnoent(error))
+                    return;
+            }
+            const entry = this.currentRoot(snapshot.concretePoolId, snapshot.canonicalRoot);
+            if (!entry || entry.generation !== snapshot.generation || entry.state !== "live")
+                return;
+            if (present) {
+                entry.consecutiveAbsences = 0;
+                return;
+            }
+            entry.consecutiveAbsences += 1;
+            if (entry.consecutiveAbsences >= 2) {
+                closes.push(this.requestProjectRootClose(snapshot.concretePoolId, snapshot.canonicalRoot, snapshot.generation, "sweep"));
+            }
+        }));
+        await Promise.all(closes);
+    }
+    currentRegistration(poolId) {
+        const registration = this.registrations.get(poolId);
+        return registration?.active ? registration : undefined;
+    }
+    currentRoot(poolId, root) {
+        return this.currentRegistration(poolId)?.roots.get(rootKey(root));
+    }
+    snapshotRoot(entry) {
+        return {
+            concretePoolId: entry.registration.concretePoolId,
+            registrationIdentity: entry.registration.registrationIdentity,
+            canonicalRoot: entry.canonicalRoot,
+            generation: entry.generation,
+            state: entry.state,
+            consecutiveAbsences: entry.consecutiveAbsences,
+        };
+    }
+    finishRootClose(entry, counts) {
+        if (counts && !entry.eventEmitted) {
+            entry.eventEmitted = true;
+            this.emit({
+                type: "subc_root_reaped",
+                realm: this.realm,
+                concretePoolId: entry.registration.concretePoolId,
+                canonicalRoot: entry.canonicalRoot,
+                generation: entry.generation,
+                consecutiveAbsenceCount: entry.consecutiveAbsences,
+                tornDownSessionCount: counts.sessions,
+                tornDownFacadeCount: counts.facades,
+                cause: entry.cause ?? "explicit",
+            });
+        }
+        const registration = entry.registration;
+        if (registration.roots.get(rootKey(entry.canonicalRoot)) === entry) {
+            registration.roots.delete(rootKey(entry.canonicalRoot));
+        }
+    }
+    deregisterInternal(registration) {
+        if (!registration.active ||
+            this.registrations.get(registration.concretePoolId) !== registration) {
+            return;
+        }
+        for (const entry of [...registration.roots.values()]) {
+            if (entry.state === "live") {
+                const close = this.requestProjectRootClose(registration.concretePoolId, entry.canonicalRoot, entry.generation, "explicit");
+                void close.catch(() => undefined);
+            }
+            registration.roots.delete(rootKey(entry.canonicalRoot));
+        }
+        registration.active = false;
+        this.registrations.delete(registration.concretePoolId);
+        if (this.registrationByPool.get(registration.pool) === registration) {
+            this.registrationByPool.delete(registration.pool);
+        }
+        this.refreshTimer();
+    }
+    refreshTimer() {
+        const shouldRun = [...this.registrations.values()].some((registration) => registration.active && registration.reapingEnabled);
+        if (shouldRun && this.intervalHandle === null) {
+            this.intervalHandle = this.timer.setInterval(() => {
+                void this.sweep().catch(() => undefined);
+            }, this.intervalMs);
+            const maybeUnref = this.intervalHandle;
+            maybeUnref?.unref?.();
+            return;
+        }
+        if (!shouldRun && this.intervalHandle !== null) {
+            this.timer.clearInterval(this.intervalHandle);
+            this.intervalHandle = null;
+        }
+    }
+    emit(event) {
+        try {
+            this.onEvent?.(event);
+        }
+        catch {
+            // Observability must not change lifecycle ownership or teardown behavior.
+        }
+    }
+}
+const defaultLifecycleRegistry = new LifecycleRegistry();
+/** Create a lifecycle registry for callers that do not inject one; use getLifecycleRegistry() for the shared default. */
+export function createLifecycleRegistry(options = {}) {
+    return new LifecycleRegistry(options);
+}
+export function getLifecycleRegistry() {
+    return defaultLifecycleRegistry;
+}
+export { LifecycleRegistry as SubcLifecycleRegistry };
+export function registerLifecyclePool(pool, options) {
+    return defaultLifecycleRegistry.registerLifecyclePool(pool, options);
+}
+//# sourceMappingURL=lifecycle-registry.js.map