@net-mesh/sdk 0.19.0

package/dist/meshos.d.ts

@@ -0,0 +1,277 @@
+/**
+ * MeshOS daemon-author SDK — TypeScript wrapper.
+ *
+ * Sits on top of the napi-rs binding at `@net-mesh/core`. Adds:
+ *
+ * - {@link MeshOsDaemon} interface for daemon implementors.
+ * - Typed {@link DaemonControl} / {@link MaintenanceState} unions
+ *   the binding emits as plain POJOs.
+ * - {@link MeshOsSdkError} typed Error subclass that parses the
+ *   substrate `<<meshos-sdk-kind:KIND>>MSG` envelope into a
+ *   structured `.kind` field.
+ * - `AsyncIterable<DaemonControl>` over the raw `nextControl()`
+ *   napi method.
+ *
+ * Slice 1 (Phase 3) ships: `start` / `registerDaemon` /
+ * `nextControl` / `tryNextControl` / `publishLog` /
+ * `gracefulShutdown` / `metadata` / `refreshMetadata`. Capability
+ * publishing is a substrate-side stub (`publishCapabilities`
+ * returns without committing). Snapshot / restore work via the
+ * daemon object's optional methods; the supervisor invokes them
+ * on migration.
+ *
+ * @example
+ * ```ts
+ * import { Identity } from '@net-mesh/core';
+ * import { MeshOsDaemonSdk, type MeshOsDaemon } from '@net-mesh/sdk/meshos';
+ *
+ * const daemon: MeshOsDaemon = {
+ *   name: 'echo',
+ *   process: (event) => [event.payload],
+ * };
+ *
+ * const sdk = MeshOsDaemonSdk.start();
+ * const handle = sdk.registerDaemon(daemon, Identity.generate());
+ * handle.publishLog('info', 'started');
+ *
+ * for await (const ev of handle.controlEvents()) {
+ *   if (ev.kind === 'Shutdown') break;
+ * }
+ *
+ * await handle.gracefulShutdown(5_000n);
+ * await sdk.shutdown();
+ * ```
+ */
+import { MeshOsDaemonHandle as NapiHandle, type CausalEventJs, type Identity, type CapabilitySetJs } from '@net-mesh/core';
+/**
+ * Typed error raised by the MeshOS SDK. The Rust side embeds a
+ * `<<meshos-sdk-kind:KIND>>MSG` envelope in the message; this
+ * class parses the kind out so callers can branch programmatically
+ * instead of regexing the message.
+ */
+export declare class MeshOsSdkError extends Error {
+    readonly kind: string;
+    constructor(kind: string, message: string);
+    /**
+     * Parse the envelope on a caught napi error. Returns the typed
+     * subclass when the envelope is present; falls through to the
+     * original error otherwise.
+     */
+    static fromCaught(err: unknown): MeshOsSdkError | Error;
+}
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+export type DaemonControlShutdown = {
+    kind: 'Shutdown';
+    gracePeriodMs: bigint;
+};
+export type DaemonControlDrainStart = {
+    kind: 'DrainStart';
+    gracePeriodMs: bigint;
+};
+export type DaemonControlDrainFinish = {
+    kind: 'DrainFinish';
+};
+export type DaemonControlBackpressureOn = {
+    kind: 'BackpressureOn';
+    level: number;
+};
+export type DaemonControlBackpressureOff = {
+    kind: 'BackpressureOff';
+};
+export type DaemonControlUnknown = {
+    kind: 'Unknown';
+};
+export type DaemonControl = DaemonControlShutdown | DaemonControlDrainStart | DaemonControlDrainFinish | DaemonControlBackpressureOn | DaemonControlBackpressureOff | DaemonControlUnknown;
+export type MaintenanceStateActive = {
+    kind: 'Active';
+};
+export type MaintenanceStateEntering = {
+    kind: 'EnteringMaintenance';
+    sinceMs: bigint;
+    deadlineRemainingMs: bigint | null;
+};
+export type MaintenanceStateSteady = {
+    kind: 'Maintenance';
+    sinceMs: bigint;
+};
+export type MaintenanceStateExiting = {
+    kind: 'ExitingMaintenance';
+    sinceMs: bigint;
+};
+export type MaintenanceStateDrainFailed = {
+    kind: 'DrainFailed';
+    sinceMs: bigint;
+    reason: string;
+};
+export type MaintenanceStateRecovery = {
+    kind: 'Recovery';
+    sinceMs: bigint;
+};
+export type MaintenanceStateUnknown = {
+    kind: 'Unknown';
+};
+export type MaintenanceState = MaintenanceStateActive | MaintenanceStateEntering | MaintenanceStateSteady | MaintenanceStateExiting | MaintenanceStateDrainFailed | MaintenanceStateRecovery | MaintenanceStateUnknown;
+export type PeerHealth = 'Healthy' | 'Degraded' | 'Unreachable' | 'Unknown';
+export type PeerMaintenance = 'Active' | 'EnteringMaintenance' | 'Maintenance' | 'ExitingMaintenance' | 'DrainFailed' | 'Recovery' | 'Unknown';
+export interface PeerSnapshot {
+    rttMs: bigint | null;
+    health: PeerHealth | null;
+    maintenance: PeerMaintenance | null;
+    cpuLoad1m: number | null;
+    memUsedBytes: bigint | null;
+    memTotalBytes: bigint | null;
+    diskUsedBytes: bigint | null;
+    diskTotalBytes: bigint | null;
+    saturationTrend: number | null;
+    capabilitySet: string[];
+    softwareVersion: string | null;
+    forkedFrom: bigint | null;
+}
+export interface MetadataView {
+    nodeId: bigint;
+    daemonId: bigint;
+    daemonName: string;
+    maintenanceState: MaintenanceState;
+    /** Keyed by peer node id. The binding emits a list of entries
+     * so BigInt keys round-trip cleanly; we materialize a Map here. */
+    peers: Map<bigint, PeerSnapshot>;
+}
+export interface CausalEvent {
+    originHash: bigint;
+    sequence: bigint;
+    payload: Buffer;
+}
+/**
+ * Daemon health envelope. Either a plain string discriminator
+ * (`'healthy'` / `'degraded'` / `'unhealthy'`) or an object form
+ * carrying an optional `reason` that rides into the substrate's
+ * `Degraded { reason }` variant.
+ */
+export type DaemonHealth = 'healthy' | 'degraded' | 'unhealthy' | {
+    kind: 'healthy' | 'degraded' | 'unhealthy';
+    reason?: string;
+};
+/**
+ * Capability tag advertisement. Mirrors the `requiredCapabilities`
+ * / `optionalCapabilities` slot consumed by the substrate's
+ * placement filter. Either a static `string[]` or a `() => string[]`
+ * callable resolved once at registration time.
+ */
+export type CapabilityAdvert = string[] | (() => string[]);
+/**
+ * A MeshOS-supervised daemon. Required: `name` (string property) +
+ * `process(event)` (returns `Buffer[]` per inbound event, or `[]`
+ * for sinks).
+ *
+ * Optional methods (the substrate falls back to defaults if
+ * absent):
+ *  - `snapshot()` — returns the daemon's serialized state, or
+ *    `null` when stateless.
+ *  - `restore(state: Buffer)` — re-seed state at migration target.
+ *  - `onControl(event: DaemonControl)` — trait callback; the SDK
+ *    *also* delivers the same event over `controlEvents()`. Use
+ *    whichever delivery model fits.
+ *  - `health()` — return liveness state; default `'healthy'`.
+ *  - `saturation()` — return load factor in `[0.0, 1.0]`; default 0.
+ *
+ * Optional properties:
+ *  - `requiredCapabilities` / `optionalCapabilities` — static tag
+ *    list or callable returning one. Resolved once at registration
+ *    time and cached on the substrate side.
+ */
+export interface MeshOsDaemon {
+    name: string;
+    process(event: CausalEvent): Buffer[];
+    snapshot?(): Buffer | null;
+    restore?(state: Buffer): void;
+    onControl?(event: DaemonControl): void;
+    health?(): DaemonHealth;
+    saturation?(): number;
+    requiredCapabilities?: CapabilityAdvert;
+    optionalCapabilities?: CapabilityAdvert;
+}
+export interface MeshOsConfig {
+    thisNode?: bigint;
+    tickIntervalMs?: bigint;
+    eventQueueCapacity?: number;
+    actionQueueCapacity?: number;
+}
+export interface MeshOsDaemonSdkOptions {
+    /** Per-daemon control-channel capacity. Default 8 events. */
+    controlCapacity?: number;
+    /** Max time (ms) the bridge waits for a JS callback (`process`
+     * / `snapshot` / `restore` / `onControl`) to respond. Default
+     * 60_000. */
+    callbackTimeoutMs?: number;
+}
+export declare class MeshOsDaemonSdk {
+    private readonly raw;
+    private constructor();
+    /**
+     * Start the SDK with optional config + the substrate's
+     * `LoggingDispatcher`. Async so the napi-side factory runs in
+     * the napi tokio context (a nested local runtime would deadlock).
+     */
+    static start(config?: MeshOsConfig, options?: MeshOsDaemonSdkOptions): Promise<MeshOsDaemonSdk>;
+    /**
+     * Register a daemon under the supplied identity. The daemon
+     * object must satisfy {@link MeshOsDaemon}; the binding eagerly
+     * resolves `process` (and optional `snapshot` / `restore` /
+     * `onControl`) into TSFNs at registration time, so a missing
+     * `process` raises immediately rather than later on the first
+     * event.
+     */
+    registerDaemon(daemon: MeshOsDaemon, identity: Identity): Promise<MeshOsDaemonHandle>;
+    /** Diagnostic counter — total control events the router dropped
+     * across every registered daemon because a daemon's channel was
+     * full. */
+    droppedControlEvents(): Promise<bigint>;
+    /** Tear down the wrapped runtime. Subsequent calls throw
+     * `MeshOsSdkError(kind: "already_shutdown")`. */
+    shutdown(): Promise<void>;
+}
+export declare class MeshOsDaemonHandle {
+    private readonly raw;
+    constructor(raw: NapiHandle);
+    /** Substrate identifier (origin hash). Stable across the
+     * handle's lifetime, readable after shutdown. */
+    get daemonId(): bigint;
+    /** Daemon's `name` at registration. Readable after shutdown. */
+    get daemonName(): string;
+    /** Cached metadata view. Refresh via {@link refreshMetadata}. */
+    metadata(): Promise<MetadataView>;
+    /** Rebuild the metadata view from the runtime's latest snapshot. */
+    refreshMetadata(): Promise<MetadataView>;
+    /** Block until the next control event arrives, the runtime
+     * shuts down, or `timeoutMs` elapses. Resolves to the event or
+     * `null` on timeout / shutdown. */
+    nextControl(timeoutMs?: bigint): Promise<DaemonControl | null>;
+    /** Non-blocking control-event receive. Returns the next event
+     * or `null` if the channel is empty. */
+    tryNextControl(): Promise<DaemonControl | null>;
+    /** Async-iterable view over control events. Terminates when
+     * `gracefulShutdown` runs or the runtime exits. Use:
+     *
+     * ```ts
+     * for await (const ev of handle.controlEvents()) {
+     *   if (ev.kind === 'Shutdown') break;
+     * }
+     * ```
+     */
+    controlEvents(): AsyncIterable<DaemonControl>;
+    /** Publish a log line tagged with this daemon's id. Non-blocking
+     * on the substrate side; the napi call is async because every
+     * handle method serializes on the inner mutex. Throws
+     * `MeshOsSdkError(kind: "queue_full" | "loop_closed")` when the
+     * substrate's log ring is saturated. */
+    publishLog(level: LogLevel, message: string): Promise<void>;
+    /** Publish (or update) the daemon's capability set. Slice 1 is
+     * a substrate-side stub — the call returns without committing. */
+    publishCapabilities(caps?: CapabilitySetJs | null): Promise<void>;
+    /** Drive a graceful shutdown. Sends
+     * `Shutdown { gracePeriodMs }` on the daemon's control channel,
+     * parks for `graceMs`, then unregisters. Consumes the handle —
+     * subsequent calls throw `already_shutdown`. */
+    gracefulShutdown(graceMs?: bigint): Promise<void>;
+}
+export type { CausalEventJs };

package/dist/meshos.js

@@ -0,0 +1,359 @@
+"use strict";
+/**
+ * MeshOS daemon-author SDK — TypeScript wrapper.
+ *
+ * Sits on top of the napi-rs binding at `@net-mesh/core`. Adds:
+ *
+ * - {@link MeshOsDaemon} interface for daemon implementors.
+ * - Typed {@link DaemonControl} / {@link MaintenanceState} unions
+ *   the binding emits as plain POJOs.
+ * - {@link MeshOsSdkError} typed Error subclass that parses the
+ *   substrate `<<meshos-sdk-kind:KIND>>MSG` envelope into a
+ *   structured `.kind` field.
+ * - `AsyncIterable<DaemonControl>` over the raw `nextControl()`
+ *   napi method.
+ *
+ * Slice 1 (Phase 3) ships: `start` / `registerDaemon` /
+ * `nextControl` / `tryNextControl` / `publishLog` /
+ * `gracefulShutdown` / `metadata` / `refreshMetadata`. Capability
+ * publishing is a substrate-side stub (`publishCapabilities`
+ * returns without committing). Snapshot / restore work via the
+ * daemon object's optional methods; the supervisor invokes them
+ * on migration.
+ *
+ * @example
+ * ```ts
+ * import { Identity } from '@net-mesh/core';
+ * import { MeshOsDaemonSdk, type MeshOsDaemon } from '@net-mesh/sdk/meshos';
+ *
+ * const daemon: MeshOsDaemon = {
+ *   name: 'echo',
+ *   process: (event) => [event.payload],
+ * };
+ *
+ * const sdk = MeshOsDaemonSdk.start();
+ * const handle = sdk.registerDaemon(daemon, Identity.generate());
+ * handle.publishLog('info', 'started');
+ *
+ * for await (const ev of handle.controlEvents()) {
+ *   if (ev.kind === 'Shutdown') break;
+ * }
+ *
+ * await handle.gracefulShutdown(5_000n);
+ * await sdk.shutdown();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeshOsDaemonHandle = exports.MeshOsDaemonSdk = exports.MeshOsSdkError = void 0;
+const core_1 = require("@net-mesh/core");
+// ----------------------------------------------------------------------------
+// Typed error envelope
+// ----------------------------------------------------------------------------
+/**
+ * Typed error raised by the MeshOS SDK. The Rust side embeds a
+ * `<<meshos-sdk-kind:KIND>>MSG` envelope in the message; this
+ * class parses the kind out so callers can branch programmatically
+ * instead of regexing the message.
+ */
+class MeshOsSdkError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(`<<meshos-sdk-kind:${kind}>>${message}`);
+        this.name = 'MeshOsSdkError';
+        this.kind = kind;
+        Object.setPrototypeOf(this, MeshOsSdkError.prototype);
+    }
+    /**
+     * Parse the envelope on a caught napi error. Returns the typed
+     * subclass when the envelope is present; falls through to the
+     * original error otherwise.
+     */
+    static fromCaught(err) {
+        if (err instanceof MeshOsSdkError)
+            return err;
+        if (!(err instanceof Error)) {
+            return new Error(String(err));
+        }
+        const parsed = parseEnvelope(err.message);
+        if (!parsed)
+            return err;
+        return new MeshOsSdkError(parsed.kind, parsed.body);
+    }
+}
+exports.MeshOsSdkError = MeshOsSdkError;
+function parseEnvelope(message) {
+    const marker = '<<meshos-sdk-kind:';
+    const start = message.indexOf(marker);
+    if (start === -1)
+        return null;
+    const kindStart = start + marker.length;
+    const end = message.indexOf('>>', kindStart);
+    if (end === -1)
+        return null;
+    return { kind: message.slice(kindStart, end), body: message.slice(end + 2) };
+}
+/**
+ * Run an operation, rethrowing the envelope as a typed
+ * `MeshOsSdkError` whose `.kind` callers can branch on.
+ */
+function rethrow(fn) {
+    try {
+        return fn();
+    }
+    catch (e) {
+        throw MeshOsSdkError.fromCaught(e);
+    }
+}
+async function rethrowAsync(fn) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        throw MeshOsSdkError.fromCaught(e);
+    }
+}
+// ----------------------------------------------------------------------------
+// MeshOsDaemonSdk — entry point
+// ----------------------------------------------------------------------------
+class MeshOsDaemonSdk {
+    raw;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /**
+     * @internal Accessor for sibling SDK modules (currently the
+     * Deck SDK's `DeckClient.fromMeshos`) that need to compose
+     * against the underlying napi handle. Not part of the public
+     * API; calling it from consumer code is unsupported.
+     */
+    __rawNapiSdk() {
+        return this.raw;
+    }
+    /**
+     * Start the SDK with optional config + the substrate's
+     * `LoggingDispatcher`. Async so the napi-side factory runs in
+     * the napi tokio context (a nested local runtime would deadlock).
+     */
+    static async start(config, options) {
+        return rethrowAsync(async () => {
+            const raw = await core_1.MeshOsDaemonSdk.start(config ? toNapiConfig(config) : undefined, options?.controlCapacity, options?.callbackTimeoutMs);
+            return new MeshOsDaemonSdk(raw);
+        });
+    }
+    /**
+     * Register a daemon under the supplied identity. The daemon
+     * object must satisfy {@link MeshOsDaemon}; the binding eagerly
+     * resolves `process` (and optional `snapshot` / `restore` /
+     * `onControl`) into TSFNs at registration time, so a missing
+     * `process` raises immediately rather than later on the first
+     * event.
+     */
+    async registerDaemon(daemon, identity) {
+        return rethrowAsync(async () => {
+            // The napi `registerDaemon` accepts a plain object with the
+            // typed callable fields. Cast through `unknown` because the
+            // generated d.ts references an internal `DaemonObjectTsfns`
+            // type that isn't reified at the napi boundary.
+            const handle = await this.raw.registerDaemon(daemon, identity);
+            return new MeshOsDaemonHandle(handle);
+        });
+    }
+    /** Diagnostic counter — total control events the router dropped
+     * across every registered daemon because a daemon's channel was
+     * full. */
+    async droppedControlEvents() {
+        return rethrowAsync(() => this.raw.droppedControlEvents());
+    }
+    /** Tear down the wrapped runtime. Subsequent calls throw
+     * `MeshOsSdkError(kind: "already_shutdown")`. */
+    async shutdown() {
+        await rethrowAsync(() => this.raw.shutdown());
+    }
+}
+exports.MeshOsDaemonSdk = MeshOsDaemonSdk;
+// ----------------------------------------------------------------------------
+// MeshOsDaemonHandle — per-daemon handle
+// ----------------------------------------------------------------------------
+class MeshOsDaemonHandle {
+    raw;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /** Substrate identifier (origin hash). Stable across the
+     * handle's lifetime, readable after shutdown. */
+    get daemonId() {
+        return this.raw.daemonId;
+    }
+    /** Daemon's `name` at registration. Readable after shutdown. */
+    get daemonName() {
+        return this.raw.daemonName;
+    }
+    /** Cached metadata view. Refresh via {@link refreshMetadata}. */
+    async metadata() {
+        return rethrowAsync(async () => fromNapiMetadata(await this.raw.metadata()));
+    }
+    /** Rebuild the metadata view from the runtime's latest snapshot. */
+    async refreshMetadata() {
+        return rethrowAsync(async () => fromNapiMetadata(await this.raw.refreshMetadata()));
+    }
+    /** Block until the next control event arrives, the runtime
+     * shuts down, or `timeoutMs` elapses. Resolves to the event or
+     * `null` on timeout / shutdown. */
+    async nextControl(timeoutMs) {
+        return rethrowAsync(async () => {
+            const ev = await this.raw.nextControl(timeoutMs);
+            return ev ? fromNapiControl(ev) : null;
+        });
+    }
+    /** Non-blocking control-event receive. Returns the next event
+     * or `null` if the channel is empty. */
+    async tryNextControl() {
+        return rethrowAsync(async () => {
+            const ev = await this.raw.tryNextControl();
+            return ev ? fromNapiControl(ev) : null;
+        });
+    }
+    /** Async-iterable view over control events. Terminates when
+     * `gracefulShutdown` runs or the runtime exits. Use:
+     *
+     * ```ts
+     * for await (const ev of handle.controlEvents()) {
+     *   if (ev.kind === 'Shutdown') break;
+     * }
+     * ```
+     */
+    controlEvents() {
+        const handle = this;
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        try {
+                            const ev = await handle.nextControl();
+                            if (ev === null)
+                                return { value: undefined, done: true };
+                            return { value: ev, done: false };
+                        }
+                        catch (e) {
+                            // After `gracefulShutdown` the napi handle throws
+                            // `already_shutdown`. Terminate cleanly.
+                            const err = MeshOsSdkError.fromCaught(e);
+                            if (err instanceof MeshOsSdkError && err.kind === 'already_shutdown') {
+                                return { value: undefined, done: true };
+                            }
+                            throw err;
+                        }
+                    },
+                    async return() {
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        };
+    }
+    /** Publish a log line tagged with this daemon's id. Non-blocking
+     * on the substrate side; the napi call is async because every
+     * handle method serializes on the inner mutex. Throws
+     * `MeshOsSdkError(kind: "queue_full" | "loop_closed")` when the
+     * substrate's log ring is saturated. */
+    async publishLog(level, message) {
+        await rethrowAsync(() => this.raw.publishLog(level, message));
+    }
+    /** Publish (or update) the daemon's capability set. Slice 1 is
+     * a substrate-side stub — the call returns without committing. */
+    async publishCapabilities(caps) {
+        await rethrowAsync(() => this.raw.publishCapabilities(caps ?? null));
+    }
+    /** Drive a graceful shutdown. Sends
+     * `Shutdown { gracePeriodMs }` on the daemon's control channel,
+     * parks for `graceMs`, then unregisters. Consumes the handle —
+     * subsequent calls throw `already_shutdown`. */
+    async gracefulShutdown(graceMs) {
+        await rethrowAsync(() => this.raw.gracefulShutdown(graceMs));
+    }
+}
+exports.MeshOsDaemonHandle = MeshOsDaemonHandle;
+// ----------------------------------------------------------------------------
+// POJO converters
+// ----------------------------------------------------------------------------
+function toNapiConfig(c) {
+    return {
+        thisNode: c.thisNode,
+        tickIntervalMs: c.tickIntervalMs,
+        eventQueueCapacity: c.eventQueueCapacity,
+        actionQueueCapacity: c.actionQueueCapacity,
+    };
+}
+function fromNapiControl(ev) {
+    switch (ev.kind) {
+        case 'Shutdown':
+            return { kind: 'Shutdown', gracePeriodMs: ev.gracePeriodMs ?? 0n };
+        case 'DrainStart':
+            return { kind: 'DrainStart', gracePeriodMs: ev.gracePeriodMs ?? 0n };
+        case 'DrainFinish':
+            return { kind: 'DrainFinish' };
+        case 'BackpressureOn':
+            return { kind: 'BackpressureOn', level: ev.level ?? 0 };
+        case 'BackpressureOff':
+            return { kind: 'BackpressureOff' };
+        default:
+            return { kind: 'Unknown' };
+    }
+}
+function fromNapiMaintenance(m) {
+    switch (m.kind) {
+        case 'Active':
+            return { kind: 'Active' };
+        case 'EnteringMaintenance':
+            return {
+                kind: 'EnteringMaintenance',
+                sinceMs: m.sinceMs ?? 0n,
+                deadlineRemainingMs: m.deadlineRemainingMs ?? null,
+            };
+        case 'Maintenance':
+            return { kind: 'Maintenance', sinceMs: m.sinceMs ?? 0n };
+        case 'ExitingMaintenance':
+            return { kind: 'ExitingMaintenance', sinceMs: m.sinceMs ?? 0n };
+        case 'DrainFailed':
+            return {
+                kind: 'DrainFailed',
+                sinceMs: m.sinceMs ?? 0n,
+                reason: m.reason ?? '',
+            };
+        case 'Recovery':
+            return { kind: 'Recovery', sinceMs: m.sinceMs ?? 0n };
+        default:
+            return { kind: 'Unknown' };
+    }
+}
+function fromNapiPeer(p) {
+    return {
+        rttMs: p.rttMs ?? null,
+        health: p.health ?? null,
+        maintenance: p.maintenance ?? null,
+        // napi-derive emits `cpu_load_1m` as `cpuLoad1M` (camelCase
+        // capitalizes digit-adjacent letters); accept that form.
+        cpuLoad1m: p.cpuLoad1M ?? null,
+        memUsedBytes: p.memUsedBytes ?? null,
+        memTotalBytes: p.memTotalBytes ?? null,
+        diskUsedBytes: p.diskUsedBytes ?? null,
+        diskTotalBytes: p.diskTotalBytes ?? null,
+        saturationTrend: p.saturationTrend ?? null,
+        capabilitySet: p.capabilitySet,
+        softwareVersion: p.softwareVersion ?? null,
+        forkedFrom: p.forkedFrom ?? null,
+    };
+}
+function fromNapiMetadata(v) {
+    const peers = new Map();
+    for (const entry of v.peers) {
+        peers.set(entry.nodeId, fromNapiPeer(entry.snapshot));
+    }
+    return {
+        nodeId: v.nodeId,
+        daemonId: v.daemonId,
+        daemonName: v.daemonName,
+        maintenanceState: fromNapiMaintenance(v.maintenanceState),
+        peers,
+    };
+}