@1mcp/agent 0.39.5 → 0.40.0-beta.0

package/build/domains/backend-preparation/service.js

@@ -0,0 +1,709 @@
+import { BackendPolicySchema, BackendReadyReadinessSchema, PreparationFailureSchema, preparationKey, PreparationOptionsSchema, PreparationTargetSchema, } from './policy.js';
+import { PreparationScheduler } from './scheduler.js';
+export class BackendPreparationService {
+    registry;
+    options;
+    scheduler;
+    jobs = new Map();
+    identities = new Map();
+    sequence = 0;
+    shuttingDown = false;
+    constructor(registry, options = {}) {
+        this.registry = registry;
+        this.options = PreparationOptionsSchema.parse(options);
+        this.scheduler = new PreparationScheduler(this.options.concurrency, this.options.queueCapacity);
+    }
+    async inspect(target, operation, options = {}) {
+        const resolved = PreparationTargetSchema.parse(target);
+        const adapter = this.registry.get(resolved.backendName);
+        if (!adapter)
+            return this.unsupported(resolved.backendName);
+        const waitMs = PreparationOptionsSchema.shape.requestWaitMs.parse(options.waitMs ?? this.options.requestWaitMs);
+        return this.probe(adapter, resolved, operation, waitMs, options.signal);
+    }
+    /** Explicit status inspection is read-only and never admits, retries, or changes a job. */
+    async inspectProgress(target, operation, options = {}) {
+        const resolved = PreparationTargetSchema.parse(target);
+        const adapter = this.registry.get(resolved.backendName);
+        if (!adapter?.progress)
+            return undefined;
+        const waitMs = PreparationOptionsSchema.shape.requestWaitMs.parse(options.waitMs ?? this.options.requestWaitMs);
+        if (waitMs === 0 || options.signal?.aborted)
+            return undefined;
+        const controller = new AbortController();
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (progress) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', stop);
+                resolve(progress);
+            };
+            const stop = () => {
+                controller.abort();
+                finish();
+            };
+            const timer = setTimeout(stop, waitMs);
+            options.signal?.addEventListener('abort', stop, { once: true });
+            try {
+                void adapter.progress(resolved, operation, { signal: controller.signal, waitMs }).then(finish, () => finish());
+            }
+            catch {
+                finish();
+            }
+        });
+    }
+    /** Recovery only reconciles native evidence. A persisted running flag never starts or kills work. */
+    async recover(target, operation, advisory, options = {}) {
+        const resolved = PreparationTargetSchema.parse(target);
+        const adapter = this.registry.get(resolved.backendName);
+        if (!adapter)
+            return this.unsupported(resolved.backendName);
+        if (!adapter.reconcile)
+            return {
+                state: 'conflict',
+                instructions: 'Native ownership reconciliation is unavailable; inspect prerequisites before explicit preparation.',
+            };
+        const waitMs = PreparationOptionsSchema.shape.requestWaitMs.parse(options.waitMs ?? this.options.requestWaitMs);
+        return this.readReadiness((signal) => adapter.reconcile(resolved, operation, advisory, { signal, waitMs }), (error) => adapter.classifyFailure(error), waitMs, options.signal);
+    }
+    async prepare(target, operation, policy, action, options = {}) {
+        if (this.shuttingDown)
+            return this.shutdownResult();
+        const resolved = Object.freeze(PreparationTargetSchema.parse(target));
+        const authority = BackendPolicySchema.parse(policy);
+        const active = this.activeJob(resolved, authority, action, operation);
+        if (active)
+            return { state: 'job', status: this.snapshot(active) };
+        const adapter = this.registry.get(resolved.backendName);
+        if (!adapter)
+            return this.unsupported(resolved.backendName);
+        const waitMs = PreparationOptionsSchema.shape.requestWaitMs.parse(options.waitMs ?? this.options.requestWaitMs);
+        const readiness = await this.probe(adapter, resolved, operation, waitMs, options.signal);
+        return this.prepareInspected(resolved, operation, authority, adapter, readiness, action, undefined, options.beforeAdmission, options.validateAdmission);
+    }
+    async prepareInspected(resolved, operation, authority, adapter, readiness, action, replacement, beforeAdmission, validateAdmission) {
+        if (this.shuttingDown)
+            return this.shutdownResult();
+        const active = this.activeJob(resolved, authority, action, operation);
+        if (active)
+            return { state: 'job', status: this.snapshot(active) };
+        if (readiness.state === 'conflict')
+            return readiness;
+        if (readiness.state === 'unsupported')
+            return readiness;
+        if (readiness.state === 'unknown')
+            return readiness;
+        if (readiness.state === 'ready') {
+            if (!action) {
+                this.clearResolvedFailure(resolved, operation, authority, readiness);
+                return { state: 'ready', readiness };
+            }
+        }
+        const selected = action ?? (readiness.state === 'required' ? readiness.action : undefined);
+        if (!selected)
+            return { state: 'forbidden', instructions: 'No permitted preparation action was selected.' };
+        if (!authority.allowedActions.includes(selected))
+            return { state: 'forbidden', instructions: `Runtime policy does not permit ${selected}.` };
+        const key = `${preparationKey(resolved, authority, this.options, operation)}:${selected}`;
+        // Another compatible inspection may have admitted a job while this inspection was pending.
+        const failed = action ? undefined : this.failedJob(resolved, authority, operation);
+        if (failed)
+            return { state: 'job', status: this.snapshot(failed) };
+        const admitted = this.findJob(key);
+        if (admitted && admitted !== replacement && admitted.status.state !== 'ready') {
+            if (replacement)
+                return {
+                    state: 'busy',
+                    instructions: `Retry of ${replacement.status.id} (${replacement.status.action}) did not start: ${admitted.status.id} owns ${selected}. Check or explicitly retry that operation; both records are preserved.`,
+                };
+            if (admitted.status.action !== selected)
+                return {
+                    state: 'busy',
+                    instructions: `Preparation ${admitted.status.id} reserves ${selected} while performing ${admitted.status.action}; wait before explicitly selecting ${selected} again.`,
+                };
+            return { state: 'job', status: this.snapshot(admitted) };
+        }
+        if (!replacement)
+            this.releaseCompletedRecords();
+        if (this.jobs.size - (replacement ? 1 : 0) >= this.options.maxRecords)
+            return {
+                state: 'busy',
+                instructions: 'Preparation status capacity reached; use a new runtime after reconciling retained operations.',
+            };
+        if (validateAdmission) {
+            await validateAdmission();
+            // Validation may have yielded to another caller, shutdown, or a completed job.
+            // Repeat identity/capacity checks, then run the synchronous mutation guard with no further await.
+            return this.prepareInspected(resolved, operation, authority, adapter, readiness, action, replacement, beforeAdmission);
+        }
+        let complete;
+        const completion = new Promise((resolve) => {
+            complete = resolve;
+        });
+        const job = {
+            status: {
+                id: `preparation-${++this.sequence}`,
+                target: resolved,
+                operation,
+                action: selected,
+                state: 'queued',
+                attempt: 1,
+                executionDeadlineMs: authority.executionDeadlineMs ?? this.options.executionDeadlineMs,
+                readiness,
+            },
+            adapter,
+            policy: authority,
+            controller: new AbortController(),
+            listeners: new Set(),
+            settling: false,
+            createdAt: Date.now(),
+            retrying: false,
+            completion,
+            complete,
+            automatic: action === undefined,
+        };
+        if (!this.scheduler.schedule(job.status.id, async (wasQueued) => {
+            try {
+                await this.execute(job, wasQueued);
+            }
+            finally {
+                job.complete();
+            }
+        }, JSON.stringify([resolved.checkoutRoot, resolved.backendName]), beforeAdmission)) {
+            return { state: 'busy', instructions: 'Preparation queue is full; submit a new request later.' };
+        }
+        if (replacement)
+            this.removeRecord(replacement);
+        this.jobs.set(job.status.id, job);
+        this.identities.set(key, job.status.id);
+        return { state: 'job', status: this.snapshot(job) };
+    }
+    /** Never receives an operation callback, so pending calls cannot be queued or replayed. */
+    async admit(target, operation, policy, preferences, options = {}) {
+        if (this.shuttingDown)
+            return this.shutdownResult();
+        const resolved = Object.freeze(PreparationTargetSchema.parse(target));
+        const authority = BackendPolicySchema.parse(policy);
+        const waitMs = PreparationOptionsSchema.shape.requestWaitMs.parse(options.waitMs ?? this.options.requestWaitMs);
+        const expiresAt = Date.now() + waitMs;
+        const remaining = () => Math.max(0, expiresAt - Date.now());
+        const active = this.activeJob(resolved, authority, undefined, operation);
+        let result;
+        if (active) {
+            result = { state: 'job', status: this.snapshot(active) };
+        }
+        else {
+            const adapter = this.registry.get(resolved.backendName);
+            if (!adapter)
+                return this.unsupported(resolved.backendName);
+            const readiness = await this.probe(adapter, resolved, operation, remaining(), options.signal);
+            const joined = this.activeJob(resolved, authority, undefined, operation);
+            if (joined)
+                result = { state: 'job', status: this.snapshot(joined) };
+            else {
+                if (readiness.state === 'ready') {
+                    this.clearResolvedFailure(resolved, operation, authority, readiness);
+                    return { state: 'ready', readiness };
+                }
+                if (readiness.state === 'unsupported')
+                    return readiness;
+                if (readiness.state === 'conflict')
+                    return readiness;
+                if (readiness.state === 'unknown')
+                    return readiness;
+                if (!preferences[resolved.backendName]?.enabled)
+                    return { state: 'disabled', instructions: readiness.instructions };
+                result = await this.prepareInspected(resolved, operation, authority, adapter, readiness, undefined, undefined, options.beforeAdmission, options.validateAdmission);
+            }
+        }
+        if (result.state !== 'job')
+            return result;
+        if (result.status.state === 'failed')
+            return result;
+        if (result.status.state === 'not_ready')
+            return result;
+        if (result.status.state === 'cancelled')
+            return result;
+        return this.pending(result.status, `Preparation ${result.status.id} is ${result.status.state}. Check status or wait, then submit the original operation again.`);
+    }
+    pending(status, instructions) {
+        return {
+            state: 'pending',
+            status,
+            operationExecuted: false,
+            operationQueued: false,
+            instructions: `${instructions} The original operation has not executed and will not be replayed.`,
+        };
+    }
+    /** All admitted jobs, including automatic jobs with no public control handle. */
+    activeStatuses() {
+        return [...this.jobs.values()]
+            .filter((job) => ['queued', 'running', 'cancelling'].includes(job.status.state))
+            .map((job) => this.snapshot(job));
+    }
+    status(id) {
+        const job = this.jobs.get(id);
+        return job ? this.snapshot(job) : undefined;
+    }
+    async wait(id, options = {}) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return undefined;
+        const waitMs = PreparationOptionsSchema.shape.requestWaitMs.parse(options.waitMs ?? this.options.requestWaitMs);
+        if (this.terminal(job))
+            return this.snapshot(job);
+        if (options.signal?.aborted)
+            return this.snapshot(job);
+        if (job.listeners.size >= 1024)
+            return this.snapshot(job);
+        await new Promise((resolve) => {
+            const finish = () => {
+                clearTimeout(timer);
+                job.listeners.delete(changed);
+                options.signal?.removeEventListener('abort', finish);
+                resolve();
+            };
+            const changed = () => {
+                if (this.terminal(job))
+                    finish();
+            };
+            const timer = setTimeout(finish, waitMs);
+            job.listeners.add(changed);
+            options.signal?.addEventListener('abort', finish, { once: true });
+        });
+        return this.snapshot(job);
+    }
+    cancel(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return undefined;
+        if (this.terminal(job))
+            return this.snapshot(job);
+        if (this.scheduler.cancelQueued(id)) {
+            this.update(job, { state: 'cancelled' });
+            job.complete();
+            return this.snapshot(job);
+        }
+        this.update(job, { state: 'cancelling' });
+        job.controller.abort();
+        return this.snapshot(job);
+    }
+    /** Explicit retry creates a new compatible identity when the execution budget changes. */
+    async retry(id, policy, options = {}) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return { state: 'unsupported', instructions: 'Unknown preparation operation.' };
+        if (this.shuttingDown)
+            return this.shutdownResult();
+        if (job.retrying)
+            return { state: 'busy', instructions: 'Explicit retry inspection is already in progress.' };
+        if (job.settling)
+            return { state: 'busy', instructions: 'Owned preparation work has not stopped yet.' };
+        if (!this.terminal(job))
+            return { state: 'job', status: this.snapshot(job) };
+        const authority = BackendPolicySchema.parse(policy ?? job.policy);
+        const deadline = authority.executionDeadlineMs ?? this.options.executionDeadlineMs;
+        if (job.status.failure?.code === 'execution_deadline') {
+            if (deadline <= job.status.executionDeadlineMs)
+                return {
+                    state: 'forbidden',
+                    instructions: 'Execution deadline exhausted; explicitly select a larger execution budget before retrying.',
+                };
+        }
+        job.retrying = true;
+        try {
+            const waitMs = PreparationOptionsSchema.shape.requestWaitMs.parse(options.waitMs ?? this.options.requestWaitMs);
+            const readiness = await this.probe(job.adapter, job.status.target, job.status.operation, waitMs, options.signal);
+            if (readiness.state === 'required' && readiness.action !== job.status.action) {
+                if (!authority.allowedActions.includes(readiness.action))
+                    return { state: 'forbidden', instructions: `Runtime policy does not permit ${readiness.action}.` };
+                const destination = this.findJob(`${preparationKey(job.status.target, authority, this.options, job.status.operation)}:${readiness.action}`);
+                if (destination && destination.status.state !== 'ready')
+                    return {
+                        state: 'busy',
+                        instructions: `Retry of ${job.status.id} did not start: ${destination.status.id} already owns ${readiness.action}. Both records are preserved.`,
+                    };
+                // A further required action is a separate job, explicitly admitted by retry.
+                // Preserve the previous action's terminal record rather than rewriting history.
+                return await this.prepareInspected(job.status.target, job.status.operation, authority, job.adapter, readiness, readiness.action, undefined, options.beforeAdmission, options.validateAdmission);
+            }
+            if (!authority.allowedActions.includes(job.status.action))
+                return { state: 'forbidden', instructions: `Runtime policy does not permit ${job.status.action}.` };
+            return await this.prepareInspected(job.status.target, job.status.operation, authority, job.adapter, readiness, job.status.action, job, options.beforeAdmission, options.validateAdmission);
+        }
+        finally {
+            job.retrying = false;
+        }
+    }
+    /** Stop admission and wait for actual owned work settlement, including expired jobs. */
+    async shutdown() {
+        this.shuttingDown = true;
+        const completions = [];
+        for (const job of this.jobs.values()) {
+            if (job.settling)
+                job.controller.abort();
+            if (!this.terminal(job))
+                this.cancel(job.status.id);
+            completions.push(job.completion);
+        }
+        await Promise.all(completions);
+    }
+    /** Only restores a validated stable failure; it confers no process ownership or repair authority. */
+    importFailure(target, operation, policy, action, failure, state = 'failed') {
+        if (this.shuttingDown)
+            return undefined;
+        const resolved = Object.freeze(PreparationTargetSchema.parse(target));
+        const authority = BackendPolicySchema.parse(policy);
+        const diagnostic = PreparationFailureSchema.parse(failure);
+        if (!operation)
+            throw new Error('Preparation operation is required');
+        if (!authority.allowedActions.includes(action))
+            return undefined;
+        const adapter = this.registry.get(resolved.backendName);
+        if (!adapter)
+            return undefined;
+        const key = `${preparationKey(resolved, authority, this.options, operation)}:${action}`;
+        if (this.findJob(key))
+            return undefined;
+        if (this.activeJob(resolved, authority, undefined, operation))
+            return undefined;
+        this.releaseCompletedRecords();
+        if (this.jobs.size >= this.options.maxRecords)
+            return undefined;
+        const job = {
+            status: {
+                id: `preparation-${++this.sequence}`,
+                target: resolved,
+                operation,
+                action,
+                state,
+                attempt: 1,
+                executionDeadlineMs: authority.executionDeadlineMs ?? this.options.executionDeadlineMs,
+                failure: diagnostic,
+            },
+            adapter,
+            policy: authority,
+            controller: new AbortController(),
+            listeners: new Set(),
+            settling: false,
+            createdAt: Date.now(),
+            finishedAt: Date.now(),
+            retrying: false,
+            completion: Promise.resolve(),
+            complete: () => { },
+            automatic: false,
+        };
+        this.jobs.set(job.status.id, job);
+        this.identities.set(key, job.status.id);
+        return this.snapshot(job);
+    }
+    /** Caller supplies fresh native evidence; advisory state alone cannot resolve a failure. */
+    clearResolvedFailure(target, operation, policy, readiness) {
+        const resolved = PreparationTargetSchema.parse(target);
+        const authority = BackendPolicySchema.parse(policy);
+        BackendReadyReadinessSchema.parse(readiness);
+        const base = preparationKey(resolved, authority, this.options, operation);
+        let cleared = 0;
+        for (const action of authority.allowedActions) {
+            const job = this.findJob(`${base}:${action}`);
+            if (!job)
+                continue;
+            if (job.status.state !== 'failed' && job.status.state !== 'not_ready')
+                continue;
+            if (job.status.operation !== operation)
+                continue;
+            if (job.settling)
+                continue;
+            if (job.retrying)
+                continue;
+            this.removeRecord(job);
+            cleared++;
+        }
+        return cleared;
+    }
+    removeRecord(job) {
+        this.jobs.delete(job.status.id);
+        for (const [key, id] of this.identities) {
+            if (id === job.status.id)
+                this.identities.delete(key);
+        }
+    }
+    shutdownResult() {
+        return { state: 'busy', instructions: 'Preparation runtime is shutting down; no new work can start.' };
+    }
+    async execute(job, wasQueued) {
+        if (job.controller.signal.aborted) {
+            this.update(job, { state: 'cancelled' });
+            return;
+        }
+        job.settling = true;
+        this.update(job, { state: 'running' });
+        const expiresAt = Date.now() + job.status.executionDeadlineMs;
+        const deadline = setTimeout(() => {
+            if (job.status.state === 'cancelling')
+                return;
+            this.update(job, {
+                state: 'failed',
+                failure: {
+                    code: 'execution_deadline',
+                    message: 'Preparation execution deadline exhausted.',
+                    retryable: false,
+                    instructions: 'Wait for owned work to stop, then explicitly retry with a larger execution budget.',
+                },
+            });
+            job.controller.abort();
+        }, job.status.executionDeadlineMs);
+        try {
+            if (wasQueued) {
+                if (job.automatic) {
+                    if (!(await this.reconcileQueuedReadiness(job, expiresAt)))
+                        return;
+                }
+            }
+            await this.runAttempts(job);
+            if (job.controller.signal.aborted) {
+                if (job.status.state !== 'failed')
+                    this.update(job, { state: 'cancelled' });
+                return;
+            }
+            const readiness = await this.probe(job.adapter, job.status.target, job.status.operation, Math.max(0, expiresAt - Date.now()), job.controller.signal);
+            if (job.controller.signal.aborted) {
+                if (job.status.state !== 'failed')
+                    this.update(job, { state: 'cancelled' });
+                return;
+            }
+            if (readiness.state !== 'ready') {
+                this.update(job, {
+                    state: 'not_ready',
+                    readiness,
+                    failure: {
+                        code: readiness.state === 'required' ? 'further_action_required' : 'not_ready',
+                        message: 'Preparation completed without verified readiness.',
+                        retryable: false,
+                        instructions: readiness.instructions,
+                    },
+                });
+                return;
+            }
+            this.update(job, { state: 'ready', readiness });
+        }
+        catch (error) {
+            if (job.status.state === 'failed')
+                return;
+            if (job.controller.signal.aborted) {
+                this.update(job, { state: 'cancelled' });
+                return;
+            }
+            this.update(job, { state: 'failed', failure: job.adapter.classifyFailure(error) });
+        }
+        finally {
+            clearTimeout(deadline);
+            job.settling = false;
+        }
+    }
+    async reconcileQueuedReadiness(job, expiresAt) {
+        const readiness = await this.probe(job.adapter, job.status.target, job.status.operation, Math.max(0, expiresAt - Date.now()), job.controller.signal);
+        if (job.controller.signal.aborted) {
+            if (job.status.state !== 'failed')
+                this.update(job, { state: 'cancelled' });
+            return false;
+        }
+        if (readiness.state === 'ready') {
+            this.update(job, { state: 'ready', readiness });
+            return false;
+        }
+        if (readiness.state !== 'required') {
+            this.update(job, {
+                state: 'failed',
+                readiness,
+                failure: {
+                    code: 'not_ready',
+                    message: 'Queued preparation could not verify native readiness.',
+                    retryable: false,
+                    instructions: readiness.instructions,
+                },
+            });
+            return false;
+        }
+        if (!job.policy.allowedActions.includes(readiness.action)) {
+            this.update(job, {
+                state: 'failed',
+                readiness,
+                failure: {
+                    code: 'action_forbidden',
+                    message: `Runtime policy does not permit ${readiness.action}.`,
+                    retryable: false,
+                    instructions: readiness.instructions,
+                },
+            });
+            return false;
+        }
+        this.moveActionIdentity(job, readiness.action);
+        this.update(job, { action: readiness.action, readiness });
+        return true;
+    }
+    moveActionIdentity(job, action) {
+        const base = preparationKey(job.status.target, job.policy, this.options, job.status.operation);
+        const destinationKey = `${base}:${action}`;
+        const destination = this.findJob(destinationKey);
+        if (destination === job)
+            return;
+        if (destination) {
+            // Keep the inferred job's original reservation when another explicit job owns this action.
+            if (destination.status.state !== 'ready')
+                return;
+        }
+        const oldKey = `${base}:${job.status.action}`;
+        if (this.identities.get(oldKey) === job.status.id)
+            this.identities.delete(oldKey);
+        this.identities.set(destinationKey, job.status.id);
+    }
+    async runAttempts(job) {
+        const retryLimit = job.policy.transientRetryLimit ?? 0;
+        for (let retry = 0;; retry++) {
+            try {
+                await job.adapter.prepare(job.status.target, job.status.action, {
+                    signal: job.controller.signal,
+                    executionDeadlineMs: job.status.executionDeadlineMs,
+                    operation: job.status.operation,
+                });
+                return;
+            }
+            catch (error) {
+                if (job.controller.signal.aborted)
+                    throw error;
+                const failure = job.adapter.classifyFailure(error);
+                if (!failure.retryable)
+                    throw error;
+                if (retry >= retryLimit)
+                    throw error;
+                this.update(job, { attempt: job.status.attempt + 1 });
+            }
+        }
+    }
+    releaseCompletedRecords() {
+        if (this.jobs.size < this.options.maxRecords)
+            return;
+        for (const [id, job] of this.jobs) {
+            if (job.settling)
+                continue;
+            if (job.retrying)
+                continue;
+            if (job.status.state !== 'ready' && job.status.state !== 'cancelled')
+                continue;
+            this.jobs.delete(id);
+            for (const [key, mappedId] of this.identities) {
+                if (mappedId === id)
+                    this.identities.delete(key);
+            }
+            return;
+        }
+    }
+    failedJob(target, policy, operation) {
+        const base = preparationKey(target, policy, this.options, operation);
+        for (const action of policy.allowedActions) {
+            const job = this.findJob(`${base}:${action}`);
+            if (job?.status.state === 'failed' || job?.status.state === 'not_ready')
+                return job;
+        }
+        return undefined;
+    }
+    activeJob(target, policy, action, operation) {
+        const base = preparationKey(target, policy, this.options, operation);
+        const actions = action ? [action] : policy.allowedActions;
+        for (const selected of actions) {
+            const job = this.findJob(`${base}:${selected}`);
+            if (action) {
+                if (job?.status.action !== action)
+                    continue;
+            }
+            if (job && !this.terminal(job))
+                return job;
+            if (job?.settling)
+                return job;
+        }
+        return undefined;
+    }
+    async probe(adapter, target, operation, waitMs, signal) {
+        return this.readReadiness((signal) => adapter.inspect(target, operation, { signal, waitMs }), (error) => adapter.classifyFailure(error), waitMs, signal);
+    }
+    async readReadiness(inspect, classifyFailure, waitMs, signal) {
+        const controller = new AbortController();
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (readiness) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', stop);
+                resolve(readiness);
+            };
+            const stop = () => {
+                controller.abort();
+                finish({
+                    state: 'unknown',
+                    reason: signal?.aborted ? 'caller_disconnected' : 'inspection_timeout',
+                    instructions: 'Readiness inspection did not complete within the caller budget; no backend operation executed. Inspect again before preparing.',
+                });
+            };
+            const timer = setTimeout(stop, waitMs);
+            if (signal?.aborted) {
+                stop();
+                return;
+            }
+            if (waitMs === 0) {
+                stop();
+                return;
+            }
+            signal?.addEventListener('abort', stop, { once: true });
+            const failed = (error) => {
+                if (settled)
+                    return;
+                try {
+                    const failure = classifyFailure(error);
+                    finish({ state: 'conflict', instructions: failure.instructions });
+                }
+                catch {
+                    finish({
+                        state: 'unsupported',
+                        instructions: 'The readiness adapter failed and could not classify the failure. Check adapter configuration and native prerequisites; no backend operation executed.',
+                    });
+                }
+            };
+            try {
+                void inspect(controller.signal).then(finish, failed);
+            }
+            catch (error) {
+                failed(error);
+            }
+        });
+    }
+    findJob(key) {
+        const id = this.identities.get(key);
+        return id ? this.jobs.get(id) : undefined;
+    }
+    snapshot(job) {
+        return structuredClone({ ...job.status, elapsedMs: Math.max(0, (job.finishedAt ?? Date.now()) - job.createdAt) });
+    }
+    update(job, fields) {
+        job.status = { ...job.status, ...fields };
+        if (this.terminal(job))
+            job.finishedAt ??= Date.now();
+        for (const listener of job.listeners)
+            listener();
+    }
+    terminal(job) {
+        return ['ready', 'not_ready', 'failed', 'cancelled'].includes(job.status.state);
+    }
+    unsupported(backendName) {
+        return {
+            state: 'unsupported',
+            instructions: `No preparation adapter is registered for ${backendName}; prepare it using supported native instructions.`,
+        };
+    }
+}
+//# sourceMappingURL=service.js.map