@floegence/flowersec-core 2.5.3 → 3.0.0

package/dist/v3/connectionController.js

@@ -0,0 +1,805 @@
+import { canonicalizeCandidatesV3, validateArtifactV3, } from "./artifact.js";
+import { artifactLeaseStateV3, claimArtifactLeaseV3, claimedArtifactV3, retireArtifactLeaseV3, } from "./artifactLease.js";
+import { ControllerCycleStateV3, ControllerRetryWaitV3, aggregateCandidateFailuresV3, blockPolicyRefreshTriggersV3, endpointKeyV3, filterBlockedCandidatesV3, selectReplacementCandidatesV3, } from "./controller.js";
+import { ConnectErrorV3, TransportFailureV3, validateRetryDispositionV3, } from "./security.js";
+import { validateRuntimeCapabilityDescriptorV3, } from "./capability.js";
+const ARTIFACT_SOURCE_FAILURE_CODES_V3 = new Set([
+    "artifact_invalid",
+    "connection_failed",
+    "expired_artifact",
+]);
+export class ConnectionControllerV3Error extends Error {
+    code;
+    failure;
+    retryDisposition;
+    constructor(code, failure, retryDisposition) {
+        super(`Flowersec v3 connection controller stopped (code=${code})`);
+        this.code = code;
+        this.failure = failure;
+        this.retryDisposition = retryDisposition;
+        this.name = "ConnectionControllerError";
+    }
+}
+export class ConnectionControllerV3 {
+    #source;
+    #connector;
+    #maximumAttempts;
+    #nowUnixSeconds;
+    #retry;
+    #capabilitySnapshot;
+    #projectSessionFailure;
+    #lifetime = new AbortController();
+    #listeners = new Set();
+    #cycle;
+    #state = "idle";
+    #session;
+    #connectedAttempt = 0;
+    #failure;
+    #disposition;
+    #scheduler;
+    #closeOperation;
+    constructor(source, connector, options) {
+        if (source === null || typeof source !== "object" || typeof source.acquire !== "function") {
+            throw new TypeError("Flowersec v3 artifact source must provide acquire()");
+        }
+        if (typeof connector !== "function")
+            throw new TypeError("Flowersec v3 lease connector is required");
+        const maximumAttempts = options.maximumAttempts ?? 0;
+        if (!Number.isSafeInteger(maximumAttempts) || maximumAttempts < 0) {
+            throw new TypeError("maximumAttempts must be a non-negative safe integer");
+        }
+        this.#source = source;
+        this.#connector = connector;
+        this.#maximumAttempts = maximumAttempts;
+        this.#cycle = new ControllerCycleStateV3(maximumAttempts);
+        this.#nowUnixSeconds = options.nowUnixSeconds ?? (() => Math.floor(Date.now() / 1_000));
+        this.#retry = new ControllerRetryWaitV3(options.clock);
+        if (typeof options.capabilitySnapshot !== "function") {
+            throw new TypeError("Flowersec v3 capability snapshot factory is required");
+        }
+        this.#capabilitySnapshot = options.capabilitySnapshot;
+        this.#projectSessionFailure = options.projectSessionFailure ?? (() => new ConnectErrorV3("connection_failed", { kind: "terminal" }));
+    }
+    get state() { return this.#state; }
+    get currentSession() { return this.#state === "connected" ? this.#session : undefined; }
+    get failure() { return this.#failure; }
+    start() {
+        if (this.#state !== "idle" || this.#scheduler !== undefined)
+            return;
+        let resolveScheduler;
+        let rejectScheduler;
+        this.#scheduler = new Promise((resolve, reject) => {
+            resolveScheduler = resolve;
+            rejectScheduler = reject;
+        });
+        void this.#run().then(resolveScheduler, rejectScheduler);
+    }
+    retryNow() {
+        return this.#state === "waiting" && this.#retry.retryNow();
+    }
+    subscribe(listener) {
+        if (typeof listener !== "function")
+            throw new TypeError("connection listener must be a function");
+        this.#listeners.add(listener);
+        try {
+            listener(this.#snapshot());
+        }
+        catch (error) {
+            this.#listeners.delete(listener);
+            throw error;
+        }
+        return () => { this.#listeners.delete(listener); };
+    }
+    async waitForSession(options = {}) {
+        if (this.currentSession !== undefined)
+            return this.currentSession;
+        if (this.#state === "failed") {
+            throw new ConnectionControllerV3Error("failed", this.#failure, this.#disposition);
+        }
+        if (this.#state === "closed") {
+            throw new ConnectionControllerV3Error("closed", this.#failure, this.#disposition);
+        }
+        if (options.signal?.aborted === true)
+            throw new ConnectionControllerV3Error("canceled");
+        return await new Promise((resolve, reject) => {
+            const finish = (session, error) => {
+                this.#listeners.delete(listener);
+                options.signal?.removeEventListener("abort", canceled);
+                session === undefined ? reject(error) : resolve(session);
+            };
+            const listener = (snapshot) => {
+                if (snapshot.state === "connected" && snapshot.currentSession !== undefined) {
+                    finish(snapshot.currentSession);
+                }
+                else if (snapshot.state === "failed") {
+                    finish(undefined, new ConnectionControllerV3Error("failed", snapshot.failure, snapshot.retryDisposition));
+                }
+                else if (snapshot.state === "closed") {
+                    finish(undefined, new ConnectionControllerV3Error("closed", snapshot.failure, snapshot.retryDisposition));
+                }
+            };
+            const canceled = () => finish(undefined, new ConnectionControllerV3Error("canceled"));
+            this.#listeners.add(listener);
+            options.signal?.addEventListener("abort", canceled, { once: true });
+        });
+    }
+    close() {
+        if (this.#closeOperation !== undefined)
+            return this.#closeOperation;
+        let resolveClose;
+        const closeOperation = new Promise((resolve) => { resolveClose = resolve; });
+        this.#closeOperation = closeOperation;
+        const active = this.#session;
+        this.#session = undefined;
+        this.#disposition = undefined;
+        this.#lifetime.abort(new ConnectionControllerV3Error("closed", this.#failure));
+        this.#transition("closed");
+        void Promise.allSettled([
+            this.#scheduler ?? Promise.resolve(),
+            active?.close() ?? Promise.resolve(),
+        ]).then(() => resolveClose());
+        return closeOperation;
+    }
+    async #run() {
+        let next = "primary";
+        let pendingDisposition;
+        let replacementContext;
+        while (!this.#lifetime.signal.aborted) {
+            if (pendingDisposition !== undefined) {
+                this.#disposition = pendingDisposition;
+                const waitOperation = this.#retry.wait(pendingDisposition, this.#cycle.snapshot().consecutiveFailures, this.#lifetime.signal);
+                this.#transition("waiting");
+                const continued = await waitOperation;
+                if (!continued)
+                    return;
+                pendingDisposition = undefined;
+            }
+            if (!this.#cycle.beginAcquisition()) {
+                this.#forceTerminalDisposition();
+                return;
+            }
+            this.#disposition = undefined;
+            this.#transition("connecting");
+            if (this.#lifetime.signal.aborted)
+                return;
+            let capability;
+            try {
+                capability = this.#capabilitySnapshot();
+                validateRuntimeCapabilityDescriptorV3(capability);
+            }
+            catch {
+                this.#recordFailure("artifact", "artifact_invalid", { kind: "terminal" });
+                return;
+            }
+            const acquisition = await this.#acquire();
+            if (this.#lifetime.signal.aborted) {
+                if (acquisition.kind === "lease")
+                    await this.#claimAndRetire(acquisition.lease);
+                return;
+            }
+            if (acquisition.kind === "failure") {
+                const error = sourceFailure(acquisition);
+                const ordinal = this.#cycle.recordFailedAcquisitionOrLease();
+                this.#recordFailure("artifact", error.code, error.disposition);
+                if (error.disposition.kind === "terminal" || this.#attemptBudgetExhausted())
+                    return;
+                pendingDisposition = error.disposition;
+                void ordinal;
+                continue;
+            }
+            let claim;
+            try {
+                claim = claimArtifactLeaseV3(acquisition.lease);
+            }
+            catch {
+                this.#cycle.recordFailedAcquisitionOrLease();
+                this.#recordFailure("artifact", "artifact_invalid", { kind: "terminal" });
+                return;
+            }
+            if (next === "replacement" && !this.#cycle.claimReplacementQuota()) {
+                await retireArtifactLeaseV3(claim);
+                this.#cycle.recordFailedAcquisitionOrLease();
+                this.#recordFailure("connect", replacementTerminal(replacementContext).code, { kind: "terminal" });
+                return;
+            }
+            const artifact = claimedArtifactV3(claim);
+            let allCandidates;
+            try {
+                validateArtifactV3(artifact);
+                allCandidates = canonicalizeCandidatesV3(artifact.path.kind, artifact.path.candidates).candidates;
+            }
+            catch {
+                await retireArtifactLeaseV3(claim);
+                this.#cycle.recordFailedAcquisitionOrLease();
+                const error = new ConnectErrorV3("artifact_invalid", { kind: "terminal" });
+                this.#recordFailure("artifact", error.code, error.disposition);
+                return;
+            }
+            try {
+                this.#assertArtifactFresh(artifact);
+            }
+            catch {
+                await retireArtifactLeaseV3(claim);
+                this.#cycle.recordFailedAcquisitionOrLease();
+                const error = new ConnectErrorV3("expired_artifact", { kind: "retryable" });
+                this.#recordFailure("artifact", error.code, error.disposition);
+                if (this.#attemptBudgetExhausted())
+                    return;
+                next = "primary";
+                replacementContext = undefined;
+                pendingDisposition = error.disposition;
+                continue;
+            }
+            const candidates = next === "replacement"
+                ? selectReplacementCandidatesV3(artifact.path.kind, replacementContext?.candidates ?? [], allCandidates, replacementContext?.triggerKeys ?? new Set(), replacementContext?.failedKeys ?? new Set(), this.#cycle)
+                : filterBlockedCandidatesV3(artifact.path.kind, allCandidates, this.#cycle);
+            if (candidates.length === 0) {
+                await retireArtifactLeaseV3(claim);
+                this.#cycle.recordFailedAcquisitionOrLease();
+                const error = next === "replacement"
+                    ? replacementTerminal(replacementContext)
+                    : this.#cycle.blockedPolicyTerminal();
+                this.#recordFailure("connect", error.code, error.disposition);
+                return;
+            }
+            let rawResult;
+            try {
+                rawResult = await this.#connector({
+                    kind: next,
+                    artifact,
+                    candidates,
+                    claim,
+                    signal: this.#lifetime.signal,
+                    capability,
+                    assertArtifactFresh: () => this.#assertArtifactFresh(artifact),
+                });
+            }
+            catch {
+                rawResult = {
+                    kind: "post_spend_failure",
+                    error: new ConnectErrorV3("connection_failed", { kind: "terminal" }),
+                };
+            }
+            let result = normalizeLeaseAttemptResultV3(rawResult, candidates, capability);
+            if (result === undefined) {
+                const malformedSession = sessionFromMalformedConnectorResultV3(rawResult);
+                if (artifactLeaseStateV3(claim) === "claimed")
+                    await retireArtifactLeaseV3(claim);
+                if (malformedSession !== undefined)
+                    await closeManagedSessionV3(malformedSession);
+                if (this.#lifetime.signal.aborted)
+                    return;
+                this.#cycle.recordFailedAcquisitionOrLease();
+                this.#recordFailure("connect", "artifact_invalid", { kind: "terminal" });
+                return;
+            }
+            if (this.#lifetime.signal.aborted) {
+                if (result.kind === "established") {
+                    if (artifactLeaseStateV3(claim) === "claimed")
+                        await retireArtifactLeaseV3(claim);
+                    await closeManagedSessionV3(result.session);
+                }
+                else if (artifactLeaseStateV3(claim) === "claimed") {
+                    await retireArtifactLeaseV3(claim);
+                }
+                return;
+            }
+            if (result.kind === "established") {
+                if (artifactLeaseStateV3(claim) !== "consumed") {
+                    if (artifactLeaseStateV3(claim) === "claimed")
+                        await retireArtifactLeaseV3(claim);
+                    this.#cycle.recordFailedAcquisitionOrLease();
+                    this.#recordFailure("connect", "artifact_invalid", { kind: "terminal" });
+                    await closeManagedSessionV3(result.session);
+                    return;
+                }
+                this.#connectedAttempt = this.#cycle.snapshot().attempts;
+                this.#cycle.established();
+                this.#failure = undefined;
+                this.#disposition = undefined;
+                this.#session = result.session;
+                this.#transition("connected");
+                const termination = await this.#waitTermination(result.session);
+                if (termination === undefined || this.#lifetime.signal.aborted)
+                    return;
+                this.#session = undefined;
+                this.#connectedAttempt = 0;
+                await closeManagedSessionV3(result.session);
+                this.#cycle = new ControllerCycleStateV3(this.#maximumAttempts);
+                let sessionFailure;
+                try {
+                    sessionFailure = this.#projectSessionFailure(termination.error);
+                    validateRetryDispositionV3(sessionFailure.disposition);
+                }
+                catch {
+                    sessionFailure = new ConnectErrorV3("connection_failed", { kind: "terminal" });
+                }
+                const disposition = sessionFailure.disposition;
+                this.#cycle.recordFailedAcquisitionOrLease();
+                this.#recordFailure("session", sessionFailure.code, disposition);
+                if (disposition.kind === "terminal")
+                    return;
+                next = "primary";
+                replacementContext = undefined;
+                pendingDisposition = disposition;
+                continue;
+            }
+            if (result.kind === "pre_spend_failure") {
+                if (artifactLeaseStateV3(claim) !== "claimed") {
+                    this.#cycle.recordFailedAcquisitionOrLease();
+                    this.#recordFailure("connect", "artifact_invalid", { kind: "terminal" });
+                    return;
+                }
+                await retireArtifactLeaseV3(claim);
+                this.#cycle.recordFailedAcquisitionOrLease();
+                const error = next === "replacement" && result.error.code !== "expired_artifact"
+                    ? replacementTerminal(replacementContext)
+                    : result.error;
+                const disposition = error.disposition;
+                this.#recordFailure("connect", error.code, disposition);
+                if (disposition.kind === "terminal" || this.#attemptBudgetExhausted())
+                    return;
+                next = "primary";
+                replacementContext = undefined;
+                pendingDisposition = result.error.disposition;
+                continue;
+            }
+            if (result.kind === "post_spend_failure") {
+                let postSpendResult = result;
+                if (artifactLeaseStateV3(claim) !== "consumed") {
+                    if (artifactLeaseStateV3(claim) === "claimed")
+                        await retireArtifactLeaseV3(claim);
+                    postSpendResult = {
+                        kind: "post_spend_failure",
+                        error: new ConnectErrorV3("artifact_invalid", { kind: "terminal" }),
+                    };
+                }
+                this.#cycle.recordFailedAcquisitionOrLease();
+                this.#recordFailure("connect", postSpendResult.error.code, postSpendResult.error.disposition);
+                if (postSpendResult.error.disposition.kind === "terminal" || this.#attemptBudgetExhausted())
+                    return;
+                next = "primary";
+                replacementContext = undefined;
+                pendingDisposition = postSpendResult.error.disposition;
+                continue;
+            }
+            if (artifactLeaseStateV3(claim) !== "claimed") {
+                this.#cycle.recordFailedAcquisitionOrLease();
+                this.#recordFailure("connect", "artifact_invalid", { kind: "terminal" });
+                return;
+            }
+            await retireArtifactLeaseV3(claim);
+            this.#cycle.recordFailedAcquisitionOrLease();
+            if (isExpired(artifact, this.#nowUnixSeconds)) {
+                const error = new ConnectErrorV3("expired_artifact", { kind: "retryable" });
+                this.#recordFailure("connect", error.code, error.disposition);
+                if (this.#attemptBudgetExhausted())
+                    return;
+                next = "primary";
+                replacementContext = undefined;
+                pendingDisposition = error.disposition;
+                continue;
+            }
+            if (next === "replacement") {
+                const error = replacementTerminal(replacementContext);
+                this.#recordFailure("connect", error.code, error.disposition);
+                return;
+            }
+            const triggerKeys = blockPolicyRefreshTriggersV3(artifact.path.kind, result.failures, this.#cycle);
+            const refresh = aggregateCandidateFailuresV3(result.failures, !this.#cycle.snapshot().replacementUsed);
+            if (refresh === "policy_refresh") {
+                const failedKeys = new Set(result.failures.map(({ candidate }) => endpointKeyV3(artifact.path.kind, candidate)));
+                replacementContext = { artifact, candidates: allCandidates, failures: result.failures, triggerKeys, failedKeys };
+                this.#rememberFailure("connect", replacementTerminal(replacementContext).code);
+                next = "replacement";
+                continue;
+            }
+            if (triggerKeys.size > 0 && refresh.code === "connection_failed") {
+                const terminal = this.#cycle.blockedPolicyTerminal();
+                this.#recordFailure("connect", terminal.code, terminal.disposition);
+                return;
+            }
+            this.#recordFailure("connect", refresh.code, refresh.disposition);
+            if (refresh.disposition.kind === "terminal" || this.#attemptBudgetExhausted())
+                return;
+            next = "primary";
+            pendingDisposition = refresh.disposition;
+        }
+    }
+    async #acquire() {
+        const acquisition = new SourceAcquisitionRaceV3(this.#source, this.#lifetime.signal);
+        let deliveredLeaseSnapshot;
+        try {
+            const result = await acquisition.value();
+            await acquisition.settle();
+            if (result === undefined)
+                return invalidSourceResult();
+            if (result === null || typeof result !== "object")
+                return invalidSourceResult();
+            const deliveredLease = Reflect.get(result, "lease");
+            if (deliveredLease !== null && typeof deliveredLease === "object") {
+                deliveredLeaseSnapshot = deliveredLease;
+            }
+            const kind = Reflect.get(result, "kind");
+            const ownKeys = Reflect.ownKeys(result);
+            if (kind === "lease") {
+                if (deliveredLeaseSnapshot === undefined)
+                    return invalidSourceResult();
+                if (!hasExactOwnKeyList(ownKeys, ["kind", "lease"])) {
+                    await this.#claimAndRetire(deliveredLeaseSnapshot);
+                    return invalidSourceResult();
+                }
+                return { kind: "lease", lease: deliveredLeaseSnapshot };
+            }
+            if (kind === "failure") {
+                if (deliveredLeaseSnapshot !== undefined)
+                    await this.#claimAndRetire(deliveredLeaseSnapshot);
+                const code = Reflect.get(result, "code");
+                const disposition = Reflect.get(result, "disposition");
+                if (!hasExactOwnKeyList(ownKeys, ["kind", "code", "disposition"]) ||
+                    typeof code !== "string" || !ARTIFACT_SOURCE_FAILURE_CODES_V3.has(code)) {
+                    return invalidSourceResult();
+                }
+                return { kind: "failure", code, disposition: validateRetryDispositionV3(disposition) };
+            }
+            if (deliveredLeaseSnapshot !== undefined)
+                await this.#claimAndRetire(deliveredLeaseSnapshot);
+            return invalidSourceResult();
+        }
+        catch (error) {
+            await acquisition.settle();
+            if (deliveredLeaseSnapshot !== undefined)
+                await this.#claimAndRetire(deliveredLeaseSnapshot);
+            if (error instanceof ConnectErrorV3) {
+                try {
+                    if (!ARTIFACT_SOURCE_FAILURE_CODES_V3.has(error.code))
+                        return invalidSourceResult();
+                    return {
+                        kind: "failure",
+                        code: error.code,
+                        disposition: validateRetryDispositionV3(error.disposition),
+                    };
+                }
+                catch {
+                    return invalidSourceResult();
+                }
+            }
+            return invalidSourceResult();
+        }
+    }
+    async #claimAndRetire(lease) {
+        try {
+            await retireArtifactLeaseV3(claimArtifactLeaseV3(lease));
+        }
+        catch {
+            // A duplicate or already-owned late lease is a source contract violation,
+            // but close still remains terminal and does not start new work.
+        }
+    }
+    #assertArtifactFresh(artifact) {
+        if (isExpired(artifact, this.#nowUnixSeconds)) {
+            throw new ConnectErrorV3("expired_artifact", { kind: "retryable" });
+        }
+    }
+    #attemptBudgetExhausted() {
+        if (this.#maximumAttempts === 0 || this.#cycle.snapshot().attempts < this.#maximumAttempts)
+            return false;
+        this.#forceTerminalDisposition();
+        return true;
+    }
+    #forceTerminalDisposition() {
+        this.#disposition = { kind: "terminal" };
+        this.#transition("failed");
+    }
+    #recordFailure(phase, code, disposition) {
+        this.#rememberFailure(phase, code);
+        this.#disposition = disposition;
+        if (disposition.kind === "terminal")
+            this.#transition("failed");
+    }
+    #rememberFailure(phase, code) {
+        this.#failure = Object.freeze({ phase, code });
+    }
+    async #waitTermination(session) {
+        try {
+            return await raceAbort(session.waitTermination(), this.#lifetime.signal);
+        }
+        catch (error) {
+            if (this.#lifetime.signal.aborted)
+                return undefined;
+            return { error: error instanceof Error ? error : new Error(String(error)) };
+        }
+    }
+    #snapshot() {
+        return Object.freeze({
+            state: this.#state,
+            attempt: this.#state === "connected" ? this.#connectedAttempt : this.#cycle.snapshot().attempts,
+            ...(this.currentSession === undefined ? {} : { currentSession: this.currentSession }),
+            ...(this.#failure === undefined ? {} : { failure: this.#failure }),
+            ...(this.#disposition === undefined ? {} : { retryDisposition: this.#disposition }),
+        });
+    }
+    #transition(state) {
+        if (this.#state === "closed" && state !== "closed")
+            return;
+        this.#state = state;
+        const snapshot = this.#snapshot();
+        for (const listener of this.#listeners) {
+            try {
+                listener(snapshot);
+            }
+            catch { /* listener isolation */ }
+        }
+    }
+}
+export function createConnectionControllerV3(source, connector, options) {
+    return new ConnectionControllerV3(source, connector, options);
+}
+/** Serializes source delivery and controller cancellation at one ownership gate. */
+class SourceAcquisitionRaceV3 {
+    #state = "pending";
+    #cleanup = Promise.resolve();
+    #sourcePromise;
+    #settled;
+    #resolveSettled;
+    #rejectSettled;
+    #signal;
+    #abort;
+    constructor(source, signal) {
+        this.#signal = signal;
+        this.#settled = new Promise((resolve, reject) => {
+            this.#resolveSettled = resolve;
+            this.#rejectSettled = reject;
+        });
+        try {
+            // Invoke the source before returning so a synchronous close cannot abort
+            // before the source has installed its own cancellation observer.
+            this.#sourcePromise = Promise.resolve(source.acquire({ signal }));
+        }
+        catch (error) {
+            this.#sourcePromise = Promise.reject(error);
+        }
+        this.#sourcePromise.then((result) => this.#deliver(result), (error) => this.#deliverFailure(error));
+        this.#abort = () => this.#cancel();
+        signal.addEventListener("abort", this.#abort, { once: true });
+        if (signal.aborted)
+            this.#cancel();
+    }
+    async value() {
+        return await this.#settled;
+    }
+    async settle() {
+        await this.#sourcePromise.catch(() => undefined);
+        await this.#cleanup;
+        this.#signal.removeEventListener("abort", this.#abort);
+    }
+    #cancel() {
+        if (this.#state !== "pending")
+            return;
+        this.#state = "canceled";
+        this.#resolveSettled(undefined);
+    }
+    #deliver(result) {
+        if (this.#state === "pending") {
+            this.#state = "delivered";
+            this.#resolveSettled(result);
+            return;
+        }
+        if (this.#state === "canceled") {
+            this.#cleanup = this.#cleanup.then(() => this.#retireLateLease(result));
+        }
+    }
+    #deliverFailure(error) {
+        if (this.#state === "pending") {
+            this.#state = "delivered";
+            this.#rejectSettled(error);
+        }
+    }
+    async #retireLateLease(result) {
+        if (result === null || typeof result !== "object")
+            return;
+        try {
+            const lease = deliveredLease(result);
+            if (lease === undefined)
+                return;
+            await retireArtifactLeaseV3(claimArtifactLeaseV3(lease));
+        }
+        catch {
+            // Late source cleanup is intentionally redacted at the public boundary.
+        }
+    }
+}
+function invalidSourceResult() {
+    return Object.freeze({
+        kind: "failure",
+        code: "artifact_invalid",
+        disposition: Object.freeze({ kind: "terminal" }),
+    });
+}
+const LEASE_ATTEMPT_RESULT_KINDS_V3 = new Set([
+    "established",
+    "candidate_failures",
+    "pre_spend_failure",
+    "post_spend_failure",
+]);
+const CONNECT_ERROR_CODES_V3 = new Set([
+    "artifact_invalid",
+    "expired_artifact",
+    "transport_security_unsupported",
+    "transport_security_failed",
+    "connection_failed",
+]);
+const TRANSPORT_FAILURE_CODES_V3 = new Set([
+    "invalid_artifact",
+    "expired_artifact",
+    "tls_unsupported",
+    "tls_policy_expired",
+    "tls_failed",
+    "connection_failed",
+]);
+const TRANSPORT_FAILURE_DETAILS_V3 = new Set([
+    "ca_untrusted",
+    "pin_mismatch",
+    "unknown",
+    "browser_pin_opaque",
+]);
+/** Enforces the runtime adapter boundary before the controller consumes a result. */
+function normalizeLeaseAttemptResultV3(value, candidates, capability) {
+    try {
+        if (value === null || typeof value !== "object")
+            return undefined;
+        const kind = Reflect.get(value, "kind");
+        if (typeof kind !== "string" || !LEASE_ATTEMPT_RESULT_KINDS_V3.has(kind))
+            return undefined;
+        if (kind === "established") {
+            if (!hasExactOwnKeys(value, ["kind", "session"]))
+                return undefined;
+            const session = Reflect.get(value, "session");
+            if (!isManagedSessionV3(session))
+                return undefined;
+            return Object.freeze({ kind: "established", session: session });
+        }
+        if (kind === "candidate_failures") {
+            if (!hasExactOwnKeys(value, ["kind", "failures"]))
+                return undefined;
+            const failures = Reflect.get(value, "failures");
+            if (!Array.isArray(failures) || failures.length !== candidates.length)
+                return undefined;
+            const normalized = failures.map((failure) => normalizeCandidateFailureV3(failure, candidates, capability));
+            if (normalized.some((failure) => failure === undefined))
+                return undefined;
+            const seen = new Set(normalized.map((failure) => failure.candidate));
+            if (seen.size !== candidates.length)
+                return undefined;
+            return Object.freeze({
+                kind,
+                failures: Object.freeze(normalized),
+            });
+        }
+        if (!hasExactOwnKeys(value, ["kind", "error"]))
+            return undefined;
+        const error = Reflect.get(value, "error");
+        if (!(error instanceof ConnectErrorV3) || !CONNECT_ERROR_CODES_V3.has(error.code))
+            return undefined;
+        const normalizedError = new ConnectErrorV3(error.code, validateRetryDispositionV3(error.disposition));
+        return Object.freeze({ kind, error: normalizedError });
+    }
+    catch {
+        return undefined;
+    }
+}
+function isManagedSessionV3(value) {
+    return value !== null && typeof value === "object" &&
+        typeof Reflect.get(value, "waitTermination") === "function" &&
+        typeof Reflect.get(value, "close") === "function";
+}
+function normalizeCandidateFailureV3(value, candidates, capability) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const keys = Reflect.ownKeys(value);
+    if (!hasExactOwnKeys(value, keys.includes("disposition")
+        ? ["candidate", "failure", "disposition"]
+        : ["candidate", "failure"]))
+        return undefined;
+    const candidate = Reflect.get(value, "candidate");
+    const failure = Reflect.get(value, "failure");
+    if (!candidates.includes(candidate))
+        return undefined;
+    if (!(failure instanceof TransportFailureV3) || !TRANSPORT_FAILURE_CODES_V3.has(failure.code) ||
+        !isValidTransportFailurePairV3(failure.code, failure.detail, candidate, capability))
+        return undefined;
+    const disposition = Reflect.get(value, "disposition");
+    const normalizedDisposition = disposition === undefined ? undefined : validateRetryDispositionV3(disposition);
+    return Object.freeze({
+        candidate: candidate,
+        failure,
+        ...(normalizedDisposition === undefined ? {} : { disposition: normalizedDisposition }),
+    });
+}
+function isValidTransportFailurePairV3(code, detail, candidate, capability) {
+    if (detail !== undefined && !TRANSPORT_FAILURE_DETAILS_V3.has(detail))
+        return false;
+    if (code === "tls_failed")
+        return detail === "ca_untrusted" || detail === "pin_mismatch" || detail === "unknown";
+    if (code === "connection_failed") {
+        if (detail === undefined)
+            return true;
+        return detail === "browser_pin_opaque" && candidate.carrier === "webtransport" &&
+            candidate.tls.mode === "pin" && capability.language === "typescript" && capability.runtime === "browser" &&
+            capability.tuples.some((tuple) => tuple.carrier === "webtransport" &&
+                tuple.networkMode === "dial" && tuple.securityModes.includes("pin"));
+    }
+    return detail === undefined;
+}
+function sessionFromMalformedConnectorResultV3(value) {
+    try {
+        if (value === null || typeof value !== "object" || Reflect.get(value, "kind") !== "established")
+            return undefined;
+        const session = Reflect.get(value, "session");
+        return isManagedSessionV3(session) ? session : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function closeManagedSessionV3(session) {
+    try {
+        await Promise.resolve(session.close());
+    }
+    catch {
+        // Adapter cleanup is best-effort after ownership has already become terminal.
+    }
+}
+function hasExactOwnKeys(value, expected) {
+    const keys = Reflect.ownKeys(value);
+    return hasExactOwnKeyList(keys, expected);
+}
+function hasExactOwnKeyList(keys, expected) {
+    return keys.length === expected.length && expected.every((key) => keys.includes(key));
+}
+function deliveredLease(value) {
+    const lease = Reflect.get(value, "lease");
+    return lease !== null && typeof lease === "object" ? lease : undefined;
+}
+function sourceFailure(result) {
+    const code = result.code === "expired_artifact" ? "expired_artifact" :
+        result.code === "connection_failed" ? "connection_failed" : "artifact_invalid";
+    return new ConnectErrorV3(code, validateRetryDispositionV3(result.disposition));
+}
+function replacementTerminal(context) {
+    if (context === undefined)
+        return new ConnectErrorV3("artifact_invalid", { kind: "terminal" });
+    const value = aggregateCandidateFailuresV3(context.failures, false);
+    return value === "policy_refresh"
+        ? new ConnectErrorV3("transport_security_failed", { kind: "terminal" })
+        : value;
+}
+function isExpired(artifact, nowUnixSeconds) {
+    let expiry;
+    try {
+        if (artifact === null || typeof artifact !== "object")
+            return false;
+        const session = Reflect.get(artifact, "session");
+        if (session === null || typeof session !== "object")
+            return false;
+        expiry = Reflect.get(session, "init_expire_at_unix_s");
+    }
+    catch {
+        return false;
+    }
+    if (!Number.isSafeInteger(expiry) || expiry < 0)
+        return false;
+    const now = nowUnixSeconds();
+    if (!Number.isSafeInteger(now) || now < 0)
+        return true;
+    return now >= expiry;
+}
+async function raceAbort(promise, signal) {
+    if (signal.aborted)
+        throw signal.reason;
+    return await new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}