@serfab/cadre-core 1.16.0 → 1.18.0

package/dist/edge-node/config.js

@@ -0,0 +1,199 @@
+/**
+ * The edge node's `CadreNodeConfig` and how a start settles its owner key. Nothing here needs a
+ * node started, so a test can build the node shape an edge device runs.
+ */
+import { DEFAULT_IDENTITY_KEY_ID } from '../key-store.js';
+import { createOwnerKey, loadOwnerSigner } from '../owner-key-store.js';
+import { OWNER_KEY_MAX_LABEL } from '../owner-key-export.js';
+/**
+ * The edge node's config: transaction profile (Ring Zulu only, intermittent connectivity), no
+ * listen address unless the platform names one, reachability through the configured relays (if
+ * any) but never a hard requirement for one, every strand the control network lists, and no
+ * automatic hibernation (the app's lifecycle runner hibernates on background). Schema signing is
+ * left at cadre-core's fail-closed default; an app with unsigned schemas relaxes it in
+ * `EdgeNodePlatform.configure`.
+ */
+export function buildEdgeNodeConfig(inputs) {
+    return {
+        // Identity comes from the key store (loaded when present, generated and persisted on first
+        // run). Mutually exclusive with `privateKey`, which would take it out of the key store.
+        keyStore: inputs.keyStore,
+        identityKeyId: DEFAULT_IDENTITY_KEY_ID,
+        controlNetwork: {
+            partyId: inputs.partyId,
+            bootstrapNodes: inputs.bootstrapAddrs,
+        },
+        profile: 'transaction',
+        storage: {
+            provider: inputs.storageProvider,
+        },
+        network: {
+            transports: inputs.transports,
+            // An edge device accepts no inbound connection, so by default it listens on nothing:
+            // the only address it ever has is the `/p2p-circuit` address a relay reservation earns
+            // it. An explicitly empty `listenAddrs` stays empty through cadre-core's derivation, and
+            // naming a relay adds the bare `/p2p-circuit` search entry to it
+            // (`cadre-core/src/relay-addrs.ts` → `resolveListenAddrs`). A browser adds `/webrtc`.
+            listenAddrs: inputs.listenAddrs ?? [],
+            // Through this config field rather than `CadreNode.reserveRelays()`, which reaches the
+            // control node only: formation has the invitee dial the control node and then the strand
+            // nodes, so both need a circuit address.
+            //
+            // NOTE: naming a relay starts a reservation supervisor that runs for as long as the
+            // control node does, including while backgrounded (hibernation stops strands, not the
+            // control node): a 5 s local check while the reservation holds, a dial every backoff
+            // interval (2 s → 60 s) while it does not. If background battery use becomes a complaint,
+            // raise `checkMs`/`maxBackoffMs` in cadre-core rather than stopping the supervisor here,
+            // which would leave a device that silently stopped being invitable.
+            relayAddrs: inputs.relayAddrs,
+            // An edge device must come up with its relay down — on a plane, on dead Wi-Fi, or with
+            // none configured. A first reservation attempt that lands nothing is logged and retried in
+            // the background instead of failing `start()`. A malformed entry still throws.
+            requireRelay: false,
+            // The platform's Noise primitives (native SHA-256 / ChaCha20-Poly1305, and X25519 in
+            // `full` mode, on a phone); only local primitives change, not the wire protocol.
+            noiseCrypto: inputs.noiseCrypto,
+            // libp2p's `connection-gater` points its `react-native` and `browser` fields at a build
+            // that refuses to dial plain `ws://`, loopback and private addresses. A cadre-host node
+            // claimed by its code on the same Wi-Fi, an emulator reaching `10.0.2.2` and a self-run
+            // relay without TLS are all of those. Only the dial is permitted: the connection is still
+            // Noise, the pinned `/p2p/<id>` decides which machine answers, and membership is still
+            // gated by `denyDialPeer` and the inbound hooks. cadre-core hands this gater to strand nodes too.
+            ...(inputs.allowPrivateDial ? { connectionGater: { denyDialMultiaddr: () => false } } : {}),
+        },
+        strandFilter: { mode: 'all' },
+        hibernation: { enabled: false },
+        trustedOwners: { store: inputs.trustedOwnerStore },
+        bootstrapPeers: { store: inputs.bootstrapPeerStore },
+        enrolledMachines: { store: inputs.enrolledMachineStore },
+        strandNetworkState: { store: inputs.strandNetworkStateStore },
+    };
+}
+/**
+ * Default bound on {@link runOwnerGenesis} and {@link wireJoinedOwnerKey}: what a start can wait
+ * for its owner step, which runs control reads and one control write, before it goes on without
+ * it. Not derived from the link, since a start that waited out a stalled write (about 84 s, see
+ * `docs/cadre-consistency.md`) would be a start the user gave up on.
+ */
+// eslint-disable-next-line no-restricted-syntax -- cuts off by design: a start goes on without its owner step rather than wait out a stalled control write; see docs/cadre-consistency.md → "Deadlines Over Optimystic's Reads and Commits"
+export const DEFAULT_OWNER_GENESIS_TIMEOUT_MS = 60000;
+/** Default `EdgeNodeOptions.ownerKeyLabel`: the founding owner key's name on its `OwnerKey` row. */
+export const DEFAULT_OWNER_KEY_LABEL = 'phone';
+/**
+ * Refuses an `ownerKeyLabel` the founding `OwnerKey` row would refuse, so a start naming one
+ * fails outright: fail-soft genesis would only log it, on that start and every later one.
+ */
+export function requireOwnerKeyLabel(label) {
+    const length = label?.trim().length ?? 0;
+    if (length > OWNER_KEY_MAX_LABEL) {
+        throw new Error(`ownerKeyLabel must be at most ${OWNER_KEY_MAX_LABEL} characters (this one has ${length})`);
+    }
+}
+/** How often {@link wireJoinedOwnerKey} asks again for an owner key an owner grant just seated. */
+const GRANTED_OWNER_RECHECK_MS = 2000;
+/**
+ * The owner step of a party this app founded. On a party with no `OwnerKey` row yet, the owner
+ * slot's key (created there now unless the slot already holds one) becomes the founding owner
+ * under `label` and is wired for signing, which also lets the node author its own `CadrePeer` row.
+ * On a party that has owners, the slot's key is wired only when it is a live owner, and no key is
+ * created: a new one could not be seated without another owner's signature. A node must be an
+ * enrolled owner to publish strands, and `CadreNode.requestJoin` works only on one. A joined
+ * party's start runs {@link wireJoinedOwnerKey} instead.
+ *
+ * Fail-soft and bounded: a failure or a genesis that has not settled within `timeoutMs` is logged
+ * and returned, and the start stands — the app can still join discovered strands and sync. A
+ * genesis that times out keeps running; its later failure is logged.
+ *
+ * NOTE: the bound is here, in cadre-core, so every edge node gets it; a Node host runs genesis
+ * through the CLI's own flow instead. Since v1.10 a control write against an unresponsive member
+ * can hold the write lock for about 84 s, so an unbounded wait here would be a real stall. A bound
+ * on that write itself, in `ControlDatabase`, would make this one redundant; drop `timeoutMs` then.
+ */
+export function runOwnerGenesis(node, options) {
+    const label = options.label ?? DEFAULT_OWNER_KEY_LABEL;
+    return withinBound('owner self-genesis', enrollFoundedOwner(node, options.keyStore, label), options.timeoutMs ?? DEFAULT_OWNER_GENESIS_TIMEOUT_MS);
+}
+/**
+ * The owner step of a party this app joined: wire a key only when the party lists it as a live
+ * owner, never insert an `OwnerKey` row, so a joined app can neither seat itself as a founder nor
+ * anchor a key that is no owner's. Only the owner slot's key is tried: the key an owner grant
+ * seated, one imported here, or one an owner of the party added. The identity key is never
+ * tried, since a machine's network identity is never an owner key. Fail-soft and bounded as
+ * {@link runOwnerGenesis} is.
+ *
+ * `granted`: an owner grant has just made this app an owner, so a key not listed yet means the
+ * row has not reached this node, not that it is no owner. It is asked again every 2 s until it
+ * is wired or the bound passes; a start that timed out wires it on the next start.
+ */
+export function wireJoinedOwnerKey(node, options) {
+    let expired = false;
+    const wiring = async () => {
+        const held = await loadOwnerSigner(options.keyStore);
+        while (!(await wireJoinedOwner(node, held))) {
+            if (!options.granted)
+                return 'member';
+            await new Promise((resolve) => setTimeout(resolve, GRANTED_OWNER_RECHECK_MS));
+            // Past the bound the start has gone on as `'timed-out'`, and may have stopped the node.
+            if (expired)
+                return 'member';
+        }
+        return 'enrolled';
+    };
+    return withinBound('wiring the joined owner key', wiring(), options.timeoutMs ?? DEFAULT_OWNER_GENESIS_TIMEOUT_MS)
+        .finally(() => {
+        expired = true;
+    });
+}
+/** `settling`, or `'failed'` when it rejects (logged), or `'timed-out'` when it has not settled within `timeoutMs` (logged). */
+async function withinBound(label, settling, timeoutMs) {
+    const settled = settling.catch((err) => {
+        console.warn(`[cadre-core/edge-node] ${label} failed:`, err);
+        return 'failed';
+    });
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timed-out'), timeoutMs);
+    });
+    try {
+        const result = await Promise.race([settled, deadline]);
+        if (result === 'timed-out') {
+            console.warn(`[cadre-core/edge-node] ${label} has not settled after ${timeoutMs} ms; starting without it`);
+        }
+        return result;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function enrollFoundedOwner(node, keyStore, label) {
+    const controlDb = node.getControlDatabase();
+    if (!controlDb) {
+        throw new Error('control database unavailable after start; cannot run owner genesis');
+    }
+    const held = await loadOwnerSigner(keyStore);
+    if (await controlDb.hasOwnerKey()) {
+        return held ? wiredIfOwner(node, held) : 'member';
+    }
+    // Loaded rather than created when the slot already holds a key: one imported before founding,
+    // or one an iOS reinstall kept in the Keychain while the app's data went.
+    const founding = held ?? (await createOwnerKey(keyStore));
+    if (!(await controlDb.ensureOwnerKey(founding.publicKey, label))) {
+        // A row arrived between the two reads: the party has an owner now, so judge the key as above.
+        return wiredIfOwner(node, founding);
+    }
+    await node.useOwnerSigner(founding);
+    return 'enrolled';
+}
+async function wiredIfOwner(node, signer) {
+    return (await node.wireOwnKeyIfOwner(signer)) ? 'enrolled' : 'member';
+}
+/**
+ * Wire `held`, the owner slot's key, when the party lists it. A node takes one owner signer, so
+ * a signer already wired is asked about instead (is it still a live owner?) and never replaced.
+ */
+async function wireJoinedOwner(node, held) {
+    if (node.getOwnerSigner() !== null)
+        return await node.wireOwnKeyIfOwner();
+    return held !== undefined && (await node.wireOwnKeyIfOwner(held));
+}
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/edge-node/config.ts"],"names":[],"mappings":"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"}

package/dist/edge-node/dissolve.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Dissolving the party this app founded and left (docs/architecture.md → "An app joins an
+ * existing cadre" → "Dissolving the party it left"): the check that the running party holds
+ * everything the left one holds, and the removal of the left party's local storage. The same
+ * removal deletes a party whose owner removed this app ("Removed from A"), with no check.
+ *
+ * The removal is local: it writes nothing to either party's control database. A marker in the
+ * node-local database names the party from before the first deletion until after the saved
+ * start stops naming it, so a removal that a crash or a failed step interrupts is finished by
+ * the next start or the next dissolve without checking again: the decision to remove was made
+ * before the marker was written. Every step deletes what may already be gone.
+ */
+import type { StrandBundle, StrandHoldings } from '../strand-move.js';
+import type { CadreNode } from '../cadre-node.js';
+import type { KeyStore } from '../key-store.js';
+import { type NodeLocalKv } from './node-local.js';
+import type { RemovableSlot } from './platform.js';
+import { type EdgeNodeOptions } from './options.js';
+import { type PendingStrandMove, type StrandMoveRecords } from './strand-move.js';
+/** How `EdgeNode.dissolveFormerParty` runs. */
+export interface DissolveFormerPartyOptions {
+    /** Strand and pending-join ids of the former party to give up although the running party does not hold them; from a `FormerPartyNotEmptyError`. */
+    discard?: readonly string[];
+}
+/**
+ * `EdgeNode.dissolveFormerParty` refused, nothing stopped: moving the former party's strands has
+ * not finished. A move into the running party finishes with `finishStrandMove()`; one into
+ * another party is adopted only there.
+ */
+export declare class StrandMovePendingError extends Error {
+    readonly pending: PendingStrandMove;
+    constructor(pending: PendingStrandMove);
+}
+/** What keeps a former party from being dissolved: `FormerPartyNotEmptyError`'s lists. */
+interface FormerPartyRemains {
+    otherMachines: string[];
+    strandIds: string[];
+    pendingJoinIds: string[];
+}
+/** `EdgeNode.dissolveFormerParty` refused, nothing deleted: the former party holds what the running party lacks, or has other machines. */
+export declare class FormerPartyNotEmptyError extends Error {
+    readonly partyId: string;
+    /** Peer ids of `CadrePeer` rows other than this node's. Not discardable: removing them is the user's choice, made in that party. */
+    readonly otherMachines: string[];
+    /** Not held by the running party and not in `discard`. */
+    readonly strandIds: string[];
+    /** Open pending joins the running party does not hold, and not in `discard`. */
+    readonly pendingJoinIds: string[];
+    constructor(partyId: string, remains: FormerPartyRemains);
+}
+/** What the former party holds, read from a node started for it alone. */
+export interface FormerPartyContent {
+    bundle: StrandBundle;
+    /** Peer ids of its `CadrePeer` rows other than the reading node's. */
+    otherMachines: string[];
+}
+export declare function readFormerParty(node: CadreNode): Promise<FormerPartyContent>;
+/** The refusal `content` earns against what the running party holds, or null when it may be dissolved. */
+export declare function formerPartyRefusal(content: FormerPartyContent, holdings: StrandHoldings, discard: readonly string[], nowMs: number): FormerPartyNotEmptyError | null;
+/** The former party's start for {@link readFormerParty}: nothing to dial or reserve on, the running Noise mode. */
+export declare function formerPartyRead(partyId: string, running: EdgeNodeOptions): EdgeNodeOptions;
+/** `options` without `formerPartyId` when it names `partyId`. */
+export declare function withoutFormerParty(options: EdgeNodeOptions, partyId: string | undefined): EdgeNodeOptions;
+/** The edge node's storage a removal reaches. No handle on the party removed may be open. */
+export interface PartyStorage {
+    /** The node-local key-value store (`EdgeNodeStorage.nodeLocal`). */
+    nodeLocal: NodeLocalKv;
+    /** `EdgeNodeNames.dissolveMarkerKey`. */
+    markerKey: string;
+    /** `EdgeNodeNames.savedStartKey`. */
+    savedStartKey: string;
+    /** `EdgeNodeStorage.destroyScope`. */
+    destroyScope: (scope: string) => Promise<void>;
+    /** The party's trusted-owner anchor slot, the platform's own or the node-local default, for its removal. */
+    trustedOwnerSlot: (partyId: string) => RemovableSlot;
+    keyStore: KeyStore;
+    moves: StrandMoveRecords;
+}
+/** Mark `partyId` as being removed, then remove its local storage. Only once removing it is decided: a dissolve's check passed, or an owner removed this app. */
+export declare function removeParty(storage: PartyStorage, partyId: string): Promise<void>;
+/** Finish the removal a marker names, if any. */
+export declare function finishMarkedRemoval(storage: PartyStorage): Promise<void>;
+/** What {@link finishRemovalAtStart} found: the party the marker named, if any, and why finishing its removal failed, if it did. */
+export interface RemovalAtStart {
+    /** Absent when there was no marker, or when it could not be read (`error` says so). */
+    partyId?: string;
+    error?: Error;
+}
+/**
+ * {@link finishMarkedRemoval} before a start, which must then not keep the party it names as
+ * `formerPartyId`, finished or not. A failure is logged and reported, and the start goes on; the
+ * marker stays for the next.
+ */
+export declare function finishRemovalAtStart(storage: PartyStorage): Promise<RemovalAtStart>;
+export {};

package/dist/edge-node/dissolve.js

@@ -0,0 +1,184 @@
+/**
+ * Dissolving the party this app founded and left (docs/architecture.md → "An app joins an
+ * existing cadre" → "Dissolving the party it left"): the check that the running party holds
+ * everything the left one holds, and the removal of the left party's local storage. The same
+ * removal deletes a party whose owner removed this app ("Removed from A"), with no check.
+ *
+ * The removal is local: it writes nothing to either party's control database. A marker in the
+ * node-local database names the party from before the first deletion until after the saved
+ * start stops naming it, so a removal that a crash or a failed step interrupts is finished by
+ * the next start or the next dissolve without checking again: the decision to remove was made
+ * before the marker was written. Every step deletes what may already be gone.
+ */
+import { controlStorageScope } from '../storage-scope.js';
+import { exportStrandBundle, unheldBundleContent } from '../strand-move.js';
+import { KeyStoreJoinedStrandStore } from '../joined-strand-store.js';
+import { bootstrapPeersKvKey, enrolledMachinesKvKey, strandNetworkKvKey } from './node-local.js';
+import { parseSavedStart, serializeSavedStart } from './options.js';
+import { toError } from './strand-move.js';
+/**
+ * `EdgeNode.dissolveFormerParty` refused, nothing stopped: moving the former party's strands has
+ * not finished. A move into the running party finishes with `finishStrandMove()`; one into
+ * another party is adopted only there.
+ */
+export class StrandMovePendingError extends Error {
+    constructor(pending) {
+        super(`Cannot dissolve party ${pending.fromPartyId}: moving its strands into party ${pending.toPartyId} has not finished`);
+        this.pending = pending;
+        this.name = 'StrandMovePendingError';
+    }
+}
+/** `EdgeNode.dissolveFormerParty` refused, nothing deleted: the former party holds what the running party lacks, or has other machines. */
+export class FormerPartyNotEmptyError extends Error {
+    constructor(partyId, remains) {
+        super(`Cannot dissolve party ${partyId}: ${describeRemains(remains)}`);
+        this.name = 'FormerPartyNotEmptyError';
+        this.partyId = partyId;
+        this.otherMachines = remains.otherMachines;
+        this.strandIds = remains.strandIds;
+        this.pendingJoinIds = remains.pendingJoinIds;
+    }
+}
+export async function readFormerParty(node) {
+    const self = node.peerId?.toString();
+    const machines = new Set((await node.listMembers()).map((member) => member.peerId));
+    return { bundle: await exportStrandBundle(node), otherMachines: [...machines].filter((peerId) => peerId !== self) };
+}
+/** The refusal `content` earns against what the running party holds, or null when it may be dissolved. */
+export function formerPartyRefusal(content, holdings, discard, nowMs) {
+    const discarded = new Set(discard);
+    const unheld = unheldBundleContent(content.bundle, holdings, nowMs);
+    const remains = {
+        otherMachines: content.otherMachines,
+        strandIds: unheld.strandIds.filter((strandId) => !discarded.has(strandId)),
+        pendingJoinIds: unheld.pendingJoinIds.filter((joinId) => !discarded.has(joinId)),
+    };
+    const empty = remains.otherMachines.length + remains.strandIds.length + remains.pendingJoinIds.length === 0;
+    return empty ? null : new FormerPartyNotEmptyError(content.bundle.partyId, remains);
+}
+/** The former party's start for {@link readFormerParty}: nothing to dial or reserve on, the running Noise mode. */
+export function formerPartyRead(partyId, running) {
+    return {
+        partyId,
+        bootstrapAddrs: [],
+        relayAddrs: [],
+        ...(running.noiseCryptoMode !== undefined && { noiseCryptoMode: running.noiseCryptoMode }),
+    };
+}
+/** `options` without `formerPartyId` when it names `partyId`. */
+export function withoutFormerParty(options, partyId) {
+    if (partyId === undefined || options.formerPartyId !== partyId)
+        return options;
+    const { formerPartyId: _dissolved, ...rest } = options;
+    return rest;
+}
+const MARKER_VERSION = 1;
+/** Mark `partyId` as being removed, then remove its local storage. Only once removing it is decided: a dissolve's check passed, or an owner removed this app. */
+export async function removeParty(storage, partyId) {
+    await storage.nodeLocal.set(storage.markerKey, JSON.stringify({ v: MARKER_VERSION, partyId }));
+    // On disk before the first deletion, so a crash during the removal leaves the marker that finishes it.
+    await storage.nodeLocal.flush();
+    await finishRemoving(storage, partyId);
+}
+/**
+ * The party a begun dissolve names, or `undefined`. A marker that does not parse is deleted with
+ * a warning: nothing can finish it, and the party it named keeps what is left of its storage.
+ */
+async function markedParty(storage) {
+    const text = await storage.nodeLocal.get(storage.markerKey);
+    if (text === undefined)
+        return undefined;
+    const partyId = parseMarker(text);
+    if (partyId === undefined) {
+        console.warn(`[cadre-core/edge-node] deleting the dissolve marker ${storage.markerKey}: it is not one this kit wrote`);
+        await storage.nodeLocal.delete(storage.markerKey);
+    }
+    return partyId;
+}
+/** Finish the removal a marker names, if any. */
+export async function finishMarkedRemoval(storage) {
+    const partyId = await markedParty(storage);
+    if (partyId !== undefined)
+        await finishRemoving(storage, partyId);
+}
+/**
+ * {@link finishMarkedRemoval} before a start, which must then not keep the party it names as
+ * `formerPartyId`, finished or not. A failure is logged and reported, and the start goes on; the
+ * marker stays for the next.
+ */
+export async function finishRemovalAtStart(storage) {
+    let partyId;
+    try {
+        partyId = await markedParty(storage);
+        if (partyId !== undefined)
+            await finishRemoving(storage, partyId);
+        return { partyId };
+    }
+    catch (err) {
+        console.warn('[cadre-core/edge-node] finishing the removal of a dissolved party failed; the next start retries:', err);
+        return { partyId, error: toError(err) };
+    }
+}
+/**
+ * Delete what is left of `partyId`'s local storage, then the marker: its control database, its
+ * node-local records, its trusted-owner anchor, its unpublished joined-strand records and its move
+ * record; then the saved start stops naming it as `formerPartyId`.
+ *
+ * NOTE: strand databases stay. A strand's storage scope is its strand id, not the party, so a
+ * moved strand's database is the running party's copy; a discarded strand's is left too, for the
+ * running party to reuse if it joins that strand again. If discarded strands' storage ever needs
+ * reclaiming, delete it here only for a strand no party on this device holds.
+ */
+async function finishRemoving(storage, partyId) {
+    await storage.destroyScope(controlStorageScope(partyId));
+    for (const key of [bootstrapPeersKvKey(partyId), enrolledMachinesKvKey(partyId), strandNetworkKvKey(partyId)]) {
+        await storage.nodeLocal.delete(key);
+    }
+    await storage.trustedOwnerSlot(partyId).remove();
+    await forgetJoinedStrands(storage.keyStore, partyId);
+    await storage.moves.remove(partyId);
+    await dropFromSavedStart(storage, partyId);
+    await storage.nodeLocal.delete(storage.markerKey);
+    // One batch: the saved start stops naming the party in the same write that deletes the marker.
+    await storage.nodeLocal.flush();
+}
+async function forgetJoinedStrands(keyStore, partyId) {
+    const joins = new KeyStoreJoinedStrandStore(keyStore, partyId);
+    for (const record of await joins.list())
+        await joins.forget(record.Id);
+}
+/** A write that throws, unlike the runtime's best-effort save, so a failure keeps the marker for the next start. */
+async function dropFromSavedStart(storage, partyId) {
+    const saved = parseSavedStart(await storage.nodeLocal.get(storage.savedStartKey));
+    if (saved?.options.formerPartyId !== partyId)
+        return;
+    await storage.nodeLocal.set(storage.savedStartKey, serializeSavedStart({ ...saved, options: withoutFormerParty(saved.options, partyId) }));
+}
+/** The party id in a marker's `text`, or `undefined` (logged) when it is not a marker. */
+function parseMarker(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        console.warn('[cadre-core/edge-node] the dissolve marker is not JSON:', err);
+        return undefined;
+    }
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const { v, partyId } = raw;
+    return v === MARKER_VERSION && typeof partyId === 'string' && partyId.length > 0 ? partyId : undefined;
+}
+/** "other machines are in it (…); the running party does not hold strands …": the non-empty lists. */
+function describeRemains(remains) {
+    const parts = [
+        listed('other machines are in it', remains.otherMachines),
+        listed('the running party does not hold its strands', remains.strandIds),
+        listed('the running party does not hold its open pending joins', remains.pendingJoinIds),
+    ].filter((part) => part !== null);
+    return parts.join('; ');
+}
+function listed(what, ids) {
+    return ids.length === 0 ? null : `${what} (${ids.join(', ')})`;
+}
+//# sourceMappingURL=dissolve.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dissolve.js","sourceRoot":"","sources":["../../src/edge-node/dissolve.ts"],"names":[],"mappings":"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"}

package/dist/edge-node/edge-join.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `EdgeNode.joinCadre`'s sequence: redeem in place on a node already running in the credential's
+ * party, or stop the running node, start one in that party, redeem there and go back on any
+ * failure (docs/architecture.md → "An app joins an existing cadre"). The credential is a machine
+ * invitation, which admits the app as a machine, or an owner grant, which makes it a machine and
+ * an owner at once ({@link JoinCredential}). Runs over a narrow view of the runtime
+ * ({@link JoinRuntime}), inside one of its transitions.
+ */
+import type { CadreNode } from '../cadre-node.js';
+import type { OwnerSigner } from '../owner-signer.js';
+import type { OwnerGenesisResult } from './config.js';
+import type { EdgeNodeStatus, JoinCadreOptions, JoinCadreResult } from './edge-node.js';
+import { type JoinCredential } from './join-credential.js';
+import type { EdgeNodeOptions, SavedStart } from './options.js';
+import { type StrandMoveRecords } from './strand-move.js';
+/** The part of the edge-node runtime a join drives. Every call runs inside the join's own transition. */
+export interface JoinRuntime {
+    /** The running node, or null. */
+    readonly node: CadreNode | null;
+    /** The options the running node was started with; null unless running. */
+    readonly runningOptions: EdgeNodeOptions | null;
+    readonly moves: StrandMoveRecords;
+    readonly status: EdgeNodeStatus;
+    setStatus(status: EdgeNodeStatus): void;
+    readSavedStart(): Promise<SavedStart | undefined>;
+    /** Stop the node and close every store; nothing runs afterwards. */
+    shutDown(): Promise<void>;
+    /** Build and start the node for `options`, subscriptions attached; nothing saved, nothing reported. */
+    bringUp(options: EdgeNodeOptions): Promise<{
+        node: CadreNode;
+        resolved: EdgeNodeOptions;
+    }>;
+    /** Start a node for `options`' party only to run `read` on it, then stop it. */
+    readAlone<T>(options: EdgeNodeOptions, read: (node: CadreNode) => Promise<T>, purpose: string): Promise<T>;
+    /** A full start: bring up, settle the owner key, adopt waiting moves, save and report `running`. */
+    buildAndStart(options: EdgeNodeOptions): Promise<CadreNode>;
+    /** The owner slot's key, created when the slot is empty: the key an owner grant seats. */
+    ownerSlotSigner(): Promise<OwnerSigner>;
+    /** `granted`: an owner grant has just seated the slot's key, so wait for the row. */
+    wireJoinedOwner(node: CadreNode, granted: boolean): Promise<OwnerGenesisResult>;
+    saveRunningStart(resolved: EdgeNodeOptions): Promise<void>;
+    reportRunning(node: CadreNode, resolved: EdgeNodeOptions, owner: OwnerGenesisResult): void;
+}
+export declare function joinCadre(runtime: JoinRuntime, credential: JoinCredential, options: JoinCadreOptions, signal: AbortSignal): Promise<JoinCadreResult>;