@matter/node 0.16.0-alpha.0-20251027-17770fb28 → 0.16.0-alpha.0-20251030-e9ca79f93

package/src/behavior/state/managed/ManagedReference.ts

@@ -31,6 +31,7 @@ type Container = Record<string | number, Val>;
  * @param id the lookup ID in the case of structs
  * @param assertWriteOk enforces ACLs and read-only
  * @param clone clones the container prior to write; undefined if not transactional
+ * @param session the access control session
  *
  * @returns a reference to the property
  */
@@ -41,6 +42,7 @@ export function ManagedReference(
     id: number | undefined,
     assertWriteOk: (value: Val) => void,
     clone: (container: Val) => Val,
+    session: AccessControl.Session,
 ) {
     let expired = false;
     let location = {
@@ -51,10 +53,24 @@ export function ManagedReference(
     const key = primaryKey === "id" ? (id ?? name) : name;
     const altKey = primaryKey === "id" ? (key === name ? undefined : name) : id;
     let value: unknown;
-    if (key in (parent.value as Container)) {
-        value = (parent.value as Container)[key];
-    } else if (altKey !== undefined) {
-        value = (parent.value as Container)[altKey];
+
+    let dynamicContainer: Val.Struct | undefined;
+    if ((parent.value as Val.Dynamic)[Val.properties]) {
+        dynamicContainer = (parent.value as Val.Dynamic)[Val.properties](parent.rootOwner, session);
+        if (key in (dynamicContainer as Container)) {
+            value = (dynamicContainer as Container)[key];
+        } else if (altKey !== undefined && altKey in (dynamicContainer as Container)) {
+            value = (dynamicContainer as Container)[altKey];
+        } else {
+            dynamicContainer = undefined;
+        }
+    }
+    if (dynamicContainer === undefined) {
+        if (key in (parent.value as Container)) {
+            value = (parent.value as Container)[key];
+        } else if (altKey !== undefined) {
+            value = (parent.value as Container)[altKey];
+        }
     }
 
     const reference: Val.Reference = {
@@ -97,9 +113,16 @@ export function ManagedReference(
 
             // Now use change to complete the update
             this.change(() => {
-                (parent.value as Container)[key] = newValue;
-                if (altKey !== undefined && altKey in parent.value) {
-                    delete (parent.value as Container)[altKey];
+                if (dynamicContainer) {
+                    (dynamicContainer as Container)[key] = newValue;
+                    if (altKey !== undefined && altKey in dynamicContainer) {
+                        delete (dynamicContainer as Container)[altKey];
+                    }
+                } else {
+                    (parent.value as Container)[key] = newValue;
+                    if (altKey !== undefined && altKey in parent.value) {
+                        delete (parent.value as Container)[altKey];
+                    }
                 }
             });
         },
@@ -108,11 +131,21 @@ export function ManagedReference(
             if (!parent.original) {
                 return undefined;
             }
-            if (key in parent.original) {
-                return (parent.original as Container)[key];
-            }
-            if (altKey !== undefined) {
-                return (parent.original as Container)[altKey];
+            if (dynamicContainer !== undefined) {
+                const origProperties = (parent.original as Val.Dynamic)[Val.properties](parent.rootOwner, session);
+                if (key in (origProperties as Container)) {
+                    return (origProperties as Container)[key];
+                }
+                if (altKey !== undefined) {
+                    return (origProperties as Container)[altKey];
+                }
+            } else {
+                if (key in parent.original) {
+                    return (parent.original as Container)[key];
+                }
+                if (altKey !== undefined) {
+                    return (parent.original as Container)[altKey];
+                }
             }
         },
 
@@ -125,9 +158,16 @@ export function ManagedReference(
                 // In transactions, clone the value if we haven't done so yet
                 if (clone && value === this.original) {
                     const newValue = clone(value);
-                    (parent.value as Container)[key] = newValue;
-                    if (altKey !== undefined && altKey in (parent.value as Container)) {
-                        delete (parent.value as Container)[altKey];
+                    if (dynamicContainer !== undefined) {
+                        (dynamicContainer as Container)[key] = newValue;
+                        if (altKey !== undefined && altKey in dynamicContainer) {
+                            delete (dynamicContainer as Container)[altKey];
+                        }
+                    } else {
+                        (parent.value as Container)[key] = newValue;
+                        if (altKey !== undefined && altKey in (parent.value as Container)) {
+                            delete (parent.value as Container)[altKey];
+                        }
                     }
                     replaceValue(newValue);
                 }
@@ -149,10 +189,18 @@ export function ManagedReference(
             }
 
             let value;
-            if (key in parent.value) {
-                value = (parent.value as Container)[key];
-            } else if (altKey !== undefined && altKey in parent.value) {
-                value = (parent.value as Container)[altKey];
+            if (dynamicContainer !== undefined) {
+                if (key in dynamicContainer) {
+                    value = (dynamicContainer as Container)[key];
+                } else if (altKey !== undefined && altKey in dynamicContainer) {
+                    value = (dynamicContainer as Container)[altKey];
+                }
+            } else {
+                if (key in parent.value) {
+                    value = (parent.value as Container)[key];
+                } else if (altKey !== undefined && altKey in parent.value) {
+                    value = (parent.value as Container)[altKey];
+                }
             }
 
             replaceValue(value);

package/src/behavior/state/managed/values/ListManager.ts

@@ -160,6 +160,7 @@ function createProxy(config: ListConfig, reference: Val.Reference<Val.List>, ses
                     () => true,
 
                     val => (Array.isArray(val) ? [...(val as Val.List)] : isObject(val) ? { ...val } : val),
+                    session,
                 );
 
                 manageEntry(subref, session);

package/src/behavior/state/managed/values/StructManager.ts

@@ -279,7 +279,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
     };
 
     if (manage === PrimitiveManager) {
-        // For primitives we don't need a manager so just proxy reads directly
+        // For primitives, we don't need a manager so just proxy reads directly
         descriptor.get = function (this: Struct) {
             if (access.mayRead(this[Internal.session], this[Internal.reference].location)) {
                 const struct = this[Internal.reference].value as Val.Dynamic;
@@ -310,7 +310,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
             }
         };
     } else {
-        // For collections we create a managed value
+        // For collections, we create a managed value
         let cloneContainer: (container: Val) => Val;
         switch (schema.effectiveMetatype) {
             case Metatype.array:
@@ -373,6 +373,8 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                 return defaultReader?.(this);
             }
 
+            // Value is null or a dynamic property, so just return it
+            // TODO Consider to also use Management for dynamic properties
             if (value === null) {
                 return value;
             }
@@ -394,7 +396,15 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
             };
 
             // Clone the container before write
-            const ref = ManagedReference(this[Internal.reference], pk, name, id, assertWriteOk, cloneContainer);
+            const ref = ManagedReference(
+                this[Internal.reference],
+                pk,
+                name,
+                id,
+                assertWriteOk,
+                cloneContainer,
+                this[Internal.session],
+            );
 
             ref.owner = manage(ref, this[Internal.session]);
 

package/src/behaviors/access-control/AccessControlServer.ts

@@ -52,13 +52,9 @@ export class AccessControlServer extends AccessControlBehavior.with("Extension")
     override initialize(): MaybePromise {
         this.reactTo(this.events.acl$Changing, this.#validateAccessControlListChanges); // Enhanced Validation
         this.reactTo(this.events.acl$Changed, this.#handleAccessControlListChange); // Event handling for changes
-        if (
-            this.state.extension !== undefined &&
-            this.events.extension$Changing !== undefined &&
-            this.events.extension$Changed !== undefined
-        ) {
-            this.reactTo(this.events.extension$Changing, this.#validateAccessControlExtensionChanges); // Enhanced Validation
-            this.reactTo(this.events.extension$Changed, this.#handleAccessControlExtensionChange); // Event handling for changes
+        if (this.state.extension !== undefined) {
+            this.maybeReactTo(this.events.extension$Changing, this.#validateAccessControlExtensionChanges); // Enhanced Validation
+            this.maybeReactTo(this.events.extension$Changed, this.#handleAccessControlExtensionChange); // Event handling for changes
         }
 
         const lifecycle = this.endpoint.lifecycle as NodeLifecycle;

package/src/behaviors/general-diagnostics/GeneralDiagnosticsServer.ts

@@ -85,15 +85,11 @@ export class GeneralDiagnosticsServer extends Base {
         this.reactTo(lifecycle.online, this.#online, { lock: true });
         this.reactTo(lifecycle.goingOffline, this.#goingOffline, { lock: true });
 
-        if (this.events.activeHardwareFaults$Changed !== undefined) {
-            this.reactTo(this.events.activeHardwareFaults$Changed, this.#triggerActiveHardwareFaultsChangedEvent);
-        }
-        if (this.events.activeRadioFaults$Changed !== undefined) {
-            this.reactTo(this.events.activeRadioFaults$Changed, this.#triggerActiveRadioFaultsChangedEvent);
-        }
-        if (this.events.activeNetworkFaults$Changed !== undefined) {
-            this.reactTo(this.events.activeNetworkFaults$Changed, this.#triggerActiveNetworkFaultsChangedEvent);
-        }
+        this.maybeReactTo(this.events.activeHardwareFaults$Changed, this.#triggerActiveHardwareFaultsChangedEvent);
+
+        this.maybeReactTo(this.events.activeRadioFaults$Changed, this.#triggerActiveRadioFaultsChangedEvent);
+
+        this.maybeReactTo(this.events.activeNetworkFaults$Changed, this.#triggerActiveNetworkFaultsChangedEvent);
     }
 
     #validateTestEnabledKey(enableKey: Bytes) {

package/src/behaviors/service-area/ServiceAreaServer.ts

@@ -40,9 +40,9 @@ export class ServiceAreaBaseServer extends ServiceAreaBase {
         this.reactTo(this.events.supportedMaps$Changing, this.#assertSupportedMaps);
         this.#assertSelectedAreas(this.state.selectedAreas);
         this.reactTo(this.events.selectedAreas$Changing, this.#assertSelectedAreas);
-        if (this.state.currentArea !== undefined && this.events.currentArea$Changing !== undefined) {
+        if (this.state.currentArea !== undefined) {
             this.#assertCurrentArea(this.state.currentArea);
-            this.reactTo(this.events.currentArea$Changing, this.#assertCurrentArea);
+            this.maybeReactTo(this.events.currentArea$Changing, this.#assertCurrentArea);
         }
         if (this.state.progress !== undefined) {
             this.#assertProgress(this.state.progress);

package/src/behaviors/thermostat/AtomicWriteHandler.ts

@@ -0,0 +1,412 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ActionContext, Behavior, ClusterBehavior, type ClusterState, ValueSupervisor } from "#behavior/index.js";
+import { Thermostat } from "#clusters/thermostat";
+import { Endpoint } from "#endpoint/Endpoint.js";
+import { BasicSet, Environment, Environmental, InternalError, Logger, ObserverGroup, serialize } from "#general";
+import { ClusterModel, DataModelPath } from "#model";
+import {
+    AccessControl,
+    assertRemoteActor,
+    Fabric,
+    FabricManager,
+    hasRemoteActor,
+    PeerAddress,
+    Subject,
+    Val,
+} from "#protocol";
+import { AttributeId, NodeId, Status, StatusResponse, StatusResponseError } from "#types";
+import { AtomicWriteState } from "./AtomicWriteState.js";
+
+const logger = Logger.get("AtomicWriteHandler");
+
+/**
+ * Handles atomic write handling according to Matter definitions.
+ * The implementation tries to be generic, but is currently only used by the Thermostat cluster, so the atomic write
+ * types are imported from there.
+ *
+ * The logic requires that the cluster behavior implements the following additional events as "pure Observable()" events,
+ * because the current implementation logic requires error thrown by the event handlers to signal validation failures to
+ * be thrown back to te emitter. This is not the case for official state events.
+ * * `${attributeName}$AtomicChanging` - emitted when an attribute is changed as part of an atomic write, before the value
+ *   is actually changed. Receives the new value, the old value and the action context as parameters.
+ * * `${attributeName}$AtomicChanged` - emitted when an attribute is changed as part of an atomic write, after the value
+ *   is actually changed. Receives the new value, the old value and the action context as parameters.
+ *
+ * TODO: Move out of thermostat behavior into a more generic behavior handler once used by other clusters too. Then we
+ *  also need to adjust how it is handled.
+ *  Proper solution might be to add the handling of the atomic Request command on interaction level and leave the
+ *  transaction open until it is rolled back or committed. This might have side effects on other parts of the system though.
+ *  So lets do that later when we have more clusters using it.
+ */
+export class AtomicWriteHandler {
+    #observers = new ObserverGroup();
+    #pendingWrites = new BasicSet<AtomicWriteState>();
+
+    constructor(fabricManager: FabricManager) {
+        this.#observers.on(fabricManager.events.deleted, fabric => this.#handleFabricRemoval(fabric));
+    }
+
+    static [Environmental.create](env: Environment) {
+        const instance = new AtomicWriteHandler(env.get(FabricManager));
+        env.set(AtomicWriteHandler, instance);
+        return instance;
+    }
+
+    close() {
+        this.#observers.close();
+        for (const writeState of Array.from(this.#pendingWrites)) {
+            writeState.close();
+        }
+    }
+
+    /**
+     * Initializes an AtomicWrite state for the given request, context, endpoint and cluster.
+     * It also implements all relevant validation according to the Matter spec.
+     */
+    #initializeState<B extends Behavior.Type>(
+        { requestType, attributeRequests, timeout }: Thermostat.AtomicRequest,
+        context: ActionContext,
+        endpoint: Endpoint,
+        cluster: B,
+    ) {
+        if (!ClusterBehavior.is(cluster) || !cluster.schema) {
+            throw new InternalError("Cluster behavior expected for atomic write handler");
+        }
+
+        // Ensure we have a valid peer and so also associated fabric
+        const peerAddress = this.#assertValidPeer(context);
+
+        // Validate AttributeRequests
+        if (attributeRequests.length === 0) {
+            throw new StatusResponse.InvalidCommandError("No attribute requests provided");
+        }
+        const attributes = new Map<AttributeId, string>();
+        for (const attr of attributeRequests) {
+            const [attributeName, _] =
+                Object.entries((cluster as ClusterBehavior.Type).cluster.attributes).find(
+                    ([_, { id }]) => id === attr,
+                ) ?? [];
+            if (attributeName === undefined || endpoint.stateOf(cluster.id)[attr] === undefined) {
+                throw new StatusResponse.InvalidCommandError(`Attribute ${attr} not supported by cluster`);
+            }
+            if (attributes.has(attr)) {
+                throw new StatusResponse.InvalidCommandError("Duplicate attribute in attribute requests");
+            }
+            attributes.set(attr, attributeName);
+        }
+
+        const existingState = this.#pendingWrites.find(
+            s =>
+                PeerAddress.is(s.peerAddress, peerAddress) &&
+                s.endpoint.number == endpoint.number &&
+                s.clusterId === (cluster as ClusterBehavior.Type).cluster.id,
+        );
+
+        if (requestType === Thermostat.RequestType.BeginWrite) {
+            if (timeout === undefined) {
+                throw new StatusResponse.InvalidCommandError("Timeout missing for BeginWrite request");
+            }
+
+            if (
+                existingState !== undefined &&
+                existingState.attributeRequests.some(attr => attributeRequests.includes(attr))
+            ) {
+                throw new StatusResponse.InvalidCommandError(
+                    "An atomic write for at least one of the attributes is already in progress for this peer",
+                );
+            }
+
+            const initialValues: Val.Struct = {};
+            for (const attr of attributeRequests) {
+                initialValues[attr] = endpoint.stateOf(cluster.id)[attr];
+            }
+
+            const state = new AtomicWriteState(
+                peerAddress,
+                endpoint,
+                cluster.cluster.id,
+                attributeRequests,
+                timeout,
+                attributes,
+                initialValues,
+            );
+            this.#pendingWrites.add(state);
+            state.closed.on(() => void this.#pendingWrites.delete(state));
+            logger.debug("Added atomic write state:", state);
+            return state;
+        }
+        if (existingState === undefined) {
+            throw new StatusResponse.InvalidInStateError("No atomic write in progress for this peer");
+        }
+        if (
+            existingState.attributeRequests.length !== attributeRequests.length ||
+            !existingState.attributeRequests.every(attr => attributeRequests.includes(attr))
+        ) {
+            throw new StatusResponse.InvalidInStateError("Attribute requests do not match existing atomic write");
+        }
+        return existingState;
+    }
+
+    /**
+     * Implements the begin write logic for an atomic write.
+     */
+    beginWrite(
+        request: Thermostat.AtomicRequest,
+        context: ActionContext,
+        endpoint: Endpoint,
+        cluster: Behavior.Type,
+    ): Thermostat.AtomicResponse {
+        if (!hasRemoteActor(context)) {
+            throw new StatusResponse.InvalidCommandError("AtomicRequest requires a remote actor");
+        }
+        if (!ClusterBehavior.is(cluster) || !cluster.schema) {
+            throw new InternalError("Cluster behavior expected for atomic write handler");
+        }
+        let commandStatusCode = Status.Success;
+        const attributeStatus = request.attributeRequests.map(attr => {
+            let statusCode = Status.Success;
+            const attributeModel = (cluster.schema!.conformant as ClusterModel.Conformant).attributes.for(attr);
+            if (!attributeModel?.quality.atomic) {
+                statusCode = Status.InvalidAction;
+            } else if (this.#pendingWriteStateForAttribute(endpoint, cluster, attr) !== undefined) {
+                statusCode = Status.Busy;
+            } else {
+                const { writeLevel } = cluster.supervisor.get(attributeModel).access.limits;
+                const location = {
+                    path: DataModelPath.none,
+                    endpoint: endpoint.number,
+                    cluster: cluster.cluster.id,
+                    owningFabric: context.fabric,
+                };
+                if (context.authorityAt(writeLevel, location) !== AccessControl.Authority.Granted) {
+                    statusCode = Status.UnsupportedAccess;
+                }
+            }
+
+            if (statusCode !== Status.Success) {
+                commandStatusCode = Status.Failure;
+            }
+            return {
+                attributeId: attr,
+                statusCode,
+            };
+        });
+
+        let timeout;
+        if (commandStatusCode === Status.Success) {
+            const state = this.#initializeState(request, context, endpoint, cluster);
+            timeout = state.timeout;
+        }
+
+        return {
+            statusCode: commandStatusCode,
+            attributeStatus,
+            timeout,
+        };
+    }
+
+    /**
+     * Handles writing a value for an attribute as part of an ongoing atomic write.
+     * It uses the *$AtomicChanging* event to trigger validation of the partial write.
+     */
+    writeAttribute(
+        context: ValueSupervisor.Session,
+        endpoint: Endpoint,
+        cluster: Behavior.Type,
+        attribute: AttributeId,
+        value: unknown,
+    ) {
+        const state = this.#assertPendingWriteForAttributeAndPeer(context, endpoint, cluster, attribute);
+        const attributeName = state.attributeNames.get(attribute)!;
+        logger.debug(`Writing pending value for attribute ${attributeName}, ${attribute} in atomic write`, value);
+        // TODO currently we only handle this one changing, so checking other state within the event potentially use
+        //  older values. We need to tweak the state for a complete solution. But ok for now!
+        endpoint
+            .eventsOf(cluster.id)
+            [
+                `${attributeName}$AtomicChanging`
+            ]?.emit(value, state.pendingAttributeValues[attribute] !== undefined ? state.pendingAttributeValues[attribute] : state.initialValues[attribute], context);
+        state.pendingAttributeValues[attribute] = value;
+        logger.debug("Atomic write state after current write:", state);
+    }
+
+    /**
+     * Implements the commit logic for an atomic write.
+     */
+    async commitWrite<B extends Behavior.Type>(
+        request: Thermostat.AtomicRequest,
+        context: ActionContext,
+        endpoint: Endpoint,
+        cluster: B,
+        clusterState: ClusterState.Type<any, B>,
+    ): Promise<Thermostat.AtomicResponse> {
+        const state = this.#initializeState(request, context, endpoint, cluster);
+
+        let commandStatusCode = Status.Success;
+        const attributeStatus = [];
+        for (const [attr, value] of Object.entries(state.pendingAttributeValues)) {
+            let statusCode = Status.Success;
+            try {
+                const attributeName = state.attributeNames.get(AttributeId(Number(attr)))!;
+                endpoint
+                    .eventsOf(cluster.id)
+                    [`${attributeName}$AtomicChanging`]?.emit(value, endpoint.stateOf(cluster.id)[attr], context);
+                endpoint
+                    .eventsOf(cluster.id)
+                    [`${attributeName}$AtomicChanged`]?.emit(value, endpoint.stateOf(cluster.id)[attr], context);
+                (clusterState as any)[attr] = value;
+                await context.transaction?.commit();
+            } catch (error) {
+                await context.transaction?.rollback();
+                logger.info(`Failed to write attribute ${attr} during atomic write commit: ${error}`);
+                statusCode = error instanceof StatusResponseError ? error.code : Status.Failure;
+                // If one fails with ConstraintError, the whole command should return ConstraintError, otherwise Failure
+                commandStatusCode =
+                    commandStatusCode === Status.Failure
+                        ? Status.Failure
+                        : commandStatusCode === Status.ConstraintError
+                          ? Status.ConstraintError
+                          : Status.Failure;
+            }
+            attributeStatus.push({
+                attributeId: AttributeId(Number(attr)),
+                statusCode,
+            });
+        }
+        state.close(); // Irrelevant of the outcome the state is closed
+        return {
+            statusCode: commandStatusCode,
+            attributeStatus,
+        };
+    }
+
+    /**
+     * Implements the rollback logic for an atomic write.
+     */
+    rollbackWrite(
+        request: Thermostat.AtomicRequest,
+        context: ActionContext,
+        endpoint: Endpoint,
+        cluster: Behavior.Type,
+    ): Thermostat.AtomicResponse {
+        const state = this.#initializeState(request, context, endpoint, cluster);
+        state.close();
+        return {
+            statusCode: Status.Success,
+            attributeStatus: state.attributeRequests.map(attr => ({
+                attributeId: attr,
+                statusCode: Status.Success,
+            })),
+        };
+    }
+
+    /**
+     * Handles fabric removal by closing all pending atomic write states for peers on the removed fabric.
+     */
+    #handleFabricRemoval(fabric: Fabric) {
+        const fabricIndex = fabric.fabricIndex;
+        for (const writeState of Array.from(this.#pendingWrites)) {
+            if (writeState.peerAddress.fabricIndex === fabricIndex) {
+                logger.debug(
+                    `Closing atomic write state for peer ${writeState.peerAddress.toString()} on endpoint ${writeState.endpoint.id} due to fabric removal`,
+                );
+                writeState.close();
+            }
+        }
+    }
+
+    /**
+     * Returns the pending write state for the given attribute, if any.
+     */
+    #pendingWriteStateForAttribute(endpoint: Endpoint, cluster: Behavior.Type, attribute: AttributeId) {
+        const writeStates = this.#pendingWrites.filter(
+            s => s.endpoint.number == endpoint.number && s.clusterId === (cluster as ClusterBehavior.Type).cluster.id,
+        );
+        if (writeStates.length === 0) {
+            return undefined;
+        }
+        const attrWriteStates = writeStates.filter(({ attributeRequests }) => attributeRequests.includes(attribute));
+        if (attrWriteStates.length === 0) {
+            return undefined;
+        }
+        if (attrWriteStates.length > 1) {
+            throw new InternalError("Multiple atomic write states found for the same attribute. Should never happen");
+        }
+        return attrWriteStates[0];
+    }
+
+    /**
+     * Returns the pending value for the given attribute and peer, if any.
+     */
+    pendingValueForAttributeAndPeer(
+        context: ValueSupervisor.Session,
+        endpoint: Endpoint,
+        cluster: Behavior.Type,
+        attribute: AttributeId,
+    ) {
+        const peerAddress = this.#derivePeerAddress(context);
+        if (peerAddress === undefined) {
+            // No valid peer address could be derived from the session
+            return undefined;
+        }
+        const attrWriteState = this.#pendingWriteStateForAttribute(endpoint, cluster, attribute);
+        if (attrWriteState === undefined) {
+            // No pending write for this attribute
+            return undefined;
+        }
+        if (!PeerAddress.is(attrWriteState.peerAddress, peerAddress)) {
+            // Pending state s for an other peer
+            return undefined;
+        }
+        logger.debug(
+            `Found pending value for attribute ${attribute} for peer ${peerAddress.nodeId}`,
+            serialize(attrWriteState.pendingAttributeValues[attribute]),
+        );
+        return attrWriteState.pendingAttributeValues[attribute];
+    }
+
+    #assertPendingWriteForAttributeAndPeer(
+        session: ValueSupervisor.Session,
+        endpoint: Endpoint,
+        cluster: Behavior.Type,
+        attribute: AttributeId,
+    ) {
+        const attrWriteState = this.#pendingWriteStateForAttribute(endpoint, cluster, attribute);
+        if (attrWriteState === undefined) {
+            throw new StatusResponse.InvalidInStateError("There is no atomic write in progress for this attribute");
+        }
+        const peerAddress = this.#derivePeerAddress(session);
+        if (peerAddress === undefined) {
+            throw new StatusResponse.InvalidInStateError("There is no atomic write in progress for this peer");
+        }
+        if (!PeerAddress.is(attrWriteState.peerAddress, peerAddress)) {
+            throw new StatusResponse.BusyError("Attribute is part of an atomic write in progress for a different peer");
+        }
+        return attrWriteState;
+    }
+
+    #derivePeerAddress(session: ValueSupervisor.Session) {
+        if (
+            hasRemoteActor(session) &&
+            Subject.isNode(session.subject) &&
+            NodeId.isOperationalNodeId(session.subject.id)
+        ) {
+            return PeerAddress({ fabricIndex: session.fabric, nodeId: NodeId(session.subject.id) });
+        }
+    }
+
+    #assertValidPeer(context: ActionContext) {
+        assertRemoteActor(context); // Also validate that we have a remote actor for processing the command
+
+        const peerAddress = this.#derivePeerAddress(context);
+        if (!context.session.associatedFabric || peerAddress === undefined) {
+            throw new StatusResponse.InvalidCommandError("AtomicRequest requires an operational session");
+        }
+        return peerAddress;
+    }
+}