@fastybird/smart-panel-backend 1.1.0-alpha.63 → 1.1.0-alpha.65

package/dist/modules/devices/services/property-command-dispatch.service.js

@@ -12,23 +12,39 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PropertyCommandDispatchService = void 0;
+exports.PropertyCommandDispatchService = exports.COMPOSITE_INTENT_FINISH_MARGIN_MS = void 0;
+const node_crypto_1 = require("node:crypto");
 const common_1 = require("@nestjs/common");
+const event_emitter_1 = require("@nestjs/event-emitter");
 const devices_constants_1 = require("../devices.constants");
 const property_value_state_model_1 = require("../models/property-value-state.model");
 const property_command_value_utils_1 = require("../utils/property-command-value.utils");
 const channels_service_1 = require("./channels.service");
 const command_latency_trace_collector_service_1 = require("./command-latency-trace-collector.service");
+const composite_property_command_registry_service_1 = require("./composite-property-command.registry.service");
+const cover_action_proof_1 = require("./cover-action-proof");
 const device_structure_lock_service_1 = require("./device-structure-lock.service");
 const devices_service_1 = require("./devices.service");
 const platform_registry_service_1 = require("./platform.registry.service");
+const property_command_admission_registry_service_1 = require("./property-command-admission.registry.service");
 const property_command_window_service_1 = require("./property-command-window.service");
 const property_metadata_service_1 = require("./property-metadata.service");
 const property_state_coordinator_service_1 = require("./property-state-coordinator.service");
 const property_value_source_registry_service_1 = require("./property-value-source.registry.service");
 const property_value_service_1 = require("./property-value.service");
+exports.COMPOSITE_INTENT_FINISH_MARGIN_MS = 100;
+class CompositeAdmissionSnapshotChangedError extends Error {
+}
+class CompositeDeadlineExceededError extends Error {
+}
 let PropertyCommandDispatchService = class PropertyCommandDispatchService {
-    constructor(propertyMetadata, propertyValues, channelsService, devicesService, platformRegistryService, valueSourceRegistry, structureLock, propertyStateCoordinator, commandWindowService, commandLatencyTraceCollector = new command_latency_trace_collector_service_1.CommandLatencyTraceCollectorService()) {
+    onModuleDestroy() {
+        this.disposed = true;
+        for (const cleanup of this.compositeCleanups)
+            cleanup();
+        this.compositeCleanups.clear();
+    }
+    constructor(propertyMetadata, propertyValues, channelsService, devicesService, platformRegistryService, valueSourceRegistry, structureLock, propertyStateCoordinator, commandWindowService, commandLatencyTraceCollector = new command_latency_trace_collector_service_1.CommandLatencyTraceCollectorService(), composites, events, admissionGuards) {
         this.propertyMetadata = propertyMetadata;
         this.propertyValues = propertyValues;
         this.channelsService = channelsService;
@@ -39,11 +55,33 @@ let PropertyCommandDispatchService = class PropertyCommandDispatchService {
         this.propertyStateCoordinator = propertyStateCoordinator;
         this.commandWindowService = commandWindowService;
         this.commandLatencyTraceCollector = commandLatencyTraceCollector;
+        this.composites = composites;
+        this.events = events;
+        this.admissionGuards = admissionGuards;
+        this.eventEpoch = (0, node_crypto_1.randomUUID)();
+        this.eventSequence = 0;
+        this.disposed = false;
+        this.activeComposites = 0;
+        this.compositeCleanups = new Set();
     }
     async dispatchBatch(updates, options = {}) {
+        const admission = this.admissionGuards?.capture?.();
+        const isCurrent = () => (options.commandEntry?.isActive() ?? true) &&
+            (options.isRequestCurrent?.() ?? true) &&
+            (options.deadlineAt === undefined || Date.now() < options.deadlineAt) &&
+            (admission?.isRequestCurrent?.() ?? admission?.isCurrent() ?? true);
+        const isLeafCurrent = (update) => isCurrent() && (options.commandEntry?.isActive(update) ?? true) && (admission?.isCurrent(update) ?? true);
+        if (!isCurrent())
+            return { success: false, reason: 'Command admission changed or expired' };
         if (updates.length === 0) {
             return { success: true };
         }
+        const planner = updates.map((update) => this.composites?.get(update.property)).find(Boolean);
+        if (planner ||
+            updates.some((update) => (0, cover_action_proof_1.isCoverControl)(update) &&
+                (this.valueSourceRegistry.resolve(update.property) !== update.property.id ||
+                    typeof this.platformRegistryService.get(update.device)?.getCoverEffectScope === 'function')))
+            return this.dispatchComposite(updates, { ...options, isRequestCurrent: isCurrent }, admission);
         const platform = this.platformRegistryService.get(updates[0].device);
         if (platform === null) {
             return { success: false, reason: 'Unsupported device type' };
@@ -57,7 +95,48 @@ let PropertyCommandDispatchService = class PropertyCommandDispatchService {
             return { success: false, reason: 'Canonical property target changed before dispatch' };
         }
         try {
-            const success = await platform.processBatch([...updates]);
+            if (!isCurrent()) {
+                this.failOwned(handles);
+                return { success: false, reason: 'Command admission changed before dispatch' };
+            }
+            const canonicalUpdates = this.admissionGuards?.hasGuards?.() || options.isRequestCurrent
+                ? await this.canonicalOrdinaryUpdates(updates)
+                : [...updates];
+            if (!canonicalUpdates) {
+                this.failOwned(handles);
+                return { success: false, reason: 'Physical target changed before dispatch' };
+            }
+            const admissionUpdates = [...updates, ...canonicalUpdates];
+            for (const update of admissionUpdates) {
+                await options.commandEntry?.assertAllowed(update);
+                await admission?.assertAllowed(update);
+            }
+            let success;
+            if (options.isRequestCurrent ||
+                canonicalUpdates.some((update) => this.admissionGuards?.requiresGuardedDispatch?.(update))) {
+                const byDevice = new Map();
+                for (const update of canonicalUpdates) {
+                    const batch = byDevice.get(update.device.id) ?? [];
+                    batch.push(update);
+                    byDevice.set(update.device.id, batch);
+                }
+                success = true;
+                const deadline = Date.now() + (options.ttlMs ?? 3000);
+                for (const batch of byDevice.values()) {
+                    const prepared = await this.platformRegistryService.get(batch[0].device)?.prepareCompositeBatch?.(batch);
+                    const guard = () => isCurrent() &&
+                        admissionUpdates.every(isLeafCurrent) &&
+                        Date.now() < deadline &&
+                        !!prepared?.isCurrent() &&
+                        handles.every((handle) => this.commandWindowService.peekGeneration(handle.canonicalPropertyId) === handle.generation);
+                    if (!prepared || !guard() || !(await prepared.dispatch(guard))) {
+                        success = false;
+                        break;
+                    }
+                }
+            }
+            else
+                success = admissionUpdates.every(isLeafCurrent) && (await platform.processBatch([...updates]));
             if (!success) {
                 this.failOwned(handles);
                 return { success: false, reason: 'Execution failed' };
@@ -69,7 +148,574 @@ let PropertyCommandDispatchService = class PropertyCommandDispatchService {
             throw error;
         }
     }
+    async canonicalOrdinaryUpdates(updates) {
+        const result = [];
+        for (const update of updates) {
+            const current = await this.propertyMetadata.findOne(update.property.id);
+            if (!current)
+                return null;
+            const id = this.valueSourceRegistry.resolve(current);
+            if (id !== this.valueSourceRegistry.resolve(update.property))
+                return null;
+            const property = id === current.id ? current : await this.propertyMetadata.findOne(id);
+            if (!property)
+                return null;
+            const channel = typeof property.channel === 'string' ? await this.channelsService.findOne(property.channel) : property.channel;
+            const device = typeof channel?.device === 'string' ? await this.devicesService.findOne(channel.device) : channel?.device;
+            if (!channel || !device)
+                return null;
+            const validation = (0, property_command_value_utils_1.validatePropertyCommandValue)(property, update.value);
+            if (!validation.valid || validation.value === undefined)
+                return null;
+            result.push({ property, channel, device, value: validation.value });
+        }
+        return result;
+    }
+    async dispatchComposite(updates, options, admission) {
+        if (this.disposed || this.activeComposites >= 128)
+            return { success: false, reason: 'Composite dispatcher unavailable or at capacity' };
+        this.activeComposites++;
+        try {
+            return await this.executeComposite(updates, options, admission);
+        }
+        finally {
+            this.activeComposites--;
+        }
+    }
+    async executeComposite(updates, options, admission) {
+        if (options.commandEntry && !options.commandEntry.isActive())
+            return { success: false, reason: 'Command entry snapshot expired or exceeded bounds' };
+        const id = (0, node_crypto_1.randomUUID)();
+        const deadline = Math.min(options.commandEntry?.deadlineAt ?? Infinity, options.deadlineAt ?? Infinity, Date.now() + Math.min(options.ttlMs ?? 10_000, 30_000));
+        if (Date.now() >= deadline)
+            return { success: false, reason: 'Composite command deadline exceeded' };
+        const planner = updates.map((update) => this.composites?.get(update.property)).find(Boolean);
+        let plan;
+        try {
+            const metadataGeneration = planner ? 0 : this.propertyMetadata.getGeneration();
+            if (!planner) {
+                plan = {
+                    revision: metadataGeneration,
+                    children: updates.map((update) => ({ memberId: update.channel.id, update })),
+                    isCurrent: () => Promise.resolve(this.propertyMetadata.getGeneration() === metadataGeneration),
+                    isDispatchCurrent: () => this.propertyMetadata.getGeneration() === metadataGeneration,
+                };
+            }
+            else {
+                plan = await this.withCompositeDeadline(this.structureLock.runShared(() => planner.plan(updates.filter((update) => planner.canHandle(update.property)), options.commandEntry)), deadline);
+                plan = {
+                    ...plan,
+                    children: [
+                        ...plan.children,
+                        ...updates
+                            .filter((update) => !planner.canHandle(update.property))
+                            .map((update) => ({ memberId: update.channel.id, update })),
+                    ],
+                };
+            }
+        }
+        catch (error) {
+            return { success: false, reason: error instanceof Error ? error.message : 'Invalid composite plan' };
+        }
+        if (!plan.children.length || plan.children.length > 2048) {
+            plan.dispose?.();
+            return { success: false, reason: 'Composite size exceeds bounds' };
+        }
+        const outcomes = plan.children.map((child) => ({
+            memberId: child.memberId,
+            memberIdentity: child.memberIdentity ?? child.update?.channel.id,
+            propertyIdentity: child.propertyIdentity ?? child.update?.property.id ?? null,
+            propertyId: child.update?.property.id ?? null,
+            status: child.update ? 'accepted' : 'unavailable',
+            reason: child.reason,
+        }));
+        const leaves = new Map();
+        const requestedValues = new Map();
+        for (const [index, child] of plan.children.entries()) {
+            if (!child.update)
+                continue;
+            const canonical = this.valueSourceRegistry.resolve(child.update.property);
+            if (Date.now() >= deadline) {
+                Object.assign(outcomes[index], {
+                    status: 'timed_out',
+                    reason: 'Composite deadline exceeded during preparation',
+                });
+                continue;
+            }
+            let source;
+            try {
+                source = await this.withCompositeDeadline(this.propertyMetadata.findOne(canonical), deadline);
+            }
+            catch (error) {
+                Object.assign(outcomes[index], {
+                    status: error instanceof CompositeDeadlineExceededError || Date.now() >= deadline ? 'timed_out' : 'failed',
+                    reason: error instanceof Error ? error.message : 'Metadata unavailable',
+                });
+                continue;
+            }
+            const validation = source ? (0, property_command_value_utils_1.validatePropertyCommandValue)(source, child.update.value) : null;
+            const targetValue = validation?.value ?? child.update.value;
+            if (requestedValues.has(canonical) && requestedValues.get(canonical) !== targetValue) {
+                const reason = 'Contradictory canonical targets in composite command';
+                for (const outcome of outcomes)
+                    if (outcome.status === 'accepted')
+                        Object.assign(outcome, { status: 'failed', reason });
+                const composite = { id, status: 'failed', children: outcomes };
+                this.events?.emit('DevicesModule.CompositeCommand.Completed', {
+                    epoch: this.eventEpoch,
+                    sequence: ++this.eventSequence,
+                    ...composite,
+                    children: composite.children.map(toEventChild),
+                    intentId: options.intentId,
+                    requestId: options.requestId,
+                    targets: updates.map(toTarget),
+                    revision: plan.revision,
+                });
+                plan.dispose?.();
+                return { success: false, reason, composite };
+            }
+            requestedValues.set(canonical, targetValue);
+            if (!validation?.valid || validation.value === undefined) {
+                Object.assign(outcomes[index], {
+                    status: 'unavailable',
+                    reason: validation?.reason ?? 'Canonical property is missing',
+                });
+                continue;
+            }
+            const sourceChannel = typeof source.channel === 'string' ? await this.channelsService.findOne(source.channel) : source.channel;
+            const sourceDeviceId = typeof sourceChannel?.device === 'string' ? sourceChannel.device : sourceChannel?.device?.id;
+            const sourceDevice = sourceDeviceId === child.update.device.id
+                ? child.update.device
+                : sourceDeviceId
+                    ? await this.devicesService.findOne(sourceDeviceId)
+                    : null;
+            if (!sourceChannel || !sourceDevice) {
+                Object.assign(outcomes[index], { status: 'unavailable', reason: 'Canonical device/channel is missing' });
+                continue;
+            }
+            const normalized = {
+                device: sourceDevice,
+                channel: sourceDevice.channels?.find((channel) => channel.id === sourceChannel.id) ?? sourceChannel,
+                property: source,
+                value: validation.value,
+            };
+            const existing = leaves.get(canonical);
+            if (existing && existing.update.value !== normalized.value) {
+                plan.dispose?.();
+                return { success: false, reason: 'Contradictory canonical targets in composite command' };
+            }
+            if (existing)
+                existing.indexes.push(index);
+            else
+                leaves.set(canonical, { update: normalized, indexes: [index] });
+        }
+        const channels = new Map();
+        for (const leaf of leaves.values()) {
+            const key = `${leaf.update.device.id}:${leaf.update.channel.id}`;
+            const channel = channels.get(key) ?? [];
+            channel.push(leaf);
+            channels.set(key, channel);
+        }
+        const effectEpochs = new Map();
+        const releaseEffects = () => {
+            for (const [scope, epoch] of effectEpochs)
+                this.commandWindowService.releaseCoverEffect(scope, epoch);
+        };
+        const effectChannels = new Map();
+        for (const leaf of leaves.values())
+            if ((0, cover_action_proof_1.isCoverControl)(leaf.update)) {
+                const scope = this.platformRegistryService.get(leaf.update.device)?.getCoverEffectScope?.(leaf.update) ??
+                    leaf.update.channel.id;
+                if (effectChannels.has(scope) && effectChannels.get(scope) !== leaf.update.channel.id) {
+                    plan.dispose?.();
+                    releaseEffects();
+                    return { success: false, reason: 'Multiple logical channels resolve to one physical cover motor' };
+                }
+                effectChannels.set(scope, leaf.update.channel.id);
+                if (effectEpochs.has(scope))
+                    continue;
+                const epoch = this.commandWindowService.beginCoverEffect(scope);
+                if (epoch === null) {
+                    plan.dispose?.();
+                    releaseEffects();
+                    return { success: false, reason: 'Cover effect is reserved or capacity exceeded' };
+                }
+                effectEpochs.set(scope, epoch);
+            }
+        const effectsCurrent = () => [...effectEpochs].every(([id, epoch]) => this.commandWindowService.isCoverEffectCurrent(id, epoch));
+        const work = [...channels.values()];
+        const preparedBatches = new Map();
+        let preparing = 0;
+        await Promise.all(Array.from({ length: Math.min(8, work.length) }, async () => {
+            while (preparing < work.length) {
+                const channel = work[preparing++];
+                let prepared;
+                try {
+                    const platform = this.platformRegistryService.get(channel[0].update.device);
+                    if (!platform)
+                        throw new Error('Unsupported physical platform');
+                    const requested = channel.map((leaf) => leaf.update);
+                    if (!platform.prepareCompositeBatch)
+                        throw new Error('Provider does not support the strict composite dispatch profile');
+                    prepared = await this.withCompositeDeadline(platform.prepareCompositeBatch(requested), Math.min(deadline, Date.now() + 1_000), (late) => late?.dispose?.());
+                    if (!prepared || !prepared.isCurrent() || prepared.updates.length !== channel.length) {
+                        const rejected = prepared;
+                        prepared = undefined;
+                        rejected?.dispose?.();
+                        const readiness = await platform.getCommandReadiness?.(requested[0]);
+                        throw new Error(readiness?.reasons.join(', ') ||
+                            'Physical batch preparation is unavailable or changed target cardinality');
+                    }
+                    const targets = new Map(prepared.updates.map((target) => [this.valueSourceRegistry.resolve(target.property), target]));
+                    if (targets.size !== channel.length)
+                        throw new Error('Prepared physical targets are not distinct');
+                    for (const leaf of channel) {
+                        const target = targets.get(this.valueSourceRegistry.resolve(leaf.update.property));
+                        if (!target || target.device.id !== leaf.update.device.id || target.channel.id !== leaf.update.channel.id)
+                            throw new Error('Prepared physical target identity changed');
+                        const validation = (0, property_command_value_utils_1.validatePropertyCommandValue)(target.property, target.value);
+                        if (!validation.valid || validation.value === undefined)
+                            throw new Error('Prepared physical target value is invalid');
+                        leaf.update = { ...target, value: validation.value };
+                        for (const index of leaf.indexes)
+                            outcomes[index].value = validation.value;
+                    }
+                    if (prepared.coverAction &&
+                        (!(0, cover_action_proof_1.validCoverAction)(prepared.coverAction, channel.map((leaf) => leaf.update)) ||
+                            prepared.coverAction.effectScope !== platform.getCoverEffectScope?.(channel[0].update)))
+                        throw new Error('Invalid cover observation footprint');
+                    preparedBatches.set(channel, prepared);
+                    prepared = undefined;
+                }
+                catch (error) {
+                    for (const leaf of channel)
+                        for (const index of leaf.indexes)
+                            Object.assign(outcomes[index], {
+                                status: 'unavailable',
+                                reason: error instanceof Error ? error.message : 'Physical preparation failed',
+                            });
+                }
+                finally {
+                    prepared?.dispose?.();
+                }
+            }
+        }));
+        let cursor = 0;
+        let lastPublished = '';
+        const publish = () => {
+            const signature = JSON.stringify(outcomes);
+            if (signature === lastPublished)
+                return;
+            lastPublished = signature;
+            this.events?.emit('DevicesModule.CompositeCommand.Progress', {
+                epoch: this.eventEpoch,
+                sequence: ++this.eventSequence,
+                id,
+                intentId: options.intentId,
+                requestId: options.requestId,
+                targets: updates.map(toTarget),
+                revision: plan.revision,
+                deadlineAt: deadline,
+                children: outcomes.map(toEventChild),
+            });
+        };
+        const ownedGenerations = new Map();
+        const observedConfirmations = new Map();
+        const channelSettlements = new Map();
+        const stopGenerations = this.commandWindowService.observeGeneration((propertyId, generation) => {
+            const owned = ownedGenerations.get(propertyId);
+            if (!owned || owned.generation === generation)
+                return;
+            for (const index of owned.indexes)
+                if (['accepted', 'confirmed'].includes(outcomes[index].status))
+                    Object.assign(outcomes[index], {
+                        status: 'superseded',
+                        reason: 'Physical generation superseded or cancelled',
+                    });
+            channelSettlements.get(propertyId)?.();
+            publish();
+        });
+        const stopConfirmations = this.commandWindowService.observeConfirmation((handle) => {
+            if (!leaves.has(handle.canonicalPropertyId))
+                return;
+            observedConfirmations.set(handle.canonicalPropertyId, handle.generation);
+            const owned = ownedGenerations.get(handle.canonicalPropertyId);
+            if (!owned || owned.generation !== handle.generation)
+                return;
+            for (const index of owned.indexes)
+                if (outcomes[index].status === 'accepted')
+                    Object.assign(outcomes[index], {
+                        status: 'confirmed',
+                        generation: handle.generation,
+                        reason: (0, cover_action_proof_1.coverConfirmationReason)(this.commandWindowService.get(handle.canonicalPropertyId)),
+                    });
+            channelSettlements.get(handle.canonicalPropertyId)?.();
+            publish();
+        });
+        const stopObserving = () => {
+            stopGenerations();
+            stopConfirmations();
+        };
+        const cleanup = () => {
+            stopObserving();
+            releaseEffects();
+            for (const child of outcomes)
+                if (child.status === 'accepted')
+                    Object.assign(child, { status: 'superseded', reason: 'Composite dispatcher stopped' });
+            for (const [canonicalPropertyId, owned] of ownedGenerations)
+                this.commandWindowService.fail({ canonicalPropertyId, generation: owned.generation });
+            for (const signal of new Set(channelSettlements.values()))
+                signal();
+        };
+        this.compositeCleanups.add(cleanup);
+        publish();
+        const workers = Array.from({ length: Math.min(8, work.length) }, async () => {
+            while (cursor < work.length) {
+                const channel = work[cursor++];
+                const prepared = preparedBatches.get(channel);
+                if (!prepared)
+                    continue;
+                const setLeaf = (leaf, status, reason, generation) => {
+                    if (status === 'confirmed')
+                        reason ??= (0, cover_action_proof_1.coverConfirmationReason)(this.commandWindowService.get(this.valueSourceRegistry.resolve(leaf.update.property)));
+                    for (const index of leaf.indexes)
+                        Object.assign(outcomes[index], { status, reason, generation });
+                };
+                const setPending = (status, reason) => {
+                    for (const leaf of channel)
+                        if (leaf.indexes.some((index) => outcomes[index].status === 'accepted'))
+                            setLeaf(leaf, status, reason);
+                    publish();
+                };
+                let handles = [];
+                let dispatchActive = true;
+                try {
+                    if (this.disposed || Date.now() >= deadline) {
+                        setPending('timed_out');
+                        continue;
+                    }
+                    if (!effectsCurrent() ||
+                        !prepared.isCurrent() ||
+                        !(await this.withCompositeDeadline(plan.isCurrent(), deadline))) {
+                        setPending('superseded', 'Binding revision changed');
+                        continue;
+                    }
+                    const admissionUpdates = channel.flatMap((leaf) => [
+                        leaf.update,
+                        ...leaf.indexes.flatMap((index) => (plan.children[index].update ? [plan.children[index].update] : [])),
+                    ]);
+                    const effects = (prepared.coverAction?.effects ?? []).map((property) => ({
+                        device: channel[0].update.device,
+                        channel: channel[0].update.channel,
+                        property,
+                        kind: 'cover_action',
+                        action: channel[0].update.property.category === devices_constants_1.PropertyCategory.COMMAND
+                            ? channel[0].update.value
+                            : channel[0].update.property.category,
+                    }));
+                    for (const effect of effects) {
+                        await options.commandEntry?.assertEffectAllowed(effect);
+                        await admission?.assertEffectAllowed?.(effect);
+                    }
+                    for (const update of admissionUpdates) {
+                        await options.commandEntry?.assertAllowed(update);
+                        await admission?.assertAllowed(update);
+                    }
+                    const admitted = await this.withCompositeDeadline(this.admitWindows(channel.map((leaf) => leaf.update), {
+                        intentId: options.intentId,
+                        ttlMs: deadline - Date.now(),
+                        deadlineAt: deadline,
+                        requiresLiveEvidence: true,
+                    }, new Map(channel.map((leaf) => [
+                        this.valueSourceRegistry.resolve(leaf.update.property),
+                        leaf.indexes.flatMap((index) => plan.children[index].admissionCheck ? [plan.children[index].admissionCheck] : []),
+                    ])), prepared.coverAction), deadline);
+                    handles = admitted?.map((window) => window.handle) ?? [];
+                    if (!admitted || handles.length !== channel.length) {
+                        setPending('unavailable', 'No correlated physical readback admission');
+                        continue;
+                    }
+                    if (handles.some((handle) => this.commandWindowService.peekGeneration(handle.canonicalPropertyId) !== handle.generation)) {
+                        setPending('superseded', 'Physical command generation replaced during compound admission');
+                        continue;
+                    }
+                    for (const leaf of channel) {
+                        const handle = handles.find((handle) => handle.canonicalPropertyId === this.valueSourceRegistry.resolve(leaf.update.property));
+                        ownedGenerations.set(handle.canonicalPropertyId, { generation: handle.generation, indexes: leaf.indexes });
+                        setLeaf(leaf, observedConfirmations.get(handle.canonicalPropertyId) === handle.generation ? 'confirmed' : 'accepted', undefined, handle.generation);
+                    }
+                    publish();
+                    const allTerminal = () => !channel.some((leaf) => leaf.indexes.some((index) => outcomes[index].status === 'accepted'));
+                    if (allTerminal())
+                        continue;
+                    const settlement = new Promise((resolve) => {
+                        const signal = () => {
+                            if (allTerminal())
+                                resolve({ success: true });
+                        };
+                        for (const handle of handles)
+                            channelSettlements.set(handle.canonicalPropertyId, signal);
+                    });
+                    const dispatched = await this.withCompositeDeadline(Promise.race([
+                        settlement,
+                        this.dispatchPreparedComposite(channel.map((leaf) => leaf.update), handles, prepared, () => dispatchActive &&
+                            effectsCurrent() &&
+                            !this.disposed &&
+                            effects.every((effect) => (options.commandEntry?.isEffectActive(effect) ?? true) &&
+                                (admission?.isEffectCurrent?.(effect) ?? !admission)) &&
+                            admissionUpdates.every((update) => (options.commandEntry?.isActive(update) ?? true) && (admission?.isCurrent(update) ?? true)) &&
+                            (options.isRequestCurrent?.() ?? true) &&
+                            Date.now() < deadline &&
+                            (plan.isDispatchCurrent?.() ?? true) &&
+                            handles.every((handle) => this.commandWindowService.peekGeneration(handle.canonicalPropertyId) === handle.generation)),
+                    ]), deadline);
+                    if (!dispatched.success) {
+                        if (prepared.isCurrent() && (plan.isDispatchCurrent?.() ?? true))
+                            for (const leaf of channel) {
+                                const handle = handles.find((handle) => handle.canonicalPropertyId === this.valueSourceRegistry.resolve(leaf.update.property));
+                                const window = this.commandWindowService.get(handle.canonicalPropertyId);
+                                if (window?.generation === handle.generation && window.state === 'confirmed_grace')
+                                    setLeaf(leaf, 'confirmed', undefined, handle.generation);
+                            }
+                        setPending(!prepared.isCurrent() ? 'superseded' : Date.now() >= deadline ? 'timed_out' : 'failed', dispatched.reason);
+                        continue;
+                    }
+                    while (!this.disposed && Date.now() < deadline) {
+                        if (!effectsCurrent() ||
+                            !prepared.isCurrent() ||
+                            !(await this.withCompositeDeadline(plan.isCurrent(), deadline))) {
+                            setPending('superseded', 'Binding revision changed');
+                            break;
+                        }
+                        for (const leaf of channel) {
+                            if (!leaf.indexes.some((index) => outcomes[index].status === 'accepted'))
+                                continue;
+                            const handle = handles.find((handle) => handle.canonicalPropertyId === this.valueSourceRegistry.resolve(leaf.update.property));
+                            const window = this.commandWindowService.get(handle.canonicalPropertyId);
+                            if (!window || window.generation !== handle.generation)
+                                setLeaf(leaf, 'superseded', 'Physical command generation replaced');
+                            else if (window.state === 'confirmed_grace')
+                                setLeaf(leaf, 'confirmed', undefined, handle.generation);
+                        }
+                        publish();
+                        if (!channel.some((leaf) => leaf.indexes.some((index) => outcomes[index].status === 'accepted')))
+                            break;
+                        await new Promise((resolve) => setTimeout(resolve, Math.min(20, Math.max(1, deadline - Date.now()))));
+                    }
+                    setPending('timed_out');
+                }
+                catch (error) {
+                    setPending(error instanceof CompositeAdmissionSnapshotChangedError
+                        ? 'superseded'
+                        : error instanceof CompositeDeadlineExceededError || Date.now() >= deadline
+                            ? 'timed_out'
+                            : 'failed', error instanceof Error ? error.message : 'Execution failed');
+                }
+                finally {
+                    dispatchActive = false;
+                    prepared.dispose?.();
+                    for (const handle of handles)
+                        channelSettlements.delete(handle.canonicalPropertyId);
+                    for (const leaf of channel)
+                        if (leaf.indexes.some((index) => outcomes[index].status !== 'confirmed'))
+                            this.failOwned(handles.filter((handle) => handle.canonicalPropertyId === this.valueSourceRegistry.resolve(leaf.update.property)));
+                }
+            }
+        });
+        try {
+            await Promise.all(workers);
+            let validation = 'unavailable';
+            let validationReason = 'Physical confirmation observed; final binding validation unavailable before deadline';
+            if (Date.now() < deadline) {
+                try {
+                    const current = await this.withCompositeDeadline(plan.isCurrent(), deadline);
+                    if (Date.now() < deadline) {
+                        if (current === true)
+                            validation = 'current';
+                        else if (current === false)
+                            validation = 'changed';
+                        else
+                            validationReason = 'Physical confirmation observed; final binding validation failed';
+                    }
+                }
+                catch (error) {
+                    if (!(error instanceof CompositeDeadlineExceededError))
+                        validationReason = 'Physical confirmation observed; final binding validation failed';
+                }
+            }
+            if (validation !== 'current')
+                for (const child of outcomes)
+                    if (child.status === 'confirmed')
+                        Object.assign(child, validation === 'changed'
+                            ? { status: 'superseded', reason: 'Binding revision changed before parent completion' }
+                            : { status: 'unavailable', reason: validationReason });
+            const confirmed = outcomes.filter((child) => child.status === 'confirmed').length;
+            const composite = {
+                id,
+                status: confirmed === outcomes.length ? 'confirmed' : confirmed > 0 ? 'partial' : 'failed',
+                children: outcomes.map((child) => ({ ...child })),
+            };
+            this.events?.emit('DevicesModule.CompositeCommand.Completed', {
+                epoch: this.eventEpoch,
+                sequence: ++this.eventSequence,
+                ...composite,
+                children: composite.children.map(toEventChild),
+                intentId: options.intentId,
+                requestId: options.requestId,
+                targets: updates.map(toTarget),
+                revision: plan.revision,
+            });
+            return {
+                success: composite.status === 'confirmed',
+                composite,
+                reason: composite.status === 'confirmed' ? undefined : `Composite command ${composite.status}`,
+            };
+        }
+        finally {
+            stopObserving();
+            this.compositeCleanups.delete(cleanup);
+            releaseEffects();
+            plan.dispose?.();
+        }
+    }
+    async dispatchPreparedComposite(updates, handles, prepared, isAdmitted) {
+        if (this.disposed ||
+            !prepared.isCurrent() ||
+            !(await this.verifyPreopenedWindows(updates, handles, prepared.coverAction)))
+            return { success: false, reason: 'Prepared provider target changed before dispatch' };
+        const action = prepared.coverAction;
+        const context = action && (0, cover_action_proof_1.validCoverAction)(action, updates)
+            ? (0, cover_action_proof_1.coverActionContext)(action, updates[0], handles[0], this.commandWindowService, this.propertyValues, () => isAdmitted() && prepared.isCurrent())
+            : undefined;
+        const success = await prepared.dispatch(isAdmitted, context);
+        return success ? { success: true } : { success: false, reason: 'Execution failed' };
+    }
+    async withCompositeDeadline(operation, deadline, onLateResult) {
+        let timer;
+        let expired = false;
+        try {
+            return await Promise.race([
+                operation.then((result) => {
+                    if (expired)
+                        onLateResult?.(result);
+                    return result;
+                }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        expired = true;
+                        reject(new CompositeDeadlineExceededError('Composite deadline exceeded'));
+                    }, Math.max(1, deadline - Date.now()));
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     async prepareApiCommand(update, ttlMs) {
+        if ((0, cover_action_proof_1.isCoverControl)(update))
+            return null;
         const admitted = await this.admitWindows([update], { ttlMs });
         const first = admitted?.[0];
         if (first === undefined) {
@@ -82,7 +728,7 @@ let PropertyCommandDispatchService = class PropertyCommandDispatchService {
             optimisticEligible: first.admission.canonicalPropertyId === update.property.id && first.admission.baseline !== null,
         };
     }
-    async admitWindows(updates, options) {
+    async admitWindows(updates, options, checks, cover) {
         return this.structureLock.runShared(async () => {
             const requestedByCanonical = new Map();
             for (const update of updates) {
@@ -93,19 +739,40 @@ let PropertyCommandDispatchService = class PropertyCommandDispatchService {
             }
             const admitted = [];
             for (const [canonicalPropertyId, requestedUpdates] of requestedByCanonical) {
-                const admission = await this.propertyStateCoordinator.run(canonicalPropertyId, async () => this.createAdmission(canonicalPropertyId, requestedUpdates));
+                let admission;
+                try {
+                    admission = await this.propertyStateCoordinator.run(canonicalPropertyId, () => this.createAdmission(canonicalPropertyId, requestedUpdates, cover));
+                }
+                catch (error) {
+                    this.failOwned(admitted.map(({ handle }) => handle));
+                    throw error;
+                }
                 if (admission === null) {
                     this.failOwned(admitted.map(({ handle }) => handle));
                     return null;
                 }
+                if (this.disposed ||
+                    !(options.commandEntry?.isActive() ?? true) ||
+                    !(options.isRequestCurrent?.() ?? true) ||
+                    (options.deadlineAt !== undefined && Date.now() >= options.deadlineAt)) {
+                    this.failOwned(admitted.map(({ handle }) => handle));
+                    return null;
+                }
                 if (!admission.eligible) {
                     continue;
                 }
+                if (checks?.get(canonicalPropertyId)?.some((check) => !check())) {
+                    this.failOwned(admitted.map(({ handle }) => handle));
+                    throw new CompositeAdmissionSnapshotChangedError('Preserved power snapshot changed before admission');
+                }
                 const handle = this.commandWindowService.open({
                     canonicalTarget: admission.canonicalTarget,
                     requestedTargets: admission.requestedTargets,
                     intentId: options.intentId,
                     commandedValue: admission.commandedValue,
+                    requiresLiveEvidence: options.requiresLiveEvidence,
+                    proofKind: cover ? 'cover_action' : undefined,
+                    effectScope: admission.effectScope,
                     previousValue: admission.previousValue,
                     ttlMs: options.ttlMs ?? 3_000,
                 });
@@ -118,7 +785,7 @@ let PropertyCommandDispatchService = class PropertyCommandDispatchService {
             return admitted;
         });
     }
-    async createAdmission(canonicalPropertyId, requestedUpdates) {
+    async createAdmission(canonicalPropertyId, requestedUpdates, cover) {
         const first = requestedUpdates[0];
         if (first === undefined) {
             return null;
@@ -156,6 +823,14 @@ let PropertyCommandDispatchService = class PropertyCommandDispatchService {
         if (commandedValue === undefined) {
             return null;
         }
+        for (const requested of requestedUpdates)
+            await this.admissionGuards?.assertAllowed(requested);
+        await this.admissionGuards?.assertAllowed({
+            device: sourceDevice,
+            channel: sourceChannel,
+            property: sourceProperty,
+            value: commandedValue,
+        });
         const baseline = await this.propertyValues.readLatest(sourceProperty);
         sourceProperty.value = baseline;
         const requestedTargets = requestedUpdates.map(toTarget);
@@ -169,10 +844,13 @@ let PropertyCommandDispatchService = class PropertyCommandDispatchService {
             commandedValue,
             previousValue: baseline?.value ?? null,
             baseline: baseline === null ? null : new property_value_state_model_1.PropertyValueState(baseline.value, baseline.lastUpdated, baseline.trend),
-            eligible: writable && !authoritative,
+            eligible: (writable && !authoritative) || (0, cover_action_proof_1.validCoverAction)(cover, requestedUpdates),
+            effectScope: (0, cover_action_proof_1.isCoverControl)(first)
+                ? (this.platformRegistryService.get(sourceDevice)?.getCoverEffectScope?.(first) ?? sourceChannel.id)
+                : undefined,
         };
     }
-    async verifyPreopenedWindows(updates, handles) {
+    async verifyPreopenedWindows(updates, handles, cover) {
         return this.structureLock.runShared(async () => {
             const requestedByCanonical = new Map();
             for (const update of updates) {
@@ -193,7 +871,7 @@ let PropertyCommandDispatchService = class PropertyCommandDispatchService {
                 if (handle === undefined) {
                     return false;
                 }
-                const admission = await this.propertyStateCoordinator.run(canonicalPropertyId, async () => this.createAdmission(canonicalPropertyId, requestedUpdates));
+                const admission = await this.propertyStateCoordinator.run(canonicalPropertyId, async () => this.createAdmission(canonicalPropertyId, requestedUpdates, cover));
                 const window = this.commandWindowService.get(canonicalPropertyId);
                 if (admission === null || !admission.eligible || window === null || window.generation !== handle.generation) {
                     return false;
@@ -212,6 +890,9 @@ exports.PropertyCommandDispatchService = PropertyCommandDispatchService;
 exports.PropertyCommandDispatchService = PropertyCommandDispatchService = __decorate([
     (0, common_1.Injectable)(),
     __param(9, (0, common_1.Optional)()),
+    __param(10, (0, common_1.Optional)()),
+    __param(11, (0, common_1.Optional)()),
+    __param(12, (0, common_1.Optional)()),
     __metadata("design:paramtypes", [property_metadata_service_1.PropertyMetadataService,
         property_value_service_1.PropertyValueService,
         channels_service_1.ChannelsService,
@@ -221,8 +902,21 @@ exports.PropertyCommandDispatchService = PropertyCommandDispatchService = __deco
         device_structure_lock_service_1.DeviceStructureLockService,
         property_state_coordinator_service_1.PropertyStateCoordinatorService,
         property_command_window_service_1.PropertyCommandWindowService,
-        command_latency_trace_collector_service_1.CommandLatencyTraceCollectorService])
+        command_latency_trace_collector_service_1.CommandLatencyTraceCollectorService,
+        composite_property_command_registry_service_1.CompositePropertyCommandRegistryService,
+        event_emitter_1.EventEmitter2,
+        property_command_admission_registry_service_1.PropertyCommandAdmissionRegistryService])
 ], PropertyCommandDispatchService);
+const toEventChild = (child) => ({
+    member_id: child.memberId,
+    property_id: child.propertyId,
+    member_identity: child.memberIdentity,
+    property_identity: child.propertyIdentity,
+    status: child.status,
+    reason: child.reason,
+    value: child.value,
+    generation: child.generation,
+});
 const toTarget = ({ device, channel, property, }) => ({
     deviceId: device.id,
     channelId: channel.id,