@matter/node 0.16.0-alpha.0-20251018-dd1ea6a8a → 0.16.0-alpha.0-20251020-3f6e46245

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter/node",
-    "version": "0.16.0-alpha.0-20251018-dd1ea6a8a",
+    "version": "0.16.0-alpha.0-20251020-3f6e46245",
     "description": "API for building Matter nodes",
     "keywords": [
         "iot",
@@ -42,14 +42,14 @@
         "#*": "./src/*"
     },
     "dependencies": {
-        "@matter/general": "0.16.0-alpha.0-20251018-dd1ea6a8a",
-        "@matter/model": "0.16.0-alpha.0-20251018-dd1ea6a8a",
-        "@matter/types": "0.16.0-alpha.0-20251018-dd1ea6a8a",
-        "@matter/protocol": "0.16.0-alpha.0-20251018-dd1ea6a8a"
+        "@matter/general": "0.16.0-alpha.0-20251020-3f6e46245",
+        "@matter/model": "0.16.0-alpha.0-20251020-3f6e46245",
+        "@matter/types": "0.16.0-alpha.0-20251020-3f6e46245",
+        "@matter/protocol": "0.16.0-alpha.0-20251020-3f6e46245"
     },
     "devDependencies": {
-        "@matter/tools": "0.16.0-alpha.0-20251018-dd1ea6a8a",
-        "@matter/testing": "0.16.0-alpha.0-20251018-dd1ea6a8a"
+        "@matter/tools": "0.16.0-alpha.0-20251020-3f6e46245",
+        "@matter/testing": "0.16.0-alpha.0-20251020-3f6e46245"
     },
     "files": [
         "dist/**/*",

package/src/behavior/Behavior.ts

@@ -14,12 +14,11 @@ import {
     Observable,
     Transaction,
 } from "#general";
-import { Schema } from "#model";
+import { ClassSemantics, Schema, Semantics } from "#model";
 import type { ClusterType } from "#types";
 import { Reactor } from "./Reactor.js";
 import type { BehaviorBacking } from "./internal/BehaviorBacking.js";
 import { DerivedState, EmptyState } from "./state/StateType.js";
-import { BehaviorSupervisor } from "./supervision/BehaviorSupervisor.js";
 import { RootSupervisor } from "./supervision/RootSupervisor.js";
 
 // Internal fields
@@ -68,7 +67,9 @@ export abstract class Behavior {
      * Schema is inferred from the methods and properties of the behavior but you can specify explicitly for additional
      * control.
      */
-    static readonly schema?: Schema;
+    static get schema() {
+        return Schema(this);
+    }
 
     /**
      * By default behaviors load lazily as they are accessed.  You can set this flag to true to force behaviors to load
@@ -139,7 +140,7 @@ export abstract class Behavior {
         if (Object.hasOwn(this, SUPERVISOR)) {
             return (this as StaticInternal)[SUPERVISOR] as RootSupervisor;
         }
-        return ((this as StaticInternal)[SUPERVISOR] = BehaviorSupervisor(this));
+        return ((this as StaticInternal)[SUPERVISOR] = RootSupervisor.for(Schema(this) ?? Schema.empty));
     }
 
     /**
@@ -310,6 +311,43 @@ Object.defineProperties(Behavior.prototype, {
     },
 });
 
+/**
+ * Install {@link ClassSemantics} extension logic to integrate schema metadata.
+ */
+Object.defineProperties(Behavior, {
+    [ClassSemantics.extend]: {
+        value(this: Behavior.Type, decoration: ClassSemantics) {
+            const type = decoration.new as Behavior.Type;
+
+            // Support static override of schema
+            if (Object.hasOwn(type, "schema") && type.schema !== undefined) {
+                decoration.mutableModel = type.schema;
+            }
+
+            // Obtain state and base schema
+            const { State, Events, defaults } = type;
+            if (!State || !defaults) {
+                return;
+            }
+
+            // Merge state properties into my schema
+            if (ClassSemantics.hasOwnSemantics(State)) {
+                const stateSemantics = Semantics.classOf(State);
+                stateSemantics.mutableModel = decoration.mutableModel;
+            }
+
+            // Merge events into my schema
+            if (ClassSemantics.hasOwnSemantics(Events)) {
+                const eventSemantics = Semantics.classOf(Events);
+                eventSemantics.mutableModel = decoration.mutableModel;
+            }
+
+            // Augment with fields for untyped state members
+            decoration.defineUnknownMembers(defaults);
+        },
+    },
+});
+
 export namespace Behavior {
     /**
      * Static properties supported by all behaviors.

package/src/behavior/cluster/ClusterBehavior.ts

@@ -7,7 +7,7 @@
 import { Events } from "#behavior/Events.js";
 import type { Agent } from "#endpoint/Agent.js";
 import { ImplementationError, MaybePromise } from "#general";
-import type { Schema } from "#model";
+import { type Schema } from "#model";
 import { ClusterComposer, ClusterType, ElementModifier, TypeFromBitSchema } from "#types";
 import { Behavior } from "../Behavior.js";
 import type { BehaviorBacking } from "../internal/BehaviorBacking.js";

package/src/behavior/cluster/ClusterBehaviorUtil.ts

@@ -7,6 +7,7 @@
 import { Events, OfflineEvent, OnlineEvent, QuietEvent } from "#behavior/Events.js";
 import { camelize, EventEmitter, GeneratedClass, ImplementationError, Observable } from "#general";
 import {
+    ClassSemantics,
     ClusterModel,
     DefaultValue,
     ElementTag,
@@ -81,9 +82,6 @@ export function createType<const C extends ClusterType>(
         }
     }
 
-    // Mutation of schema will almost certainly result in logic errors so ensure that can't happen
-    schema.freeze();
-
     const newProps = {} as Record<string, ValueModel>;
     const scope = Scope(schema);
 
@@ -110,15 +108,17 @@ export function createType<const C extends ClusterType>(
                 value: cluster,
                 enumerable: true,
             },
-
-            schema: {
-                value: schema,
-            },
         },
 
         instanceDescriptors: createDefaultCommandDescriptors(cluster, base),
     }) as ClusterBehavior.Type;
 
+    // Decorate the class
+    ClassSemantics.of(type).mutableModel = schema;
+
+    // Mutation of schema will almost certainly result in logic errors so ensure that can't happen
+    schema.finalize();
+
     if (useCache) {
         ClusterBehaviorCache.set(cluster, base, schema, type);
     }

package/src/behavior/supervision/RootSupervisor.ts

@@ -8,6 +8,7 @@ import { camelize, InternalError } from "#general";
 import {
     AttributeModel,
     ClusterModel,
+    ElementTag,
     FeatureMap,
     FeatureSet,
     Matter,
@@ -160,8 +161,9 @@ export class RootSupervisor implements ValueSupervisor {
             // TODO: We should handle writable/fabric scoped being non-volatile already in the conformance interpreter
             if (
                 member.effectiveQuality.nonvolatile ||
-                member.effectiveAccess.writable ||
-                member.effectiveAccess.fabricScoped
+                // Persist all writable attributes in addition to those officially marked as nonvolatile
+                (member.tag === ElementTag.Attribute &&
+                    (member.effectiveAccess.writable || member.effectiveAccess.fabricScoped))
             ) {
                 if (key === "id") {
                     const id = member.effectiveId;

package/src/behavior/system/commissioning/CommissioningClient.ts

@@ -19,7 +19,22 @@ import {
     Time,
     Timestamp,
 } from "#general";
-import { DatatypeModel, FieldElement } from "#model";
+import {
+    bool,
+    duration,
+    fabricIdx,
+    field,
+    listOf,
+    mandatory,
+    nodeId,
+    nonvolatile,
+    string,
+    systimeMs,
+    uint16,
+    uint32,
+    uint8,
+    vendorId,
+} from "#model";
 import type { ClientNode } from "#node/ClientNode.js";
 import type { Node } from "#node/Node.js";
 import { IdentityService } from "#node/server/IdentityService.js";
@@ -32,14 +47,15 @@ import {
     FabricAuthority,
     FabricManager,
     LocatedNodeCommissioningOptions,
-    PeerAddress,
-    SessionParameters,
+    PeerAddress as ProtocolPeerAddress,
+    SessionIntervals as ProtocolSessionIntervals,
     Subscribe,
 } from "#protocol";
 import {
     CaseAuthenticatedTag,
     DeviceTypeId,
     DiscoveryCapabilitiesBitmap,
+    FabricIndex,
     ManualPairingCodeCodec,
     NodeId,
     TypeFromPartialBitSchema,
@@ -194,7 +210,7 @@ export class CommissioningClient extends Behavior {
             throw new ImplementationError("Cannot decommission node that is not commissioned");
         }
 
-        const formerAddress = PeerAddress(peerAddress).toString();
+        const formerAddress = ProtocolPeerAddress(peerAddress).toString();
 
         const opcreds = this.agent.get(OperationalCredentialsClient);
 
@@ -218,7 +234,7 @@ export class CommissioningClient extends Behavior {
      * If you override, matter.js commissions to the point where commissioning over PASE is complete.  You must then
      * complete commissioning yourself by connecting to the device and invokeint the "CommissioningComplete" command.
      */
-    protected async finalizeCommissioning(_address: PeerAddress, _discoveryData?: DiscoveryData) {
+    protected async finalizeCommissioning(_address: ProtocolPeerAddress, _discoveryData?: DiscoveryData) {
         throw new NotImplementedError();
     }
 
@@ -235,7 +251,7 @@ export class CommissioningClient extends Behavior {
         endpoint.lifecycle.initialized.emit(this.state.peerAddress !== undefined);
     }
 
-    #peerAddressChanged(addr?: PeerAddress) {
+    #peerAddressChanged(addr?: ProtocolPeerAddress) {
         const node = this.endpoint as ClientNode;
 
         if (addr) {
@@ -258,174 +274,198 @@ export class CommissioningClient extends Behavior {
             node.lifecycle.decommissioned.emit(this.context);
         }
     }
+}
 
+export namespace CommissioningClient {
     /**
-     * Define logical schema.  This enables runtime validation, make fields persistent and makes subfields editable.
+     * Concrete version of {@link ProtocolPeerAddress}.
      */
-    static override readonly schema = new DatatypeModel(
-        {
-            name: "CommissioningState",
-            type: "struct",
-        },
-
-        FieldElement({
-            name: "peerAddress",
-            type: "struct",
-            quality: "N",
-            children: [
-                FieldElement({ name: "fabricIndex", type: "fabric-id" }),
-                FieldElement({ name: "nodeId", type: "node-id" }),
-            ],
-        }),
-
-        FieldElement({
-            name: "addresses",
-            type: "list",
-            quality: "N",
-            children: [
-                FieldElement({
-                    name: "entry",
-                    type: "struct",
-                    children: [
-                        FieldElement({ name: "type", type: "string" }),
-                        FieldElement({ name: "ip", type: "string" }),
-                        FieldElement({ name: "port", type: "uint16" }),
-                        FieldElement({ name: "peripheralAddress", type: "string" }),
-                    ],
-                }),
-            ],
-        }),
-
-        FieldElement({ name: "discoveredAt", type: "systime-ms", quality: "N", conformance: "M" }),
-        FieldElement({ name: "onlineAt", type: "systime-ms" }),
-        FieldElement({ name: "offlineAt", type: "systime-ms" }),
-        FieldElement({ name: "ttl", type: "uint32", quality: "N" }),
-        FieldElement({ name: "deviceIdentifier", type: "string", quality: "N" }),
-        FieldElement({ name: "discriminator", type: "uint16", quality: "N" }),
-        FieldElement({ name: "commissioningMode", type: "uint8", quality: "N" }),
-        FieldElement({ name: "vendorId", type: "vendor-id", quality: "N" }),
-        FieldElement({ name: "productId", type: "uint16", quality: "N" }),
-        FieldElement({ name: "deviceType", type: "uint16", quality: "N" }),
-        FieldElement({ name: "deviceName", type: "string", quality: "N" }),
-        FieldElement({ name: "rotatingIdentifier", type: "string", quality: "N" }),
-        FieldElement({ name: "pairingHint", type: "uint32", quality: "N" }),
-        FieldElement({ name: "pairingInstructions", type: "string", quality: "N" }),
-        FieldElement({
-            name: "sessionParameters",
-            type: "struct",
-            quality: "N",
-            children: [
-                FieldElement({ name: "idleInterval", type: "duration", constraint: "max 3600000" }),
-                FieldElement({ name: "activeInterval", type: "duration", constraint: "max 3600000" }),
-                FieldElement({ name: "activeThreshold", type: "duration", constraint: "max 65535" }),
-            ],
-        }),
-        FieldElement({ name: "tcpSupport", type: "uint8", quality: "N" }),
-        FieldElement({ name: "longIdleOperatingMode", type: "bool", quality: "N" }),
-    );
-}
+    export class PeerAddress implements ProtocolPeerAddress {
+        @field(fabricIdx, mandatory)
+        fabricIndex: FabricIndex;
+
+        @field(nodeId, mandatory)
+        nodeId: NodeId;
+
+        constructor(fabricIndex: FabricIndex, nodeId: NodeId) {
+            this.fabricIndex = fabricIndex;
+            this.nodeId = nodeId;
+        }
+    }
+
+    /**
+     * Concrete version of {@link SessionIntervals}.
+     */
+    export class SessionIntervals implements ProtocolSessionIntervals {
+        @field(duration.extend({ constraint: "max 3600000" }), mandatory)
+        idleInterval: Duration;
+
+        @field(duration.extend({ constraint: "max 3600000" }), mandatory)
+        activeInterval: Duration;
+
+        @field(duration.extend({ constraint: "max 65535" }), mandatory)
+        activeThreshold: Duration;
+
+        constructor(intervals: SessionIntervals) {
+            this.idleInterval = intervals.idleInterval;
+            this.activeInterval = intervals.activeInterval;
+            this.activeThreshold = intervals.activeThreshold;
+        }
+    }
+
+    /**
+     * The network address of a node.
+     */
+    export class NetworkAddress implements ServerAddress.Definition {
+        @field(string, mandatory)
+        type: "udp" | "tcp" | "ble";
+
+        @field(string)
+        ip?: string;
+
+        @field(uint16)
+        port?: number;
+
+        @field(string)
+        peripheralAddress?: string;
+
+        @field(uint32)
+        ttl?: Duration | undefined;
+
+        @field(systimeMs)
+        discoveredAt?: Timestamp | undefined;
+
+        constructor(address: NetworkAddress) {
+            this.type = address.type;
+            this.ip = address.ip;
+            this.port = address.port;
+            this.peripheralAddress = address.peripheralAddress;
+            this.ttl = address.ttl;
+            this.discoveredAt = address.discoveredAt;
+        }
+    }
 
-export namespace CommissioningClient {
     export class State {
         /**
          * Fabric index and node ID for paired peers.  If this is undefined the node is uncommissioned.
          */
+        @field(PeerAddress, nonvolatile)
         peerAddress?: PeerAddress;
 
         /**
          * Known network addresses for the device.  If this is undefined the node has not been located on any network
          * interface.
          */
+        @field(listOf(NetworkAddress), nonvolatile)
         addresses?: ServerAddress.Definition[];
 
         /**
          * Time at which the device was discovered.
          */
+        @field(systimeMs, nonvolatile)
         discoveredAt?: Timestamp;
 
         /**
          * Time at which we discovered the device's current operational addresses.
          */
+        @field(systimeMs)
         onlineAt?: Timestamp;
 
         /**
          * Time at which we concluded the device's current operational address is unreachable.
          */
+        @field(systimeMs)
         offlineAt?: Timestamp;
 
         /**
          * The TTL of the discovery record if applicable (in seconds).
          */
+        @field(duration, nonvolatile)
         ttl?: Duration;
 
         /**
          * The canonical global ID of the device.
          */
+        @field(string, nonvolatile)
         deviceIdentifier?: string;
 
         /**
          * The device's long discriminator.
          */
+        @field(uint16, nonvolatile)
         discriminator?: number;
 
         /**
          * The last know commissioning mode of the device.
          */
+        @field(uint8, nonvolatile)
         commissioningMode?: CommissioningMode;
 
         /**
          * Vendor.
          */
+        @field(vendorId, nonvolatile)
         vendorId?: VendorId;
 
         /**
          * Product.
          */
+        @field(uint16, nonvolatile)
         productId?: number;
 
         /**
          * Advertised device type.
          */
+        @field(uint16, nonvolatile)
         deviceType?: DeviceTypeId;
 
         /**
          * The advertised device name specified by the user.
          */
+        @field(string, nonvolatile)
         deviceName?: string;
 
         /**
          * An optional manufacturer-specific unique rotating ID for uniquely identifying the device.
          */
+        @field(string, nonvolatile)
         rotatingIdentifier?: string;
 
         /**
          * A bitmap indicating how to transition the device to commissioning mode from its current state.
          */
+        @field(uint32, nonvolatile)
         pairingHint?: number;
 
         /**
          * Textual pairing instructions associated with pairing hint.
          */
+        @field(string, nonvolatile)
         pairingInstructions?: string;
 
         /**
-         * The remote node's session parameters.
+         * The remote node's session intervals.
          */
-        sessionParameters?: Partial<SessionParameters>;
+        @field(SessionIntervals, nonvolatile)
+        sessionIntervals?: Partial<ProtocolSessionIntervals>;
 
         /**
          * TCP support bitmap.
          */
+        @field(uint8, nonvolatile)
         tcpSupport?: number;
 
         /**
          * Indicates whether node is ICD with a slow (15 s+) polling interval.
          */
+        @field(bool, nonvolatile)
         longIdleTimeOperatingMode?: boolean;
     }
 
     export class Events extends BaseEvents {
-        peerAddress$Changed = new Observable<[value: PeerAddress | undefined, oldValue: PeerAddress | undefined]>();
+        peerAddress$Changed = new Observable<
+            [value: ProtocolPeerAddress | undefined, oldValue: ProtocolPeerAddress | undefined]
+        >();
     }
 
     /**

package/src/behavior/system/commissioning/CommissioningServer.ts

@@ -296,35 +296,6 @@ export class CommissioningServer extends Behavior {
         );
     }
 
-    /**
-     * Obtain pairing codes for a node.
-     */
-    static pairingCodesFor(node: Endpoint) {
-        const bi = node.stateOf(BasicInformationBehavior);
-        const comm = node.stateOf(CommissioningServer);
-        const net = node.stateOf(NetworkServer);
-
-        const qrPairingCode = QrPairingCodeCodec.encode([
-            {
-                version: 0,
-                vendorId: bi.vendorId,
-                productId: bi.productId,
-                flowType: comm.flowType,
-                discriminator: comm.discriminator,
-                passcode: comm.passcode,
-                discoveryCapabilities: DiscoveryCapabilitiesSchema.encode(net.discoveryCapabilities),
-            },
-        ]);
-
-        return {
-            manualPairingCode: ManualPairingCodeCodec.encode({
-                discriminator: comm.discriminator,
-                passcode: comm.passcode,
-            }),
-            qrPairingCode,
-        };
-    }
-
     /**
      * Define logical schema to make passcode and discriminator persistent.
      */
@@ -384,9 +355,33 @@ export namespace CommissioningServer {
         ble?: BleAdvertiser.Options;
 
         [Val.properties](endpoint: Endpoint) {
+            const comm = this;
             return {
                 get pairingCodes() {
-                    return CommissioningServer.pairingCodesFor(endpoint);
+                    const bi = endpoint.stateOf(BasicInformationBehavior);
+                    const net = endpoint.stateOf(NetworkServer);
+
+                    const qrPairingCode = QrPairingCodeCodec.encode([
+                        {
+                            version: 0,
+                            vendorId: bi.vendorId,
+                            productId: bi.productId,
+                            flowType: comm.flowType,
+                            discriminator: comm.discriminator,
+                            passcode: comm.passcode,
+                            discoveryCapabilities: DiscoveryCapabilitiesSchema.encode(net.discoveryCapabilities),
+                        },
+                    ]);
+
+                    return {
+                        manualPairingCode: ManualPairingCodeCodec.encode({
+                            // We use -1 to flag "need generated value" but this will crash the pairing code generator.  So use 0
+                            // so we don't throw an error during initialization
+                            discriminator: comm.discriminator < 0 ? 0 : comm.discriminator,
+                            passcode: comm.passcode < 0 ? 0 : comm.passcode,
+                        }),
+                        qrPairingCode,
+                    };
                 },
 
                 get fabrics() {

package/src/behavior/system/commissioning/RemoteDescriptor.ts

@@ -57,7 +57,7 @@ export namespace RemoteDescriptor {
             rotatingIdentifier,
             pairingHint,
             pairingInstructions,
-            sessionParameters,
+            sessionIntervals,
             tcpSupport,
             longIdleTimeOperatingMode,
         } = long;
@@ -102,8 +102,8 @@ export namespace RemoteDescriptor {
             result.PI = pairingInstructions;
         }
 
-        if (sessionParameters !== undefined) {
-            const { idleInterval, activeInterval, activeThreshold } = sessionParameters;
+        if (sessionIntervals !== undefined) {
+            const { idleInterval, activeInterval, activeThreshold } = sessionIntervals;
 
             if (idleInterval !== undefined) {
                 result.SII = idleInterval;
@@ -189,7 +189,7 @@ export namespace RemoteDescriptor {
         if (SAT !== undefined) {
             (sessionParameters ??= {}).activeThreshold = SAT;
         }
-        long.sessionParameters = sessionParameters;
+        long.sessionIntervals = sessionParameters;
 
         long.deviceType = DT === undefined ? undefined : DeviceTypeId(DT);
         long.deviceName = DN;

package/src/behavior/system/network/NetworkClient.ts

@@ -20,8 +20,14 @@ export class NetworkClient extends NetworkBehavior {
     declare events: NetworkClient.Events;
 
     override initialize() {
-        this.reactTo(this.events.autoSubscribe$Changed, this.#handleSubscription);
-        this.reactTo(this.events.defaultSubscription$Changed, this.#handleChangedDefaultSubscription);
+        if (this.#node.isGroup) {
+            // Groups can never subscribe
+            this.state.autoSubscribe = false;
+            this.state.defaultSubscription = undefined;
+        } else {
+            this.reactTo(this.events.autoSubscribe$Changed, this.#handleSubscription, { offline: true });
+            this.reactTo(this.events.defaultSubscription$Changed, this.#handleChangedDefaultSubscription);
+        }
     }
 
     override async startup() {

package/src/behavior/system/network/NetworkServer.ts

@@ -49,7 +49,7 @@ export class NetworkServer extends NetworkBehavior {
             discoveryCaps.onIpNetwork = true;
         }
 
-        this.reactTo(this.agent.get(CommissioningServer).events.commissioned, this.#endUncommissionedMode);
+        this.reactTo(this.endpoint.eventsOf(CommissioningServer).commissioned, this.#endUncommissionedMode);
 
         return super.initialize();
     }

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

@@ -77,21 +77,14 @@ export class AccessControlServer extends AccessControlBehavior.with("Extension")
                 // Handle Backward compatibility to Matter.js before 0.9.1 and add the missing ACL entry if no entry was set
                 // so far by the controller
                 const fallbackAcl: AccessControlTypes.AccessControlEntry = {
-                    fabricIndex: fabric.fabricIndex,
                     privilege: AccessControlTypes.AccessControlEntryPrivilege.Administer,
                     authMode: AccessControlTypes.AccessControlEntryAuthMode.Case,
                     subjects: [fabric.rootNodeId],
                     targets: null, // entire node
+                    fabricIndex: fabric.fabricIndex,
                 };
                 this.state.acl.push(fallbackAcl);
                 fabricAcls.push(fallbackAcl);
-                logger.warn(
-                    "Added missing ACL entry for fabric",
-                    fabric.fabricIndex,
-                    "for Node ID",
-                    fabric.rootNodeId,
-                    ". This should only happen once after upgrading to matter.js 0.9.1",
-                );
             }
             fabric.accessControl.aclList = fabricAcls;
             fabric.accessControl.extensionEntryAccessCheck = this.extensionEntryAccessCheck.bind(this);