@serfab/cadre-host 0.9.0 → 0.10.0

package/dist/donation/index.js

@@ -12,5 +12,6 @@ export { GrantService, createGrantAdminHandlers, DEFAULT_MAX_NODES, } from './gr
 export { GrantError, DonationError } from './types.js';
 /* ──────────────── donation lifecycle (2-donation-service) ──────────────── */
 export { DonationStore } from './donation-store.js';
-export { DonationService, DONATION_AWAITING_SEED_TTL_MS, DONATION_REAP_SWEEP_MS, } from './donation-service.js';
+export { DonationService, DONATION_AWAITING_SEED_TTL_MS, DONATION_PROVISIONING_TTL_MS, DONATION_REAP_SWEEP_MS, } from './donation-service.js';
+export { DonationSupervisor, DONATION_RESPAWN_BACKOFF_BASE_MS, DONATION_RESPAWN_BACKOFF_MAX_MS, DONATION_RESPAWN_MAX_ATTEMPTS, DONATION_RESPAWN_HEALTHY_MS, DONATION_RESPAWN_SWEEP_MS, } from './donation-supervisor.js';
 //# sourceMappingURL=index.js.map

package/dist/donation/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/donation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAWvD,+EAA+E;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,eAAe,EACf,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/donation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAWvD,+EAA+E;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,eAAe,EACf,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EACL,kBAAkB,EAClB,gCAAgC,EAChC,+BAA+B,EAC/B,6BAA6B,EAC7B,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC"}

package/dist/donation/types.d.ts

@@ -120,6 +120,12 @@ export type DonationStatus = 'provisioning' | 'awaiting_seed' | 'seeded' | 'erro
  * foreign party), and `seedToken` gates the node's own `POST /seed` — it is
  * minted host-side, persisted here (so a host restart in the request→seed gap
  * can still present the seed), and NEVER returned to the grantee.
+ *
+ * The record also carries every input the original spawn consumed
+ * (`partyId` + `profile` + `bootstrapNodes` + `ownerKeys`), so a crashed node can
+ * be re-spawned from the record alone — see `DonationService.respawn`. Records
+ * written before those two fields existed have neither; such a record is NOT
+ * respawnable and is skipped (never crashes a sweep).
  */
 export interface Donation {
     /** "grn_<nanoid>" — also the donated node's orchestrator containerId. */
@@ -128,6 +134,26 @@ export interface Donation {
     grantToken: string;
     /** The REQUESTER's cadre (a foreign party this host merely hosts a node for). */
     partyId: string;
+    /**
+     * Requester control-network bootstrap multiaddrs — replayed on respawn.
+     * Absent on records written before respawn support; those are not respawnable.
+     */
+    bootstrapNodes?: string[];
+    /**
+     * Requester owner public key(s), base64url — replayed as the node's pinned
+     * seed-trust anchors (`CADRE_OWNER_KEYS`) on respawn. Absent on records written
+     * before respawn support; those are not respawnable.
+     */
+    ownerKeys?: string[];
+    /**
+     * Respawn bookkeeping, owned by the supervisor's backoff. Absent until the
+     * first respawn attempt. Not secret — it rides along in `DonationView` so the
+     * borrower's `GET /grants/:id` shows the counters for free.
+     */
+    respawn?: {
+        attempts: number;
+        lastAttemptAt: string;
+    };
     /** Node profile. Defaults to `storage` so the node participates and is dialable. */
     profile: 'storage' | 'transaction';
     status: DonationStatus;

package/dist/donation/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/donation/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAyKH,sEAAsE;AACtE,MAAM,OAAO,aAAc,SAAQ,KAAK;IAGtC,YAAY,IAAuB,EAAE,OAAe;QAClD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAUD,6DAA6D;AAC7D,MAAM,OAAO,UAAW,SAAQ,KAAK;IAGnC,YAAY,IAAoB,EAAE,OAAe;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/donation/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAgMH,sEAAsE;AACtE,MAAM,OAAO,aAAc,SAAQ,KAAK;IAGtC,YAAY,IAAuB,EAAE,OAAe;QAClD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAUD,6DAA6D;AAC7D,MAAM,OAAO,UAAW,SAAQ,KAAK;IAGnC,YAAY,IAAoB,EAAE,OAAe;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/index.d.ts

@@ -22,8 +22,10 @@ export { HostProcessOrchestrator, OWNER_CONTAINER_ID } from './orchestrator/inde
 export type { HostProcessConfig, PersistedHandle, ManagedNodeInfo, NodeStateListener, NodePorts, OwnerAdminEndpoint, OwnerSpawnConfig, } from './orchestrator/index.js';
 export { OwnerNodeClient, OwnerNodeUnavailableError } from './owner/index.js';
 export type { OwnerNodeClientOptions } from './owner/index.js';
-export { TrustCircleService, TrustCircleStore, TrustCircleError, createTrustCircleHandlers, parseDuration, DEFAULT_INVITE_TTL_MS, } from './auth/index.js';
+export { TrustCircleService, TrustCircleStore, TrustCircleError, createTrustCircleHandlers, parseDuration, ensureSelfLabel, DEFAULT_INVITE_TTL_MS, } from './auth/index.js';
 export type { TrustCircleServiceOptions, CadreNodeLike, TrustCircleMember, PendingInvite, TrustCircleFile, TrustCircleSnapshot, TrustCircleHandlers, TrustCircleErrorCode, } from './auth/index.js';
+export { StrandService, StrandError, createStrandHandlers } from './strands/index.js';
+export type { StrandServiceOptions, CadreNodeLike as StrandCadreNodeLike, StrandSummary, StrandListSnapshot, StrandRemovalResult, StrandHandlers, StrandErrorCode, } from './strands/index.js';
 export { GrantStore, GrantService, createGrantAdminHandlers, GrantError, DEFAULT_MAX_NODES, DonationStore, DonationService, DonationError, } from './donation/index.js';
 export type { Grant, GrantDenyReason, GrantValidation, GrantValidator, GrantFile, GrantAdminHandlers, GrantErrorCode, GrantServiceOptions, Donation, DonationView, DonationStatus, DonationFile, DonationErrorCode, DonationProvisionRequest, DonationSeedResult, DonationPeerInfo, DonationServiceOptions, } from './donation/index.js';
 export { Installer, readHostConfig, updateHostConfig, writeHostConfig } from './installer/index.js';

package/dist/index.js

@@ -19,7 +19,9 @@
  */
 export { HostProcessOrchestrator, OWNER_CONTAINER_ID } from './orchestrator/index.js';
 export { OwnerNodeClient, OwnerNodeUnavailableError } from './owner/index.js';
-export { TrustCircleService, TrustCircleStore, TrustCircleError, createTrustCircleHandlers, parseDuration, DEFAULT_INVITE_TTL_MS, } from './auth/index.js';
+export { TrustCircleService, TrustCircleStore, TrustCircleError, createTrustCircleHandlers, parseDuration, ensureSelfLabel, DEFAULT_INVITE_TTL_MS, } from './auth/index.js';
+/* ──────────────── strand management ──────────────── */
+export { StrandService, StrandError, createStrandHandlers } from './strands/index.js';
 /* ──────────────── donation grant tokens ──────────────── */
 export { GrantStore, GrantService, createGrantAdminHandlers, GrantError, DEFAULT_MAX_NODES, DonationStore, DonationService, DonationError, } from './donation/index.js';
 export { Installer, readHostConfig, updateHostConfig, writeHostConfig } from './installer/index.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAWH,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAWtF,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAG9E,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,yBAAyB,EACzB,aAAa,EACb,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAYzB,6DAA6D;AAE7D,OAAO,EACL,UAAU,EACV,YAAY,EACZ,wBAAwB,EACxB,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,qBAAqB,CAAC;AAqB7B,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAepG,mEAAmE;AAEnE,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,iBAAiB,CAAC;AAQzB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,cAAc,EACd,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAe3B,OAAO,EACL,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,GACd,MAAM,gBAAgB,CAAC;AA+BxB,+DAA+D;AAE/D,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAWH,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAWtF,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAG9E,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,yBAAyB,EACzB,aAAa,EACb,eAAe,EACf,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAYzB,yDAAyD;AAEzD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAWtF,6DAA6D;AAE7D,OAAO,EACL,UAAU,EACV,YAAY,EACZ,wBAAwB,EACxB,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,qBAAqB,CAAC;AAqB7B,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAepG,mEAAmE;AAEnE,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,GACX,MAAM,iBAAiB,CAAC;AAQzB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,cAAc,EACd,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAe3B,OAAO,EACL,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,GACd,MAAM,gBAAgB,CAAC;AA+BxB,+DAA+D;AAE/D,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/dist/orchestrator/host-process-orchestrator.d.ts

@@ -1,5 +1,4 @@
 import type { Orchestrator, OrchestratorCreateRequest, OrchestratorCreateResult, OrchestratorStats } from '@serfab/cadre-provider';
-import { type PersistedHandle } from './state-store.js';
 import { type OwnerSpawnConfig, type HostProcessConfig, type ManagedNodeInfo, type NodeStateListener } from './types.js';
 /** Fixed friendly id for the admin's owner node. */
 export declare const OWNER_CONTAINER_ID = "owner";
@@ -84,9 +83,44 @@ export declare class HostProcessOrchestrator implements Orchestrator {
      * transitions (child exit, manual stop). Returns an unsubscribe fn.
      */
     onStateChange(listener: NodeStateListener): () => void;
-    /** Handles that init() found dead (PID gone or token mismatch). */
-    listDeadHandles(): PersistedHandle[];
+    /**
+     * Spawn a generic managed node — the donated-node path (the requester's cadre,
+     * pinned to the *requester's* owner key). The node is given its own protobuf
+     * identity key inside its workdir (`ensureNodeIdentity`, reused across
+     * re-spawns of the same containerId), which is what makes its peer id stable
+     * across restarts AND what makes its node-local stores durable: `cadre-cli
+     * start` opens the file-backed bootstrap-peer and trusted-owner stores only
+     * when a protobuf identity key file is configured, and puts them beside it.
+     * Terminating the loan (`removeContainer`) deletes the workdir, so the key and
+     * both stores go with it.
+     */
     createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult>;
+    /**
+     * Remove the working directory a spawn created for `containerId` when no
+     * handle owns it — the cleanup of last resort for a donation record that
+     * never got a `dockerId` (the host died between `ensureNodeIdentity` and the
+     * handle write, so `createContainer`'s own unwind never ran). Returns whether
+     * anything was removed.
+     *
+     * Synchronous, mirroring {@link resolveDockerId}: nothing on this path needs
+     * to await.
+     */
+    reclaimWorkdir(containerId: string): boolean;
+    /**
+     * Best-effort removal of a workdir no handle owns. Logs, never throws: every
+     * caller is either unwinding a failure it must report instead of this one, or
+     * tearing a container down along a path where a surviving directory is a
+     * nuisance rather than a fault.
+     *
+     * `retries` sizes the wait for the OS to release a cwd handle — Windows drops
+     * it asynchronously after a child exits. `createContainer`'s unwind needs none
+     * of that (its throw surface ends before any child is spawned), but
+     * `reclaimWorkdir` can still meet an orphan process the previous host left
+     * running with this directory as its cwd, so it is not a *guaranteed*
+     * no-process path either — it simply logs and leaves the directory when the
+     * removal fails.
+     */
+    private discardWorkdir;
     /**
      * Resolve the push credentials to inject into the node about to spawn. Called
      * on every spawn so a re-spawn re-reads the secret store — raw private keys are
@@ -120,12 +154,82 @@ export declare class HostProcessOrchestrator implements Orchestrator {
     restartOwnerNode(): Promise<ManagedNodeInfo>;
     /**
      * Core spawn mechanics shared by `createContainer` and `ensureOwnerNode`.
-     * The caller has already allocated `ports`. Releases the ports on a
-     * synchronous spawn failure.
+     *
+     * The caller has already allocated `ports` and **owns their lifetime**: this
+     * method never releases them, so every caller must release on any throw out
+     * of here (it has to unwind its handle drop on the same path anyway — see
+     * `restoreDroppedHandles`).
+     *
+     * That contract holds because this method throws only *before* the child is
+     * spawned and its handle stored — everything after that point is
+     * best-effort. Anything new added at the tail must keep it that way.
+     *
+     * Entirely synchronous, which is what makes that unwind sound. Do not add an
+     * `await` here.
      */
     private launchChild;
+    /**
+     * Drop any handle left over from a previous spawn of the same `containerId`
+     * and release its ports. Handles are keyed by the per-spawn `dockerId`, so
+     * without this a re-spawn (donated-node respawn) would strand the prior
+     * handle in the map forever, leaking four ports from a bounded range each
+     * time. Mirrors the same cleanup in `ensureOwnerNode`.
+     *
+     * DO NOT delete the workdir: the identity key and node-local stores
+     * (trusted-owner anchor, retained cold-start dial targets) live there and are
+     * the whole reason a respawn comes back as the same node. `launchChild`
+     * reuses the same workdir.
+     *
+     * NOTE: releasing the ports hands them straight back to the allocator, so a
+     * re-spawn while the *previous* child is still listening can bind-clash. Every
+     * caller today re-spawns only a container it has established is not running
+     * (`DonationService.respawn`, `ensureOwnerNode`). If a caller ever needs to
+     * replace a live child, stop it first — or hold the ports until its exit.
+     *
+     * **The drop is reversible.** It happens before the launch can fail, so the
+     * dropped handles are returned and every caller restores them via
+     * {@link restoreDroppedHandles} when the launch throws — otherwise the caller
+     * would be left holding a dockerId this orchestrator no longer knows, and the
+     * node's workdir could never be reclaimed. On a *successful* spawn the drop
+     * stands: `DonationService.abandonRespawn` depends on the old handle being
+     * gone by then.
+     */
+    private dropStaleHandle;
+    /**
+     * Inverse of {@link dropStaleHandle}, for a spawn that then failed: put each
+     * handle back in the map and re-reserve its four ports, leaving host state
+     * exactly as the failed attempt found it.
+     *
+     * **Precondition: the drop → launch window is synchronous.** Restoring is
+     * sound only because nothing can have taken those ports or run cleanup
+     * against the handle in between — `launchChild` contains no `await` and both
+     * callers resolve push credentials *before* their drop. `launchChild`'s half
+     * is enforced: its declared return type is not a Promise, so adding an
+     * `await` there is a compile error. The callers' half is not — an `await`
+     * slipped between a drop and its launch silently breaks this.
+     *
+     * No `persist()` here: `state.json` is rewritten only by `launchChild` and
+     * only *after* the new handle is stored, so throughout the failure window the
+     * on-disk state still lists the dropped handle — this restore realigns memory
+     * to disk rather than diverging from it.
+     *
+     * NOTE: a restored handle keeps `alive: true` even if its child exited while
+     * it was out of the map (`launchChild`'s exit listener looks the handle up by
+     * dockerId and finds nothing). Only reachable by re-spawning a container
+     * whose child is still live, which `dropStaleHandle`'s note above already
+     * forbids.
+     */
+    private restoreDroppedHandles;
+    /** A managed node's own directory under `rootDir` — config, log, storage, identity. */
+    private workdirFor;
     /** Locate the owner node's handle, if one has been spawned. */
     private findOwnerHandle;
+    /**
+     * Inverse of {@link releasePorts} — hold a handle's whole port set against
+     * the allocator. Used both to rehydrate on `init` and to undo a drop whose
+     * launch then failed.
+     */
+    private reservePorts;
     private releasePorts;
     stopContainer(dockerId: string): Promise<void>;
     removeContainer(dockerId: string): Promise<void>;