@bota.dev/web-app-sdk 2.0.0-beta.0

package/dist/workflowRuntime.js

@@ -0,0 +1,1508 @@
+import { BotaSDKError, normalizeCoreError, } from "./errors.js";
+import { canonicalGattUuid } from "./gatt.js";
+import { BrowserStorageError, } from "./storage.js";
+import { BrowserTransportError, } from "./transport.js";
+export class BrowserWorkflowRuntime {
+    core;
+    transport;
+    devices = new Map();
+    characteristicLeases = new Map();
+    disconnectListeners = new Set();
+    activeOwner = null;
+    connectedDevice = null;
+    poisonedDeviceId = null;
+    destroyed = false;
+    destroyPromise = null;
+    coreDispatchTail = Promise.resolve();
+    nextConnectionAttempt = 0;
+    connectionAttempts = new Map();
+    pendingConnectionSettlements = new Map();
+    constructor(core, transport) {
+        this.core = core;
+        this.transport = transport;
+    }
+    get connectedDeviceHandle() {
+        return this.connectedDevice;
+    }
+    registerDevice(device) {
+        this.devices.set(device.id, device);
+    }
+    registeredDevice(deviceId) {
+        return this.devices.get(deviceId) ?? null;
+    }
+    async waitForPendingConnection(deviceId) {
+        await this.pendingConnectionSettlements.get(deviceId);
+    }
+    unregisterDevice(deviceId) {
+        this.devices.delete(deviceId);
+        if (this.connectedDevice?.id === deviceId)
+            this.connectedDevice = null;
+    }
+    markDeviceDisconnected(deviceId) {
+        if (this.poisonedDeviceId === deviceId)
+            this.poisonedDeviceId = null;
+        if (this.connectedDevice?.id !== deviceId)
+            return;
+        this.connectedDevice = null;
+        for (const listener of [...this.disconnectListeners]) {
+            try {
+                listener(deviceId);
+            }
+            catch {
+                // Lifecycle observers own their asynchronous cleanup and errors.
+            }
+        }
+        const owner = this.activeOwner;
+        if (!owner)
+            return;
+        if (owner.kind === 'direct') {
+            if (owner.operation === 'disconnect')
+                return;
+            owner.terminalError ??= new BotaSDKError('device_disconnected', owner.operation);
+            owner.abortController.abort();
+            return;
+        }
+        const generation = owner.generation;
+        void this.dispatchDeviceDisconnected(owner, deviceId, generation).catch((error) => {
+            void this.failOwner(owner, error);
+        });
+    }
+    poisonBleOwnership(deviceId) {
+        if (this.connectedDevice?.id === deviceId)
+            this.poisonedDeviceId = deviceId;
+    }
+    onDeviceDisconnected(listener) {
+        this.disconnectListeners.add(listener);
+        return () => this.disconnectListeners.delete(listener);
+    }
+    claimCharacteristicLease(operation, device, serviceUuid, characteristicUuid) {
+        if (this.destroyed)
+            throw new BotaSDKError('cancelled', operation);
+        if (this.connectedDevice?.id !== device.id) {
+            throw new BotaSDKError('device_disconnected', operation);
+        }
+        if (this.poisonedDeviceId !== null) {
+            throw new BotaSDKError('operation_in_progress', operation);
+        }
+        const key = [
+            device.id,
+            canonicalGattUuid(serviceUuid),
+            canonicalGattUuid(characteristicUuid),
+        ].join(':');
+        if (this.characteristicLeases.has(key)) {
+            throw new BotaSDKError('operation_in_progress', operation);
+        }
+        const owner = Symbol(key);
+        this.characteristicLeases.set(key, owner);
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                if (this.characteristicLeases.get(key) === owner) {
+                    this.characteristicLeases.delete(key);
+                }
+            },
+        };
+    }
+    run(operationId, cancellationId, start, hosts, observer, completionHandoff) {
+        const operation = operationFromId(operationId);
+        if (this.destroyed) {
+            return Promise.reject(new BotaSDKError('cancelled', operation));
+        }
+        if (this.activeOwner
+            || this.pendingConnectionSettlements.size > 0
+            || (this.poisonedDeviceId !== null && operation !== 'disconnect')) {
+            return Promise.reject(new BotaSDKError('operation_in_progress', operation));
+        }
+        if (operationId.length === 0 || cancellationId.byteLength !== 16) {
+            return Promise.reject(new BotaSDKError('invalid_input', operation));
+        }
+        const result = deferred();
+        const owner = {
+            kind: 'workflow',
+            operationId,
+            operation,
+            cancellationId: cancellationId.slice(),
+            abortController: new AbortController(),
+            cancellationAbortController: null,
+            cancellationGeneration: null,
+            hosts,
+            observer,
+            result,
+            notifications: [],
+            queue: [],
+            requests: new Map(),
+            subscriptions: new Map(),
+            timers: new Map(),
+            cleanups: [],
+            pendingGattSetups: new Set(),
+            pendingGattWrites: new Set(),
+            pendingExternalOperations: new Set(),
+            completionHandoff,
+            completionEvidence: null,
+            completing: false,
+            completionPromise: null,
+            completionFailure: null,
+            generation: 0,
+            pumping: false,
+            inlineEffects: null,
+            terminal: false,
+            cancelling: false,
+            cancelPromise: null,
+            failure: null,
+            failurePromise: null,
+            cleanupPromise: null,
+            lastProgress: null,
+            lastFirmwareProgress: null,
+            authorizedScanExhausted: false,
+            authorizedReconnectDeviceIds: new Set(this.devices.keys()),
+        };
+        this.activeOwner = owner;
+        try {
+            this.enqueueEffects(owner, start(), owner.generation);
+        }
+        catch (error) {
+            void this.failOwner(owner, error);
+        }
+        return result.promise;
+    }
+    async cancel(operationId) {
+        const owner = this.activeOwner;
+        if (!owner
+            || owner.kind !== 'workflow'
+            || owner.operationId !== operationId
+            || owner.terminal) {
+            return;
+        }
+        await this.enterCancellation(owner);
+    }
+    async runExclusive(operation, body) {
+        if (this.destroyed)
+            throw new BotaSDKError('cancelled', operation);
+        if (this.activeOwner
+            || this.pendingConnectionSettlements.size > 0
+            || (this.poisonedDeviceId !== null && operation !== 'disconnect')) {
+            throw new BotaSDKError('operation_in_progress', operation);
+        }
+        const abortController = new AbortController();
+        let settle;
+        const settled = new Promise((resolve) => {
+            settle = resolve;
+        });
+        const owner = {
+            kind: 'direct',
+            operation,
+            abortController,
+            terminalError: null,
+            settled,
+        };
+        this.activeOwner = owner;
+        try {
+            const value = await body(abortController.signal);
+            if (owner.terminalError)
+                throw owner.terminalError;
+            if (abortController.signal.aborted || this.destroyed) {
+                throw new BotaSDKError('cancelled', operation);
+            }
+            return value;
+        }
+        catch (error) {
+            const normalized = normalizeRuntimeError(error, operation);
+            if (owner.terminalError) {
+                throw normalized.code === 'cancelled'
+                    ? owner.terminalError
+                    : normalized;
+            }
+            if (abortController.signal.aborted || this.destroyed) {
+                throw new BotaSDKError('cancelled', operation);
+            }
+            throw normalized;
+        }
+        finally {
+            if (this.activeOwner === owner)
+                this.activeOwner = null;
+            settle();
+        }
+    }
+    destroy() {
+        if (this.destroyPromise)
+            return this.destroyPromise;
+        this.destroyed = true;
+        this.destroyPromise = (async () => {
+            const owner = this.activeOwner;
+            if (!owner)
+                return;
+            if (owner.kind === 'workflow') {
+                await this.cancel(owner.operationId);
+                return;
+            }
+            owner.abortController.abort();
+            await owner.settled;
+        })();
+        return this.destroyPromise;
+    }
+    enqueueEffects(owner, effects, generation) {
+        if (owner.terminal || generation !== owner.generation) {
+            for (const effect of effects)
+                scrubTransientEffect(effect);
+            return;
+        }
+        const queue = owner.inlineEffects ?? owner.queue;
+        for (let index = 0; index < effects.length; index += 1) {
+            const effect = effects[index];
+            if (!effect)
+                continue;
+            try {
+                this.validateEnvelope(owner, effect, generation);
+                queue.push({ envelope: effect, generation });
+            }
+            catch (error) {
+                scrubTransientEffect(effect);
+                for (const remaining of effects.slice(index + 1)) {
+                    scrubTransientEffect(remaining);
+                }
+                throw error;
+            }
+        }
+        if (owner.inlineEffects === null)
+            this.ensurePump(owner);
+    }
+    async dispatchDeviceDisconnected(owner, deviceId, generation) {
+        if (owner.terminal
+            || this.activeOwner !== owner
+            || owner.generation !== generation)
+            return;
+        const requestId = owner.subscriptions.keys().next().value
+            ?? owner.requests.keys().next().value;
+        if (requestId === undefined) {
+            throw new BotaSDKError('device_disconnected', owner.operation);
+        }
+        const effects = await this.serializedCoreCall(() => {
+            if (owner.terminal
+                || this.activeOwner !== owner
+                || owner.generation !== generation)
+                return [];
+            const status = this.core.status();
+            if (status.kind === 'completed'
+                || status.kind === 'cancelled'
+                || status.kind === 'failed')
+                return [];
+            return this.dispatchCurrentOwnerEvent(owner, generation, {
+                requestId,
+                kind: 'ble_disconnected',
+                peripheralId: deviceId,
+                reasonCode: null,
+            });
+        });
+        if (owner.terminal
+            || this.activeOwner !== owner
+            || owner.generation !== generation)
+            return;
+        this.enqueueEffects(owner, effects, generation);
+    }
+    validateEnvelope(owner, envelope, generation) {
+        if (!equalBytes(envelope.cancellationId, owner.cancellationId)) {
+            throw new BotaSDKError('internal_error', owner.operation);
+        }
+        const operation = publicOperation(envelope.operation);
+        if (owner.operation === 'unknown')
+            owner.operation = operation;
+        if (operation !== 'unknown' && owner.operation !== operation) {
+            throw new BotaSDKError('internal_error', owner.operation);
+        }
+        if (owner.requests.has(envelope.requestId)) {
+            throw new BotaSDKError('internal_error', owner.operation);
+        }
+        owner.requests.set(envelope.requestId, {
+            generation,
+            cancellationId: envelope.cancellationId.slice(),
+        });
+    }
+    ensurePump(owner) {
+        if (owner.pumping || owner.terminal)
+            return;
+        owner.pumping = true;
+        void this.pump(owner).catch(async (error) => {
+            await this.failOwner(owner, error);
+        }).finally(() => {
+            owner.pumping = false;
+            if (owner.queue.length > 0 && !owner.terminal)
+                this.ensurePump(owner);
+        });
+    }
+    async pump(owner) {
+        while (owner.queue.length > 0 && !owner.terminal) {
+            const queued = owner.queue.shift();
+            if (!queued)
+                continue;
+            if (queued.generation !== owner.generation) {
+                scrubTransientEffect(queued.envelope);
+                continue;
+            }
+            await this.executeEffect(owner, queued);
+        }
+        if (!owner.terminal && owner.queue.length === 0) {
+            await this.finishFromCoreStatus(owner);
+        }
+    }
+    async finishFromCoreStatus(owner) {
+        const status = this.core.status();
+        switch (status.kind) {
+            case 'completed':
+                if (!this.hasCompletionEvidence(owner)) {
+                    throw new BotaSDKError('internal_error', owner.operation);
+                }
+                await this.finishSuccess(owner);
+                return;
+            case 'cancelled':
+                await this.finishCancelled(owner);
+                return;
+            case 'failed':
+                await this.finishFailure(owner, normalizeCoreError(status.error, owner.operation));
+                return;
+            case 'idle':
+                return;
+            case 'running':
+                try {
+                    owner.observer?.onRunning?.();
+                }
+                catch {
+                    // Observer failures do not change device workflow state.
+                }
+                return;
+        }
+    }
+    async executeEffect(owner, queued) {
+        const { envelope, generation } = queued;
+        const context = this.effectContext(owner, envelope, generation);
+        const { effect } = envelope;
+        switch (effect.kind) {
+            case 'notify':
+                await this.handleNotification(owner, effect.notification);
+                return;
+            case 'ble_start_scan':
+                await this.startAuthorizedScan(owner, envelope, context, generation);
+                return;
+            case 'ble_stop_scan':
+                await context.dispatch({
+                    requestId: envelope.requestId,
+                    kind: 'ble_scan_stopped',
+                });
+                return;
+            case 'ble_connect':
+                await this.connectDevice(owner, envelope, context, generation);
+                return;
+            case 'ble_discover_services':
+                await this.discoverServices(owner, envelope, context, generation);
+                return;
+            case 'ble_disconnect':
+                await this.disconnectDevice(owner, envelope, context, generation);
+                return;
+            case 'ble_read':
+                await this.readCharacteristic(owner, envelope, context, generation);
+                return;
+            case 'ble_write':
+                await this.writeCharacteristic(owner, envelope, context, generation);
+                return;
+            case 'ble_subscribe':
+                await this.subscribe(owner, envelope, context, generation);
+                return;
+            case 'ble_unsubscribe':
+                await this.unsubscribe(owner, effect.serviceUuid, effect.characteristicUuid);
+                return;
+            case 'timer_schedule':
+                await this.scheduleTimer(owner, envelope, context, generation);
+                return;
+            case 'timer_cancel':
+                this.cancelTimer(owner, effect.timerId);
+                return;
+            case 'progress':
+                this.reportProgress(owner, effect.completedUnits, effect.totalUnits);
+                return;
+            case 'persistence_load_checkpoint':
+            case 'persistence_save_checkpoint':
+            case 'persistence_delete_checkpoint':
+            case 'persistence_save_connection_identity':
+                await this.executeHost(owner, owner.hosts.persistence, envelope, context, generation);
+                return;
+            case 'host_material_prepare_provisioning':
+                await this.executeHost(owner, owner.hosts.hostMaterial, envelope, context, generation);
+                return;
+            case 'recording_sink_truncate':
+            case 'recording_sink_append':
+            case 'recording_sink_finalize':
+            case 'recording_sink_discard':
+                await this.executeHost(owner, owner.hosts.recordingSink, envelope, context, generation);
+                return;
+            case 'network_download':
+                await this.executeHost(owner, owner.hosts.network, envelope, context, generation);
+                return;
+            case 'firmware_blob_read_chunk':
+                await this.executeHost(owner, owner.hosts.firmwareBlob, envelope, context, generation);
+                return;
+            case 'encrypted_upload_v2_load_checkpoint':
+            case 'encrypted_upload_v2_delete_checkpoint':
+            case 'encrypted_upload_v2_truncate_sink':
+            case 'encrypted_upload_v2_prepare_session':
+            case 'encrypted_upload_v2_start_transfer':
+            case 'encrypted_upload_v2_repair_window':
+            case 'encrypted_upload_v2_save_checkpoint':
+            case 'encrypted_upload_v2_acknowledge_window':
+            case 'encrypted_upload_v2_stage_artifacts':
+            case 'encrypted_upload_v2_await_completion_receipt':
+            case 'encrypted_upload_v2_confirm_with_receipt':
+            case 'encrypted_upload_v2_abort':
+                await this.executeHost(owner, owner.hosts.encryptedUploadV2, envelope, context, generation);
+                return;
+        }
+        const unhandledEffect = effect;
+        void unhandledEffect;
+        throw new BotaSDKError('internal_error', owner.operation);
+    }
+    effectContext(owner, envelope, generation) {
+        const signal = this.ownerSignal(owner, generation);
+        const context = {
+            operationId: owner.operationId,
+            cancellationId: owner.cancellationId.slice(),
+            signal,
+            dispatch: async (event) => {
+                await this.dispatchFromContext(owner, envelope, generation, context, event);
+            },
+            addCleanup: (cleanup) => {
+                if (owner.terminal || generation !== owner.generation) {
+                    void cleanup().catch(() => undefined);
+                    return;
+                }
+                owner.cleanups.push(cleanup);
+            },
+        };
+        return context;
+    }
+    async dispatchFromContext(owner, envelope, generation, context, event) {
+        if (owner.terminal || generation !== owner.generation)
+            return;
+        if (event.requestId !== envelope.requestId
+            || !equalBytes(context.cancellationId, owner.cancellationId)) {
+            throw new BotaSDKError('internal_error', owner.operation);
+        }
+        const request = owner.requests.get(event.requestId);
+        if (!request
+            || request.generation !== generation
+            || !equalBytes(request.cancellationId, owner.cancellationId)) {
+            throw new BotaSDKError('internal_error', owner.operation);
+        }
+        const effects = await this.serializedCoreCall(() => {
+            if (owner.terminal || generation !== owner.generation)
+                return [];
+            const status = this.core.status();
+            if (status.kind === 'completed'
+                || status.kind === 'cancelled'
+                || status.kind === 'failed') {
+                return [];
+            }
+            return this.dispatchCurrentOwnerEvent(owner, generation, event);
+        });
+        if (owner.terminal || generation !== owner.generation)
+            return;
+        this.enqueueEffects(owner, effects, generation);
+    }
+    async startAuthorizedScan(owner, envelope, context, generation) {
+        if (!this.transport.supportsAuthorizedDevices) {
+            throw new BotaSDKError('picker_required', owner.operation);
+        }
+        const authorizedResult = await this.awaitOwnerStep(owner, generation, this.trackExternalOperation(owner, this.transport.getAuthorizedDevices()));
+        if (authorizedResult.kind === 'cancelled')
+            return;
+        if (authorizedResult.kind === 'failed')
+            throw authorizedResult.error;
+        const authorized = authorizedResult.value;
+        if (owner.terminal || generation !== owner.generation)
+            return;
+        let forwarded = 0;
+        for (const device of authorized) {
+            if (!owner.authorizedReconnectDeviceIds.has(device.id))
+                continue;
+            this.devices.set(device.id, device);
+            forwarded += 1;
+            await context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'ble_scan_result',
+                candidate: {
+                    peripheralId: device.id,
+                    name: device.name,
+                    advertisedAddress: null,
+                    rssi: 0,
+                },
+            });
+        }
+        owner.authorizedScanExhausted = forwarded === 0;
+    }
+    async connectDevice(owner, envelope, context, generation) {
+        if (envelope.effect.kind !== 'ble_connect')
+            return;
+        const device = this.devices.get(envelope.effect.peripheralId);
+        if (!device) {
+            await this.dispatchBleFailure(context, envelope.requestId, null);
+            return;
+        }
+        const lifecycle = deferred();
+        this.trackExternalSettlement(owner, lifecycle.promise);
+        try {
+            const attempt = ++this.nextConnectionAttempt;
+            this.connectionAttempts.set(device.id, attempt);
+            const pendingConnection = this.transport.connect(device);
+            const connection = await this.awaitOwnerStep(owner, generation, pendingConnection);
+            if (connection.kind === 'cancelled') {
+                let settlement;
+                settlement = pendingConnection.then(async () => {
+                    if (this.connectionAttempts.get(device.id) === attempt
+                        && this.connectedDevice?.id !== device.id) {
+                        await this.transport.disconnect(device).catch(() => undefined);
+                    }
+                }, () => undefined).finally(() => {
+                    if (this.connectionAttempts.get(device.id) === attempt) {
+                        this.connectionAttempts.delete(device.id);
+                    }
+                    if (this.pendingConnectionSettlements.get(device.id) === settlement) {
+                        this.pendingConnectionSettlements.delete(device.id);
+                    }
+                });
+                this.pendingConnectionSettlements.set(device.id, settlement);
+                await settlement;
+                return;
+            }
+            if (this.connectionAttempts.get(device.id) === attempt) {
+                this.connectionAttempts.delete(device.id);
+            }
+            if (connection.kind === 'failed') {
+                await this.dispatchBleFailure(context, envelope.requestId, connection.error);
+                return;
+            }
+            if (owner.terminal
+                || generation !== owner.generation
+                || owner.abortController.signal.aborted) {
+                await this.transport.disconnect(device).catch(() => undefined);
+                return;
+            }
+            this.connectedDevice = device;
+            await context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'ble_connected',
+                peripheralId: device.id,
+            });
+        }
+        finally {
+            lifecycle.resolve(undefined);
+        }
+    }
+    async discoverServices(owner, envelope, context, generation) {
+        if (envelope.effect.kind !== 'ble_discover_services')
+            return;
+        const device = this.devices.get(envelope.effect.peripheralId);
+        if (!device || this.connectedDevice?.id !== device.id) {
+            await this.dispatchBleFailure(context, envelope.requestId, null);
+            return;
+        }
+        const discovery = await this.awaitOwnerStep(owner, generation, this.trackExternalOperation(owner, this.transport.discoverServices(device)));
+        if (discovery.kind === 'cancelled')
+            return;
+        if (discovery.kind === 'completed') {
+            await context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'ble_services_discovered',
+                peripheralId: device.id,
+            });
+        }
+        else {
+            await this.dispatchBleFailure(context, envelope.requestId, discovery.error);
+        }
+    }
+    async disconnectDevice(owner, envelope, context, generation) {
+        if (envelope.effect.kind !== 'ble_disconnect')
+            return;
+        const device = this.devices.get(envelope.effect.peripheralId);
+        try {
+            if (device && this.connectedDevice?.id === device.id) {
+                const disconnected = await this.awaitOwnerStep(owner, generation, this.trackExternalOperation(owner, this.transport.disconnect(device)));
+                if (disconnected.kind === 'cancelled')
+                    return;
+                if (disconnected.kind === 'failed')
+                    throw disconnected.error;
+            }
+            if (this.connectedDevice?.id === envelope.effect.peripheralId) {
+                this.connectedDevice = null;
+            }
+            await context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'ble_disconnected',
+                peripheralId: envelope.effect.peripheralId,
+                reasonCode: null,
+            });
+        }
+        catch (error) {
+            await this.dispatchBleFailure(context, envelope.requestId, error);
+        }
+    }
+    async readCharacteristic(owner, envelope, context, generation) {
+        if (envelope.effect.kind !== 'ble_read')
+            return;
+        const device = this.connectedDevice;
+        if (!device) {
+            await this.dispatchBleFailure(context, envelope.requestId, null);
+            return;
+        }
+        const read = await this.awaitOwnerStep(owner, generation, this.trackExternalOperation(owner, this.transport.read(device, envelope.effect.serviceUuid, envelope.effect.characteristicUuid)));
+        if (read.kind === 'cancelled')
+            return;
+        if (read.kind === 'completed') {
+            await context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'ble_read_completed',
+                value: read.value,
+            });
+        }
+        else {
+            await this.dispatchBleFailure(context, envelope.requestId, read.error);
+        }
+    }
+    async writeCharacteristic(owner, envelope, context, generation) {
+        if (envelope.effect.kind !== 'ble_write')
+            return;
+        const payload = envelope.effect.payload;
+        const device = this.connectedDevice;
+        if (!device) {
+            payload.fill(0);
+            await this.dispatchBleFailure(context, envelope.requestId, null);
+            return;
+        }
+        const transportPayload = payload.slice();
+        let pendingWrite;
+        try {
+            pendingWrite = this.transport.write(device, envelope.effect.serviceUuid, envelope.effect.characteristicUuid, transportPayload, envelope.effect.withResponse).finally(() => {
+                transportPayload.fill(0);
+                payload.fill(0);
+            });
+        }
+        catch (error) {
+            transportPayload.fill(0);
+            payload.fill(0);
+            throw error;
+        }
+        let trackedWrite;
+        trackedWrite = pendingWrite.finally(() => {
+            owner.pendingGattWrites.delete(trackedWrite);
+        });
+        owner.pendingGattWrites.add(trackedWrite);
+        const write = await this.awaitOwnerStep(owner, generation, trackedWrite);
+        if (write.kind === 'cancelled')
+            return;
+        if (write.kind === 'completed') {
+            await context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'ble_write_completed',
+            });
+        }
+        else {
+            await this.dispatchBleFailure(context, envelope.requestId, write.error);
+        }
+    }
+    async subscribe(owner, envelope, context, generation) {
+        if (envelope.effect.kind !== 'ble_subscribe')
+            return;
+        const device = this.connectedDevice;
+        if (!device) {
+            await this.dispatchBleFailure(context, envelope.requestId, null);
+            return;
+        }
+        const characteristicUuid = envelope.effect.characteristicUuid;
+        const pendingSubscription = this.trackGattSetup(owner, generation, this.transport.subscribe(device, envelope.effect.serviceUuid, envelope.effect.characteristicUuid, (notification) => {
+            void context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'ble_notification',
+                characteristicUuid,
+                value: notification.value,
+            }).catch((error) => {
+                void this.failOwner(owner, error);
+            });
+        }), async (subscription) => subscription.remove());
+        const subscribed = await this.awaitOwnerStep(owner, generation, pendingSubscription.promise);
+        if (subscribed.kind === 'cancelled')
+            return;
+        if (subscribed.kind === 'failed') {
+            pendingSubscription.cancel();
+            await this.dispatchBleFailure(context, envelope.requestId, subscribed.error);
+            return;
+        }
+        const subscription = subscribed.value;
+        if (owner.terminal || generation !== owner.generation) {
+            pendingSubscription.cancel();
+            await pendingSubscription.settlement;
+            return;
+        }
+        try {
+            let removal = null;
+            const runtimeSubscription = {
+                serviceUuid: envelope.effect.serviceUuid,
+                characteristicUuid: envelope.effect.characteristicUuid,
+                subscription,
+                remove: () => {
+                    removal ??= subscription.remove();
+                    return removal;
+                },
+            };
+            owner.subscriptions.set(envelope.requestId, runtimeSubscription);
+            context.addCleanup(runtimeSubscription.remove);
+            pendingSubscription.transferOwnership();
+            await context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'ble_subscribed',
+                characteristicUuid: envelope.effect.characteristicUuid,
+            });
+        }
+        catch (error) {
+            await this.dispatchBleFailure(context, envelope.requestId, error);
+        }
+    }
+    async unsubscribe(owner, serviceUuid, characteristicUuid) {
+        const matches = [...owner.subscriptions.entries()].filter(([, value]) => value.serviceUuid === serviceUuid
+            && value.characteristicUuid === characteristicUuid);
+        for (const [requestId, value] of matches) {
+            await value.remove();
+            owner.subscriptions.delete(requestId);
+        }
+    }
+    async scheduleTimer(owner, envelope, context, generation) {
+        if (envelope.effect.kind !== 'timer_schedule')
+            return;
+        const effect = envelope.effect;
+        const delayMs = Number(effect.delayMs);
+        if (!Number.isSafeInteger(delayMs)
+            || delayMs < 0
+            || delayMs > 2_147_483_647) {
+            throw new BotaSDKError('internal_error', owner.operation);
+        }
+        this.cancelTimer(owner, effect.timerId);
+        if (owner.authorizedScanExhausted) {
+            owner.authorizedScanExhausted = false;
+            await context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'timer_fired',
+                timerId: effect.timerId,
+            });
+            return;
+        }
+        const timer = setTimeout(() => {
+            owner.timers.delete(effect.timerId);
+            if (owner.terminal || generation !== owner.generation)
+                return;
+            void context.dispatch({
+                requestId: envelope.requestId,
+                kind: 'timer_fired',
+                timerId: effect.timerId,
+            }).catch((error) => {
+                void this.failOwner(owner, error);
+            });
+        }, delayMs);
+        owner.timers.set(effect.timerId, timer);
+        context.addCleanup(async () => {
+            clearTimeout(timer);
+            owner.timers.delete(effect.timerId);
+        });
+    }
+    cancelTimer(owner, timerId) {
+        const timer = owner.timers.get(timerId);
+        if (timer)
+            clearTimeout(timer);
+        owner.timers.delete(timerId);
+    }
+    async executeHost(owner, host, envelope, context, generation) {
+        if (!host) {
+            throw new BotaSDKError('unsupported_capability', publicOperation(envelope.operation));
+        }
+        const execution = this.trackExternalOperation(owner, host.execute(envelope, context));
+        const executed = await this.awaitOwnerStep(owner, generation, execution);
+        if (executed.kind === 'cancelled')
+            return;
+        if (executed.kind === 'failed')
+            throw executed.error;
+        if (!executed.value)
+            return;
+        const events = Array.isArray(executed.value)
+            ? executed.value
+            : [executed.value];
+        for (const event of events)
+            await context.dispatch(event);
+    }
+    async awaitOwnerStep(owner, generation, promise) {
+        const signal = this.ownerSignal(owner, generation);
+        const settled = promise.then((value) => ({ kind: 'completed', value }), (error) => ({ kind: 'failed', error }));
+        if (owner.terminal
+            || generation !== owner.generation
+            || signal.aborted) {
+            return { kind: 'cancelled' };
+        }
+        let resolveCancellation;
+        const cancellation = new Promise((resolve) => {
+            resolveCancellation = () => resolve({ kind: 'cancelled' });
+        });
+        signal.addEventListener('abort', resolveCancellation, { once: true });
+        const result = await Promise.race([settled, cancellation]);
+        signal.removeEventListener('abort', resolveCancellation);
+        return result;
+    }
+    trackGattSetup(owner, generation, promise, cleanup) {
+        const signal = this.ownerSignal(owner, generation);
+        let decisionMade = false;
+        let resolveDecision;
+        const decision = new Promise((resolve) => {
+            resolveDecision = resolve;
+        });
+        const decide = (value) => {
+            if (decisionMade)
+                return;
+            decisionMade = true;
+            signal.removeEventListener('abort', onAbort);
+            resolveDecision(value);
+        };
+        const onAbort = () => decide('cancelled');
+        signal.addEventListener('abort', onAbort, {
+            once: true,
+        });
+        if (signal.aborted)
+            onAbort();
+        let settlement;
+        settlement = promise.then(async (value) => {
+            const setupDecision = await decision;
+            if (setupDecision === 'cancelled'
+                || owner.terminal
+                || generation !== owner.generation) {
+                await cleanup(value);
+            }
+        }, () => undefined).finally(() => {
+            signal.removeEventListener('abort', onAbort);
+            owner.pendingGattSetups.delete(settlement);
+        });
+        owner.pendingGattSetups.add(settlement);
+        return {
+            promise,
+            settlement,
+            cancel: () => decide('cancelled'),
+            transferOwnership: () => decide('transferred'),
+        };
+    }
+    async settlePendingGattSetups(owner) {
+        let failure = null;
+        while (owner.pendingGattSetups.size > 0) {
+            const settlements = [...owner.pendingGattSetups];
+            const results = await Promise.allSettled(settlements);
+            for (const result of results) {
+                if (failure === null && result.status === 'rejected') {
+                    failure = result.reason;
+                }
+            }
+        }
+        if (failure !== null)
+            throw failure;
+    }
+    async settlePendingGattWrites(owner) {
+        let failure = null;
+        while (owner.pendingGattWrites.size > 0) {
+            const settlements = [...owner.pendingGattWrites];
+            const results = await Promise.allSettled(settlements);
+            for (const result of results) {
+                if (failure === null && result.status === 'rejected') {
+                    failure = result.reason;
+                }
+            }
+        }
+        if (failure !== null)
+            throw failure;
+    }
+    trackExternalOperation(owner, promise) {
+        this.trackExternalSettlement(owner, promise.then(() => undefined, () => undefined));
+        return promise;
+    }
+    trackExternalSettlement(owner, pending) {
+        let settlement;
+        settlement = pending.finally(() => {
+            owner.pendingExternalOperations.delete(settlement);
+        });
+        owner.pendingExternalOperations.add(settlement);
+    }
+    async settlePendingExternalOperations(owner) {
+        while (owner.pendingExternalOperations.size > 0) {
+            await Promise.allSettled([...owner.pendingExternalOperations]);
+        }
+    }
+    ownerSignal(owner, generation) {
+        if (owner.cancellationGeneration === generation
+            && owner.cancellationAbortController) {
+            return owner.cancellationAbortController.signal;
+        }
+        return owner.abortController.signal;
+    }
+    async handleNotification(owner, notification) {
+        owner.notifications.push(notification);
+        try {
+            owner.observer?.onNotification?.(notification);
+        }
+        catch {
+            // Observer failures do not change device workflow state.
+        }
+        if (notification.kind === 'progress') {
+            this.reportProgress(owner, notification.completedUnits, notification.totalUnits);
+        }
+        else if (notification.kind === 'firmware_progress') {
+            this.reportFirmwareProgress(owner, notification.phase, notification.completedBytes, notification.totalBytes);
+        }
+        switch (notification.kind) {
+            case 'completed':
+                await this.finishSuccess(owner);
+                return;
+            case 'cancelled':
+                await this.finishCancelled(owner);
+                return;
+            case 'failed': {
+                const error = normalizeCoreError(notification.error, owner.operation);
+                if (owner.cancelling) {
+                    owner.failure ??= { error };
+                    await this.finishFailure(owner, owner.failure.error);
+                }
+                else {
+                    await this.failOwner(owner, error);
+                }
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    reportProgress(owner, completedUnits, totalUnits) {
+        if (completedUnits < 0n
+            || totalUnits < 0n
+            || completedUnits > totalUnits
+            || (owner.lastProgress !== null
+                && (completedUnits < owner.lastProgress.completedUnits
+                    || totalUnits !== owner.lastProgress.totalUnits))) {
+            throw new BotaSDKError('protocol_error', owner.operation);
+        }
+        owner.lastProgress = { completedUnits, totalUnits };
+        try {
+            owner.observer?.onProgress?.(completedUnits, totalUnits);
+        }
+        catch {
+            // Observer failures do not change device workflow state.
+        }
+    }
+    reportFirmwareProgress(owner, phase, completedBytes, totalBytes) {
+        const previous = owner.lastFirmwareProgress;
+        if (completedBytes < 0n
+            || totalBytes < 0n
+            || completedBytes > totalBytes
+            || (previous !== null
+                && (firmwarePhaseIndex(phase) < firmwarePhaseIndex(previous.phase)
+                    || totalBytes !== previous.totalBytes
+                    || (phase === previous.phase
+                        && completedBytes < previous.completedBytes)))) {
+            throw new BotaSDKError('protocol_error', owner.operation);
+        }
+        owner.lastFirmwareProgress = { phase, completedBytes, totalBytes };
+        try {
+            owner.observer?.onProgress?.(completedBytes, totalBytes);
+        }
+        catch {
+            // Observer failures do not change device workflow state.
+        }
+    }
+    async dispatchBleFailure(context, requestId, error) {
+        await context.dispatch({
+            requestId,
+            kind: 'ble_failed',
+            platformCode: platformCode(error),
+        });
+    }
+    async serializedCoreCall(body) {
+        const result = this.coreDispatchTail.then(body);
+        this.coreDispatchTail = result.then(() => undefined, () => undefined);
+        return await result;
+    }
+    dispatchCurrentOwnerEvent(owner, generation, event) {
+        const effects = this.core.dispatch(event);
+        const status = this.core.status();
+        if (status.kind === 'completed'
+            && publicOperation(status.operation) === owner.operation) {
+            const request = owner.requests.get(event.requestId);
+            if (request
+                && request.generation === generation
+                && equalBytes(request.cancellationId, owner.cancellationId)) {
+                owner.completionEvidence = {
+                    requestId: event.requestId,
+                    generation,
+                    cancellationId: request.cancellationId.slice(),
+                };
+            }
+        }
+        return effects;
+    }
+    hasCompletionEvidence(owner) {
+        const evidence = owner.completionEvidence;
+        return evidence !== null
+            && evidence.generation === owner.generation
+            && owner.requests.has(evidence.requestId)
+            && equalBytes(evidence.cancellationId, owner.cancellationId);
+    }
+    enterCancellation(owner) {
+        if (owner.cancelPromise)
+            return owner.cancelPromise;
+        const cancellation = deferred();
+        owner.cancelPromise = cancellation.promise;
+        const started = owner.failure
+            ? this.cancelAfterFailure(owner, owner.failure.error)
+            : this.cancelOwner(owner);
+        void started.then(() => cancellation.resolve(undefined), cancellation.reject);
+        return cancellation.promise;
+    }
+    async cancelOwner(owner) {
+        if (owner.terminal)
+            return Promise.resolve();
+        if (owner.completing) {
+            await owner.result.promise.catch(() => undefined);
+            return;
+        }
+        if (await this.confirmationAttemptedOrClaimCancellation(owner)) {
+            await owner.result.promise;
+            return;
+        }
+        this.beginCancellation(owner);
+        let cleanupError = null;
+        try {
+            await this.cleanupAndSettle(owner, true);
+        }
+        catch (error) {
+            cleanupError = error;
+        }
+        try {
+            const effects = await this.serializedCoreCall(() => this.core.cancel(owner.cancellationId.slice()));
+            this.enqueueEffects(owner, effects, owner.generation);
+        }
+        catch (error) {
+            await this.finishFailure(owner, cleanupError ?? error);
+        }
+        try {
+            await owner.result.promise;
+        }
+        catch (error) {
+            if (cleanupError === null
+                && error instanceof BotaSDKError
+                && error.code === 'cancelled') {
+                return;
+            }
+            throw normalizeRuntimeError(cleanupError ?? error, owner.operation);
+        }
+    }
+    finishSuccess(owner, priorError) {
+        if (priorError !== undefined) {
+            owner.completionFailure ??= { error: priorError };
+        }
+        if (owner.completionPromise)
+            return owner.completionPromise;
+        if (owner.terminal)
+            return Promise.resolve();
+        if (owner.failure) {
+            return this.finishFailure(owner, owner.failure.error);
+        }
+        owner.completing = true;
+        owner.completionPromise = (async () => {
+            try {
+                await owner.completionHandoff?.({
+                    notifications: [...owner.notifications],
+                });
+            }
+            catch (error) {
+                owner.completionFailure ??= { error };
+            }
+            owner.terminal = true;
+            discardQueuedEffects(owner.queue);
+            try {
+                await this.cleanupAndSettle(owner, false);
+            }
+            catch (error) {
+                owner.completionFailure ??= { error };
+            }
+            this.releaseOwner(owner);
+            if (owner.completionFailure) {
+                owner.result.reject(normalizeRuntimeError(owner.completionFailure.error, owner.operation));
+            }
+            else {
+                owner.result.resolve({ notifications: [...owner.notifications] });
+            }
+        })();
+        return owner.completionPromise;
+    }
+    async finishCancelled(owner) {
+        if (owner.terminal)
+            return;
+        owner.terminal = true;
+        discardQueuedEffects(owner.queue);
+        owner.cancellationAbortController?.abort();
+        let cleanupError = null;
+        try {
+            await this.cleanupAndSettle(owner, true);
+        }
+        catch (error) {
+            cleanupError = error;
+        }
+        this.releaseOwner(owner);
+        if (owner.failure) {
+            owner.result.reject(normalizeRuntimeError(owner.failure.error, owner.operation));
+        }
+        else if (cleanupError !== null) {
+            owner.result.reject(normalizeRuntimeError(cleanupError, owner.operation));
+        }
+        else {
+            owner.result.reject(new BotaSDKError('cancelled', owner.operation));
+        }
+    }
+    failOwner(owner, error) {
+        if (owner.terminal)
+            return Promise.resolve();
+        if (this.hasCompletionEvidence(owner)) {
+            return this.finishSuccess(owner, error);
+        }
+        if (owner.failurePromise)
+            return owner.failurePromise;
+        owner.failure = { error };
+        owner.failurePromise = owner.cancelling
+            ? this.finishFailure(owner, error)
+            : this.enterCancellation(owner);
+        return owner.failurePromise;
+    }
+    async cancelAfterFailure(owner, error) {
+        if (await this.confirmationAttemptedOrClaimCancellation(owner)) {
+            await this.finishFailure(owner, error);
+            return;
+        }
+        this.beginCancellation(owner);
+        await this.cleanupAndSettle(owner, true).catch(() => undefined);
+        let effects;
+        try {
+            effects = await this.serializedCoreCall(() => this.core.cancel(owner.cancellationId.slice()));
+        }
+        catch {
+            await this.finishFailure(owner, error);
+            return;
+        }
+        try {
+            await this.executeCancellationEffects(owner, effects, owner.generation);
+        }
+        catch {
+            // The originating operation error remains the public terminal failure.
+        }
+        if (!owner.terminal)
+            await this.finishFailure(owner, error);
+    }
+    async executeCancellationEffects(owner, effects, generation) {
+        if (owner.inlineEffects) {
+            throw new BotaSDKError('internal_error', owner.operation);
+        }
+        const queue = [];
+        const failures = [];
+        owner.inlineEffects = queue;
+        try {
+            this.enqueueEffects(owner, effects, generation);
+            while (queue.length > 0 && !owner.terminal) {
+                const queued = queue.shift();
+                if (!queued)
+                    continue;
+                if (queued.generation !== owner.generation) {
+                    scrubTransientEffect(queued.envelope);
+                    continue;
+                }
+                try {
+                    await this.executeEffect(owner, queued);
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+        }
+        finally {
+            discardQueuedEffects(queue);
+            owner.inlineEffects = null;
+        }
+        if (failures.length > 0)
+            throw failures[0];
+    }
+    async finishFailure(owner, error) {
+        if (owner.terminal)
+            return;
+        owner.terminal = true;
+        owner.abortController.abort();
+        owner.cancellationAbortController?.abort();
+        discardQueuedEffects(owner.queue);
+        await this.cleanupAndSettle(owner, true).catch(() => undefined);
+        this.releaseOwner(owner);
+        owner.result.reject(normalizeRuntimeError(error, owner.operation));
+    }
+    beginCancellation(owner) {
+        owner.cancelling = true;
+        owner.generation += 1;
+        owner.abortController.abort();
+        discardQueuedEffects(owner.queue);
+        owner.cancellationAbortController = new AbortController();
+        owner.cancellationGeneration = owner.generation;
+    }
+    async confirmationAttemptedOrClaimCancellation(owner) {
+        for (const host of uniqueHosts(owner.hosts)) {
+            if (await host.confirmationAttemptedOrClaimCancellation?.(owner.cancellationId.slice()))
+                return true;
+        }
+        return false;
+    }
+    async cleanupAndSettle(owner, cancelHosts) {
+        let failure = null;
+        try {
+            await this.settlePendingGattWrites(owner);
+        }
+        catch (error) {
+            failure = error;
+        }
+        try {
+            await this.cleanupOwner(owner, cancelHosts);
+        }
+        catch (error) {
+            if (failure === null)
+                failure = error;
+        }
+        try {
+            await this.settlePendingGattSetups(owner);
+        }
+        catch (error) {
+            if (failure === null)
+                failure = error;
+        }
+        try {
+            await this.settlePendingExternalOperations(owner);
+        }
+        catch (error) {
+            if (failure === null)
+                failure = error;
+        }
+        if (failure !== null)
+            throw failure;
+    }
+    cleanupOwner(owner, cancelHosts) {
+        if (owner.cleanupPromise)
+            return owner.cleanupPromise;
+        owner.cleanupPromise = (async () => {
+            const failures = [];
+            if (cancelHosts) {
+                const hosts = uniqueHosts(owner.hosts);
+                for (const host of hosts) {
+                    try {
+                        await host.cancel();
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                }
+            }
+            for (const cleanup of [...owner.cleanups].reverse()) {
+                try {
+                    await cleanup();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            owner.cleanups.length = 0;
+            for (const timer of owner.timers.values())
+                clearTimeout(timer);
+            owner.timers.clear();
+            owner.subscriptions.clear();
+            if (failures.length > 0)
+                throw failures[0];
+        })();
+        return owner.cleanupPromise;
+    }
+    releaseOwner(owner) {
+        if (this.activeOwner === owner)
+            this.activeOwner = null;
+    }
+}
+export function createBrowserPersistenceHost(storage, now = Date.now) {
+    return {
+        execute: async (envelope, context) => {
+            switch (envelope.effect.kind) {
+                case 'persistence_load_checkpoint': {
+                    const checkpoint = storage
+                        ? await storage.loadWorkflowCheckpoint(context.operationId)
+                        : null;
+                    return {
+                        requestId: envelope.requestId,
+                        kind: 'checkpoint_loaded',
+                        checkpoint: checkpoint,
+                    };
+                }
+                case 'persistence_save_checkpoint':
+                    if (storage) {
+                        await storage.saveWorkflowCheckpoint(context.operationId, envelope.effect.checkpoint);
+                    }
+                    return { requestId: envelope.requestId, kind: 'checkpoint_saved' };
+                case 'persistence_delete_checkpoint':
+                    if (storage) {
+                        await storage.deleteWorkflowCheckpoint(context.operationId);
+                    }
+                    return null;
+                case 'persistence_save_connection_identity':
+                    if (storage) {
+                        await storage.saveVerifiedDevice({
+                            schemaVersion: 1,
+                            serialNumber: envelope.effect.serialNumber,
+                            browserDeviceId: envelope.effect.candidate.peripheralId,
+                            name: envelope.effect.candidate.name,
+                            updatedAtEpochMs: now(),
+                        });
+                    }
+                    return {
+                        requestId: envelope.requestId,
+                        kind: 'connection_identity_saved',
+                    };
+                default:
+                    throw new BotaSDKError('internal_error', publicOperation(envelope.operation));
+            }
+        },
+        cancel: async () => undefined,
+    };
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    return { promise, resolve, reject };
+}
+function equalBytes(left, right) {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    for (let index = 0; index < left.byteLength; index += 1) {
+        if (left[index] !== right[index])
+            return false;
+    }
+    return true;
+}
+function platformCode(error) {
+    if (typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && typeof error.code === 'number') {
+        return error.code;
+    }
+    return null;
+}
+function discardQueuedEffects(queue) {
+    for (const queued of queue)
+        scrubTransientEffect(queued.envelope);
+    queue.length = 0;
+}
+function scrubTransientEffect(envelope) {
+    const effect = envelope.effect;
+    if (effect.kind === 'ble_write') {
+        effect.payload.fill(0);
+    }
+    else if (effect.kind === 'host_material_prepare_provisioning') {
+        effect.nonce.fill(0);
+        effect.devicePublicKey.fill(0);
+    }
+}
+function uniqueHosts(hosts) {
+    return [...new Set([
+            hosts.persistence,
+            hosts.recordingSink,
+            hosts.network,
+            hosts.firmwareBlob,
+            hosts.hostMaterial,
+            hosts.encryptedUploadV2,
+        ].filter((host) => host !== undefined))];
+}
+function firmwarePhaseIndex(phase) {
+    switch (phase) {
+        case 'downloading':
+            return 0;
+        case 'awaiting_device':
+            return 1;
+        case 'transferring':
+            return 2;
+        case 'verifying':
+            return 3;
+        case 'rebooting':
+            return 4;
+        case 'reconnecting':
+            return 5;
+        case 'complete':
+            return 6;
+    }
+}
+function publicOperation(operation) {
+    switch (operation) {
+        case 'connect':
+            return 'connect';
+        case 'reconnect':
+            return 'reconnect';
+        case 'provision':
+            return 'provision';
+        case 'transfer_recording':
+            return 'transfer_recording';
+        case 'upload':
+            return 'upload';
+        case 'update_firmware':
+            return 'update_firmware';
+        case 'read_device_logs':
+            return 'read_device_logs';
+        default:
+            return 'unknown';
+    }
+}
+function operationFromId(operationId) {
+    const prefix = operationId.split(':', 1)[0];
+    switch (prefix) {
+        case 'connect':
+            return 'connect';
+        case 'reconnect':
+            return 'reconnect';
+        case 'provision':
+            return 'provision';
+        case 'transfer_recording':
+            return 'transfer_recording';
+        case 'upload':
+            return 'upload';
+        case 'update_firmware':
+            return 'update_firmware';
+        case 'read_device_logs':
+            return 'read_device_logs';
+        default:
+            return 'unknown';
+    }
+}
+function normalizeRuntimeError(error, operation) {
+    if (error instanceof BotaSDKError)
+        return error;
+    if (error instanceof BrowserStorageError) {
+        return new BotaSDKError(error.code, operation, { cause: error });
+    }
+    if (error instanceof BrowserTransportError) {
+        const code = error.code === 'disconnected'
+            ? 'device_disconnected'
+            : error.code === 'permission_denied'
+                ? 'permission_denied'
+                : error.code === 'picker_cancelled'
+                    ? 'picker_cancelled'
+                    : 'bluetooth_unavailable';
+        return new BotaSDKError(code, operation, { cause: error });
+    }
+    return normalizeCoreError(error, operation);
+}