@serfab/cadre-core 1.16.0 → 1.18.0

package/dist/edge-node/edge-node.js

@@ -0,0 +1,704 @@
+/**
+ * `createEdgeNode` — build, start, stop and rebuild an edge device's `CadreNode` the prescribed
+ * way: identity and owner key in the app's key store, the four node-local stores durable and
+ * party-scoped, raw storage per scope from the app's storage, owner genesis, the last start
+ * remembered for unattended starts, and the switch to another party's cadre by machine
+ * invitation or owner grant.
+ *
+ * Nothing platform-specific is imported here. The app passes in its key store, its storage and
+ * its transports (`EdgeNodePlatform`), so a Node test runs this code over fakes, and the React
+ * Native kit's `createPhoneNode` is this over the secure store and rn-leveldb.
+ */
+import { CadreNode } from '../cadre-node.js';
+import { DEFAULT_IDENTITY_KEY_ID } from '../key-store.js';
+import { loadOrCreateIdentityKey } from '../identity-key.js';
+import { exportOwnerKey, importOwnerKeyInto } from '../owner-key-flows.js';
+import { createOwnerKey, loadOwnerSigner } from '../owner-key-store.js';
+import { PersistentBootstrapPeerStore } from '../bootstrap-peer-store.js';
+import { PersistentEnrolledMachineStore } from '../enrolled-machine-store.js';
+import { PersistentStrandNetworkStateStore } from '../strand-network-state.js';
+import { PersistentTrustedOwnerStore } from '../trusted-owner-store.js';
+import { readStrandHoldings } from '../strand-move.js';
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
+import { webSockets } from '@libp2p/websockets';
+import { buildEdgeNodeConfig, requireOwnerKeyLabel, runOwnerGenesis, wireJoinedOwnerKey } from './config.js';
+import { finishMarkedRemoval, finishRemovalAtStart, formerPartyRead, formerPartyRefusal, readFormerParty, removeParty, StrandMovePendingError, withoutFormerParty, } from './dissolve.js';
+import { joinCadre } from './edge-join.js';
+import { bootstrapPeersKvKey, enrolledMachinesKvKey, kvStoreSlot, strandNetworkKvKey, trustedOwnersKvKey, } from './node-local.js';
+import { parseSavedStart, serializeSavedStart, startAfterRemoval } from './options.js';
+import { redeemOwnerGrantText } from './owner-grant.js';
+import { DEFAULT_EDGE_NODE_NAMES } from './platform.js';
+import { adoptMoveRecord, adoptMovesInto, pendingMove, StrandMoveRecords, toError } from './strand-move.js';
+/** Edge nodes by storage id: two over the same storage would share databases and an identity. */
+const edgeNodes = new Map();
+/**
+ * Create the app's edge node. Call once per app. Throws when an edge node over the same storage
+ * (`platform.storage.id`) is starting or running in this process; a stopped or failed one is
+ * replaced (a development reload re-runs the module that calls this).
+ */
+export function createEdgeNode(platform) {
+    const id = platform.storage.id;
+    const existing = edgeNodes.get(id);
+    if (existing && ['starting', 'joining', 'running'].includes(existing.status.state)) {
+        throw new Error(`an edge node over storage '${id}' is already ${existing.status.state}; create one per app and share it`);
+    }
+    const created = new EdgeNodeRuntime(platform, { ...DEFAULT_EDGE_NODE_NAMES, ...platform.names });
+    edgeNodes.set(id, created);
+    return created;
+}
+class EdgeNodeRuntime {
+    constructor(platform, names) {
+        this.platform = platform;
+        this.names = names;
+        this.current = null;
+        this.runningOptions = null;
+        this.starting = null;
+        this.stopping = null;
+        /** One per join called and not yet settled, so a stop can cancel them. */
+        this.joins = new Set();
+        /**
+         * Start, stop, restart, join and dissolve run one at a time, in call order: each opens or closes
+         * the stores the others use, so a start overlapping a stop would build on handles the stop then closes.
+         */
+        this.transitions = Promise.resolve();
+        this.currentStatus = { state: 'stopped' };
+        this.lastUnfinishedRemoval = null;
+        this.subscriptions = new Set();
+        this.statusListeners = new Set();
+        this.keyStore = platform.keyStore;
+        this.moves = new StrandMoveRecords(this.keyStore);
+    }
+    get status() {
+        return this.currentStatus;
+    }
+    get node() {
+        return this.currentStatus.state === 'running' ? this.current : null;
+    }
+    get options() {
+        return this.currentStatus.state === 'running' ? this.runningOptions : null;
+    }
+    get unfinishedRemoval() {
+        return this.lastUnfinishedRemoval;
+    }
+    identityPeerId() {
+        const status = this.currentStatus;
+        // A join may wait minutes for a member; the screen showing the join request must not wait with it.
+        const peerId = status.state === 'running' || status.state === 'joining' ? status.node.peerId : undefined;
+        if (peerId)
+            return Promise.resolve(peerId.toString());
+        return this.inTurn(async () => {
+            const key = await loadOrCreateIdentityKey(this.keyStore, DEFAULT_IDENTITY_KEY_ID);
+            // A public key's string form is its peer id's.
+            return key.publicKey.toString();
+        });
+    }
+    start(options) {
+        if (this.starting)
+            return this.starting;
+        return this.trackStart(() => (this.current?.isRunning ? Promise.resolve(this.current) : this.buildAndStart(options)));
+    }
+    stop() {
+        // A join can wait for a member until its invitation expires; the user's disconnect ends it.
+        // NOTE: the cancelled join starts the party it left again, and only then does this stop
+        // stop it. If that restart makes Disconnect noticeably slow, let a join cancelled by a stop
+        // save the left start with `autoStart: false` and stay stopped instead.
+        for (const join of this.joins)
+            join.abort(new Error('the edge node was stopped during a join'));
+        return this.trackStop(() => this.stopAndClearAutoStart());
+    }
+    restart(options) {
+        this.starting = null;
+        return this.trackStart(async () => {
+            await this.shutDown();
+            return this.buildAndStart(options);
+        });
+    }
+    joinCadre(credential, options = {}) {
+        // A start called from here on runs after this join rather than joining a start it replaces.
+        this.starting = null;
+        const cancel = new AbortController();
+        const release = relayAbort(options.signal, cancel);
+        this.joins.add(cancel);
+        const joining = this.inTurn(() => joinCadre(this, credential, options, cancel.signal));
+        const settled = () => {
+            this.joins.delete(cancel);
+            release();
+        };
+        joining.then(settled, settled);
+        return joining;
+    }
+    async loadSavedStart() {
+        // A stop in progress decides `autoStart`: answer after it, so an unattended start does
+        // not act on the value the stop is replacing. Its failure is its caller's.
+        await this.stopping?.catch(() => undefined);
+        return this.readSavedStart();
+    }
+    linkRequestSlot() {
+        return kvStoreSlot(this.nodeLocalRecords(), this.names.linkRequestKey);
+    }
+    recommendationSlot() {
+        return kvStoreSlot(this.nodeLocalRecords(), this.names.recommendationsKey);
+    }
+    /** The node-local store for a record the app keeps across stops and starts. */
+    nodeLocalRecords() {
+        // Each get and set asks the platform for the store again: a stop closes it, and the record outlives the stop.
+        const kv = async () => {
+            // Opening it while a stop is closing it would take a second lock on the same name.
+            // NOTE: a restart, join or dissolve closes it too, with no `stopping` to wait on, so a
+            // read in that short window can fail on the lock. If that is ever seen, track each shutdown as `stopping` is tracked.
+            await this.stopping?.catch(() => undefined);
+            return this.nodeLocalKv();
+        };
+        return {
+            get: async (key) => (await kv()).get(key),
+            set: async (key, value) => (await kv()).set(key, value),
+            flush: async () => (await kv()).flush(),
+        };
+    }
+    async pendingStrandMove() {
+        const formerPartyId = (this.runningOptions ?? (await this.readSavedStart())?.options)?.formerPartyId;
+        if (formerPartyId === undefined)
+            return undefined;
+        const record = await this.moves.load(formerPartyId);
+        return record && pendingMove(record);
+    }
+    finishStrandMove() {
+        return this.inTurn(async () => {
+            const node = this.node;
+            const running = this.runningOptions;
+            const formerPartyId = running?.formerPartyId;
+            if (!node?.isRunning || !running || formerPartyId === undefined)
+                return undefined;
+            const record = await this.moves.load(formerPartyId);
+            if (record?.targetPartyId !== node.partyId)
+                return undefined;
+            // A joined start that settled as a member stopped asking for the owner row after its
+            // bound; one that arrived since makes this adoption an owner's rather than a refusal.
+            // A founded party never re-asks here: genesis is its owner step, and a signer already
+            // wired is never replaced.
+            if (running.origin === 'joined' && node.getOwnerSigner() === null && (await this.wireJoinedOwner(node, false)) === 'enrolled') {
+                this.reportEnrolled(node);
+            }
+            const report = await adoptMoveRecord(node, this.moves, record);
+            // The adoption wires the key or throws, so a start that settled as a member is an owner now.
+            this.reportEnrolled(node);
+            return report;
+        });
+    }
+    dissolveFormerParty(options = {}) {
+        // A start called from here on runs after this dissolve rather than joining a start whose node it stops.
+        this.starting = null;
+        return this.inTurn(() => this.dissolve(options.discard ?? []));
+    }
+    on(event, handler) {
+        const subscription = {
+            attach: (node) => node.on(event, handler),
+            detach: (node) => node.off(event, handler),
+        };
+        this.subscriptions.add(subscription);
+        if (this.current)
+            subscription.attach(this.current);
+        return () => {
+            this.subscriptions.delete(subscription);
+            if (this.current)
+                subscription.detach(this.current);
+        };
+    }
+    onStatus(listener) {
+        this.statusListeners.add(listener);
+        return () => {
+            this.statusListeners.delete(listener);
+        };
+    }
+    ownerPublicKey() {
+        return this.node?.getOwnerSigner()?.publicKey ?? null;
+    }
+    // ── owner keys ───────────────────────────────────────────────────────────
+    // In turn with the transitions: genesis creates the owner slot's key inside a start, and the
+    // slot's check-then-set must not race an import.
+    listOwnerKeys() {
+        return this.onRunningNode((node) => node.listOwnerKeys());
+    }
+    exportOwnerKey(options = {}) {
+        return this.inTurn(() => exportOwnerKey(this.keyStore, options));
+    }
+    importOwnerKey(text, passphrase) {
+        return this.inTurn(async () => {
+            const node = this.node?.isRunning ? this.node : null;
+            const imported = await importOwnerKeyInto(this.keyStore, node, text, passphrase);
+            if (imported.wired && node)
+                this.reportEnrolled(node);
+            return imported;
+        });
+    }
+    planOwnerKeyRemoval(key) {
+        return this.onRunningNode((node) => node.planOwnerKeyRemoval(key));
+    }
+    removeOwner(key, options = {}) {
+        return this.onRunningNode((node) => node.removeOwner(key, options));
+    }
+    createOwnerGrant(options = {}) {
+        return this.onRunningNode((node) => node.createOwnerGrant(options));
+    }
+    listOwnerGrants() {
+        return this.onRunningNode((node) => node.listOwnerGrants());
+    }
+    withdrawOwnerGrant(key) {
+        return this.onRunningNode((node) => node.withdrawOwnerGrant(key));
+    }
+    redeemOwnerGrant(text) {
+        return this.onRunningNode(async (node) => {
+            const redeemed = await redeemOwnerGrantText(this, node, text);
+            if (redeemed.wired)
+                this.reportEnrolled(node);
+            return redeemed;
+        });
+    }
+    /** Run `op` on the running node, in turn with start, stop and join; throws when none is running. */
+    onRunningNode(op) {
+        return this.inTurn(async () => {
+            const node = this.node;
+            if (!node?.isRunning)
+                throw new Error('The edge node is not running; start it first');
+            return await op(node);
+        });
+    }
+    /** A key was wired after the start settled: a start reported as a member is an owner now. */
+    reportEnrolled(node) {
+        if (this.currentStatus.state === 'running' && this.currentStatus.owner !== 'enrolled') {
+            this.setStatus({ state: 'running', node, owner: 'enrolled' });
+        }
+    }
+    // ── transitions ──────────────────────────────────────────────────────────
+    /** Run `op` after every transition called before it, whether those succeeded or failed. */
+    inTurn(op) {
+        const result = this.transitions.then(op);
+        this.transitions = result.catch(() => undefined);
+        return result;
+    }
+    /**
+     * Queue a transition that rewrites the saved start as it takes the node down (a stop, a
+     * removal), and let `loadSavedStart` and the app-link slots wait for it until it settles.
+     */
+    trackStop(op) {
+        // A start called from here on runs after this transition rather than joining the one it ends.
+        this.starting = null;
+        const stopping = this.inTurn(op);
+        this.stopping = stopping;
+        const settled = () => {
+            if (this.stopping === stopping)
+                this.stopping = null;
+        };
+        stopping.then(settled, settled);
+        return stopping;
+    }
+    /** Queue a start, and let later `start` calls join it until it settles. */
+    trackStart(op) {
+        const starting = this.inTurn(op);
+        this.starting = starting;
+        const settled = () => {
+            if (this.starting === starting)
+                this.starting = null;
+        };
+        starting.then(settled, settled);
+        return starting;
+    }
+    // ── start ────────────────────────────────────────────────────────────────
+    // `bringUp`, `readAlone`, `buildAndStart`, `ownerSlotSigner`, `wireJoinedOwner`,
+    // `saveRunningStart` and `reportRunning` are public as the join's and the owner-grant
+    // redemption's view of this runtime (`JoinRuntime`, `OwnerGrantRuntime`); the class itself
+    // never leaves this module.
+    async buildAndStart(options) {
+        this.setStatus({ state: 'starting' });
+        try {
+            const { node, resolved } = await this.bringUp(options);
+            const owner = await this.settleOwnerKey(node, resolved);
+            // Finishes a move a join left: the app was killed before adopting, or its key was wired
+            // only now. A move record the key store refuses to read fails the start.
+            // NOTE: a pending move delays `running` by its control writes, a few per strand. If a
+            // resumed move makes a start noticeably slow, adopt after `markRunning` instead, as a
+            // transition of its own.
+            if (owner === 'enrolled')
+                await adoptMovesInto(node, this.moves);
+            await this.markRunning(node, resolved, owner);
+            return node;
+        }
+        catch (err) {
+            // The start's own error is the one to report; a failure tearing down after it is only logged.
+            await this.shutDown().catch((cleanupErr) => {
+                console.warn('[cadre-core/edge-node] cleaning up after a failed start failed:', cleanupErr);
+            });
+            const error = toError(err);
+            this.setStatus({ state: 'failed', error });
+            throw error;
+        }
+    }
+    /** Build the node for `options`, every subscription attached, and start it, after finishing a begun dissolve. */
+    async bringUp(options) {
+        const removal = await finishRemovalAtStart(this.partyStorage());
+        this.noteRemovalAtStart(removal);
+        const resolved = withoutFormerParty(await this.resolveOptions(options), removal.partyId);
+        const node = new CadreNode(await this.buildConfig(resolved));
+        this.current = node;
+        for (const subscription of this.subscriptions)
+            subscription.attach(node);
+        this.watchRemoval(node);
+        await node.start();
+        return { node, resolved };
+    }
+    /** What `unfinishedRemoval` reports after a start: a marker that could not be read leaves the last report standing. */
+    noteRemovalAtStart(removal) {
+        if (removal.partyId !== undefined) {
+            this.lastUnfinishedRemoval = removal.error ? { partyId: removal.partyId, error: removal.error } : null;
+        }
+        else if (!removal.error) {
+            this.lastUnfinishedRemoval = null;
+        }
+    }
+    /**
+     * Start a node for `options`' party only to run `read` on it, then stop it. Nothing subscribes,
+     * nothing is saved and no strand launches: the node never reports running. A join exports the
+     * strands of a stopped party this way, and a dissolve reads the party it removes.
+     */
+    async readAlone(options, read, purpose) {
+        this.setStatus({ state: 'starting' });
+        try {
+            const config = await this.buildConfig(await this.resolveOptions(options));
+            const node = new CadreNode({ ...config, strandFilter: { mode: 'none' } });
+            this.current = node;
+            await node.start();
+            return await read(node);
+        }
+        finally {
+            // The read's own error, if any, is the one to report.
+            await this.shutDown().catch((err) => {
+                console.warn(`[cadre-core/edge-node] stopping the node started to ${purpose} failed:`, err);
+            });
+        }
+    }
+    /** A founded party runs owner genesis; a joined one only wires a key the party already lists. */
+    settleOwnerKey(node, options) {
+        if (options.origin === 'joined')
+            return this.wireJoinedOwner(node, false);
+        return runOwnerGenesis(node, { keyStore: this.keyStore, label: options.ownerKeyLabel, timeoutMs: this.platform.ownerGenesisTimeoutMs });
+    }
+    /** The owner slot's key, created when the slot is empty: what an owner grant seats. Inside a transition, as the slot's check-then-set must be. */
+    async ownerSlotSigner() {
+        return (await loadOwnerSigner(this.keyStore)) ?? (await createOwnerKey(this.keyStore));
+    }
+    /** `granted`: an owner grant has just seated the slot's key, so wait for the row. */
+    wireJoinedOwner(node, granted) {
+        return wireJoinedOwnerKey(node, { keyStore: this.keyStore, timeoutMs: this.platform.ownerGenesisTimeoutMs, granted });
+    }
+    /** Report a node that came up, saving its options only now, so a failed start never replaces the last one that came up. */
+    async markRunning(node, resolved, owner) {
+        await this.saveRunningStart(resolved);
+        this.reportRunning(node, resolved, owner);
+    }
+    saveRunningStart(resolved) {
+        return this.saveStart({ options: resolved, autoStart: true, writtenBy: this.platform.dataVersion });
+    }
+    reportRunning(node, resolved, owner) {
+        this.runningOptions = resolved;
+        this.setStatus({ state: 'running', node, owner });
+    }
+    /**
+     * The options as this start runs and saves them. The Noise mode is resolved, so a later
+     * build's default does not change a device that already ran. Options naming no `origin`
+     * take the saved start's `origin` and `formerPartyId` when it is for the same party, so a
+     * party this app joined, started again from a hand-typed party id, does not run owner genesis.
+     */
+    async resolveOptions(options) {
+        requireOwnerKeyLabel(options.ownerKeyLabel);
+        const resolved = { ...options };
+        const defaultMode = this.platform.noiseCrypto?.defaultMode;
+        if (resolved.noiseCryptoMode === undefined && defaultMode !== undefined)
+            resolved.noiseCryptoMode = defaultMode;
+        if (resolved.origin === undefined) {
+            const saved = (await this.readSavedStart())?.options;
+            if (saved?.partyId === resolved.partyId) {
+                if (saved.origin !== undefined)
+                    resolved.origin = saved.origin;
+                if (saved.formerPartyId !== undefined)
+                    resolved.formerPartyId = saved.formerPartyId;
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Open the node-local stores and assemble the config. A store read failure propagates and fails
+     * the start: an unreadable trusted-owner anchor is a refusal to start, not a silent downgrade to
+     * trusting nobody, and starting empty would let the next write destroy an intact anchor. (The
+     * enrolled-machine store cold-starts instead; a lost repair hint must not stop a node.)
+     */
+    async buildConfig(options) {
+        const { partyId, relayAddrs } = options;
+        const { platform } = this;
+        const config = buildEdgeNodeConfig({
+            ...options,
+            noiseCrypto: this.buildNoiseCrypto(options.noiseCryptoMode),
+            keyStore: this.keyStore,
+            storageProvider: (scope) => platform.storage.rawStorage(scope),
+            transports: (platform.transports ?? defaultTransports)(relayAddrs),
+            listenAddrs: platform.listenAddrs?.(relayAddrs) ?? [],
+            allowPrivateDial: platform.allowPrivateDial ?? true,
+            trustedOwnerStore: await PersistentTrustedOwnerStore.open(this.trustedOwnerSlot(partyId), partyId),
+            bootstrapPeerStore: await PersistentBootstrapPeerStore.open(this.nodeLocalSlot(bootstrapPeersKvKey(partyId)), partyId),
+            enrolledMachineStore: await PersistentEnrolledMachineStore.open(this.nodeLocalSlot(enrolledMachinesKvKey(partyId)), partyId),
+            strandNetworkStateStore: await PersistentStrandNetworkStateStore.open(this.nodeLocalSlot(strandNetworkKvKey(partyId)), partyId),
+        });
+        return platform.configure ? platform.configure(config) : config;
+    }
+    buildNoiseCrypto(mode) {
+        const noiseCrypto = this.platform.noiseCrypto;
+        return noiseCrypto && mode ? noiseCrypto.build(mode) : undefined;
+    }
+    // ── dissolve ─────────────────────────────────────────────────────────────
+    // NOTE: this file is about 1050 lines (`wc -l`), the dissolve's and the removal's transitions
+    // the largest part (the storage they delete is in `dissolve.ts`; the join is `edge-join.ts`,
+    // the owner-grant redemption `owner-grant.ts`), then the owner-key and owner-grant
+    // pass-throughs. If any of them grows further, move it to a module of its own over a narrow
+    // view of this runtime, as the join is.
+    /** docs/architecture.md → "Dissolving the party it left". */
+    async dissolve(discard) {
+        await this.finishMarkedRemoval();
+        const { node, running, formerPartyId } = this.runningWithFormerParty();
+        const record = await this.moves.load(formerPartyId);
+        if (record)
+            throw new StrandMovePendingError(pendingMove(record));
+        const holdings = await readStrandHoldings(node);
+        try {
+            await this.shutDown();
+            const content = await this.readAlone(formerPartyRead(formerPartyId, running), readFormerParty, 'read the party it left');
+            const refusal = formerPartyRefusal(content, holdings, discard, Date.now());
+            if (refusal)
+                throw refusal;
+            await removeParty(this.partyStorage(), formerPartyId);
+        }
+        catch (err) {
+            await this.startAgainAfterDissolve(running);
+            throw err;
+        }
+        await this.buildAndStart(withoutFormerParty(running, formerPartyId));
+    }
+    runningWithFormerParty() {
+        const node = this.node;
+        const running = this.runningOptions;
+        const formerPartyId = running?.formerPartyId;
+        if (!node?.isRunning || !running || formerPartyId === undefined) {
+            throw new Error('Nothing to dissolve: the edge node is not running with a former party, one this app founded and left');
+        }
+        // Only a hand-built start names its own party; dissolving it would delete the running party's control database.
+        if (formerPartyId === running.partyId) {
+            throw new Error(`Cannot dissolve party ${formerPartyId}: it is the running party, not one this app left`);
+        }
+        return { node, running, formerPartyId };
+    }
+    /** After a refused or failed dissolve. The dissolve's own error is the one its caller gets; this one is only logged. */
+    async startAgainAfterDissolve(running) {
+        try {
+            await this.buildAndStart(running);
+        }
+        catch (err) {
+            console.warn('[cadre-core/edge-node] starting the running party again after a dissolve failed:', err);
+        }
+    }
+    /** Finish the removal a marker names, if any; finished, it is no longer an unfinished one to report. */
+    async finishMarkedRemoval() {
+        await finishMarkedRemoval(this.partyStorage());
+        this.lastUnfinishedRemoval = null;
+    }
+    // ── removal ──────────────────────────────────────────────────────────────
+    /**
+     * Answer `node` reporting that an owner removed this app from its party
+     * ({@link forgetRemovedParty}). Attached before the node starts, so no report comes before it
+     * and `removedFromCadre()` has nothing to add; never detached, so a report raised while the
+     * node stops, which it made while running, is still answered.
+     *
+     * NOTE: a device removed while its app was not running never sees its own row live after the
+     * next start, so it never reports (docs/architecture.md → "The removed machine learns it"), and
+     * keeps the party's data while every other machine refuses it. If users meet this, persist
+     * "seen live" per party so the rule survives a restart.
+     */
+    watchRemoval(node) {
+        node.on('cadre:removed', (removal) => {
+            void this.trackStop(() => this.forgetRemovedParty(removal));
+        });
+    }
+    /**
+     * In turn with start, stop and join: stop the removed party's node, point the saved start away
+     * from that party, delete its local storage and report `removed`. A node of another party, started
+     * by a join that ran before this turn, keeps running; only the removed party's storage goes.
+     * Nothing starts unattended afterwards: the user sees why the app left its cadre first. A
+     * failure is logged and leaves `status` `failed`; never rejects.
+     *
+     * NOTE: `start` does not refuse the removed party's options, so an app that cached them builds
+     * that party again on empty storage. If one is seen doing so, refuse a start of `partyId` while
+     * `status` is `removed`.
+     */
+    async forgetRemovedParty(removal) {
+        const { partyId } = removal;
+        try {
+            if (this.current !== null && this.current.partyId !== partyId) {
+                await this.removeLocalParty(partyId);
+                if (this.runningOptions)
+                    this.runningOptions = withoutFormerParty(this.runningOptions, partyId);
+                return;
+            }
+            await this.shutDown().catch((err) => {
+                // `shutDown` has closed every store and dropped the node whether or not its stop threw.
+                console.warn(`[cadre-core/edge-node] stopping the node of party ${partyId}, which removed this app, failed:`, err);
+            });
+            const formerPartyId = await this.leaveRemovedStart(partyId);
+            await this.removeLocalParty(partyId);
+            this.setStatus({ state: 'removed', partyId, removal, ...(formerPartyId !== undefined && { formerPartyId }) });
+        }
+        catch (err) {
+            console.warn(`[cadre-core/edge-node] acting on this app's removal from party ${partyId} failed:`, err);
+            this.setStatus({ state: 'failed', error: toError(err) });
+        }
+    }
+    /**
+     * Replace a saved start of `partyId` with {@link startAfterRemoval}'s, or delete it, before any
+     * of the party's storage goes, so no start builds that party again on deleted storage; returns
+     * the former party the new start names. A saved start of another party is left alone. Throws a
+     * failed read or write, and the storage then stays, matching the saved start that still names it.
+     */
+    async leaveRemovedStart(partyId) {
+        const saved = await this.readSavedStart();
+        if (saved?.options.partyId !== partyId)
+            return undefined;
+        const next = startAfterRemoval(saved);
+        if (next)
+            await this.nodeLocalSlot(this.names.savedStartKey).save(serializeSavedStart(next));
+        else
+            await this.deleteSavedStart();
+        return next?.options.partyId;
+    }
+    /**
+     * Delete `partyId`'s local storage with the dissolve's marked removal, after finishing one a
+     * failure left, so this marker does not replace it. A failure is logged: once the marker is
+     * written, the next start finishes the removal.
+     */
+    async removeLocalParty(partyId) {
+        try {
+            await this.finishMarkedRemoval();
+            await removeParty(this.partyStorage(), partyId);
+        }
+        catch (err) {
+            console.warn(`[cadre-core/edge-node] deleting the storage of party ${partyId}, which removed this app, failed:`, err);
+        }
+    }
+    // ── stop ─────────────────────────────────────────────────────────────────
+    async stopAndClearAutoStart() {
+        // NOTE: with no node running (the last start failed) the saved record is left alone, so an
+        // earlier `autoStart: true` survives this stop. The reference app offers Disconnect only
+        // while connected; if an app lets a user stop a node whose start failed, rewrite the
+        // saved record with `autoStart: false` here too.
+        if (this.runningOptions) {
+            await this.saveStart({ options: this.runningOptions, autoStart: false, writtenBy: this.platform.dataVersion });
+        }
+        await this.shutDown();
+    }
+    /**
+     * Stop the node and close every store, the node's references cleared first: a throwing
+     * `stop()` must not leave a node whose stores the `finally` has just closed, which the next
+     * `start` would hand back as running.
+     */
+    async shutDown() {
+        const stopping = this.current;
+        this.current = null;
+        this.runningOptions = null;
+        try {
+            if (stopping) {
+                for (const subscription of this.subscriptions)
+                    subscription.detach(stopping);
+                await stopping.stop();
+            }
+        }
+        finally {
+            // The node-local store first, flushed, then every raw store: the platform's contract.
+            await this.platform.storage.close();
+            this.setStatus({ state: 'stopped' });
+        }
+    }
+    // ── storage ──────────────────────────────────────────────────────────────
+    nodeLocalKv() {
+        return this.platform.storage.nodeLocal();
+    }
+    nodeLocalSlot(key) {
+        return kvStoreSlot(this.nodeLocalKv(), key);
+    }
+    /** The party's trusted-owner anchor: the platform's slot, else the node-local key. */
+    trustedOwnerSlot(partyId) {
+        return this.platform.storage.trustedOwnerSlot?.(partyId) ?? nodeLocalRemovableSlot(this.nodeLocalKv(), trustedOwnersKvKey(partyId));
+    }
+    partyStorage() {
+        return {
+            nodeLocal: this.nodeLocalKv(),
+            markerKey: this.names.dissolveMarkerKey,
+            savedStartKey: this.names.savedStartKey,
+            destroyScope: (scope) => this.platform.storage.destroyScope(scope),
+            trustedOwnerSlot: (partyId) => this.trustedOwnerSlot(partyId),
+            keyStore: this.keyStore,
+            moves: this.moves,
+        };
+    }
+    /** The saved start, read directly: inside a transition, `loadSavedStart` would wait on a stop queued behind it. */
+    async readSavedStart() {
+        return parseSavedStart(await this.nodeLocalSlot(this.names.savedStartKey).load());
+    }
+    /** Delete the saved start, durably; a failed write throws. */
+    async deleteSavedStart() {
+        const kv = this.nodeLocalKv();
+        await kv.delete(this.names.savedStartKey);
+        await kv.flush();
+    }
+    /** Best-effort: a failed write is logged and changes nothing about the node. */
+    async saveStart(saved) {
+        try {
+            await this.nodeLocalSlot(this.names.savedStartKey).save(serializeSavedStart(saved));
+        }
+        catch (err) {
+            console.warn('[cadre-core/edge-node] could not save the start options:', err);
+        }
+    }
+    setStatus(status) {
+        this.currentStatus = status;
+        for (const listener of this.statusListeners) {
+            try {
+                listener(status);
+            }
+            catch (err) {
+                console.warn('[cadre-core/edge-node] status listener threw:', err);
+            }
+        }
+    }
+}
+/** The default anchor slot: one node-local key, whose removal is durable when it resolves, as `kvStoreSlot`'s save is. */
+function nodeLocalRemovableSlot(kv, key) {
+    return {
+        ...kvStoreSlot(kv, key),
+        remove: async () => {
+            await kv.delete(key);
+            await kv.flush();
+        },
+    };
+}
+/** Abort `target` with `source`'s reason when `source` aborts; returns the unsubscribe. */
+function relayAbort(source, target) {
+    if (!source)
+        return () => { };
+    const abort = () => target.abort(source.reason);
+    if (source.aborted) {
+        abort();
+        return () => { };
+    }
+    source.addEventListener('abort', abort, { once: true });
+    return () => source.removeEventListener('abort', abort);
+}
+/** WebSockets to dial the party's machines and relays, and circuit relay to be reachable through one. */
+function defaultTransports() {
+    return [webSockets(), circuitRelayTransport()];
+}
+//# sourceMappingURL=edge-node.js.map