@try-works/dsh-model-as-tool 0.1.0 → 0.1.2

package/lib/contract-payload.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Translation from a model's native result to a contract's payload.
+ *
+ * The spec puts this responsibility on adapters: they "translate between the
+ * capability's canonical representation and the model's native interface". It is
+ * a separate module from the invoke adapters because the two change for different
+ * reasons — an adapter changes when the vendor SDK does, a translator changes when
+ * the contract does — and conflating them is how a contract silently drifts to
+ * match whatever the SDK happened to return.
+ *
+ * The contract is the authority. When a translation cannot supply a field the
+ * contract requires, that is reported rather than faked; TOOL-01 is explicit that
+ * an incomplete clip must not be presented as fully transcribed.
+ *
+ * @module @try-works/dsh-model-as-tool/contract-payload
+ */
+import type { JsonValue } from './adapters/index.ts';
+/** Raised when a native result cannot be expressed under its contract. */
+export declare class PayloadTranslationError extends Error {
+    readonly name = "PayloadTranslationError";
+}
+/**
+ * Translate a contract's validated arguments into an adapter's native shape.
+ *
+ * This is the input half of the same seam as {@link toContractPayload}. An adapter
+ * speaks its SDK's vocabulary — `audio_path` — while the contract publishes the
+ * caller's vocabulary — `audio.path`. Without this translation the contract layer
+ * would be cosmetic: the model would advertise one shape and the implementation
+ * would read another, and every call would fail on a name that no longer exists.
+ *
+ * The contract is the authority here too, so the mapping is explicit and total
+ * rather than a spread that happens to overlap.
+ * @param contractId - the contract the call was validated against.
+ * @param contractArgs - the validated contract arguments.
+ * @returns the arguments the selected adapter expects.
+ */
+export declare function toNativeArgs(contractId: string, contractArgs: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * Translate a native implementation result into the payload its contract declares.
+ * @param contractId - the contract the implementation was selected for.
+ * @param native - the adapter's native result.
+ * @param args - the validated arguments, for contract-conditional translation.
+ * @returns the contract payload.
+ * @throws PayloadTranslationError when the native result cannot satisfy the contract.
+ */
+export declare function toContractPayload(contractId: string, native: Record<string, JsonValue>, args?: Readonly<Record<string, unknown>>): Record<string, JsonValue>;
+//# sourceMappingURL=contract-payload.d.ts.map

package/lib/contract-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-payload.d.ts","sourceRoot":"","sources":["../src/contract-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,0EAA0E;AAC1E,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,SAAkB,IAAI,6BAA4B;CACnD;AAyED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACjC,IAAI,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GAC3C,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAW3B"}

package/lib/contract-payload.js

@@ -0,0 +1,137 @@
+/**
+ * Translation from a model's native result to a contract's payload.
+ *
+ * The spec puts this responsibility on adapters: they "translate between the
+ * capability's canonical representation and the model's native interface". It is
+ * a separate module from the invoke adapters because the two change for different
+ * reasons — an adapter changes when the vendor SDK does, a translator changes when
+ * the contract does — and conflating them is how a contract silently drifts to
+ * match whatever the SDK happened to return.
+ *
+ * The contract is the authority. When a translation cannot supply a field the
+ * contract requires, that is reported rather than faked; TOOL-01 is explicit that
+ * an incomplete clip must not be presented as fully transcribed.
+ *
+ * @module @try-works/dsh-model-as-tool/contract-payload
+ */
+/** Raised when a native result cannot be expressed under its contract. */
+export class PayloadTranslationError extends Error {
+    name = 'PayloadTranslationError';
+}
+/** Best-effort read of a numeric field. */
+function numberOf(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Translate a native language-detection result into the `text.language_detect`
+ * payload.
+ *
+ * The only rename is the vendor's `isTooCloseToCall` to the contract's
+ * `tooCloseToCall`; every other field already matches, which is what makes this a
+ * translation rather than a reshape.
+ * @param native - the adapter's result.
+ * @returns the contract payload, without the `meta` envelope the host stamps.
+ */
+function languageDetectPayload(native) {
+    const candidates = Array.isArray(native.candidates) ? native.candidates : [];
+    return {
+        // A model that found no language signal returns null rather than a guess.
+        language: typeof native.language === 'string' ? native.language : null,
+        reliability: typeof native.reliability === 'string' ? native.reliability : 'unknown',
+        tooCloseToCall: native.isTooCloseToCall === true,
+        candidates: candidates,
+    };
+}
+/**
+ * Translate a native transcription result into the `stt.transcribe` payload.
+ *
+ * `coverage` is the interesting field. Voz streams the whole file and fails loudly
+ * on a short decode, so a returned transcript covers all the audio it read;
+ * `transcribedSeconds` is taken from the last word's end time, which is a lower
+ * bound on the audio actually processed. When no words are reported, coverage is
+ * reported as zero seconds with `complete: true` only because the engine ran to
+ * completion — an empty transcript is a valid result (TOOL-01), not a failure.
+ * @param native - the adapter's result.
+ * @param requestedWords - whether the caller asked for word timings.
+ * @returns the contract payload, without the `meta` envelope the host stamps.
+ */
+function transcribePayload(native, requestedWords) {
+    const words = Array.isArray(native.words) ? native.words : null;
+    if (requestedWords && words === null) {
+        // TOOL-01: an unsupported timestamp request is an error, never a silent
+        // omission the caller might read as "there were no word timings".
+        throw new PayloadTranslationError('word timestamps were requested but the implementation returned none; '
+            + 'this is reported as an error rather than an empty list');
+    }
+    let transcribedSeconds = 0;
+    if (words !== null && words.length > 0) {
+        const last = words[words.length - 1];
+        transcribedSeconds = numberOf(last.end) ?? 0;
+    }
+    const truncated = native.wordsTruncated === true;
+    return {
+        text: typeof native.text === 'string' ? native.text : '',
+        coverage: {
+            complete: !truncated,
+            transcribedSeconds,
+            totalSeconds: null,
+            reason: truncated ? 'word list truncated for transport; the transcript text is complete' : null,
+        },
+        words: words === null ? null : words,
+        language: typeof native.language === 'string' ? native.language : null,
+    };
+}
+/**
+ * Translate a contract's validated arguments into an adapter's native shape.
+ *
+ * This is the input half of the same seam as {@link toContractPayload}. An adapter
+ * speaks its SDK's vocabulary — `audio_path` — while the contract publishes the
+ * caller's vocabulary — `audio.path`. Without this translation the contract layer
+ * would be cosmetic: the model would advertise one shape and the implementation
+ * would read another, and every call would fail on a name that no longer exists.
+ *
+ * The contract is the authority here too, so the mapping is explicit and total
+ * rather than a spread that happens to overlap.
+ * @param contractId - the contract the call was validated against.
+ * @param contractArgs - the validated contract arguments.
+ * @returns the arguments the selected adapter expects.
+ */
+export function toNativeArgs(contractId, contractArgs) {
+    switch (contractId) {
+        case 'stt.transcribe': {
+            const audio = contractArgs.audio;
+            return {
+                audio_path: audio?.path,
+                // The contract defaults `timestamps` to none, while the adapter defaults
+                // its own flag to true. Mapping explicitly keeps the contract's default
+                // authoritative instead of letting the adapter's leak through.
+                include_words: contractArgs.timestamps === 'word',
+                ...contractArgs.language === undefined ? {} : { language: contractArgs.language },
+            };
+        }
+        default:
+            // `text.language_detect` already shares its argument names with the adapter.
+            return { ...contractArgs };
+    }
+}
+/**
+ * Translate a native implementation result into the payload its contract declares.
+ * @param contractId - the contract the implementation was selected for.
+ * @param native - the adapter's native result.
+ * @param args - the validated arguments, for contract-conditional translation.
+ * @returns the contract payload.
+ * @throws PayloadTranslationError when the native result cannot satisfy the contract.
+ */
+export function toContractPayload(contractId, native, args = {}) {
+    switch (contractId) {
+        case 'text.language_detect':
+            return languageDetectPayload(native);
+        case 'stt.transcribe':
+            return transcribePayload(native, args.timestamps === 'word');
+        default:
+            // A contract with no translator returns the native payload unchanged, which
+            // the output schema then accepts or rejects on its own terms.
+            return native;
+    }
+}
+//# sourceMappingURL=contract-payload.js.map

package/lib/deployment-coordinator.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Deployment coordination: preparation, single-flight loading and reference counting
+ * (RES-02, RES-03, RES-05).
+ *
+ * This is the module that makes readiness states PRODUCED rather than assigned. Before
+ * it, `prepared-cold` and `ready` were values a test could write; here they are values
+ * this coordinator derives from what actually happened.
+ *
+ * Three rules shape the design:
+ *
+ * - **One operation per EXACT deployment** (RES-05). The key that identifies a
+ *   deployment includes the model revision, engine version, quantization and
+ *   preprocessing recipe, not just a model name — two builds of "the same model" that
+ *   differ in quantization are different deployments and loading one must not satisfy
+ *   a request for the other.
+ * - **Concurrent callers JOIN** (RES-05). A second caller during a load awaits the
+ *   same promise rather than starting a second load, which is the difference between
+ *   sharing 349 MB and allocating it twice.
+ * - **A failed or interrupted preparation cannot become ready** (RES-03). Failure is
+ *   recorded as failure, and a later caller retries rather than inheriting a
+ *   half-prepared deployment that reports success.
+ *
+ * @module @try-works/dsh-model-as-tool/deployment-coordinator
+ */
+import type { ModelReadiness } from '@try-works/tool-mode-extension-sdk';
+/**
+ * The identity of an EXACT provider deployment (RES-02, RES-05).
+ *
+ * Every field participates in the deployment key. Pinning only the model name would
+ * let a caller be served by a differently-quantized build than the one it requested.
+ */
+export interface DeploymentIdentity {
+    /** The extension package that provides it. */
+    readonly extensionId: string;
+    /** The model inside that package. */
+    readonly modelId: string;
+    /** The exact model revision, not a branch or a floating tag. */
+    readonly modelRevision: string;
+    /** The engine or SDK version the assets were converted for. */
+    readonly engineVersion: string;
+    /** The quantization, which changes outputs and is therefore part of identity. */
+    readonly quantization: string;
+    /** The tokenizer identity. */
+    readonly tokenizer: string;
+    /** The preprocessing recipe version. */
+    readonly preprocessingRecipe: string;
+}
+/**
+ * The stable key for an exact deployment (RES-05).
+ *
+ * A delimiter that cannot appear in a component, so two different field combinations
+ * cannot collide into one key.
+ * @param identity - the deployment identity.
+ * @returns the key.
+ */
+export declare function deploymentKey(identity: DeploymentIdentity): string;
+/** One asset a preparation must obtain (RES-02, RES-03). */
+export interface PlannedAsset {
+    /** The asset id from the lock file. */
+    readonly assetId: string;
+    /** The download size in bytes, for the pre-approval disclosure. */
+    readonly bytes: number;
+    /** The pinned source. */
+    readonly source: string;
+    /** The expected content digest. */
+    readonly digest: string;
+    /**
+     * Whether this asset is an EXECUTABLE.
+     *
+     * RES-02: prebuilt engine downloads count as executable installation, so they
+     * require the separate executable-preparation approval rather than riding along
+     * with a model download.
+     */
+    readonly executable: boolean;
+}
+/** What a preparation would do, shown before approval (RES-02). */
+export interface PreparationPlan {
+    readonly identity: DeploymentIdentity;
+    readonly assets: readonly PlannedAsset[];
+    /** Total download size, so an operator approves a number rather than a hope. */
+    readonly totalBytes: number;
+    /** Total bytes retained after installation. */
+    readonly storageBytes: number;
+    /** Whether any asset is executable, which changes which approval is needed. */
+    readonly requiresExecutableApproval: boolean;
+    /** The pinned license terms, surfaced before the download rather than after. */
+    readonly license: {
+        readonly name: string;
+        readonly url: string;
+    };
+}
+/**
+ * Build the pre-approval disclosure (RES-02).
+ *
+ * An operator approving a preparation is approving a specific download of a specific
+ * size under specific terms, so all three are computed here rather than discovered
+ * during the install.
+ * @param identity - the exact deployment.
+ * @param assets - the assets the lock resolves to.
+ * @param license - the pinned license.
+ * @returns the plan.
+ */
+export declare function planPreparation(identity: DeploymentIdentity, assets: readonly PlannedAsset[], license: {
+    readonly name: string;
+    readonly url: string;
+}): PreparationPlan;
+/** A preparation that has not yet completed. */
+export interface DeploymentRecord {
+    /** The exact deployment key. */
+    readonly key: string;
+    /** The identity it belongs to. */
+    readonly identity: DeploymentIdentity;
+    /** The current state, using the RES-04 vocabulary. */
+    readiness: ModelReadiness;
+    /** How many callers currently hold a reference. */
+    activeUsers: number;
+    /** When the current load began, if one is in progress. */
+    loadingSince: number | null;
+    /** Why it failed, when it did. */
+    failureReason: string | null;
+}
+/** What a caller receives when it acquires a deployment. */
+export interface DeploymentLease {
+    /** The deployment key. */
+    readonly key: string;
+    /** The state at acquisition. */
+    readonly readiness: ModelReadiness;
+    /** Whether the caller waited for a load to finish. */
+    readonly joined: boolean;
+    /** Release this caller's reference. Idempotent. */
+    release(): void;
+}
+/** Raised when a deployment cannot be prepared. */
+export declare class DeploymentError extends Error {
+    readonly name = "DeploymentError";
+    readonly key: string;
+    constructor(key: string, message: string);
+}
+/**
+ * Coordinates preparation, loading and reference counting per exact deployment.
+ *
+ * Not thread-safe in the language sense — Node is single-threaded — but
+ * single-flight with respect to `await`: two callers that reach `acquire` before the
+ * load settles both await ONE promise.
+ */
+export declare class DeploymentCoordinator {
+    #private;
+    /** Every tracked deployment, for diagnostics. */
+    get deployments(): readonly DeploymentRecord[];
+    /** One deployment's record. */
+    record(key: string): DeploymentRecord | undefined;
+    /**
+     * The state to report for a deployment that has not been touched yet.
+     * @param identity - the exact deployment.
+     * @returns the readiness.
+     */
+    readinessOf(identity: DeploymentIdentity): ModelReadiness;
+    /**
+     * Prepare and load a deployment, joining an in-flight load if there is one.
+     *
+     * RES-05: "One preparation/load operation per exact provider deployment; concurrent
+     * callers join or queue."
+     * @param identity - the exact deployment.
+     * @param load - performs the load. Called AT MOST ONCE per concurrent group.
+     * @param options - cancellation for THIS caller.
+     * @returns the lease.
+     * @throws DeploymentError when the load fails.
+     */
+    acquire(identity: DeploymentIdentity, load: () => Promise<void>, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<DeploymentLease>;
+    /**
+     * Unload a deployment, but only when it is IDLE (RES-05).
+     *
+     * "Unload only idle resources or an explicitly revoked deployment after coordinated
+     * cleanup." Unloading a busy deployment would discard another caller's work.
+     * @param key - the deployment key.
+     * @param force - set only for an explicitly revoked deployment.
+     * @returns whether it was unloaded, and why not when it was not.
+     */
+    unload(key: string, force?: boolean): {
+        readonly unloaded: boolean;
+        readonly reason?: string;
+    };
+    /**
+     * Revoke a deployment, discarding in-flight work after coordinated cleanup (RES-05).
+     * @param key - the deployment key.
+     * @returns whether it was revoked.
+     */
+    revoke(key: string): boolean;
+}
+/** An asset ownership record (RES-03). */
+export interface AssetOwnership {
+    /** The content digest, which is what makes sharing safe. */
+    readonly digest: string;
+    /** The holders of this asset, by owner id. */
+    readonly owners: readonly string[];
+}
+/**
+ * Decide which assets may be deleted (RES-03).
+ *
+ * RES-03: "Package uninstall and asset purge are separate operations; delete only
+ * unreferenced host-owned assets." So removing an owner does not delete anything, and
+ * an asset with another owner is never deleted.
+ * @param ownership - the current records.
+ * @param removedOwner - the owner being uninstalled.
+ * @returns the digests that are now unreferenced, and those still held.
+ */
+export declare function purgeCandidates(ownership: readonly AssetOwnership[], removedOwner: string): {
+    readonly deletable: readonly string[];
+    readonly retained: readonly string[];
+};
+//# sourceMappingURL=deployment-coordinator.d.ts.map

package/lib/deployment-coordinator.d.ts.map

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

package/lib/deployment-coordinator.js

@@ -0,0 +1,274 @@
+/**
+ * Deployment coordination: preparation, single-flight loading and reference counting
+ * (RES-02, RES-03, RES-05).
+ *
+ * This is the module that makes readiness states PRODUCED rather than assigned. Before
+ * it, `prepared-cold` and `ready` were values a test could write; here they are values
+ * this coordinator derives from what actually happened.
+ *
+ * Three rules shape the design:
+ *
+ * - **One operation per EXACT deployment** (RES-05). The key that identifies a
+ *   deployment includes the model revision, engine version, quantization and
+ *   preprocessing recipe, not just a model name — two builds of "the same model" that
+ *   differ in quantization are different deployments and loading one must not satisfy
+ *   a request for the other.
+ * - **Concurrent callers JOIN** (RES-05). A second caller during a load awaits the
+ *   same promise rather than starting a second load, which is the difference between
+ *   sharing 349 MB and allocating it twice.
+ * - **A failed or interrupted preparation cannot become ready** (RES-03). Failure is
+ *   recorded as failure, and a later caller retries rather than inheriting a
+ *   half-prepared deployment that reports success.
+ *
+ * @module @try-works/dsh-model-as-tool/deployment-coordinator
+ */
+/**
+ * The stable key for an exact deployment (RES-05).
+ *
+ * A delimiter that cannot appear in a component, so two different field combinations
+ * cannot collide into one key.
+ * @param identity - the deployment identity.
+ * @returns the key.
+ */
+export function deploymentKey(identity) {
+    return [
+        identity.extensionId,
+        identity.modelId,
+        identity.modelRevision,
+        identity.engineVersion,
+        identity.quantization,
+        identity.tokenizer,
+        identity.preprocessingRecipe,
+        // A unit separator is used rather than a printable character because a model id can
+        // legitimately contain most printable ones.
+    ].join('\u001f');
+}
+/**
+ * Build the pre-approval disclosure (RES-02).
+ *
+ * An operator approving a preparation is approving a specific download of a specific
+ * size under specific terms, so all three are computed here rather than discovered
+ * during the install.
+ * @param identity - the exact deployment.
+ * @param assets - the assets the lock resolves to.
+ * @param license - the pinned license.
+ * @returns the plan.
+ */
+export function planPreparation(identity, assets, license) {
+    const totalBytes = assets.reduce((sum, asset) => sum + asset.bytes, 0);
+    return {
+        identity,
+        assets,
+        totalBytes,
+        // Storage is stated separately from download because an operator approving
+        // bandwidth is not thereby approving disk.
+        storageBytes: totalBytes,
+        requiresExecutableApproval: assets.some(asset => asset.executable),
+        license,
+    };
+}
+/** Raised when a deployment cannot be prepared. */
+export class DeploymentError extends Error {
+    name = 'DeploymentError';
+    key;
+    constructor(key, message) {
+        super(message);
+        this.key = key;
+    }
+}
+/**
+ * Coordinates preparation, loading and reference counting per exact deployment.
+ *
+ * Not thread-safe in the language sense — Node is single-threaded — but
+ * single-flight with respect to `await`: two callers that reach `acquire` before the
+ * load settles both await ONE promise.
+ */
+export class DeploymentCoordinator {
+    #records = new Map();
+    /** The in-flight load per key, so concurrent callers join rather than duplicate. */
+    #loading = new Map();
+    /** Per-caller release handlers, so releasing is idempotent. */
+    #leases = new WeakSet();
+    /** Every tracked deployment, for diagnostics. */
+    get deployments() {
+        return [...this.#records.values()];
+    }
+    /** One deployment's record. */
+    record(key) {
+        return this.#records.get(key);
+    }
+    /**
+     * The state to report for a deployment that has not been touched yet.
+     * @param identity - the exact deployment.
+     * @returns the readiness.
+     */
+    readinessOf(identity) {
+        return this.#records.get(deploymentKey(identity))?.readiness ?? 'needs-preparation';
+    }
+    /**
+     * Prepare and load a deployment, joining an in-flight load if there is one.
+     *
+     * RES-05: "One preparation/load operation per exact provider deployment; concurrent
+     * callers join or queue."
+     * @param identity - the exact deployment.
+     * @param load - performs the load. Called AT MOST ONCE per concurrent group.
+     * @param options - cancellation for THIS caller.
+     * @returns the lease.
+     * @throws DeploymentError when the load fails.
+     */
+    async acquire(identity, load, options = {}) {
+        const key = deploymentKey(identity);
+        let record = this.#records.get(key);
+        if (record === undefined) {
+            record = {
+                key,
+                identity,
+                readiness: 'needs-preparation',
+                activeUsers: 0,
+                loadingSince: null,
+                failureReason: null,
+            };
+            this.#records.set(key, record);
+        }
+        // A previous failure must not be inherited as a success: RES-03 says a failed or
+        // interrupted preparation cannot become ready, so the next caller RETRIES.
+        if (record.readiness === 'failed') {
+            record.readiness = 'needs-preparation';
+            record.failureReason = null;
+        }
+        let joined = false;
+        if (record.readiness === 'ready') {
+            // Already loaded: nothing to join.
+        }
+        else {
+            let pending = this.#loading.get(key);
+            if (pending === undefined) {
+                pending = this.#startLoad(record, load);
+                this.#loading.set(key, pending);
+            }
+            else {
+                joined = true;
+            }
+            try {
+                await pending;
+            }
+            catch (error) {
+                // The caller is told WHY, and the record keeps the failure so a later caller
+                // retries rather than seeing a stale success.
+                throw new DeploymentError(key, `${identity.extensionId}/${identity.modelId} could not be prepared: `
+                    + `${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (options.signal?.aborted === true) {
+            // Cancellation is PER INVOCATION (RES-05): this caller gives up, and the
+            // deployment it just waited for is left loaded and available to whoever else
+            // wants it. Killing it here would destroy another caller's legitimate work.
+            throw new DeploymentError(key, 'the caller cancelled before the deployment could be used');
+        }
+        record.activeUsers += 1;
+        const lease = {
+            key,
+            readiness: record.readiness,
+            joined,
+            release: () => this.#release(key, lease),
+        };
+        return lease;
+    }
+    /** Start the single load for a key. */
+    #startLoad(record, load) {
+        record.readiness = 'loading';
+        record.loadingSince = Date.now();
+        const pending = (async () => {
+            try {
+                await load();
+                // A load that threw is not ready; a load that returned is.
+                record.readiness = 'ready';
+                record.failureReason = null;
+            }
+            catch (error) {
+                // RES-03: a failed or interrupted preparation CANNOT become ready.
+                record.readiness = 'failed';
+                record.failureReason = error instanceof Error ? error.message : String(error);
+                throw error;
+            }
+            finally {
+                record.loadingSince = null;
+                this.#loading.delete(record.key);
+            }
+        })();
+        return pending;
+    }
+    /** Decrement a caller's reference. */
+    #release(key, lease) {
+        if (this.#leases.has(lease))
+            return;
+        this.#leases.add(lease);
+        const record = this.#records.get(key);
+        if (record === undefined)
+            return;
+        record.activeUsers = Math.max(0, record.activeUsers - 1);
+    }
+    /**
+     * Unload a deployment, but only when it is IDLE (RES-05).
+     *
+     * "Unload only idle resources or an explicitly revoked deployment after coordinated
+     * cleanup." Unloading a busy deployment would discard another caller's work.
+     * @param key - the deployment key.
+     * @param force - set only for an explicitly revoked deployment.
+     * @returns whether it was unloaded, and why not when it was not.
+     */
+    unload(key, force = false) {
+        const record = this.#records.get(key);
+        if (record === undefined)
+            return { unloaded: false, reason: 'no such deployment' };
+        if (this.#loading.has(key)) {
+            return { unloaded: false, reason: 'a load is in progress' };
+        }
+        if (record.activeUsers > 0 && !force) {
+            // The count is the whole point: another caller is using this right now.
+            return { unloaded: false, reason: `${record.activeUsers} caller(s) are still using it` };
+        }
+        record.readiness = 'prepared-cold';
+        return { unloaded: true };
+    }
+    /**
+     * Revoke a deployment, discarding in-flight work after coordinated cleanup (RES-05).
+     * @param key - the deployment key.
+     * @returns whether it was revoked.
+     */
+    revoke(key) {
+        const record = this.#records.get(key);
+        if (record === undefined)
+            return false;
+        // Revocation is the one case that may discard a busy deployment, and it is
+        // explicit: the operator asked for it rather than a policy inferring it.
+        record.activeUsers = 0;
+        record.readiness = 'prepared-cold';
+        return true;
+    }
+}
+/**
+ * Decide which assets may be deleted (RES-03).
+ *
+ * RES-03: "Package uninstall and asset purge are separate operations; delete only
+ * unreferenced host-owned assets." So removing an owner does not delete anything, and
+ * an asset with another owner is never deleted.
+ * @param ownership - the current records.
+ * @param removedOwner - the owner being uninstalled.
+ * @returns the digests that are now unreferenced, and those still held.
+ */
+export function purgeCandidates(ownership, removedOwner) {
+    const deletable = [];
+    const retained = [];
+    for (const asset of ownership) {
+        const remaining = asset.owners.filter(owner => owner !== removedOwner);
+        // An asset with a remaining owner is RETAINED, because deleting it would break a
+        // deployment nobody uninstalled.
+        if (remaining.length === 0)
+            deletable.push(asset.digest);
+        else
+            retained.push(asset.digest);
+    }
+    return { deletable, retained };
+}
+//# sourceMappingURL=deployment-coordinator.js.map