@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/lifecycle.js

@@ -0,0 +1,932 @@
+/**
+ * Activation and deactivation (EXT-04, EXT-26, EXT-27, EXT-28).
+ *
+ * The two orderings this module exists to enforce:
+ *
+ * - **Activate commits last.** Contributions are published to a candidate set,
+ *   and the catalog generation advances only once EVERY required contribution has
+ *   been accepted. A half-activated package is worse than an inactive one,
+ *   because tools would appear that nothing can serve.
+ * - **Deactivate persists intent first.** The inactive preference is made durable
+ *   BEFORE anything is withdrawn. If withdrawal then fails or the process dies,
+ *   the durable answer is still "inactive", so a restart cannot resurrect a
+ *   package the operator switched off.
+ *
+ * Rollback is deliberately NARROW: a failed activation withdraws only the handles
+ * it published itself. Touching another extension's contributions would turn one
+ * bad package into an outage of every package.
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/lifecycle
+ */
+import { rmSync } from 'node:fs';
+import { ManagementError } from "./../errors.js";
+import { discoverExtension } from "./../discovery.js";
+import { isProcessAlive } from "./store.js";
+import { summarize } from "./../state.js";
+const CALLABLE_READINESS = new Set([
+    'prepared-cold',
+    'loading',
+    'ready',
+    'busy',
+]);
+/** Default grace period for a contribution to finish stopping, in milliseconds. */
+export const DEFAULT_STOP_GRACE_MS = 5000;
+/**
+ * Whether an extension's readiness should block activation.
+ *
+ * EXT-26 is explicit that a valid package with merely UNPREPARED model assets may
+ * be active with `needs-preparation` diagnostics: the tools exist and can be
+ * described, and preparation happens on first use. A FAILED model is different —
+ * it will not become ready by waiting.
+ * @param readiness - per-deployment readiness.
+ * @returns diagnostics, and whether activation may proceed.
+ */
+export function assessReadiness(readiness) {
+    const diagnostics = [];
+    let proceed = true;
+    for (const [deployment, value] of Object.entries(readiness)) {
+        if (value === 'failed') {
+            proceed = false;
+            diagnostics.push({
+                code: 'not-registerable',
+                subject: deployment,
+                message: `the model deployment ${deployment} is in a failed state and will not become ready by waiting`,
+            });
+        }
+        else if (value === 'needs-preparation' || value === 'preparing') {
+            diagnostics.push({
+                code: 'needs-preparation',
+                subject: deployment,
+                message: `the model deployment ${deployment} is ${value}; working inference tools are withheld until preparation is complete`,
+            });
+        }
+    }
+    return { proceed, diagnostics };
+}
+/** The extension lifecycle for one profile. */
+export class ExtensionLifecycle {
+    #store;
+    #profile;
+    #registrar;
+    #onWithdrawal;
+    #protectedBuiltins;
+    #networkPolicy;
+    #onAudit;
+    #generation = 1;
+    #operations = new Set();
+    #assertIdle(extensionId) {
+        if (this.#operations.has(extensionId)) {
+            throw new ManagementError('EXTENSION_IN_USE', 'activate', `${extensionId} has a lifecycle operation in progress`, 'Wait for the current operation to settle, then retry.');
+        }
+    }
+    async #exclusive(extensionId, work) {
+        this.#assertIdle(extensionId);
+        this.#operations.add(extensionId);
+        try {
+            return await work();
+        }
+        finally {
+            this.#operations.delete(extensionId);
+        }
+    }
+    /** Handles published by this profile, keyed by extension then contribution name. */
+    #published = new Map();
+    #callableTools = new Map();
+    /**
+     * Extensions whose published surface THIS instance owns.
+     *
+     * Distinct from `#published`, which is empty once every handle has been
+     * withdrawn. Reconciliation must not republish a surface another process owns:
+     * a CLI attached to no host holds no handles and cannot manage one.
+     */
+    #owned = new Set();
+    constructor(options) {
+        this.#store = options.store;
+        this.#profile = options.profile;
+        this.#registrar = options.registrar;
+        this.#onWithdrawal = options.onWithdrawal;
+        this.#protectedBuiltins = new Set(options.protectedBuiltins ?? []);
+        this.#networkPolicy = options.networkPolicy ?? 'any';
+        this.#onAudit = options.onAudit;
+        this.#generation = options.generation ?? 1;
+    }
+    /** Run a lifecycle operation, emitting its outcome as an EXT-35 audit event. */
+    async #audited(operation, extensionId, version, work) {
+        try {
+            const result = await work();
+            this.#onAudit?.({ operation, extensionId, version, outcome: 'succeeded' });
+            return result;
+        }
+        catch (error) {
+            this.#onAudit?.({
+                operation,
+                extensionId,
+                version,
+                outcome: 'failed',
+                reason: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    /** The current catalog generation. */
+    get generation() {
+        return this.#generation;
+    }
+    /** Read the persisted states for this profile. */
+    states() {
+        return this.#store.readProfileState(this.#profile).value;
+    }
+    /** Read one extension's persisted state. */
+    stateOf(extensionId) {
+        return this.states().find(state => state.extensionId === extensionId);
+    }
+    /** Replace one extension's state in the profile, preserving the others. */
+    #writeState(state) {
+        const others = this.states().filter(candidate => candidate.extensionId !== state.extensionId);
+        // The EXT-30 update pointers (activeVersions/previousVersions) live in the
+        // SAME profile document and are PRESERVED on every lifecycle write: the
+        // commit flow writes the pointer, and the rebind's own activate/deactivate
+        // must not erase it (the host's quiesce/rebind hooks call exactly these
+        // lifecycle writes). A corrupt pointer read fails closed like any other
+        // unreadable state — the write then proceeds WITHOUT inventing pointers.
+        const pointers = this.#store.readProfilePointers(this.#profile);
+        if (pointers.corrupt) {
+            this.#store.writeProfileState(this.#profile, [...others, state]);
+            return;
+        }
+        const { activeVersions, previousVersions } = pointers.value;
+        this.#store.writeProfileState(this.#profile, [...others, state], undefined, activeVersions, previousVersions);
+    }
+    /**
+     * Activate an installed extension (EXT-26).
+     *
+     * Verifies the installed bytes and locks, checks readiness, publishes every
+     * required contribution, and advances the generation only if all of that
+     * succeeded. On any failure the contributions THIS call published are withdrawn
+     * and the generation is left where it was.
+     * @param extensionId - the extension to activate.
+     * @param version - the installed version to activate.
+     * @param options - failure-recording policy for probe activations.
+     * @returns the activation outcome.
+     * @throws ManagementError when the extension is not installed, its content changed, or a contribution cannot be registered.
+     */
+    async activate(extensionId, version, options = {}) {
+        // The store lock wraps the WHOLE operation: activation writes state, and an
+        // offline CLI editing the same store must not interleave its read-modify-write
+        // between this one's read and write (EXT-31).
+        return this.#audited('activate', extensionId, version, () => (this.#store.exclusive(() => this.#exclusive(extensionId, () => this.#activate(extensionId, version, options)))));
+    }
+    /**
+     * Retry owned deletion left pending by a previous uninstall (EXT-29).
+     *
+     * An uninstall that could not delete its private installation keeps the record and
+     * leaves the installation absent in the profile state. On restart this finds only
+     * those records, deletes exactly the recorded path, and removes the record only
+     * after the deletion succeeds.
+     * @returns the cleaned ids and the failures with reasons.
+     */
+    async retryCleanupPending() {
+        const cleaned = [];
+        const failed = [];
+        const absent = new Set(this.states().filter(state => state.installation === 'absent').map(state => state.extensionId));
+        for (const record of this.#store.listInstalled().value) {
+            if (!absent.has(record.extensionId))
+                continue;
+            try {
+                rmSync(record.installPath, { recursive: true, force: true });
+                this.#store.removeRecord(record.extensionId);
+                cleaned.push(record.extensionId);
+            }
+            catch (error) {
+                failed.push({
+                    extensionId: record.extensionId,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return { cleaned, failed };
+    }
+    async #activate(extensionId, version, options) {
+        const record = this.#findRecord(extensionId, version);
+        if (record === undefined) {
+            throw new ManagementError('EXTENSION_INACTIVE', 'activate', `${extensionId}@${version} is not installed`, 'Install it first; activation does not install.');
+        }
+        // Checked BEFORE anything is published: activating bytes that differ from the
+        // ones the operator approved would execute code nobody reviewed.
+        const integrity = this.#store.verifyUnchanged(record);
+        if (!integrity.unchanged) {
+            throw new ManagementError('INTEGRITY_MISMATCH', 'activate', `${extensionId}@${version} cannot be activated: ${integrity.diagnostic ?? 'the installed content changed'}`, 'Reinstall the package from its declared source, then activate it.');
+        }
+        /**
+         * LIC-04: no-network admission is decided from the DECLARED behaviour before
+         * anything is published. Suppressing required telemetry to fit the policy would
+         * breach the licence, so the refusal names the alternative instead.
+         */
+        if (this.#networkPolicy === 'no-network') {
+            const discovery = this.#discoverOf(record);
+            if (discovery === undefined) {
+                throw new ManagementError('EXTENSION_FAULT', 'activate', `${extensionId}@${version} cannot be read, so its network behaviour cannot be checked`, 'Reinstall the package or repair its manifest.');
+            }
+            if (!discovery.noNetwork.eligible) {
+                throw new ManagementError('PERMISSION_REQUIRED', 'activate', `${extensionId} is not eligible for a strict no-network deployment: `
+                    + `${discovery.noNetwork.reason ?? 'its declared network behaviour does not allow it'}`, discovery.noNetwork.alternative ?? 'Choose an implementation whose declared behaviour is network-free.');
+            }
+        }
+        const previous = this.stateOf(extensionId);
+        /**
+         * An extension THIS instance already has active is not a competing publication:
+         * re-activating it is how a caller picks up newly recorded readiness. Refusing
+         * here made preparation a dead end — every model-backed package publishes
+         * `implementation` metadata handles, so the guard fired even when nothing was
+         * actually serving a tool. Reconcile the surface instead.
+         */
+        if (previous?.observedActivation === 'active' && this.#owned.has(extensionId)) {
+            const refresher = this.#store.listInstalled().value.find(candidate => candidate.extensionId === extensionId);
+            const refreshedTools = this.#toolsOf(record);
+            const refreshedReadiness = this.#readinessOf(record, previous.readiness);
+            const refreshedDiagnostics = [...assessReadiness(refreshedReadiness).diagnostics];
+            this.#writeState(this.#stateFor(record, {
+                desiredActivation: 'active',
+                observedActivation: 'active',
+                tools: refreshedTools,
+                readiness: refreshedReadiness,
+            }));
+            if (refresher !== undefined)
+                await this.#reconcileSurface(extensionId, refreshedDiagnostics);
+            return {
+                extensionId,
+                version,
+                state: this.stateOf(extensionId) ?? this.#stateFor(record, {
+                    desiredActivation: 'active', observedActivation: 'active',
+                    tools: refreshedTools, readiness: refreshedReadiness,
+                }),
+                diagnostics: refreshedDiagnostics,
+                generation: this.#generation,
+            };
+        }
+        /**
+         * ADOPTION IS NOT ACTIVATION. State saying `active` means SOMEBODY published this
+         * surface. If this instance holds no handles for it, the question is whether that
+         * owner is GONE (a restart: restoring is the whole point of RUN-05) or ALIVE
+         * (another host: republishing would create a second owner serving the same names).
+         * The recorded owner PID is the only durable way to tell them apart, because
+         * handles are in-memory.
+         *
+         * The cases that must REFUSE are: a live foreign PID, and OUR OWN PID without
+         * local ownership (another instance of this process published it). A dead or
+         * absent PID is a restart of a legacy owner and may be restored.
+         */
+        if (previous?.observedActivation === 'active' && !this.#owned.has(extensionId)) {
+            const pid = previous.ownerPid;
+            const foreignLive = pid !== undefined && pid !== process.pid && isProcessAlive(pid);
+            const sameProcessStranger = pid === process.pid;
+            if (foreignLive || sameProcessStranger) {
+                throw new ManagementError('EXTENSION_IN_USE', 'activate', `${extensionId} is already active under ${foreignLive ? `live process ${pid}` : 'another owner in this process'}`, 'Deactivate it through the owning host before activating it here.');
+            }
+        }
+        if ((this.#published.get(extensionId)?.size ?? 0) > 0
+            || previous?.observedActivation === 'quarantined'
+            || previous?.observedActivation === 'deactivating'
+            || previous?.observedActivation === 'activating') {
+            throw new ManagementError('EXTENSION_IN_USE', 'activate', `${extensionId} is already published or requires cleanup before activation`, 'Deactivate through the owning host and confirm cleanup before activating again.');
+        }
+        const tools = this.#toolsOf(record);
+        const readiness = this.#readinessOf(record, previous?.readiness);
+        const assessment = assessReadiness(readiness);
+        const diagnostics = [...assessment.diagnostics];
+        if (!assessment.proceed) {
+            const reason = diagnostics.map(entry => entry.message).join('; ');
+            const failed = {
+                desiredActivation: 'active',
+                observedActivation: 'failed',
+                tools,
+                readiness,
+            };
+            // A probe activation suppresses the cause: its refusal is a probe artifact,
+            // not an operator-facing reason. A real attempt records it durably.
+            this.#writeState(this.#stateFor(record, options.recordFailure === false
+                ? failed
+                : { ...failed, activationError: reason }));
+            throw new ManagementError('EXTENSION_FAULT', 'activate', `${extensionId}@${version} cannot be activated: ${reason}`, 'Prepare or repair the model deployment, then activate again.');
+        }
+        // Intended-active is persisted before publication so a crash mid-activation
+        // leaves a record that activation was attempted, not a silent no-op. The
+        // override set OMITS `activationError`, which is how a retry clears the previous
+        // failure's reason: #stateFor rebuilds the object rather than keeping stale fields.
+        this.#writeState(this.#stateFor(record, {
+            desiredActivation: 'active',
+            observedActivation: 'activating',
+            tools, readiness,
+        }));
+        const published = [];
+        const callableTools = new Set();
+        try {
+            for (const contribution of this.#contributionsOf(record, readiness, diagnostics)) {
+                if (contribution.kind === 'tool')
+                    callableTools.add(contribution.name);
+                const handle = await this.#registrar.publish(contribution);
+                published.push({ kind: contribution.kind, name: contribution.name, handle });
+            }
+        }
+        catch (error) {
+            // Rollback is NARROW: only what this call published is withdrawn, so one bad
+            // package cannot disturb the others.
+            const remaining = new Map();
+            for (const entry of published.reverse()) {
+                try {
+                    await this.#registrar.withdraw(entry.handle);
+                }
+                catch {
+                    remaining.set(entry.kind ? `${entry.kind}:${entry.name}` : `unknown:${entry.name}`, entry.handle);
+                }
+            }
+            if (remaining.size > 0)
+                this.#published.set(extensionId, remaining);
+            const reason = error instanceof Error ? error.message : String(error);
+            const failed = {
+                desiredActivation: 'active',
+                observedActivation: remaining.size > 0 ? 'quarantined' : 'failed',
+                tools,
+                readiness,
+            };
+            // The published-contribution refusal is the cause the operator must see;
+            // the thrown ManagementError is not persisted anywhere else. A probe
+            // activation suppresses it (see ActivationOptions.recordFailure).
+            this.#writeState(this.#stateFor(record, options.recordFailure === false
+                ? failed
+                : { ...failed, activationError: reason }));
+            throw new ManagementError('EXTENSION_FAULT', 'activate', `${extensionId}@${version} was not activated: ${reason}`, 'Fix the reported contribution and activate again; other extensions were not disturbed.');
+        }
+        const handles = new Map(published.map(entry => [`${entry.kind}:${entry.name}`, entry.handle]));
+        this.#published.set(extensionId, handles);
+        this.#callableTools.set(extensionId, callableTools);
+        this.#owned.add(extensionId);
+        // Committed only now, once every required contribution was accepted.
+        this.#generation += 1;
+        // No `activationError` in the override set: a successful activation CARRIES NO
+        // stale failure reason forward (an active extension must not look faulted).
+        const state = this.#stateFor(record, {
+            desiredActivation: 'active',
+            observedActivation: 'active',
+            tools, readiness,
+        });
+        this.#writeState(state);
+        return { extensionId, version, state, diagnostics, generation: this.#generation };
+    }
+    /**
+     * Deactivate an extension (EXT-27).
+     *
+     * The inactive intent is made durable FIRST, so a failure or crash during
+     * withdrawal cannot resurrect the package on the next start.
+     * @param extensionId - the extension to deactivate.
+     * @returns the deactivation outcome, which reports honestly when it is not fully stopped.
+     */
+    async deactivate(extensionId) {
+        return this.#audited('deactivate', extensionId, null, () => (this.#store.exclusive(() => this.#exclusive(extensionId, () => this.#deactivate(extensionId)))));
+    }
+    async #deactivate(extensionId) {
+        const current = this.stateOf(extensionId);
+        if (current === undefined) {
+            throw new ManagementError('EXTENSION_INACTIVE', 'deactivate', `${extensionId} is not known in profile ${this.#profile}`, 'Nothing to deactivate.');
+        }
+        // ORDERING: persist inactive intent before withdrawing anything.
+        this.#writeState({ ...current, desiredActivation: 'inactive', observedActivation: 'deactivating' });
+        const handles = this.#published.get(extensionId) ?? new Map();
+        const hadHandles = handles.size > 0;
+        const failures = [];
+        for (const [name, handle] of handles) {
+            try {
+                await this.#registrar.withdraw(handle);
+                handles.delete(name);
+            }
+            catch (error) {
+                failures.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (handles.size === 0) {
+            this.#published.delete(extensionId);
+            this.#callableTools.delete(extensionId);
+        }
+        /**
+         * A store that says the extension was ACTIVE while this process holds no
+         * handles means somebody else published them — normally a host this CLI is not
+         * attached to, or a previous run that has since exited.
+         *
+         * Reporting a clean stop here would be a lie of exactly the kind EXT-27
+         * forbids: the contributions are still published somewhere, and this process
+         * has no way to withdraw them. Saying so is the only honest answer.
+         */
+        const deadOwner = current.ownerPid !== undefined
+            && current.ownerPid !== process.pid
+            && !isProcessAlive(current.ownerPid);
+        const orphaned = (current.observedActivation === 'active' || current.observedActivation === 'quarantined'
+            || current.observedActivation === 'deactivating' || current.observedActivation === 'activating') && !hadHandles
+            && !deadOwner;
+        if (orphaned) {
+            failures.push('the contributions were published by another process and cannot be withdrawn from here; '
+                + 'stop the owning host, or deactivate through it');
+        }
+        const stopped = failures.length === 0;
+        /**
+         * onWithdrawal — a TEARDOWN OBSERVER, exactly once per withdrawn extension.
+         *
+         * It runs AFTER every registrar handle withdrawal has settled (successes
+         * and failures alike: a host must dispose its worker in both cases) and
+         * BEFORE the final state write, inside the existing store + operation
+         * locks. Its failure is RECORDED, never thrown: the state write below must
+         * commit even when a disposal callback misbehaves — losing the durable
+         * "inactive" answer to a hook error would let a restart resurrect the
+         * package the operator switched off. The error surfaces on the result.
+         */
+        let hookFailure;
+        if (this.#onWithdrawal !== undefined) {
+            try {
+                await this.#onWithdrawal(extensionId);
+            }
+            catch (error) {
+                hookFailure = error instanceof Error ? error.message : String(error);
+            }
+        }
+        const { ownerPid: _previousOwner, ...withoutOwner } = current;
+        const inactive = {
+            ...(stopped ? withoutOwner : current),
+            desiredActivation: 'inactive',
+            observedActivation: stopped ? 'inactive' : 'quarantined',
+        };
+        this.#writeState(inactive);
+        // Ownership ends only with a CONFIRMED stop; a quarantined extension still has
+        // live handlers this instance must be able to retry withdrawing.
+        if (failures.length === 0) {
+            this.#generation += 1;
+            this.#owned.delete(extensionId);
+        }
+        return {
+            extensionId,
+            state: inactive,
+            // Never claim a full stop while something it owns is still running.
+            fullyStopped: failures.length === 0,
+            ...failures.length === 0 ? {} : { cleanupFailure: failures.join('; ') },
+            ...hookFailure === undefined ? {} : { hookFailure },
+            generation: this.#generation,
+        };
+    }
+    /**
+     * Enable or disable ONE tool inside an active extension (EXT-04).
+     *
+     * Independent of activation: the package stays active while a single tool is
+     * hidden from callers.
+     *
+     * ASYNC because the toggle also reconciles the PUBLISHED surface: a disabled
+     * tool is withdrawn from the registrar rather than merely remembered as off,
+     * and a re-enabled one is published again. When this instance does not own the
+     * surface — a CLI with no host attached — only the durable choice is recorded,
+     * because it cannot manage a registry another process owns.
+     * @param extensionId - the owning extension.
+     * @param toolName - the tool to toggle.
+     * @param enabled - the new visibility.
+     * @throws ManagementError when the extension or tool is unknown.
+     * @returns the state after the change.
+     */
+    async setToolEnabled(extensionId, toolName, enabled) {
+        return this.#store.exclusive(() => this.#exclusive(extensionId, () => this.#setToolEnabled(extensionId, toolName, enabled)));
+    }
+    async #setToolEnabled(extensionId, toolName, enabled) {
+        const current = this.stateOf(extensionId);
+        if (current === undefined) {
+            throw new ManagementError('EXTENSION_INACTIVE', 'deactivate', `${extensionId} is not known`, 'Nothing to toggle.');
+        }
+        const tool = current.tools.find(candidate => candidate.toolName === toolName);
+        if (tool === undefined) {
+            throw new ManagementError('INVALID_EXTENSION', 'deactivate', `${extensionId} contributes no tool named ${JSON.stringify(toolName)}`, 'List the extension to see the tools it contributes.');
+        }
+        const next = {
+            ...current,
+            tools: current.tools.map(candidate => candidate.toolName === toolName ? { ...candidate, enabled } : candidate),
+        };
+        /**
+         * INTENT IS PERSISTED BEFORE THE SURFACE MOVES. Disabling a tool that stays
+         * REGISTERED would keep answering callers, which is the defect this ordering
+         * exists to close; writing the choice first means a crash mid-reconcile
+         * leaves the durable answer as "off" rather than silently "on".
+         */
+        this.#writeState(next);
+        if (next.observedActivation === 'active' && this.#owned.has(extensionId)) {
+            await this.#reconcileSurface(extensionId);
+        }
+        return this.stateOf(extensionId) ?? next;
+    }
+    /**
+     * Bring the PUBLISHED surface back in line with the current state (EXT-04).
+     *
+     * A tool toggle is not only a state edit: the registrar still holds the handles
+     * from activation. This recomputes the desired contribution set — which already
+     * encodes disabled tools, readiness gates and dependent usage skills — and then
+     * withdraws what is no longer wanted and publishes what is newly wanted.
+     *
+     * Nothing is recomputed for an extension that is not active: a deactivated
+     * package has no visible surface to reconcile, so this is a no-op there.
+     * @param extensionId - the extension whose surface to reconcile.
+     */
+    async #reconcileSurface(extensionId, diagnostics = []) {
+        const record = this.#store.listInstalled().value.find(candidate => candidate.extensionId === extensionId);
+        if (record === undefined)
+            return;
+        /**
+         * THE SAME INTEGRITY GATE ACTIVATION USES. Activation refuses to publish bytes
+         * that changed after installation; reconcile publishes and withdraws through the
+         * SAME registry, so skipping the check here would make "edit the installed
+         * package, then toggle an unrelated tool" a way to run code nobody reviewed.
+         */
+        const integrity = this.#store.verifyUnchanged(record);
+        if (!integrity.unchanged) {
+            throw new ManagementError('INTEGRITY_MISMATCH', 'activate', `${extensionId} surface cannot be reconciled: ${integrity.diagnostic ?? 'the installed content changed'}`, 'Reinstall the package from its declared source, then toggle the tool.');
+        }
+        /**
+         * AN UNKNOWN DESIRED SET IS NOT AN EMPTY ONE. `#contributionsOf` returns [] when
+         * the manifest cannot be read, and treating that as "nothing is wanted" would
+         * withdraw the ENTIRE surface — a transient AV-scanner lock or concurrent writer
+         * would silently unregister every tool while the durable state still said active.
+         * Refuse instead, leaving the surface exactly as it was.
+         */
+        const discovery = this.#discoverOf(record);
+        if (discovery === undefined) {
+            throw new ManagementError('INVALID_EXTENSION', 'activate', `${extensionId} manifest could not be read, so the published surface was left untouched`, 'Ensure the installed package is readable, then retry.');
+        }
+        const state = this.stateOf(extensionId);
+        const previous = this.#published.get(extensionId) ?? new Map();
+        const desired = this.#contributionsOf(record, state?.readiness ?? {}, diagnostics);
+        /**
+         * Keyed by KIND AND NAME. A manifest may legally declare a tool named `shared`
+         * and an implementation whose id is also `shared` (uniqueness is per-label), so
+         * name-only keying would let one kind's survival mask the other's withdrawal.
+         */
+        const keyOf = (contribution) => `${contribution.kind}:${contribution.name}`;
+        const desiredKeys = new Set(desired.map(keyOf));
+        /**
+         * A REDUNDANT TOGGLE IS A NO-OP. When the published keys already equal the
+         * desired keys, there is nothing to withdraw or publish, and bumping the
+         * generation would invalidate consumer caches for a surface that did not move.
+         * This check ALSO makes a retry cheap: after a failed withdrawal the surviving
+         * key is still present, so a retry that now succeeds is a real change and does
+         * move the generation.
+         */
+        const existingKeys = new Set(previous.keys());
+        if (existingKeys.size === desiredKeys.size && [...existingKeys].every(key => desiredKeys.has(key))) {
+            return;
+        }
+        /**
+         * `live` and `visible` record what ACTUALLY exists after this pass, and they are
+         * committed in the `finally` below. Mutating the stored map in place and only then
+         * updating `#callableTools` would let a mid-pass failure leave admission asserting
+         * a surface the registry no longer has — the exact divergence this reconcile
+         * exists to remove.
+         */
+        const live = new Map();
+        const visible = new Set();
+        const failures = [];
+        for (const [key, handle] of [...previous]) {
+            // Keys are `kind:name`, so the KIND participates in the match rather than
+            // only the name: a tool and an implementation may legally share a name.
+            const name = key.slice(key.indexOf(':') + 1);
+            if (desiredKeys.has(key)) {
+                live.set(key, handle);
+                visible.add(name);
+                continue;
+            }
+            try {
+                await this.#registrar.withdraw(handle);
+            }
+            catch (error) {
+                // A handle that would not withdraw is STILL PUBLISHED, so it stays tracked
+                // and stays visible; forgetting it would be the lie.
+                failures.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+                live.set(key, handle);
+                visible.add(name);
+            }
+        }
+        for (const contribution of desired) {
+            const key = keyOf(contribution);
+            if (live.has(key))
+                continue;
+            try {
+                const handle = await this.#registrar.publish(contribution);
+                live.set(key, handle);
+                visible.add(contribution.name);
+            }
+            catch (error) {
+                failures.push(`${contribution.name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (live.size === 0)
+            this.#published.delete(extensionId);
+        else
+            this.#published.set(extensionId, live);
+        this.#callableTools.set(extensionId, new Set(desired.filter(contribution => contribution.kind === 'tool' && visible.has(contribution.name))
+            .map(contribution => contribution.name)));
+        /**
+         * The surface moved (fully or partly), so consumers must see a new generation.
+         * This advances BEFORE the failure is raised, because a partly-reconciled
+         * surface is still a different surface and must not be served under the old
+         * generation.
+         */
+        this.#generation += 1;
+        if (failures.length > 0) {
+            throw new ManagementError('EXTENSION_FAULT', 'deactivate', `${extensionId} surface was only partly reconciled: ${failures.join('; ')}`, 'Retry the toggle once the reported contribution can be managed; what remains published is still tracked.');
+        }
+    }
+    /**
+     * Whether a tool may be invoked right now.
+     * @param extensionId - the owning extension.
+     * @param toolName - the tool being invoked.
+     */
+    admits(extensionId, toolName) {
+        const current = this.stateOf(extensionId);
+        if (current === undefined)
+            return false;
+        /**
+         * ADMISSION MUST AGREE WITH PUBLICATION. The surface is exactly the tool
+         * contributions this instance committed, so a tool withheld for a missing,
+         * mismatched or unprepared binding is not admitted merely because its
+         * enablement flag survives in state. Readiness is already folded into that
+         * committed set, which also stops an UNRELATED deployment's preparation from
+         * rejecting a tool whose own binding is callable.
+         */
+        if (!(this.#callableTools.get(extensionId)?.has(toolName) ?? false))
+            return false;
+        /**
+         * Enablement and lifecycle are checked HERE rather than through
+         * `admitsInvocation`, because that helper also requires EVERY declared
+         * deployment to be callable. This tool's binding was already evaluated when its
+         * contribution was published, so an unrelated unprepared deployment must not
+         * make a callable tool inadmissible.
+         */
+        if (current.installation !== 'installed')
+            return false;
+        if (current.desiredActivation !== 'active' || current.observedActivation !== 'active')
+            return false;
+        return current.tools.find(tool => tool.toolName === toolName)?.enabled === true;
+    }
+    /**
+     * Uninstall an installed extension (EXT-04, EXT-28).
+     * @param extensionId - the extension to remove.
+     * @param options - `deactivate` must be set to remove an active package.
+     * @throws ManagementError `EXTENSION_IN_USE`, `BUILTIN_PROTECTED`, or `EXTENSION_INACTIVE`.
+     */
+    async uninstall(extensionId, options = {}) {
+        return this.#audited('uninstall', extensionId, null, () => (this.#store.exclusive(() => this.#exclusive(extensionId, () => this.#uninstall(extensionId, options)))));
+    }
+    async #uninstall(extensionId, options) {
+        if (this.#protectedBuiltins.has(extensionId)) {
+            throw new ManagementError('BUILTIN_PROTECTED', 'uninstall', `${extensionId} is a protected built-in of this host release`, 'Built-ins cannot be uninstalled; update the host release instead. A package manifest cannot change this list.');
+        }
+        const current = this.stateOf(extensionId);
+        const active = current?.observedActivation === 'active' || current?.desiredActivation === 'active'
+            || current?.observedActivation === 'quarantined' || current?.observedActivation === 'deactivating'
+            || (this.#published.get(extensionId)?.size ?? 0) > 0;
+        if (active && options.deactivate !== true) {
+            throw new ManagementError('EXTENSION_IN_USE', 'uninstall', `${extensionId} is active in profile ${this.#profile}`, 'Re-run with deactivation requested; the affected profiles and tools are listed in the preview.');
+        }
+        if (active) {
+            const stopped = await this.#deactivate(extensionId);
+            if (!stopped.fullyStopped) {
+                throw new ManagementError('EXTENSION_IN_USE', 'uninstall', `${extensionId} cleanup is incomplete: ${stopped.cleanupFailure ?? 'owned resources are not confirmed stopped'}`, 'Retry cleanup through the owning host; installed bytes and quarantine are retained.');
+            }
+        }
+        // The disabled tombstone is RETAINED rather than deleted, so a later automatic
+        // install cannot silently resurrect a package the operator removed (EXT-28).
+        const previous = this.stateOf(extensionId);
+        const { ownerPid: _staleOwner, ...withoutOwner } = previous ?? {
+            extensionId,
+            installation: 'absent',
+            desiredActivation: 'inactive',
+            observedActivation: 'inactive',
+            readiness: {},
+            tools: [],
+            export: 'not-exported',
+        };
+        this.#writeState({
+            ...withoutOwner,
+            installation: 'absent',
+            desiredActivation: 'inactive',
+            observedActivation: 'inactive',
+            tools: [],
+        });
+        this.#callableTools.delete(extensionId);
+        this.#owned.delete(extensionId);
+        /**
+         * EXT-28: delete the private installation (including its private resolved
+         * dependencies) BEFORE forgetting the record. If Windows still holds a file, the
+         * record remains and the caller gets CLEANUP_PENDING, so the uninstall can be
+         * retried; erasing the record first would orphan bytes with no way to find them.
+         */
+        for (const installedRecord of this.#store.listInstalled().value.filter(record => record.extensionId === extensionId)) {
+            try {
+                rmSync(installedRecord.installPath, { recursive: true, force: true });
+            }
+            catch (error) {
+                throw new ManagementError('CLEANUP_PENDING', 'uninstall', `${extensionId} could not delete its private installation at ${installedRecord.installPath}: `
+                    + `${error instanceof Error ? error.message : String(error)}`, 'Retry uninstall after the owning process releases the files; it remains recorded and inactive.');
+            }
+        }
+        this.#store.removeRecord(extensionId);
+    }
+    #findRecord(extensionId, version) {
+        return this.#store.listInstalled().value.find(record => record.extensionId === extensionId && record.version === version);
+    }
+    /** The tools a record contributes, all enabled by default. */
+    #toolsOf(record) {
+        const discovery = this.#discoverOf(record);
+        const tools = discovery?.manifest.tools ?? [];
+        const previous = this.stateOf(record.extensionId)?.tools ?? [];
+        return tools.map(tool => {
+            const previousTool = previous.find(candidate => candidate.toolName === tool.name);
+            return {
+                toolName: tool.name,
+                enabled: previousTool?.enabled ?? true,
+                // A preserved provider pick must survive re-activation too: rebuilding
+                // the selection from the manifest drops it otherwise, which would undo
+                // the BASE-09 migration's provider preservation on the next refresh.
+                ...previousTool?.selectedImplementation === undefined ? {} : { selectedImplementation: previousTool.selectedImplementation },
+            };
+        });
+    }
+    /** Re-read the installed manifest, or undefined when it cannot be read. */
+    #discoverOf(record) {
+        try {
+            return discoverExtension(record.installPath);
+        }
+        catch {
+            // A package whose manifest no longer reads is reported by the caller as
+            // contributing nothing, rather than crashing the whole lifecycle.
+            return undefined;
+        }
+    }
+    /** Default declared model deployments to needs-preparation until a host records a stronger fact. */
+    #readinessOf(record, previous) {
+        const discovery = this.#discoverOf(record);
+        const readiness = {};
+        for (const model of discovery?.manifest.models ?? []) {
+            readiness[model.id] = previous?.[model.id] ?? 'needs-preparation';
+        }
+        return readiness;
+    }
+    /**
+     * Record host-inspected readiness for an extension's declared deployments.
+     *
+     * This is the production writer `#readinessOf` reads: without it, every declared
+     * model stays `needs-preparation` forever and a model-backed package can never
+     * publish a callable tool. Inspection is the host's read-only EXT-18 surface, so
+     * recording it here is how "prepared" becomes a durable fact rather than a guess.
+     *
+     * Only values for deployments the CURRENT manifest declares are kept, matching the
+     * projection `#readinessOf` already applies, and `failed` is recorded so a failed
+     * deployment refuses activation instead of staying silent.
+     *
+     * ASYNC because a readiness CHANGE also moves the surface: a deployment that just
+     * became `failed` must have its tool withdrawn, and one that just became callable
+     * must be published. Recording without reconciling would leave the published
+     * snapshot stale, which is exactly the divergence admission exists to prevent.
+     * @param extensionId - the extension whose deployments were inspected.
+     * @param inspected - readiness keyed by deployment id.
+     * @returns the state after recording.
+     * @throws ManagementError when the extension is not installed.
+     */
+    async recordReadiness(extensionId, inspected) {
+        return this.#store.exclusive(() => this.#exclusive(extensionId, () => this.#recordReadiness(extensionId, inspected)));
+    }
+    async #recordReadiness(extensionId, inspected) {
+        const current = this.stateOf(extensionId);
+        if (current === undefined) {
+            throw new ManagementError('EXTENSION_INACTIVE', 'activate', `${extensionId} is not known`, 'Nothing to record for it.');
+        }
+        const record = this.#store.listInstalled().value.find(candidate => candidate.extensionId === extensionId);
+        if (record === undefined) {
+            throw new ManagementError('EXTENSION_INACTIVE', 'activate', `${extensionId} is not installed`, 'Install it before recording readiness.');
+        }
+        const discovery = this.#discoverOf(record);
+        if (discovery === undefined) {
+            // An UNREADABLE manifest cannot say which deployments are declared, so recording
+            // against it would write junk into the durable state. Refuse rather than guess.
+            throw new ManagementError('INVALID_EXTENSION', 'activate', `${extensionId} manifest could not be read, so readiness was not recorded`, 'Ensure the installed package is readable, then retry.');
+        }
+        const declared = new Set(discovery.manifest.models.map(model => model.id));
+        const readiness = { ...current.readiness };
+        for (const [id, value] of Object.entries(inspected)) {
+            // Unknown deployments are DROPPED, mirroring the projection activation applies:
+            // a removed deployment's stale readiness must not poison the current manifest.
+            if (declared.has(id))
+                readiness[id] = value;
+        }
+        const changed = Object.entries(readiness).some(([id, value]) => current.readiness[id] !== value);
+        const next = { ...current, readiness };
+        this.#writeState(next);
+        // The surface must agree with the new facts: a tool whose deployment just failed
+        // is withdrawn, and one that just became callable is published.
+        if (changed && next.observedActivation === 'active' && this.#owned.has(extensionId)) {
+            await this.#reconcileSurface(extensionId);
+        }
+        return this.stateOf(extensionId) ?? next;
+    }
+    /** The contributions a record publishes. */
+    #contributionsOf(record, readiness, diagnostics) {
+        const discovery = this.#discoverOf(record);
+        if (discovery === undefined)
+            return [];
+        const contributions = [];
+        const declaredVisibleTools = new Set();
+        /**
+         * A declarative package declares tools for discovery/readiness, but its
+         * IMPLEMENTATION is the single contribution that publishes the standard
+         * contract tool. Publishing both makes the registrar see the same tool name
+         * twice ("already registered"), which aborts activation for a manifest that
+         * is correct per the declarative specification.
+         */
+        const declarative = discovery.manifest.execution.kind === 'declarative';
+        const disabled = new Set(this.stateOf(record.extensionId)?.tools
+            .filter(tool => !tool.enabled).map(tool => tool.toolName) ?? []);
+        for (const tool of discovery.manifest.tools) {
+            if (disabled.has(tool.name))
+                continue;
+            const candidates = discovery.manifest.implementations.filter(implementation => implementation.contractId === tool.contractId);
+            const implementations = candidates.filter(implementation => implementation.contractVersion === tool.contractVersion);
+            if (implementations.length === 0) {
+                diagnostics.push({
+                    code: 'not-registerable',
+                    subject: tool.name,
+                    message: `${tool.name} is withheld because no implementation serves ${tool.contractId}@${tool.contractVersion}`,
+                });
+                continue;
+            }
+            // Dispatch currently selects the FIRST exact contract binding. Do not let
+            // a later ready alternative justify visibility for that unprepared target.
+            const selected = implementations[0];
+            const callable = selected?.modelId === undefined
+                || CALLABLE_READINESS.has(readiness[selected.modelId] ?? 'needs-preparation');
+            if (!callable) {
+                diagnostics.push({
+                    code: 'needs-preparation',
+                    subject: tool.name,
+                    message: `${tool.name} is withheld because no implementation for ${tool.contractId} is prepared and callable`,
+                });
+                continue;
+            }
+            declaredVisibleTools.add(tool.name);
+            if (declarative)
+                continue;
+            contributions.push({
+                extensionId: record.extensionId, kind: 'tool', name: tool.name, contractId: tool.contractId,
+            });
+        }
+        for (const implementation of discovery.manifest.implementations) {
+            contributions.push({
+                extensionId: record.extensionId,
+                kind: 'implementation',
+                name: implementation.id,
+                contractId: implementation.contractId,
+            });
+        }
+        const visibleTools = new Set([
+            ...declaredVisibleTools,
+            ...contributions.filter(entry => entry.kind === 'tool').map(entry => entry.name),
+        ]);
+        for (const skill of discovery.manifest.skills) {
+            // Setup guidance has no required tools; usage guidance must not advertise
+            // leaves withheld by readiness. Keep both projections in the same decision.
+            if (skill.requiresTools?.some(id => {
+                const tool = discovery.manifest.tools.find(candidate => candidate.id === id);
+                return !visibleTools.has(tool?.name ?? id);
+            }))
+                continue;
+            contributions.push({ extensionId: record.extensionId, kind: 'skill', name: skill.name });
+        }
+        return contributions;
+    }
+    /**
+     * Build a state value for a record.
+     *
+     * The override set decides the WHOLE persisted state: a field it omits is absent
+     * from the new document, never inherited from the previous one. That is what makes
+     * a successful transition clear `activationError` without assigning `undefined`
+     * (which `exactOptionalPropertyTypes` rightly refuses).
+     */
+    #stateFor(record, overrides) {
+        const previous = this.stateOf(record.extensionId);
+        return {
+            extensionId: record.extensionId,
+            installation: 'installed',
+            export: previous?.export ?? 'not-exported',
+            /**
+             * The PID is stamped while THIS process publishes or is about to publish the
+             * surface, and dropped on any confirmed stop. That is what lets a restarted
+             * process restore an `active` record whose owner died, while still refusing a
+             * LIVE second owner.
+             */
+            ...overrides.observedActivation === 'active' || overrides.observedActivation === 'activating'
+                ? { ownerPid: process.pid }
+                : {},
+            ...overrides,
+        };
+    }
+}
+export { summarize };
+//# sourceMappingURL=lifecycle.js.map