@net-mesh/sdk 0.19.0

package/dist/compute.js

@@ -0,0 +1,741 @@
+"use strict";
+/**
+ * Compute surface — `MeshDaemon` + `DaemonRuntime`.
+ *
+ * Stage 3 of `SDK_COMPUTE_SURFACE_PLAN.md`. Sub-step 1 lands the
+ * skeleton: a caller can build a runtime against an existing
+ * {@link MeshNode}, register a factory (stored but not yet
+ * invoked), start the runtime, and shut it down. Event delivery,
+ * migration, and snapshot/restore land in subsequent sub-steps.
+ *
+ * @example
+ * ```ts
+ * import { MeshNode, DaemonRuntime } from '@net-mesh/sdk';
+ *
+ * const mesh = await MeshNode.create({ bindAddr: '127.0.0.1:0', psk: '...' });
+ * const rt = DaemonRuntime.create(mesh);
+ *
+ * // Sub-step 1: register a factory shape the TS side can see.
+ * // Sub-step 2+ will actually invoke the returned object on
+ * // events delivered by Rust.
+ * rt.registerFactory('echo', () => ({
+ *   name: 'echo',
+ *   process: (event) => [event.payload],
+ * }));
+ *
+ * await rt.start();
+ * // ... daemons would run here (sub-step 3+) ...
+ * await rt.shutdown();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DaemonRuntime = exports.MigrationHandle = exports.DaemonHandle = exports.MigrationError = exports.DaemonError = void 0;
+const core_1 = require("@net-mesh/core");
+const _internal_js_1 = require("./_internal.js");
+// ----------------------------------------------------------------------------
+// Errors — `daemon:` prefix dispatch, mirrors identity/token/cortex pattern.
+// ----------------------------------------------------------------------------
+/**
+ * Base class for daemon-layer errors: factory registration, runtime
+ * lifecycle, spawn/stop, migration. The Rust side prefixes every
+ * message with `daemon:`; this file peels the prefix and rethrows
+ * the typed class so TS callers can `catch (e: DaemonError)`.
+ */
+class DaemonError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DaemonError';
+        Object.setPrototypeOf(this, DaemonError.prototype);
+    }
+}
+exports.DaemonError = DaemonError;
+/**
+ * Typed migration failure. Subclass of {@link DaemonError} so
+ * `catch (e: DaemonError)` still matches; callers who want to
+ * discriminate use `e instanceof MigrationError` + `e.kind`.
+ *
+ * **Retriability:** only `kind === 'not-ready'` is retriable
+ * (the source SDK auto-retries on this by default). Everything
+ * else is terminal — a caller's own retry loop won't help.
+ */
+class MigrationError extends DaemonError {
+    kind;
+    /** Number of NotReady retries on `not-ready-timeout`. */
+    attempts;
+    /** Daemon origin on `daemon-not-found` / `already-migrating`. */
+    originHash;
+    /** Node ID on `target-unavailable`. */
+    nodeId;
+    /** Size / max on `snapshot-too-large`. */
+    size;
+    max;
+    /** Underlying string detail on `state-failed` / `identity-transport-failed`. */
+    detail;
+    constructor(kind, message, extras = {}) {
+        super(message);
+        this.name = 'MigrationError';
+        this.kind = kind;
+        this.attempts = extras.attempts;
+        this.originHash = extras.originHash;
+        this.nodeId = extras.nodeId;
+        this.size = extras.size;
+        this.max = extras.max;
+        this.detail = extras.detail;
+        Object.setPrototypeOf(this, MigrationError.prototype);
+    }
+}
+exports.MigrationError = MigrationError;
+/**
+ * Parse a `migration: <kind>[: <detail>]` body (already stripped
+ * of the `daemon:` prefix) into a typed {@link MigrationError}.
+ * Unknown kinds fall back to `kind: 'unknown'` with the raw body
+ * as the message — defensive default so the error surface stays
+ * typed even if the Rust side adds new variants.
+ */
+function parseMigrationError(body, fullMessage) {
+    // Body shape (after stripping `migration: `):
+    //   <kind>
+    //   <kind>: <detail>
+    // For some kinds detail is parsed; for others it's free text.
+    const afterPrefix = body.slice('migration:'.length).trim();
+    const firstColon = afterPrefix.indexOf(':');
+    const kind = firstColon === -1 ? afterPrefix : afterPrefix.slice(0, firstColon).trim();
+    const rest = firstColon === -1 ? '' : afterPrefix.slice(firstColon + 1).trim();
+    switch (kind) {
+        case 'not-ready':
+        case 'factory-not-found':
+        case 'compute-not-supported':
+        case 'already-migrating': {
+            // `already-migrating` may also carry an originHash on the
+            // orchestrator path; parse it when present.
+            if (kind === 'already-migrating' && rest) {
+                return new MigrationError(kind, fullMessage, {
+                    originHash: parseMaybeHex(rest),
+                });
+            }
+            return new MigrationError(kind, fullMessage);
+        }
+        case 'state-failed':
+        case 'identity-transport-failed':
+            return new MigrationError(kind, fullMessage, { detail: rest });
+        case 'not-ready-timeout':
+            return new MigrationError(kind, fullMessage, {
+                attempts: Number.parseInt(rest, 10),
+            });
+        case 'daemon-not-found':
+            return new MigrationError(kind, fullMessage, {
+                originHash: parseMaybeHex(rest),
+            });
+        case 'target-unavailable':
+            return new MigrationError(kind, fullMessage, {
+                nodeId: parseMaybeHexBigInt(rest),
+            });
+        case 'wrong-phase':
+            return new MigrationError(kind, fullMessage, { detail: rest });
+        case 'snapshot-too-large': {
+            const [sizeStr, maxStr] = rest.split(':').map((s) => s.trim());
+            return new MigrationError(kind, fullMessage, {
+                size: Number.parseInt(sizeStr ?? '', 10),
+                max: Number.parseInt(maxStr ?? '', 10),
+            });
+        }
+        default:
+            return new MigrationError('unknown', fullMessage);
+    }
+}
+function parseMaybeHex(s) {
+    const trimmed = s.trim();
+    if (!trimmed)
+        return undefined;
+    const n = trimmed.startsWith('0x')
+        ? Number.parseInt(trimmed.slice(2), 16)
+        : Number.parseInt(trimmed, 10);
+    return Number.isFinite(n) ? n : undefined;
+}
+function parseMaybeHexBigInt(s) {
+    const trimmed = s.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        return trimmed.startsWith('0x') ? BigInt(trimmed) : BigInt(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+}
+function toDaemonError(e) {
+    const msg = e?.message ?? String(e);
+    if (msg.startsWith('daemon:')) {
+        const body = msg.slice('daemon:'.length).trim();
+        if (body.startsWith('migration:')) {
+            throw parseMigrationError(body, msg.slice('daemon:'.length).trim());
+        }
+        throw new DaemonError(body);
+    }
+    throw e;
+}
+// ----------------------------------------------------------------------------
+// DaemonHandle — thin wrapper over the NAPI handle.
+// ----------------------------------------------------------------------------
+/**
+ * Handle to a running daemon. Returned by
+ * {@link DaemonRuntime.spawn}; pass its `originHash` back to
+ * {@link DaemonRuntime.stop} to tear the daemon down.
+ *
+ * Cloning the JS object shares the same underlying daemon.
+ * Dropping the handle does **not** stop the daemon — callers must
+ * call `stop` explicitly.
+ */
+class DaemonHandle {
+    inner;
+    /** @internal */
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /**
+     * 64-bit hash of the daemon's identity — the key used by the
+     * registry, factory registry, and migration dispatcher.
+     */
+    get originHash() {
+        return this.inner.originHash;
+    }
+    /**
+     * Full 32-byte `EntityId` (ed25519 public key) of the daemon's
+     * identity. Returned as a `Buffer` to match the convention used
+     * by `Identity.entityId`.
+     */
+    get entityId() {
+        return this.inner.entityId;
+    }
+    /**
+     * Current runtime statistics for this daemon. Reads a live
+     * atomic snapshot from the registry — cheap enough to poll.
+     *
+     * Throws {@link DaemonError} if the daemon has been stopped.
+     */
+    stats() {
+        try {
+            return this.inner.stats();
+        }
+        catch (e) {
+            return toDaemonError(e);
+        }
+    }
+}
+exports.DaemonHandle = DaemonHandle;
+// ----------------------------------------------------------------------------
+// MigrationHandle — observe and abort an in-flight migration.
+// ----------------------------------------------------------------------------
+/**
+ * Handle to an in-flight migration. Returned by
+ * {@link DaemonRuntime.startMigration} /
+ * {@link DaemonRuntime.startMigrationWith}.
+ *
+ * Dropping the handle does NOT cancel the migration — the
+ * orchestrator keeps driving it to completion in the background.
+ * Keep the handle to observe phase transitions or request abort.
+ */
+class MigrationHandle {
+    inner;
+    /** @internal */
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /** 64-bit origin hash of the daemon being migrated. */
+    get originHash() {
+        return this.inner.originHash;
+    }
+    /** Node ID of the source (currently hosting) node. */
+    get sourceNode() {
+        return this.inner.sourceNode;
+    }
+    /** Node ID of the target (post-cutover) node. */
+    get targetNode() {
+        return this.inner.targetNode;
+    }
+    /**
+     * Current migration phase, or `null` once the migration has
+     * left the orchestrator's records (terminal success or abort).
+     * Callers distinguish success from abort by remembering the
+     * last non-null phase they observed.
+     */
+    phase() {
+        const p = this.inner.phase();
+        return p ?? null;
+    }
+    /**
+     * Async iterator that yields each distinct migration phase as
+     * the orchestrator transitions through them, and terminates
+     * cleanly once the migration reaches a terminal state (either
+     * `complete` on success, or abort / failure — the orchestrator
+     * record is gone either way).
+     *
+     * **Usage pattern:**
+     * ```ts
+     * const mig = await rt.startMigration(origin, a, b);
+     * const phases: MigrationPhase[] = [];
+     * for await (const phase of mig.phases()) {
+     *   phases.push(phase);
+     * }
+     * // Inspect `phases.at(-1)` — `'complete'` vs anything else
+     * // distinguishes success from abort / failure.
+     * ```
+     *
+     * **Call site ordering:** iterate as soon as the handle is
+     * returned. If you await `wait()` first and then call
+     * `phases()`, the orchestrator record may already be cleared
+     * and the iterator yields nothing.
+     *
+     * **Sampling cadence:** polls every 50 ms — matching the Rust
+     * SDK's `wait()` cadence. Phase transitions faster than that
+     * may be missed; acceptable for Stage 1 since real migrations
+     * spend hundreds of ms per phase on network round-trips. A
+     * broadcast-channel push replacement is documented as future
+     * work in `DAEMON_IDENTITY_MIGRATION_PLAN.md`.
+     */
+    async *phases() {
+        let last = null;
+        while (true) {
+            const current = this.phase();
+            if (current === null) {
+                // Orchestrator cleaned up — terminal state reached.
+                return;
+            }
+            if (current !== last) {
+                yield current;
+                last = current;
+            }
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    }
+    /**
+     * Block until the migration reaches a terminal state. Resolves
+     * on `complete`; rejects with {@link DaemonError} on abort or
+     * structured failure (target unavailable, restore failed, etc.).
+     *
+     * No wall-clock timeout — a migration stalled against an
+     * unresponsive peer blocks indefinitely. Use
+     * {@link MigrationHandle.waitWithTimeout} for a bound.
+     */
+    async wait() {
+        try {
+            await this.inner.wait();
+        }
+        catch (e) {
+            toDaemonError(e);
+        }
+    }
+    /**
+     * Like {@link wait} with a caller-controlled timeout (in
+     * milliseconds). On timeout the orchestrator record is aborted
+     * and the promise rejects with {@link DaemonError}.
+     */
+    async waitWithTimeout(timeoutMs) {
+        try {
+            await this.inner.waitWithTimeout(timeoutMs);
+        }
+        catch (e) {
+            toDaemonError(e);
+        }
+    }
+    /**
+     * Request cancellation of the migration. Best-effort: past
+     * `cutover` the routing flip cannot be undone cleanly, and
+     * this call resolves without aborting.
+     */
+    async cancel() {
+        try {
+            await this.inner.cancel();
+        }
+        catch (e) {
+            toDaemonError(e);
+        }
+    }
+}
+exports.MigrationHandle = MigrationHandle;
+// ----------------------------------------------------------------------------
+// DaemonRuntime — thin wrapper over the NAPI class.
+// ----------------------------------------------------------------------------
+/**
+ * Per-mesh compute runtime. Holds the kind-keyed factory table and
+ * drives the `Registering → Ready → ShuttingDown` lifecycle.
+ *
+ * Construct via {@link create}; the runtime shares the given mesh's
+ * underlying `MeshNode` (no second socket). Shutting down the
+ * runtime does NOT shut down the mesh — the caller owns that.
+ */
+class DaemonRuntime {
+    inner;
+    /**
+     * TS-side factory table, keyed by `kind`. `registerFactory`
+     * inserts here; `spawn` looks up and invokes. Duplicates the
+     * kind set that lives on the NAPI side — the NAPI copy drives
+     * migration-targeting and the `already registered` check at
+     * registration time; this map is what actually gets *called*.
+     */
+    factories = new Map();
+    constructor(inner) {
+        this.inner = inner;
+        // Register on the WeakMap so sibling SDK modules (currently
+        // `groups`) can reach the native pointer without a public
+        // escape-hatch method on the class instance. See
+        // `./_internal.ts` for the rationale.
+        (0, _internal_js_1.setNapiRuntime)(this, inner);
+    }
+    /**
+     * Build a compute runtime against an existing {@link MeshNode}.
+     */
+    static create(mesh) {
+        try {
+            return new DaemonRuntime(core_1.DaemonRuntime.create((0, _internal_js_1.getNapiMesh)(mesh)));
+        }
+        catch (e) {
+            return toDaemonError(e);
+        }
+    }
+    /**
+     * Promote to `Ready`. Installs the migration subprotocol handler.
+     * Idempotent on an already-ready runtime; rejects on a runtime
+     * that has been shut down.
+     */
+    async start() {
+        try {
+            await this.inner.start();
+        }
+        catch (e) {
+            toDaemonError(e);
+        }
+    }
+    /**
+     * Tear down the runtime. Drains daemons, clears factory
+     * registrations, uninstalls the migration handler. Idempotent:
+     * a second call on an already-shut-down runtime is a no-op.
+     */
+    async shutdown() {
+        try {
+            await this.inner.shutdown();
+        }
+        catch (e) {
+            toDaemonError(e);
+        }
+    }
+    /**
+     * `true` iff the runtime has transitioned to `Ready` and has not
+     * yet begun shutting down.
+     */
+    isReady() {
+        return this.inner.isReady();
+    }
+    /** Number of daemons currently registered with the runtime. */
+    daemonCount() {
+        return this.inner.daemonCount();
+    }
+    /**
+     * Register a factory closure under `kind`. The factory returns a
+     * {@link MeshDaemon}-shaped object. Second registration of the
+     * same `kind` throws {@link DaemonError}.
+     *
+     * Sub-step 1 stores the factory but does not invoke it — event
+     * dispatch to daemon `process` lands in sub-step 3.
+     *
+     * ## Migration targeting
+     *
+     * `registerFactory` alone is **not sufficient** to accept
+     * inbound migrations — it registers the kind-to-factory mapping
+     * only on the SDK side. Migrations lookup by `origin_hash`, not
+     * by kind. Future sub-steps will surface `expectMigration` and
+     * `registerMigrationTargetIdentity` for that wiring.
+     */
+    registerFactory(kind, factory) {
+        try {
+            // Register on NAPI so the kind is tracked for migration
+            // targeting and so the `already registered` check there
+            // fires on duplicate calls before we mutate our own map.
+            // The NAPI side stores a TSFN of the factory but doesn't
+            // invoke it — the actual invocation happens on the TS side
+            // at `spawn` time (see `spawn` below).
+            this.inner.registerFactory(kind, factory);
+            this.factories.set(kind, factory);
+        }
+        catch (e) {
+            toDaemonError(e);
+        }
+    }
+    /**
+     * Spawn a daemon of `kind` under the given {@link Identity}.
+     *
+     * Invokes the user-supplied factory (registered via
+     * {@link DaemonRuntime.registerFactory}), extracts the
+     * returned daemon's `process` / `snapshot` / `restore`
+     * methods, and hands each to NAPI as a separate JS function.
+     * NAPI builds a `ThreadsafeFunction` per method so the
+     * eventual event-dispatch path (sub-step 3) can call them
+     * from any tokio task.
+     *
+     * **Sub-step 2b** (current): method TSFNs are stored on the
+     * Rust side but **not yet invoked**. `process` / `snapshot` /
+     * `restore` behave as no-ops. Sub-step 3 wires the full
+     * round-trip so events land in the JS daemon.
+     *
+     * `kind` must have been registered first — spawning an
+     * unregistered kind throws {@link DaemonError}.
+     */
+    async spawn(kind, identity, config) {
+        const factory = this.factories.get(kind);
+        if (!factory) {
+            throw new DaemonError(`no factory registered for kind '${kind}'`);
+        }
+        // Invoke the factory in JS. Accepts both sync and async
+        // factories per the `DaemonFactory` type. The returned
+        // instance owns its own state (closures, class fields); the
+        // method bindings below capture `this` so per-instance state
+        // survives across calls.
+        const instance = await factory();
+        // Method extraction. `snapshot` / `restore` are optional —
+        // stateless daemons omit them. `bind(instance)` preserves
+        // `this` inside user code when NAPI invokes the function
+        // off the main thread via the TSFN.
+        //
+        // Shape conversion for `process`: the SDK `MeshDaemon.process`
+        // returns `Buffer[]`; NAPI's generated type is
+        // `(arg: CausalEventJs) => Buffer[]`. Signatures match in
+        // practice — the Rust side marshals a full `CausalEventJs`,
+        // and the SDK's `MeshDaemon` contract requires `Buffer[]`.
+        const process = instance.process.bind(instance);
+        const snapshot = instance.snapshot
+            ? instance.snapshot.bind(instance)
+            : undefined;
+        const restore = instance.restore
+            ? instance.restore.bind(instance)
+            : undefined;
+        try {
+            const handle = await this.inner.spawn(kind, identity.toNapi(), process, snapshot, restore, config
+                ? {
+                    autoSnapshotInterval: config.autoSnapshotInterval,
+                    maxLogEntries: config.maxLogEntries,
+                    callbackTimeoutMs: config.callbackTimeoutMs,
+                }
+                : undefined);
+            return new DaemonHandle(handle);
+        }
+        catch (e) {
+            return toDaemonError(e);
+        }
+    }
+    /**
+     * Spawn a daemon of `kind` from a previously-taken snapshot.
+     * Parallel to {@link DaemonRuntime.spawn} but seeds the
+     * daemon's initial state from `snapshotBytes` by calling its
+     * `restore` method before any events land.
+     *
+     * `snapshotBytes` must be the exact `Buffer` returned by a
+     * prior call to {@link DaemonRuntime.snapshot}; mismatched or
+     * corrupted bytes surface as `daemon: snapshot decode failed`.
+     *
+     * `kind` must be registered and the caller's {@link Identity}
+     * must match the snapshot's `entityId` — a mismatch throws
+     * {@link DaemonError} before any side effects.
+     */
+    async spawnFromSnapshot(kind, identity, snapshotBytes, config) {
+        const factory = this.factories.get(kind);
+        if (!factory) {
+            throw new DaemonError(`no factory registered for kind '${kind}'`);
+        }
+        // Same factory-decomposition dance as `spawn`: invoke in JS,
+        // extract methods, hand them to NAPI as separate functions.
+        // The daemon's initial (pre-restore) state is built by the
+        // factory here; the core's `from_snapshot` will then call
+        // `restore` on the bridge with `snapshotBytes`.
+        const instance = await factory();
+        const process = instance.process.bind(instance);
+        const snapshot = instance.snapshot
+            ? instance.snapshot.bind(instance)
+            : undefined;
+        const restore = instance.restore
+            ? instance.restore.bind(instance)
+            : undefined;
+        try {
+            const handle = await this.inner.spawnFromSnapshot(kind, identity.toNapi(), snapshotBytes, process, snapshot, restore, config
+                ? {
+                    autoSnapshotInterval: config.autoSnapshotInterval,
+                    maxLogEntries: config.maxLogEntries,
+                    callbackTimeoutMs: config.callbackTimeoutMs,
+                }
+                : undefined);
+            return new DaemonHandle(handle);
+        }
+        catch (e) {
+            return toDaemonError(e);
+        }
+    }
+    /**
+     * Take a snapshot of a running daemon by `originHash`. Returns
+     * the daemon's serialized state bytes, or `null` if the daemon
+     * is stateless (no `snapshot` method, or it returned `null`).
+     *
+     * The returned `Buffer` is opaque to the caller — the wire
+     * format is the core's `StateSnapshot` encoding, including
+     * version headers and the chain link at the snapshot point.
+     * Feed it unchanged to {@link DaemonRuntime.spawnFromSnapshot}
+     * to restore the daemon on another node or after a restart.
+     */
+    async snapshot(originHash) {
+        try {
+            const buf = await this.inner.snapshot(originHash);
+            return buf ?? null;
+        }
+        catch (e) {
+            return toDaemonError(e);
+        }
+    }
+    /**
+     * Stop a daemon, removing it from the runtime's registry.
+     * Idempotent during `ShuttingDown`; rejects with
+     * {@link DaemonError} during `Registering` or when the origin
+     * is unknown.
+     */
+    async stop(originHash) {
+        try {
+            await this.inner.stop(originHash);
+        }
+        catch (e) {
+            toDaemonError(e);
+        }
+    }
+    /**
+     * Deliver a single causal event to a live daemon and return
+     * the daemon's output buffers. Routes through the core
+     * `DaemonRegistry::deliver` → `MeshDaemon::process` path,
+     * which invokes the JS `process(event)` callback registered
+     * at spawn time and waits for its return.
+     *
+     * Direct ingress — Stage 1 convenience. Mesh-dispatched
+     * delivery (via the causal subprotocol on an inbound packet)
+     * lands in a later stage; this method stays as test sugar + a
+     * manual-trigger surface.
+     *
+     * Throws {@link DaemonError} if `originHash` doesn't match a
+     * live daemon, if the daemon's `process` throws, or if the
+     * runtime is shutting down.
+     */
+    async deliver(originHash, event) {
+        try {
+            return await this.inner.deliver(originHash, {
+                originHash: event.originHash,
+                sequence: event.sequence,
+                payload: event.payload,
+            });
+        }
+        catch (e) {
+            return toDaemonError(e);
+        }
+    }
+    /**
+     * Initiate a migration for the daemon identified by
+     * `originHash`, moving it from `sourceNode` to `targetNode`.
+     *
+     * Returns a {@link MigrationHandle} whose `wait()` resolves
+     * when the migration reaches a terminal state. On local-source
+     * migrations (`sourceNode === mesh.nodeId`) the snapshot is
+     * taken synchronously inside this call; on remote-source
+     * migrations the orchestrator drives the state machine via
+     * inbound wire messages.
+     *
+     * Both node IDs are `u64` — pass as `bigint` to avoid silent
+     * precision loss past 2^53.
+     */
+    async startMigration(originHash, sourceNode, targetNode) {
+        try {
+            const handle = await this.inner.startMigration(originHash, sourceNode, targetNode);
+            return new MigrationHandle(handle);
+        }
+        catch (e) {
+            return toDaemonError(e);
+        }
+    }
+    /**
+     * {@link startMigration} with caller-supplied options. Use this
+     * to opt out of identity transport (when the daemon doesn't
+     * need to sign on the target) or to tune the NotReady-retry
+     * budget.
+     */
+    async startMigrationWith(originHash, sourceNode, targetNode, opts) {
+        try {
+            const handle = await this.inner.startMigrationWith(originHash, sourceNode, targetNode, {
+                transportIdentity: opts.transportIdentity,
+                retryNotReadyMs: opts.retryNotReadyMs,
+            });
+            return new MigrationHandle(handle);
+        }
+        catch (e) {
+            return toDaemonError(e);
+        }
+    }
+    /**
+     * Declare that a migration will land on this node for the given
+     * `originHash` of `kind`. Registers a placeholder factory; the
+     * migration snapshot's identity envelope supplies the real
+     * keypair at restore time.
+     *
+     * Must be called BEFORE the source initiates the migration —
+     * the target dispatcher checks for a factory entry when the
+     * inbound `SnapshotReady` lands, and rejects with
+     * `FactoryNotFound` if nothing is registered.
+     *
+     * The source must migrate with `transportIdentity: true`
+     * (default). Without the envelope the dispatcher emits
+     * `IdentityTransportFailed` because the placeholder has no
+     * keypair. Use {@link registerMigrationTargetIdentity} for the
+     * explicit public-identity-migration case.
+     */
+    expectMigration(kind, originHash, config) {
+        try {
+            this.inner.expectMigration(kind, originHash, config
+                ? {
+                    autoSnapshotInterval: config.autoSnapshotInterval,
+                    maxLogEntries: config.maxLogEntries,
+                    callbackTimeoutMs: config.callbackTimeoutMs,
+                }
+                : undefined);
+        }
+        catch (e) {
+            toDaemonError(e);
+        }
+    }
+    /**
+     * Pre-register a target-side identity for a migration that
+     * will NOT carry an identity envelope (source used
+     * `transportIdentity: false`). The target holds the matching
+     * {@link Identity}; the dispatcher restores the daemon with
+     * that identity instead of overriding it from an envelope.
+     *
+     * For the common envelope-transport case, prefer
+     * {@link expectMigration} — the caller doesn't need to know
+     * the daemon's private key ahead of time.
+     */
+    registerMigrationTargetIdentity(kind, identity, config) {
+        try {
+            this.inner.registerMigrationTargetIdentity(kind, identity.toNapi(), config
+                ? {
+                    autoSnapshotInterval: config.autoSnapshotInterval,
+                    maxLogEntries: config.maxLogEntries,
+                    callbackTimeoutMs: config.callbackTimeoutMs,
+                }
+                : undefined);
+        }
+        catch (e) {
+            toDaemonError(e);
+        }
+    }
+    /**
+     * Query the orchestrator's current migration phase for
+     * `originHash`, or `null` if no migration is in flight for
+     * that origin. Works on any node — source, target, or an
+     * observer that heard the migration on the mesh.
+     */
+    migrationPhase(originHash) {
+        const p = this.inner.migrationPhase(originHash);
+        return p ?? null;
+    }
+}
+exports.DaemonRuntime = DaemonRuntime;