@matter/nodejs-shell 0.17.9 → 0.18.0-alpha.0-20260812-4d7f2790e

package/src/shell/cmd_session.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { SessionsBehavior } from "@matter/node";
 import { MatterNode } from "../MatterNode.js";
 
 export default function commands(theNode: MatterNode) {
@@ -12,11 +13,8 @@ export default function commands(theNode: MatterNode) {
         describe: "Manage session",
         builder: {},
         handler: async () => {
-            if (!theNode.commissioningController) {
-                throw new Error("CommissioningController not initialized");
-            }
-
-            const sessions = theNode.commissioningController?.getActiveSessionInformation();
+            await theNode.start();
+            const sessions = Object.values(theNode.node.stateOf(SessionsBehavior).sessions);
             console.log(sessions);
         },
     };

package/src/shell/cmd_subscribe.ts

@@ -4,10 +4,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Diagnostic } from "@matter/general";
+import { ImplementationError, ObserverGroup } from "@matter/general";
+import { NetworkClient } from "@matter/node";
 import type { Argv } from "yargs";
 import { MatterNode } from "../MatterNode.js";
 
+const watchers = new Map<string, ObserverGroup>();
+
 export default function commands(theNode: MatterNode) {
     return {
         command: "subscribe [node-id]",
@@ -23,21 +26,41 @@ export default function commands(theNode: MatterNode) {
         handler: async (argv: any) => {
             const { nodeId: subscribeNodeId } = argv;
             const node = (await theNode.connectAndGetNodes(subscribeNodeId))[0];
+            if (node === undefined) {
+                throw new ImplementationError("No commissioned node to subscribe to");
+            }
+            const nodeId = node.peerAddress?.nodeId;
+            if (nodeId === undefined) {
+                throw new ImplementationError("Resolved node has no peer address to subscribe to");
+            }
+            const key = String(nodeId);
+
+            // Re-subscribing the same node replaces its watcher so change lines are not logged twice.
+            watchers.get(key)?.close();
+            watchers.delete(key);
+            const observers = new ObserverGroup();
+            watchers.set(key, observers);
+            observers.on(node.lifecycle.destroyed, () => {
+                watchers.get(key)?.close();
+                watchers.delete(key);
+            });
 
-            await node.subscribeAllAttributesAndEvents({
-                attributeChangedCallback: ({ path: { nodeId, clusterId, endpointId, attributeName }, value }) =>
-                    console.log(
-                        `${subscribeNodeId}: Attribute ${nodeId}/${endpointId}/${clusterId}/${attributeName} changed to ${Diagnostic.json(
-                            value,
-                        )}`,
-                    ),
-                eventTriggeredCallback: ({ path: { nodeId, clusterId, endpointId, eventName }, events }) =>
-                    console.log(
-                        `${subscribeNodeId} Event ${nodeId}/${endpointId}/${clusterId}/${eventName} triggered with ${Diagnostic.json(
-                            events,
-                        )}`,
-                    ),
+            // Attribute/event/structure changes for every peer are logged node-wide by installDiagnosticLogging
+            // (MatterNode.start); this command only establishes the subscription and reports its liveness.
+
+            // Surface subscription liveness transitions (establishment, drop, re-establishment).
+            observers.on(node.eventsOf(NetworkClient).subscriptionStatusChanged, isActive => {
+                console.log(`${nodeId}: subscription ${isActive ? "active" : "inactive"}`);
             });
+
+            // Enabling auto-subscribe establishes (and thereafter re-establishes) the sustained subscription; changes
+            // flow to the already-registered listener above.
+            await node.set({ network: { autoSubscribe: true } });
+
+            const subscriptionActive = await node.act(agent => agent.get(NetworkClient).subscriptionActive);
+            console.log(
+                `Subscribed to node ${nodeId} (subscription active: ${subscriptionActive}). Attribute and event changes will be logged below as they arrive.`,
+            );
         },
     };
 }

package/src/shell/webassets/index.html

@@ -285,7 +285,7 @@
                     logMessage(`Received: "${trimmed}"`, trimmed.toLowerCase().includes('error') ? 'error' : 'received');
 
                     // result of nodes log command
-                    let matches = message.match(/INFO\s+PairedNode [^0-9]*(\d+)\D*/);
+                    let matches = message.match(/Logging structure of Node\s+(\d+)/);
                     if (matches) { // could save this message of extensive node data for later use
                         let currentNode = matches[1];
                         let currentEndpoint = null;

package/src/tsconfig.json

@@ -11,9 +11,6 @@
         {
             "path": "../../general/src"
         },
-        {
-            "path": "../../matter.js/src"
-        },
         {
             "path": "../../model/src"
         },

package/src/util/ClusterEndpoint.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ClientNode, ClusterBehavior, Endpoint } from "@matter/node";
+import { Read, ReadResult } from "@matter/protocol";
+import { AttributePath, ClusterId, EventPath, Status } from "@matter/types";
+import { MatterNode } from "../MatterNode.js";
+import { awaitSeeded } from "./awaitSeeded.js";
+
+export interface ResolvedClusterEndpoint {
+    node: ClientNode;
+    endpoint: Endpoint;
+    behaviorType: ClusterBehavior.Type;
+}
+
+/**
+ * Connect to `nodeIdStr`, wait for the peer's endpoint structure to seed, and resolve the behavior implementing
+ * `clusterId` on `endpointId`. Mirrors the legacy `getDeviceById(endpointId)?.getClusterClientById(clusterId)` lookup
+ * (same "not found" message on any failure) so the three cluster-access command files can share one gate.
+ */
+export async function resolveClusterEndpoint(
+    theNode: MatterNode,
+    nodeIdStr: string,
+    endpointId: number,
+    clusterId: number,
+): Promise<ResolvedClusterEndpoint | undefined> {
+    const node = (await theNode.connectAndGetNodes(nodeIdStr))[0];
+    if (!(await awaitSeeded(node))) {
+        return undefined;
+    }
+
+    const behaviorType = node.endpoints.has(endpointId)
+        ? node.endpoints.for(endpointId).behaviors.forCluster(ClusterId(clusterId))
+        : undefined;
+    if (behaviorType === undefined) {
+        console.log(`ERROR: Cluster ${node.peerAddress?.nodeId}/${endpointId}/${clusterId} not found.`);
+        return undefined;
+    }
+    return { node, endpoint: node.endpoints.for(endpointId), behaviorType };
+}
+
+/**
+ * True only when `name` is a *known-absent* attribute/command of `behaviorType` on `endpoint`.
+ *
+ * The supported set derives from the behavior's global attribute/command list, which is EMPTY until that list has
+ * been read (a narrow window right after connect). An empty set is treated as "not yet known" — the caller proceeds
+ * to the live read/invoke rather than false-rejecting a genuinely supported element. Only a populated set that omits
+ * `name` is a real "unsupported" answer.
+ */
+export function elementKnownUnsupported(
+    endpoint: Endpoint,
+    behaviorType: ClusterBehavior.Type,
+    kind: "attributes" | "commands",
+    name: string,
+): boolean {
+    const elements = endpoint.behaviors.elementsOf(behaviorType)[kind];
+    return elements.size > 0 && !elements.has(name);
+}
+
+/**
+ * Live (un-cached) attribute read via the interaction protocol. Used for `--remote` reads and for the numeric
+ * by-id command, which (like its legacy predecessor) must work for clusters the node has no behavior for.
+ */
+export async function readAttributesRemote(
+    node: ClientNode,
+    attributes: AttributePath[],
+    isFabricFiltered: boolean,
+): Promise<ReadResult.AttributeValue[]> {
+    const values = new Array<ReadResult.AttributeValue>();
+    for await (const chunk of node.interaction.read(Read({ attributes, fabricFilter: isFabricFiltered }))) {
+        for await (const report of chunk) {
+            if (report.kind === "attr-value") {
+                values.push(report);
+            } else if (report.kind === "attr-status") {
+                // A device-declined read (e.g. UnsupportedAttribute/UnsupportedAccess) otherwise reads as empty.
+                const { path, status } = report;
+                console.log(
+                    `ERROR: ${path.endpointId}/${path.clusterId}/${path.attributeId}: ${Status[status] ?? status}`,
+                );
+            }
+        }
+    }
+    return values;
+}
+
+/** Live event read via the interaction protocol (there is no local event cache to read from instead). */
+export async function readEventsRemote(
+    node: ClientNode,
+    events: EventPath[],
+    isFabricFiltered: boolean,
+): Promise<ReadResult.EventValue[]> {
+    const values = new Array<ReadResult.EventValue>();
+    for await (const chunk of node.interaction.read(Read({ events, fabricFilter: isFabricFiltered }))) {
+        for await (const report of chunk) {
+            if (report.kind === "event-value") {
+                values.push(report);
+            } else if (report.kind === "event-status") {
+                const { path, status } = report;
+                console.log(`ERROR: ${path.endpointId}/${path.clusterId}/${path.eventId}: ${Status[status] ?? status}`);
+            }
+        }
+    }
+    return values;
+}

package/src/util/awaitSeeded.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Duration, ObserverGroup, Seconds, Time } from "@matter/general";
+import { ClientNode } from "@matter/node";
+
+const DEFAULT_SEEDED_TIMEOUT = Seconds(60);
+
+/**
+ * Wait (bounded) for a peer's endpoint structure to seed before reading it.
+ *
+ * Legacy `await node.events.initialized` blocked forever for an offline peer; the direct replacement
+ * `await node.lifecycle.seeded` inherits that hang. This bounds the wait: it returns `true` once the node is seeded
+ * and, on timeout, prints an "offline?" notice and returns `false` so the caller can abort the command instead of
+ * hanging.
+ */
+export async function awaitSeeded(
+    node: ClientNode,
+    { timeout = DEFAULT_SEEDED_TIMEOUT, quiet = false }: { timeout?: Duration; quiet?: boolean } = {},
+): Promise<boolean> {
+    if (node.lifecycle.isSeeded) {
+        return true;
+    }
+
+    const observers = new ObserverGroup();
+    const sleep = Time.sleep("awaitSeeded", timeout);
+    try {
+        const seeded = new Promise<void>(resolve => observers.on(node.lifecycle.seeded, () => resolve()));
+        const isSeeded = await Promise.race([seeded.then(() => true), sleep.then(() => false)]);
+        if (!isSeeded && !quiet) {
+            console.log(
+                `Node ${node.peerAddress?.nodeId} did not become ready within ${Duration.format(timeout)} (offline?); giving up.`,
+            );
+        }
+        return isSeeded;
+    } finally {
+        sleep.cancel();
+        observers.close();
+    }
+}

package/src/util/diagnosticLogging.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Diagnostic, ObserverGroup } from "@matter/general";
+import {
+    ChangeNotificationService,
+    ClientNode,
+    ClusterBehavior,
+    Endpoint,
+    NodeConnectionState,
+    ServerNode,
+} from "@matter/node";
+
+/** True if `endpoint` belongs to `node`'s endpoint tree (the node itself is its own root endpoint). */
+function ownedBy(endpoint: Endpoint, node: Endpoint) {
+    for (let e: Endpoint | undefined = endpoint; e !== undefined; e = e.owner) {
+        if (e === node) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function connectionStateLabel(state: NodeConnectionState) {
+    switch (state) {
+        case NodeConnectionState.Connected:
+            return "connected";
+        case NodeConnectionState.Disconnected:
+            return "disconnected";
+        case NodeConnectionState.Reconnecting:
+            return "reconnecting";
+        case NodeConnectionState.WaitingForDeviceDiscovery:
+            return "waiting for device to be discovered again";
+    }
+}
+
+/**
+ * Wire node-wide diagnostic logging once for the controller and all its peers.
+ *
+ * Replaces the legacy per-connect `createDiagnosticCallbacks` (attribute/event/state callbacks passed into each
+ * `PairedNode.connect`), which the ClientNode API dropped. A single aggregate {@link ChangeNotificationService} stream
+ * covers attribute/event changes for every peer, and each peer's connection-state transitions are logged from its
+ * lifecycle. Registered handlers are owned by `observers` and torn down when it closes.
+ */
+export function installDiagnosticLogging(node: ServerNode, observers: ObserverGroup): void {
+    observers.on(node.env.get(ChangeNotificationService).change, change => {
+        const { endpoint } = change;
+        const peer = node.peers.commissioned.find(peer => ownedBy(endpoint, peer));
+        if (peer === undefined) {
+            return; // A change on the controller's own node, not a peer.
+        }
+        const nodeId = peer.peerAddress?.nodeId;
+
+        switch (change.kind) {
+            case "update": {
+                const { behavior, properties, version } = change;
+                if (!ClusterBehavior.is(behavior)) {
+                    break;
+                }
+                const state = endpoint.stateOf(behavior.id);
+                const changed =
+                    properties === undefined ? state : Object.fromEntries(properties.map(name => [name, state[name]]));
+                console.log(
+                    `Node ${nodeId}: Attribute ${endpoint.number}/${behavior.cluster.id} changed to ${Diagnostic.json(changed)} (version ${version})`,
+                );
+                break;
+            }
+            case "event": {
+                const { behavior, event, number, timestamp, priority, payload } = change;
+                if (!ClusterBehavior.is(behavior)) {
+                    break;
+                }
+                console.log(
+                    `Node ${nodeId}: Event ${endpoint.number}/${behavior.cluster.id}/${event.propertyName} (#${number}, priority ${priority}, at ${timestamp}) triggered with ${Diagnostic.json(payload)}`,
+                );
+                break;
+            }
+            case "delete": {
+                console.log(`Node ${nodeId}: Endpoint ${endpoint.number} removed`);
+                break;
+            }
+        }
+    });
+
+    // Log each commissioned peer's connection-state transitions, torn down when the peer is removed.
+    // peers.added/deleted fire for every node in the container (including transient discovery and group nodes),
+    // so key the handlers by node to remove them on cull and skip nodes without a peer address.
+    const connectionHandlers = new Map<ClientNode, (state: NodeConnectionState) => void>();
+    const watchConnection = (peer: ClientNode) => {
+        if (connectionHandlers.has(peer)) {
+            return;
+        }
+        const handler = (state: NodeConnectionState) => {
+            const nodeId = peer.peerAddress?.nodeId;
+            if (nodeId !== undefined) {
+                console.log(`Node ${nodeId} ${connectionStateLabel(state)}`);
+            }
+        };
+        connectionHandlers.set(peer, handler);
+        peer.lifecycle.connectionStateChanged.on(handler);
+    };
+    const unwatchConnection = (peer: ClientNode) => {
+        const handler = connectionHandlers.get(peer);
+        if (handler !== undefined) {
+            peer.lifecycle.connectionStateChanged.off(handler);
+            connectionHandlers.delete(peer);
+        }
+    };
+    for (const peer of node.peers.commissioned) {
+        watchConnection(peer);
+    }
+    observers.on(node.peers.added, watchConnection);
+    observers.on(node.peers.deleted, unwatchConnection);
+}

package/src/util/legacyStorageMigration.ts

@@ -0,0 +1,275 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Environment,
+    isObject,
+    Logger,
+    StorageManager,
+    StorageService,
+    SupportedStorageTypes,
+    Time,
+} from "@matter/general";
+import { ClientNode, NetworkClient, RemoteDescriptor, ServerNode, ServerNodeStore } from "@matter/node";
+import { DiscoveryData, OperationalAddress, PeerAddress } from "@matter/protocol";
+import { EventNumber, FabricIndex, NodeId } from "@matter/types";
+
+const logger = Logger.get("LegacyStorageMigration");
+
+/** A pre-0.16 `credentials` entry (fabric config or CA key material); relocated verbatim, never decoded. */
+type LegacyCredentialRecord = Record<string, SupportedStorageTypes>;
+
+/**
+ * A pre-0.16 `fabrics` entry; only `fabricIndex` is read here, the rest was relocated verbatim in step 1.
+ * Intersected with `Record<string, SupportedStorageTypes>` (rather than a plain interface) so the type still
+ * satisfies `StorageContext.get`'s `SupportedStorageTypes` constraint.
+ */
+type LegacyFabricRecord = Record<string, SupportedStorageTypes> & { fabricIndex: number };
+
+/** Per-node metadata carried in a `commissionedNodes` list entry. `deviceData` is intentionally not migrated. */
+type LegacyCommissionedEntry = Record<string, SupportedStorageTypes> & {
+    operationalServerAddress?: OperationalAddress;
+    discoveryData?: DiscoveryData;
+};
+
+/** One `commissionedNodes` list entry: the peer's raw stored node id paired with its metadata. */
+type LegacyCommissionedNode = [bigint, LegacyCommissionedEntry];
+
+/** True for a pre-0.16 cached attribute record (current storage keeps the bare value instead). */
+function isLegacyAttributeRecord(value: SupportedStorageTypes): value is Record<string, SupportedStorageTypes> {
+    return isObject(value) && "value" in value;
+}
+
+async function stepOneNeeded(mgr: StorageManager): Promise<boolean> {
+    const credentials = mgr.createContext("credentials");
+    if (!(await credentials.has("fabric"))) {
+        return false;
+    }
+    const fabrics = await mgr.createContext("fabrics").get<LegacyCredentialRecord[]>("fabrics", []);
+    return fabrics.length === 0;
+}
+
+async function stepTwoNeeded(mgr: StorageManager): Promise<boolean> {
+    const nodes = mgr.createContext("nodes");
+    const commissioned = await nodes.get<SupportedStorageTypes[]>("commissionedNodes", []);
+    if (commissioned.length === 0) {
+        return false;
+    }
+    // Current-format storage keys each peer under its own subcontext of "nodes".
+    return (await nodes.contexts()).length === 0;
+}
+
+/**
+ * True when a pre-0.16 controller storage still needs migrating to the current layout.
+ * See docs/MIGRATION_CONTROLLER_018.md.
+ */
+export async function legacyMigrationNeeded(env: Environment, id: string): Promise<boolean> {
+    const mgr = await env.get(StorageService).open(id);
+    try {
+        return (await stepOneNeeded(mgr)) || (await stepTwoNeeded(mgr));
+    } finally {
+        await closeStorage(mgr, id);
+    }
+}
+
+/**
+ * Step 1: relayout fabric + certificate authority data from the legacy `credentials` context into the
+ * `fabrics`/`certificates` contexts the current controller reads. Must run before the controller ServerNode is
+ * constructed. Idempotent.
+ */
+export async function migrateLegacyControllerCredentials(env: Environment, id: string): Promise<void> {
+    const mgr = await env.get(StorageService).open(id);
+    try {
+        if (!(await stepOneNeeded(mgr))) {
+            logger.debug(`No legacy controller credentials to migrate for store ${id}`);
+            return;
+        }
+
+        const credentials = mgr.createContext("credentials");
+        const fabricStore = mgr.createContext("fabrics");
+        const certificates = mgr.createContext("certificates");
+
+        let fabric: LegacyCredentialRecord | undefined;
+        for (const key of await credentials.keys()) {
+            if (key === "fabric") {
+                fabric = await credentials.get<LegacyCredentialRecord>("fabric");
+            } else if (!(await certificates.has(key))) {
+                await certificates.set(key, await credentials.get<SupportedStorageTypes>(key));
+            }
+        }
+
+        // Certificate authority keys must land in `certificates` before `fabrics.fabrics` is written: a crash
+        // between the two would otherwise strand the CA under the old layout while the guard reports "migrated".
+        if (fabric !== undefined) {
+            await fabricStore.set("fabrics", [fabric]);
+        }
+        logger.info(`Migrated legacy controller credentials for store ${id}`);
+    } finally {
+        await closeStorage(mgr, id);
+    }
+}
+
+/**
+ * Step 2: migrate cached per-node data (`node-<id>` attribute trees + the `commissionedNodes` list) into the
+ * current per-peer store layout, and register each peer. Must run after the controller ServerNode is constructed
+ * (so its fabric is loaded) but before it goes online. Non-destructive — old data is left in place for
+ * {@link cleanupLegacyStorage}. Idempotent (skips peers that already exist); a peer that fails to migrate is
+ * skipped without aborting the rest and its partially-written store is cleared. Returns migrated counts.
+ */
+export async function migrateLegacyCommissionedNodes(
+    node: ServerNode,
+): Promise<{ nodes: number; endpoints: number; failed: number }> {
+    const serverStore = node.env.get(ServerNodeStore);
+    const baseStorage = serverStore.storage;
+    const nodesCtx = baseStorage.createContext("nodes");
+
+    // Per-peer idempotency is handled below; this only needs to know whether there is legacy data left to
+    // look at, so a resume after a partial run isn't skipped.
+    if (!(await nodesCtx.has("commissionedNodes"))) {
+        logger.debug("No former commissioned nodes to migrate.");
+        return { nodes: 0, endpoints: 0, failed: 0 };
+    }
+    const commissioned = await nodesCtx.get<LegacyCommissionedNode[]>("commissionedNodes", []);
+
+    // A migrated Era-B store carries exactly one fabric. Anything else (no fabric yet, or an unexpected
+    // multi-fabric store) cannot be addressed here; skip rather than abort the shell's startup. Report the
+    // skipped peers as failed so the caller does not treat this as a clean run and proceed to delete them.
+    const fabrics = await baseStorage.createContext("fabrics").get<LegacyFabricRecord[]>("fabrics", []);
+    if (fabrics.length !== 1) {
+        logger.warn(`Skipping legacy node migration: expected exactly one migrated fabric, found ${fabrics.length}`);
+        return { nodes: 0, endpoints: 0, failed: commissioned.length };
+    }
+    const fabricIndex = FabricIndex(fabrics[0].fabricIndex);
+
+    let migratedNodes = 0;
+    let migratedEndpoints = 0;
+    let failedNodes = 0;
+
+    for (const [rawNodeId, { operationalServerAddress, discoveryData }] of commissioned) {
+        const nodeId = NodeId(rawNodeId);
+        const peerAddress = PeerAddress({ fabricIndex, nodeId });
+
+        const existingPeer = node.peers.get(peerAddress);
+        if (existingPeer !== undefined) {
+            logger.debug(`Node ${nodeId} already migrated, skipping`);
+            if (existingPeer.stateOf(NetworkClient).autoSubscribe) {
+                await existingPeer.setStateOf(NetworkClient, { autoSubscribe: false });
+            }
+            continue;
+        }
+
+        const id = serverStore.clientStores.allocateId();
+        let peerNode: ClientNode | undefined;
+        try {
+            const oldNode = baseStorage.createContext(`node-${nodeId}`);
+
+            const maxEventNumber = await oldNode.get<EventNumber>("__maxEventNumber__", EventNumber(0));
+
+            // Written before forAddress() below allocates the peer's store for the same id, which loads rather
+            // than overwrites whatever is already on disk under that context.
+            const peerStorage = nodesCtx.createContext(id).createContext("endpoints");
+            let endpointsForNode = 0;
+            for (const ep of await oldNode.contexts()) {
+                const oldEndpoint = oldNode.createContext(ep);
+                const newEndpoint = peerStorage.createContext(ep);
+                for (const cluster of await oldEndpoint.contexts()) {
+                    const oldCluster = oldEndpoint.createContext(cluster);
+                    const newCluster = newEndpoint.createContext(cluster);
+                    for (const key of await oldCluster.keys()) {
+                        const value = await oldCluster.get(key);
+                        if (key === "__version__") {
+                            await newCluster.set(key, value);
+                        } else if (isLegacyAttributeRecord(value)) {
+                            await newCluster.set(key, value.value);
+                        }
+                    }
+                }
+                endpointsForNode++;
+            }
+
+            const commissioning = RemoteDescriptor.toLongForm({
+                // Fallback only — a peer with its own discoveredAt keeps it.
+                discoveredAt: Time.nowMs,
+                ...discoveryData,
+                addresses: operationalServerAddress ? [operationalServerAddress] : [],
+            });
+
+            peerNode = await node.peers.forAddress(peerAddress, { id });
+            await peerNode.set({ commissioning, network: { maxEventNumber, autoSubscribe: false } });
+            migratedNodes++;
+            migratedEndpoints += endpointsForNode;
+            logger.info(`Migrated commissioned node ${nodeId} as ${id}`);
+        } catch (error) {
+            failedNodes++;
+            logger.error(`Failed to migrate commissioned node ${nodeId} as ${id}, skipping:`, error);
+            if (peerNode !== undefined) {
+                await peerNode.delete();
+            }
+            await nodesCtx.createContext(id).clearAll();
+        }
+    }
+
+    return { nodes: migratedNodes, endpoints: migratedEndpoints, failed: failedNodes };
+}
+
+/**
+ * Irreversible: once the legacy artifacts are deleted there is no way back, so this must only be run when the
+ * operator is certain migration succeeded and the store will not be downgraded below 0.16.
+ *
+ * Deletes all legacy (pre-0.16) storage artifacts once migration is no longer needed (the same
+ * `stepOneNeeded`/`stepTwoNeeded` predicate {@link legacyMigrationNeeded} uses). It does not verify that every
+ * individual peer migrated successfully: this is an explicit, user-confirmed action (e.g. the shell's
+ * `--cleanup-legacy-storage` flag). Running it against a store where step 1 or step 2 has not fully completed
+ * loses the un-migrated data; that is accepted, and is the caller's responsibility. Idempotent.
+ */
+export async function cleanupLegacyStorage(env: Environment, id: string): Promise<void> {
+    const mgr = await env.get(StorageService).open(id);
+    try {
+        if ((await stepOneNeeded(mgr)) || (await stepTwoNeeded(mgr))) {
+            logger.warn(`Refusing legacy cleanup for store ${id}: migration has not completed`);
+            return;
+        }
+        await wipeLegacyContexts(mgr);
+        logger.info(`Removed legacy storage artifacts for store ${id}`);
+    } finally {
+        await closeStorage(mgr, id);
+    }
+}
+
+/**
+ * Unconditionally remove the legacy (pre-0.16) storage artifacts, no migration-state guard.
+ *
+ * A factory reset clears the current-format fabric but not the legacy source; leaving it would let the next boot
+ * re-migrate and resurrect the identity/key material the reset destroyed. The reset path therefore wipes the
+ * legacy source too. Unlike {@link cleanupLegacyStorage} this makes no completeness assumption — the reset is
+ * discarding everything regardless.
+ */
+export async function eraseLegacyStorage(env: Environment, id: string): Promise<void> {
+    const mgr = await env.get(StorageService).open(id);
+    try {
+        await wipeLegacyContexts(mgr);
+    } finally {
+        await closeStorage(mgr, id);
+    }
+}
+
+async function wipeLegacyContexts(mgr: StorageManager): Promise<void> {
+    for (const context of await mgr.driver.contexts([])) {
+        if (context.startsWith("node-")) {
+            await mgr.createContext(context).clearAll();
+        }
+    }
+    await mgr.createContext("nodes").delete("commissionedNodes");
+    await mgr.createContext("credentials").clearAll();
+}
+
+async function closeStorage(mgr: StorageManager, id: string): Promise<void> {
+    try {
+        await mgr.close();
+    } catch (closeError) {
+        logger.warn(`Error closing storage for store ${id}:`, closeError);
+    }
+}