@serfab/cadre-host 0.8.1 → 0.10.0

package/dist/donation/__tests__/fake-orchestrator.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared fake orchestrator for the donation unit tests — no real child
+ * processes. Records every create / stop / remove, hands out deterministic
+ * unique spawn results, and tracks per-`dockerId` liveness so a test can crash
+ * one node and let the supervisor observe exactly that one as down.
+ *
+ * This file holds no tests of its own; its contract is pinned by the sibling
+ * `fake-orchestrator.test.ts`, which exists so a future agent cannot make a
+ * failing donation test go green by relaxing the fake.
+ */
+import type { Orchestrator, OrchestratorCreateRequest, OrchestratorCreateResult, OrchestratorStats } from '@serfab/cadre-provider';
+import type { ManagedNodeInfo, NodeStateListener } from '../../orchestrator/types.js';
+/**
+ * Mirrors the parts of `HostProcessOrchestrator`'s handle lifecycle the donation
+ * code depends on:
+ *
+ * - a **successful** `createContainer` drops every prior handle for the same
+ *   `containerId` (the real `dropStaleHandle`), so an old `dockerId` stops
+ *   resolving the moment its container re-spawns;
+ * - a **failed** `createContainer` leaves those handles exactly as it found them
+ *   (the real `restoreDroppedHandles`);
+ * - `stopContainer` / `removeContainer` throw `Container not found: <dockerId>`
+ *   for a handle this orchestrator no longer knows (the real `requireHandle`);
+ * - `reclaimWorkdir` refuses a containerId that still resolves to a live
+ *   handle (the real guard — that directory belongs to `removeContainer`).
+ *
+ * Consequently `stopped` / `removed` mean **"handles this orchestrator actually
+ * acted on"**, not "calls attempted" — a stop aimed at a dropped handle is
+ * rejected and never appears. `onStop` still fires for those rejected calls, so
+ * a test can observe the attempt separately from its outcome.
+ */
+export declare class FakeOrchestrator implements Orchestrator {
+    createCalls: OrchestratorCreateRequest[];
+    stopped: string[];
+    removed: string[];
+    /**
+     * Container ids whose workdir this orchestrator actually removed. Same
+     * "acted on, not attempted" rule as `stopped` / `removed`: a refused reclaim
+     * leaves no entry.
+     */
+    reclaimedWorkdirs: string[];
+    failCreate: boolean;
+    createDelayMs: number;
+    /**
+     * Observation hook — lets a test inspect the world as the stop happens. Fires
+     * even when the handle is unknown and the stop is then rejected.
+     */
+    onStop?: (dockerId: string) => void;
+    /**
+     * Observation hook — fires before the spawn resolves or fails, modelling the
+     * real class's *pre-drop* `await` window (`ensureNodeIdentity`, `resolvePush`).
+     * Work driven from here sees the previous handle still alive. Contrast
+     * {@link onSpawned}.
+     */
+    onCreate?: (request: OrchestratorCreateRequest) => void;
+    /**
+     * Observation hook — fires once the drop has landed and the new child is
+     * registered, immediately before `createContainer` resolves. Models the
+     * microtask gap between the real `createContainer` returning and its caller's
+     * `await` resuming: the real drop → launch → return runs synchronously, so
+     * this is the earliest point other code can observe the post-drop world.
+     * Contrast {@link onCreate}.
+     */
+    onSpawned?: (dockerId: string) => void;
+    /** Observation hook — fires before the liveness answer is computed. */
+    onIsRunning?: (dockerId: string) => void;
+    private readonly children;
+    private readonly listeners;
+    private counter;
+    createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult>;
+    stopContainer(dockerId: string): Promise<void>;
+    removeContainer(dockerId: string): Promise<void>;
+    /**
+     * NOTE: this and {@link getLogs} take an unknown `dockerId` where the real
+     * class throws (`requireHandle`). No donation path calls either, so the gap is
+     * unobservable — route them through `requireChild` if one starts to.
+     */
+    getStats(): Promise<OrchestratorStats>;
+    /** Unknown handles read as not running, matching the real orchestrator. */
+    isRunning(dockerId: string): Promise<boolean>;
+    /** Resolve a spawn's friendly containerId back to its dockerId. */
+    resolveDockerId(containerId: string): string | undefined;
+    /**
+     * Remove the workdir of a container no handle owns, mirroring the real
+     * `reclaimWorkdir`. Refuses (returns `false`, records nothing) while a child
+     * for that containerId still resolves — that directory belongs to
+     * `removeContainer`, which stops the child first.
+     *
+     * There is no directory here to check for existence, so a first reclaim of an
+     * unresolvable id always reports `true`; the real class returns `false` when
+     * the path is already gone. Nothing in the donation layer branches on the
+     * return value, so the gap is unobservable — model it if one starts to.
+     */
+    reclaimWorkdir(containerId: string): boolean;
+    getLogs(): Promise<string>;
+    onStateChange(listener: NodeStateListener): () => void;
+    /** Kill a child out from under the host — the crash the supervisor exists for. */
+    crash(dockerId: string): void;
+    /** Emit an arbitrary state change (e.g. the owner node stopping). */
+    emit(info: ManagedNodeInfo): void;
+    /** Mirrors `HostProcessOrchestrator.requireHandle` — unknown handles throw. */
+    private requireChild;
+}

package/dist/donation/__tests__/fake-orchestrator.js

@@ -0,0 +1,180 @@
+/**
+ * Shared fake orchestrator for the donation unit tests — no real child
+ * processes. Records every create / stop / remove, hands out deterministic
+ * unique spawn results, and tracks per-`dockerId` liveness so a test can crash
+ * one node and let the supervisor observe exactly that one as down.
+ *
+ * This file holds no tests of its own; its contract is pinned by the sibling
+ * `fake-orchestrator.test.ts`, which exists so a future agent cannot make a
+ * failing donation test go green by relaxing the fake.
+ */
+function sleep(ms) {
+    return new Promise((res) => setTimeout(res, ms));
+}
+/**
+ * Mirrors the parts of `HostProcessOrchestrator`'s handle lifecycle the donation
+ * code depends on:
+ *
+ * - a **successful** `createContainer` drops every prior handle for the same
+ *   `containerId` (the real `dropStaleHandle`), so an old `dockerId` stops
+ *   resolving the moment its container re-spawns;
+ * - a **failed** `createContainer` leaves those handles exactly as it found them
+ *   (the real `restoreDroppedHandles`);
+ * - `stopContainer` / `removeContainer` throw `Container not found: <dockerId>`
+ *   for a handle this orchestrator no longer knows (the real `requireHandle`);
+ * - `reclaimWorkdir` refuses a containerId that still resolves to a live
+ *   handle (the real guard — that directory belongs to `removeContainer`).
+ *
+ * Consequently `stopped` / `removed` mean **"handles this orchestrator actually
+ * acted on"**, not "calls attempted" — a stop aimed at a dropped handle is
+ * rejected and never appears. `onStop` still fires for those rejected calls, so
+ * a test can observe the attempt separately from its outcome.
+ */
+export class FakeOrchestrator {
+    constructor() {
+        this.createCalls = [];
+        this.stopped = [];
+        this.removed = [];
+        /**
+         * Container ids whose workdir this orchestrator actually removed. Same
+         * "acted on, not attempted" rule as `stopped` / `removed`: a refused reclaim
+         * leaves no entry.
+         */
+        this.reclaimedWorkdirs = [];
+        this.failCreate = false;
+        this.createDelayMs = 0;
+        this.children = new Map();
+        this.listeners = new Set();
+        this.counter = 0;
+    }
+    async createContainer(request) {
+        this.createCalls.push(request);
+        this.onCreate?.(request);
+        if (this.createDelayMs)
+            await sleep(this.createDelayMs);
+        if (this.failCreate)
+            throw new Error('spawn boom');
+        // Drop the prior handles for this container, mirroring `dropStaleHandle`.
+        // Success-only, and placed here on purpose: the real drop happens after the
+        // spawn's every `await` and cannot fail afterwards, and a create that throws
+        // puts the handles back (`restoreDroppedHandles`) — so a failed create must
+        // leave them untouched. `DonationSupervisor`'s give-up test depends on that.
+        for (const [id, child] of this.children) {
+            if (child.containerId === request.containerId)
+                this.children.delete(id);
+        }
+        const n = ++this.counter;
+        const dockerId = `dock_${n}`;
+        this.children.set(dockerId, {
+            containerId: request.containerId,
+            partyId: request.partyId,
+            profile: request.profile,
+            running: true,
+        });
+        this.onSpawned?.(dockerId);
+        return {
+            dockerId,
+            healthEndpoint: `http://127.0.0.1:${9000 + n}/health`,
+            metricsEndpoint: `http://127.0.0.1:${9000 + n}/metrics`,
+            seedEndpoint: `http://127.0.0.1:${9000 + n}/seed`,
+            seedToken: `seed-token-${n}`,
+            p2pPort: 4000 + n,
+        };
+    }
+    async stopContainer(dockerId) {
+        // Before the check: a test may want to observe that a stop was *attempted*
+        // even when this orchestrator rejects it.
+        this.onStop?.(dockerId);
+        const child = this.requireChild(dockerId);
+        this.stopped.push(dockerId);
+        child.running = false;
+    }
+    async removeContainer(dockerId) {
+        // NOTE: the real `removeContainer` stops a still-live child first; this one
+        // only deletes, so a remove aimed at a running child records no `stopped`
+        // entry and emits no state change. Every donation caller stops before it
+        // reclaims, so nothing sees the difference today — if one stops doing that,
+        // stop the child here too.
+        this.requireChild(dockerId);
+        this.removed.push(dockerId);
+        this.children.delete(dockerId);
+    }
+    /**
+     * NOTE: this and {@link getLogs} take an unknown `dockerId` where the real
+     * class throws (`requireHandle`). No donation path calls either, so the gap is
+     * unobservable — route them through `requireChild` if one starts to.
+     */
+    async getStats() {
+        return { cpuPercent: 0, memoryBytes: 0, networkRxBytes: 0, networkTxBytes: 0 };
+    }
+    /** Unknown handles read as not running, matching the real orchestrator. */
+    async isRunning(dockerId) {
+        this.onIsRunning?.(dockerId);
+        return this.children.get(dockerId)?.running ?? false;
+    }
+    /** Resolve a spawn's friendly containerId back to its dockerId. */
+    resolveDockerId(containerId) {
+        for (const [dockerId, child] of this.children) {
+            if (child.containerId === containerId)
+                return dockerId;
+        }
+        return undefined;
+    }
+    /**
+     * Remove the workdir of a container no handle owns, mirroring the real
+     * `reclaimWorkdir`. Refuses (returns `false`, records nothing) while a child
+     * for that containerId still resolves — that directory belongs to
+     * `removeContainer`, which stops the child first.
+     *
+     * There is no directory here to check for existence, so a first reclaim of an
+     * unresolvable id always reports `true`; the real class returns `false` when
+     * the path is already gone. Nothing in the donation layer branches on the
+     * return value, so the gap is unobservable — model it if one starts to.
+     */
+    reclaimWorkdir(containerId) {
+        if (this.resolveDockerId(containerId))
+            return false;
+        this.reclaimedWorkdirs.push(containerId);
+        return true;
+    }
+    async getLogs() {
+        return '';
+    }
+    onStateChange(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** Kill a child out from under the host — the crash the supervisor exists for. */
+    crash(dockerId) {
+        const child = this.children.get(dockerId);
+        if (!child?.running)
+            return;
+        child.running = false;
+        this.emit(toNodeInfo(dockerId, child));
+    }
+    /** Emit an arbitrary state change (e.g. the owner node stopping). */
+    emit(info) {
+        for (const listener of this.listeners)
+            listener(info);
+    }
+    /** Mirrors `HostProcessOrchestrator.requireHandle` — unknown handles throw. */
+    requireChild(dockerId) {
+        const child = this.children.get(dockerId);
+        if (!child)
+            throw new Error(`Container not found: ${dockerId}`);
+        return child;
+    }
+}
+function toNodeInfo(dockerId, child) {
+    return {
+        id: child.containerId,
+        dockerId,
+        partyId: child.partyId,
+        profile: child.profile,
+        status: child.running ? 'running' : 'stopped',
+        spawnedAt: new Date(0).toISOString(),
+        workdir: `/fake/${child.containerId}`,
+        ports: { health: 0, metrics: 0, p2p: 0, admin: 0 },
+    };
+}
+//# sourceMappingURL=fake-orchestrator.js.map

package/dist/donation/__tests__/fake-orchestrator.js.map

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

package/dist/donation/donation-service.d.ts

@@ -0,0 +1,361 @@
+import type { Orchestrator } from '@serfab/cadre-provider';
+import type { DonationStore } from './donation-store.js';
+import type { DonationStatus, DonationView, GrantValidator } from './types.js';
+/**
+ * Default age after which a donation still stuck in `awaiting_seed` is
+ * auto-terminated: the requester provisioned a node but never presented a seed
+ * (it vanished, or abandoned the flow), leaving an orphaned child holding host
+ * ports. 30 minutes.
+ *
+ * NOTE: not operator-configurable yet — a single module constant. If hosts need
+ * to tune the grace period, promote this to `host.config.json`.
+ */
+export declare const DONATION_AWAITING_SEED_TTL_MS: number;
+/**
+ * Default age after which a donation still stuck in `provisioning` is
+ * auto-terminated: the host wrote the row before starting the child, and a
+ * crash/kill in that window (or during the spawn itself) leaves nothing to
+ * advance it across a restart. A real spawn (identity key read/gen, port
+ * allocation, process spawn) completes in well under a second normally, so 5
+ * minutes is generously past "any plausible spawn" without risking a false
+ * reap of one still genuinely in flight under heavy load.
+ */
+export declare const DONATION_PROVISIONING_TTL_MS: number;
+/** How often the reap sweep runs while cadre-host is up. 5 minutes. */
+export declare const DONATION_REAP_SWEEP_MS: number;
+/** A grantee-driven request to provision one donated node. */
+export interface DonationProvisionRequest {
+    /** The grant token that authorizes this donation (the quota key). */
+    grantToken: string;
+    /** The REQUESTER's cadre — the party the donated node joins. */
+    partyId: string;
+    /** Requester control-network bootstrap multiaddrs (dialable, with `/p2p/`). */
+    bootstrapNodes: string[];
+    /**
+     * The requester's owner public key(s), base64url. Pinned as cold-start
+     * seed-trust anchors on the donated node so it accepts the requester-signed
+     * seed presented in {@link DonationService.applySeed}. Without these the node's
+     * node-local trusted-owner anchor holds no key for the requester's party, and
+     * the default anchored policy rejects every seed.
+     *
+     * Shape-validated on the way in ({@link DonationService.provision}): every entry
+     * must decode as a base64url 32-byte Ed25519 public key, the same rule the node
+     * itself applies to `CADRE_OWNER_KEYS`. So everything downstream — the persisted
+     * record, the child's environment, a later respawn replaying it — carries values
+     * the node can actually start with. Curve membership is NOT checked (see
+     * `requireEd25519PublicKeyB64`): a well-formed key naming the wrong signer still
+     * fails at seed time, as any wrong key would.
+     */
+    ownerKeys: string[];
+    /** Node profile; defaults to `storage` so the node participates and is dialable. */
+    profile?: 'storage' | 'transaction';
+}
+/**
+ * Outcome of {@link DonationService.applySeed}.
+ *
+ * - `seeded` — the node accepted the seed and the record now says so.
+ * - `rejected` — the node refused the seed (its own seed-trust policy). Nothing
+ *   written.
+ * - `abandoned` — the seed reached the node, but the loan ended while the
+ *   request was in flight. The ending wins: the record is left exactly as the
+ *   ending wrote it. `status` is the status that won, absent when the row is
+ *   gone entirely.
+ */
+export type DonationSeedResult = {
+    outcome: 'seeded';
+    peersAdded: number;
+} | {
+    outcome: 'rejected';
+    error?: string;
+} | {
+    outcome: 'abandoned';
+    status?: DonationStatus;
+};
+/** Live peer identity of a donated node. */
+export interface DonationPeerInfo {
+    peerId: string;
+    multiaddrs: string[];
+}
+/**
+ * Outcome of {@link DonationService.respawn}. Three distinct non-throwing ends,
+ * which a bare `DonationView | undefined` conflated:
+ *
+ * - `respawned` — a new child is up and the record now names its handles.
+ * - `not_respawnable` — the record predates persisted spawn inputs, so there is
+ *   nothing to replay. Permanent; no child was spawned.
+ * - `abandoned` — the loan ended (or the record vanished) while the spawn was in
+ *   flight. The ending wins: the record is left exactly as the ending wrote it
+ *   and the new child is cleaned up. `status` is the status that won, absent
+ *   when the row is gone entirely.
+ */
+export type RespawnResult = {
+    outcome: 'respawned';
+    donation: DonationView;
+} | {
+    outcome: 'not_respawnable';
+} | {
+    outcome: 'abandoned';
+    status?: DonationStatus;
+};
+/**
+ * Orchestrator capabilities the donation cleanup paths need beyond the base
+ * `Orchestrator`. Both are optional — only `HostProcessOrchestrator` implements
+ * them; absent on a test double or a future orchestrator, the cleanup degrades
+ * to terminalizing the record with nothing to reclaim.
+ */
+export interface DonationOrchestrator extends Orchestrator {
+    /**
+     * Resolve a spawn's friendly containerId (== a donation's id) back to its
+     * current dockerId, so a stuck-`provisioning` reap can find and reclaim a
+     * child that was actually spawned before the host died.
+     */
+    resolveDockerId?(containerId: string): string | undefined;
+    /**
+     * Remove the working directory a spawn created for `containerId` when no
+     * handle owns it — the cleanup of last resort for a record that never got a
+     * `dockerId`. Returns whether anything was removed. Refuses when a handle
+     * still resolves (that child's directory belongs to `removeContainer`).
+     */
+    reclaimWorkdir?(containerId: string): boolean;
+}
+/** Constructor options. */
+export interface DonationServiceOptions {
+    /** Orchestrator that spawns/stops the donated node child process. */
+    orchestrator: DonationOrchestrator;
+    /** Grant validator (identity/expiry/revocation + quota). */
+    grants: GrantValidator;
+    /** Persistent donation store (`donations.json`). */
+    store: DonationStore;
+    /** Clock override for tests. */
+    now?: () => Date;
+}
+/**
+ * DonationService — drives the donate-a-node lifecycle on behalf of an external
+ * requester (a friend's phone). It is cadre-host's analogue of cadre-provider's
+ * `ContainerService`, minus Docker/billing, plus the grant-token gate.
+ *
+ * The host contributes capacity only: it spawns a generic node into the
+ * *requester's* cadre (`partyId`), pins the requester's owner key(s) so the node
+ * will accept a requester-signed seed, and presents that seed to the node's
+ * `POST /seed` — it never holds the requester's authority private key.
+ *
+ * Scope note: this class covers the service surface the node-donation
+ * integration test drives directly (`provision` / `getPeer` / `applySeed` /
+ * `terminate` / `get` / `list`). The grantee-facing HTTP routes, the `bin/host.ts`
+ * wiring, and the stale-`awaiting_seed` reap sweep are owned by the
+ * `2-donation-service` ticket and land alongside this file.
+ */
+export declare class DonationService {
+    private readonly orchestrator;
+    private readonly grants;
+    private readonly store;
+    private readonly now;
+    /**
+     * Per-grant-token serialization tail. `provision` chains onto the prior
+     * provision for the same token so the quota check and record-create are
+     * atomic — two concurrent requests at `count = maxNodes - 1` can't both pass.
+     *
+     * NOTE: one entry per distinct token, never evicted. Fine at household scale
+     * (a handful of grants); if grant counts ever grow large, evict the tail once
+     * it resolves.
+     */
+    private readonly provisionTail;
+    constructor(opts: DonationServiceOptions);
+    /**
+     * Provision a donated node for a validated grant. Serialized per grant token
+     * so the quota check and record-create are atomic. On any orchestrator failure
+     * the reserved resources are reclaimed and the record is marked `error`.
+     *
+     * The owner-key pins are shape-checked FIRST — ahead of the per-grant lock, the
+     * quota check and the record write — so a malformed request costs nothing: no
+     * waiting behind another provision, no grant quota slot burned, no workdir or
+     * port taken, and no `error` record to explain later. Without it the request is
+     * answered as provisioned and the child dies at boot, which is the one place the
+     * caller cannot act on the typo.
+     */
+    provision(request: DonationProvisionRequest): Promise<DonationView>;
+    private provisionLocked;
+    /**
+     * Mark a still-`provisioning` record as failed — and ONLY such a record. A row
+     * that went `terminated` while the spawn was in flight is the borrower's own
+     * ending and must not be rewritten as a host fault; a row that vanished must
+     * not be recreated.
+     *
+     * Best-effort (mirroring {@link storeRespawnAttempt}): we are already unwinding a
+     * provision failure, and a store error here must not mask the error being
+     * reported to the caller.
+     */
+    private markProvisionFailed;
+    /**
+     * Live peer identity of a donated node, read fresh from its `/status` every
+     * call (no cache) so a re-keyed identity / remapped multiaddr is never served
+     * stale. Throws `peer_unavailable` while the node has no peer identity yet.
+     */
+    getPeer(id: string): Promise<DonationPeerInfo>;
+    /**
+     * Present the requester's phone-signed seed to the donated node's `POST /seed`,
+     * authenticated with the host↔node `seedToken`. On success the donation moves
+     * to `seeded`. The node still enforces its own seed-trust policy, so a seed
+     * signed by a key the node did not pin comes back `rejected`.
+     *
+     * **An ending that lands mid-seed wins.** The record is re-read after the node
+     * answers; if the loan ended (or the row vanished) while the request was in
+     * flight, that write stands and we report `abandoned` rather than marking a
+     * dead loan `seeded`. Unlike an abandoned respawn there is nothing to clean up
+     * — the record named its `dockerId` the whole time, so the ending's own
+     * `terminate` already stopped and reclaimed the child.
+     */
+    applySeed(id: string, encodedSeed: string): Promise<DonationSeedResult>;
+    /**
+     * Re-spawn a donated node that is no longer running, replaying the spawn
+     * inputs persisted on the record. The node keeps its workdir — and with it its
+     * identity key, trusted-owner anchor, and retained bootstrap peers — so it
+     * comes back as the *same* peer and rejoins from its own durable node-local
+     * stores. Only the host-side handles change: `dockerId`, `seedEndpoint`,
+     * `seedToken` are written back fresh.
+     *
+     * **Status is deliberately unchanged.** A `seeded` node stays `seeded` (it
+     * needs no re-seeding); an `awaiting_seed` node stays `awaiting_seed` and the
+     * borrower's later seed goes to the new endpoint/token.
+     *
+     * **An ending that lands mid-spawn wins.** The record is re-read after the
+     * orchestrator returns; if it went `terminated` (or `error`, or vanished)
+     * while the child was starting, that write stands and the new child is
+     * abandoned — see {@link abandonRespawn}. Both non-`respawned` outcomes are
+     * skips, not failures, so a sweep over the store keeps going. Orchestrator
+     * failures DO throw; the caller owns backoff/give-up.
+     *
+     * NOTE: not serialized. Two overlapping calls for the same id both spawn a
+     * child, and the second spawn drops the first's orchestrator handle — leaving
+     * an unmanaged process. A supervisor with more than one trigger (timer +
+     * exit event) must not let its passes overlap on one id.
+     */
+    respawn(id: string): Promise<RespawnResult>;
+    /**
+     * Give up on a respawn whose loan ended while the child was starting: stop the
+     * new child and, unless the record went `error`, reclaim it.
+     *
+     * Reclaim, not merely stop. The ending's own cleanup already ran and found
+     * nothing: `HostProcessOrchestrator.createContainer` calls `dropStaleHandle`
+     * *while* spawning, so by the time the concurrent `terminate` reached its
+     * stop/reclaim the old handle was gone and both calls were swallowed as
+     * best-effort no-ops. The new handle is now the only thing holding that
+     * spawn's ports and workdir, so stopping alone would leak both. On a
+     * `terminated` record the loan is over and the workdir (identity key +
+     * node-local stores) goes with it — which is what `terminate` intended.
+     *
+     * `error` is the deliberate exception: `removeContainer` deletes the workdir,
+     * and `DonationSupervisor.giveUp` keeps it on purpose so the identity key the
+     * borrower's cadre approved survives. Since both spawns share one workdir
+     * (`<rootDir>/<containerId>`), reclaiming here would delete exactly what
+     * `giveUp` meant to keep.
+     *
+     * NOTE: that skipped reclaim leaks the new spawn's four ports — the record
+     * still names the *previous* `dockerId`, so a later `terminate` cleans up the
+     * old handle, not this one. Unreachable today (`giveUp` is only called from
+     * the supervisor's serialized pass, so it cannot overlap a respawn); if a
+     * second `respawn` caller ever appears, write the new `dockerId` onto the
+     * `error` record here so that later `terminate` reclaims the right child.
+     */
+    private abandonRespawn;
+    /**
+     * Terminate a donation: mark the record `terminated` FIRST, then stop + remove
+     * the child process (kept in the store for audit, excluded from the live-node
+     * tally).
+     *
+     * Order matters: stopping the child fires the orchestrator's `onStateChange`,
+     * and a respawn supervisor listening there must already see a terminal record
+     * — otherwise it observes "node gone, record still `seeded`" and resurrects a
+     * loan the borrower just ended. The tradeoff: a crash between the write and
+     * the stop leaves a `terminated` record with a live child (reaped on the next
+     * host start), which is strictly better than resurrecting an ended loan.
+     */
+    terminate(id: string): Promise<void>;
+    /**
+     * Auto-terminate donations still `awaiting_seed` past `ttlMs` — a requester
+     * that provisioned a node but never presented a seed leaves an orphaned child
+     * holding host ports. Run on a periodic sweep and once at startup for records
+     * recovered from disk. Age is measured from the record's `updatedAt` (set when
+     * it entered `awaiting_seed`). Best-effort per record: a failed terminate is
+     * logged and the sweep continues. Returns the reaped donation ids.
+     */
+    reapStaleAwaitingSeed(ttlMs?: number): Promise<string[]>;
+    /**
+     * Auto-terminate donations stuck in `provisioning` past `ttlMs` — the record
+     * is written before the child spawn starts, so a host crash/kill anywhere in
+     * that window (including mid-spawn) leaves nothing to advance it across a
+     * restart: there is no in-flight `provisionLocked` call left to reach its
+     * post-spawn re-read. Run on the same periodic sweep and startup pass as
+     * {@link reapStaleAwaitingSeed}. Age is measured from `updatedAt`, which for a
+     * genuinely-stuck row equals `createdAt` — `provisionLocked` never touches a
+     * `provisioning` record again except to advance it out of this predicate.
+     * Best-effort per record: a failed reap is logged and the sweep continues.
+     * Returns the reaped donation ids.
+     */
+    reapStaleProvisioning(ttlMs?: number): Promise<string[]>;
+    /**
+     * Terminalize a stuck-`provisioning` record as `error` and reclaim any child
+     * the orchestrator can still find for it. Status is written FIRST (same
+     * ordering rule as {@link terminate}): reclaiming fires `onStateChange`, and
+     * anything listening must already see a terminal record.
+     *
+     * NOTE: the stop only reaches a child the orchestrator has a handle for.
+     * `HostProcessOrchestrator.launchChild` spawns the process and persists the
+     * handle in the same synchronous step, so the only child this misses is one
+     * whose host died between the OS spawn and that write — an orphan *process*
+     * this reap terminalizes the record for but cannot kill (its ports stay held
+     * until a reboot). Its working directory is no longer out of reach, though:
+     * with no handle to resolve we fall back to reclaiming by container name,
+     * which also covers the far commoner case of a host that died before any
+     * child existed at all. If the spawn→persist window ever widens (an async
+     * step added between the two), the orchestrator still needs its own orphan
+     * *process* sweep — a record that names no handle cannot get one after the
+     * fact.
+     */
+    private reclaimStuckProvisioning;
+    /** One donation (redacted), or undefined when unknown. */
+    get(id: string): DonationView | undefined;
+    /** All donations (redacted), optionally scoped to one grant token. */
+    list(grantToken?: string): DonationView[];
+    private requireDonation;
+    /** Best-effort stop; logs but never throws (cleanup path). */
+    private safeStop;
+    /**
+     * Persist a failed respawn's attempt counters — plus, when the spawn itself
+     * succeeded and it was the record write that failed, the new child's handles.
+     * Merged onto whatever is on disk now, never written wholesale: the caller's
+     * copy predates the orchestrator round-trip and `store.put` replaces the whole
+     * row, so writing it back would undo a `terminate` that landed while the spawn
+     * was in flight and resurrect a loan the borrower just ended.
+     *
+     * `status` and `updatedAt` are deliberately untouched — the attempt did not
+     * succeed, and `updatedAt` is what defers the stale-`awaiting_seed` reap.
+     *
+     * Recording `spawned` is what keeps the record pointing at the child that
+     * actually exists: `createContainer` already dropped the handle the record
+     * previously named, so leaving the old `dockerId` there would send every later
+     * stop/reclaim at an id the orchestrator cannot resolve — stranding the node's
+     * workdir on disk forever.
+     *
+     * Best-effort: we are already unwinding a respawn failure, and a store error
+     * here must not mask it. Losing the write costs the caller one extra attempt
+     * before backoff; the supervisor's next pass re-reads the record, finds the
+     * named child not running, and respawns again — which drops whatever handle is
+     * current, so the ports self-heal either way.
+     */
+    private storeRespawnAttempt;
+    /** Best-effort remove; logs but never throws (cleanup path). */
+    private safeReclaim;
+    /**
+     * Best-effort removal of the working directory of a donation whose spawn
+     * never produced a `dockerId`; logs but never throws (cleanup path). A no-op
+     * on an orchestrator without the capability, and on one that refuses because
+     * a live handle still owns the directory.
+     */
+    private safeReclaimWorkdir;
+    /**
+     * Run `fn` after any in-flight provision for the same grant token, so the
+     * quota check + record-create pair is atomic per grant.
+     */
+    private serializeByGrant;
+}