@net-mesh/sdk 0.19.0

package/dist/deck.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Deck SDK — operator-side TypeScript wrapper.
+ *
+ * Sits on top of the napi-rs binding at `@net-mesh/core`. Adds:
+ *
+ * - {@link DeckSdkError} typed Error subclass that parses the
+ *   substrate `<<deck-sdk-kind:KIND>>MSG` envelope.
+ * - Auto-JSON-parsing for `status()` and `snapshots()`.
+ * - `AsyncIterable<unknown>` (parsed `MeshOsSnapshot` JSON) / `AsyncIterable<StatusSummary>`
+ *   wrappers over the raw `nextSnapshot()` / `nextSummary()`
+ *   methods.
+ *
+ * Slice 1 ships client + admin (all 9 methods) + snapshot/status
+ * streams + operator identity. Audit / logs / failures land in
+ * slice 2; ICE in slice 3.
+ *
+ * @example
+ * ```ts
+ * import { MeshOsDaemonSdk } from '@net-mesh/sdk/meshos';
+ * import { DeckClient, OperatorIdentity } from '@net-mesh/sdk/deck';
+ *
+ * const sdk = await MeshOsDaemonSdk.start();
+ * const identity = OperatorIdentity.generate();
+ * const client = await DeckClient.fromMeshos(sdk, identity);
+ *
+ * const commit = await client.admin.enterMaintenance(0xABCDn, 600_000n);
+ * console.log(`committed at ${commit.commitId} kind=${commit.eventKind}`);
+ *
+ * for await (const snap of client.snapshots()) {
+ *   // snap is a parsed object
+ *   break;
+ * }
+ *
+ * await sdk.shutdown();
+ * ```
+ */
+import { AdminCommands as NapiAdmin, AuditQuery as NapiAuditQuery, IceCommands as NapiIceCommands, IceProposal as NapiIceProposal, OperatorIdentity, OperatorRegistry as NapiOperatorRegistry, SimulatedIceProposal as NapiSimulatedIceProposal } from '@net-mesh/core';
+import { MeshOsDaemonSdk, type MeshOsConfig } from './meshos.js';
+export declare class DeckSdkError extends Error {
+    readonly kind: string;
+    constructor(kind: string, message: string);
+    static fromCaught(err: unknown): DeckSdkError | Error;
+}
+export { OperatorIdentity };
+export interface ChainCommit {
+    commitId: bigint;
+    operatorId: bigint;
+    eventKind: string;
+    committedAtMs: bigint;
+}
+export interface PeerCounts {
+    healthy: number;
+    degraded: number;
+    unreachable: number;
+    unknown: number;
+}
+export interface DaemonCounts {
+    running: number;
+    starting: number;
+    stopping: number;
+    stopped: number;
+    backingOff: number;
+    crashLooping: number;
+}
+export interface StatusSummary {
+    peers: PeerCounts;
+    daemons: DaemonCounts;
+    replicaChains: number;
+    avoidListEntries: number;
+    recentlyEmittedCount: number;
+    recentFailureCount: number;
+    adminAuditRingDepth: number;
+    freezeRemainingMs: bigint | null;
+    localMaintenanceActive: boolean;
+}
+export interface DeckClientConfig {
+    snapshotPollIntervalMs?: bigint;
+    iceSignatureThreshold?: number;
+}
+export declare class AdminCommands {
+    private readonly raw;
+    constructor(raw: NapiAdmin);
+    drain(node: bigint, drainForMs: bigint): Promise<ChainCommit>;
+    enterMaintenance(node: bigint, drainForMs?: bigint | null): Promise<ChainCommit>;
+    exitMaintenance(node: bigint): Promise<ChainCommit>;
+    cordon(node: bigint): Promise<ChainCommit>;
+    uncordon(node: bigint): Promise<ChainCommit>;
+    dropReplicas(node: bigint, chains: bigint[]): Promise<ChainCommit>;
+    invalidatePlacement(node: bigint): Promise<ChainCommit>;
+    restartAllDaemons(node: bigint): Promise<ChainCommit>;
+    clearAvoidList(node: bigint): Promise<ChainCommit>;
+}
+export declare class DeckClient {
+    private readonly raw;
+    private constructor();
+    /**
+     * Construct a deck client that owns a private supervisor
+     * runtime. Mirrors the cdylib's `net_deck_client_new`
+     * (operator-only mode) for consumers without a separately-
+     * managed `MeshOsDaemonSdk`.
+     *
+     * `operatorSeed` must be exactly 32 bytes of ed25519 seed
+     * material. Call `.close()` (or use `await using`) to drain
+     * the supervisor at end of scope; otherwise the runtime
+     * releases on GC.
+     */
+    static new(operatorSeed: Buffer, meshosConfig?: MeshOsConfig, deckConfig?: DeckClientConfig): Promise<DeckClient>;
+    /**
+     * Construct against a running `MeshOsDaemonSdk`. Reuses the
+     * SDK's tokio runtime so streams + admin commits run on the
+     * same supervisor scheduler.
+     */
+    static fromMeshos(sdk: MeshOsDaemonSdk, identity: OperatorIdentity, config?: DeckClientConfig): Promise<DeckClient>;
+    /**
+     * Tear down the private supervisor runtime if this client owns
+     * one (constructed via `DeckClient.new`). No-op for clients
+     * built via `fromMeshos` against an externally-managed SDK.
+     * Idempotent: subsequent calls return without throwing.
+     */
+    close(): Promise<void>;
+    /**
+     * `await using` hook so `await using deck = await DeckClient.new(...)`
+     * drains the supervisor at scope exit.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Operator identity bound to this client. */
+    identity(): OperatorIdentity;
+    /** Typed admin-event surface. */
+    get admin(): AdminCommands;
+    /** Break-glass surface. Returns `IceCommands` whose factories
+     * produce `IceProposal`s. Each must be `.simulate()`-d
+     * (yielding a `SimulatedIceProposal`) before `.commit(...)`. */
+    get ice(): IceCommands;
+    /**
+     * One-shot read of the latest `MeshOsSnapshot` (parsed JSON;
+     * `unknown` because the substrate snapshot's exact shape isn't
+     * mirrored in the TS surface — consumers cast or use a runtime
+     * validator).
+     */
+    status(): unknown;
+    /** One-shot read of the rolled-up `StatusSummary`. */
+    statusSummary(): StatusSummary;
+    /**
+     * Live snapshot stream as `AsyncIterable<unknown>` (parsed `MeshOsSnapshot` JSON). JSON
+     * parsing happens automatically.
+     *
+     * Async on the napi side because the substrate creates a
+     * `tokio::time::Interval` that needs a runtime context.
+     */
+    snapshots(): Promise<AsyncIterable<unknown> & {
+        close: () => Promise<void>;
+    }>;
+    /** Live status-summary stream. */
+    statusSummaryStream(): Promise<AsyncIterable<StatusSummary> & {
+        close: () => Promise<void>;
+    }>;
+    /**
+     * Fluent admin-audit query builder. Chain `.recent(n)` /
+     * `.byOperator(id)` / `.between(start, end)` / `.forceOnly()` /
+     * `.since(seq)` before calling `.collect()` (eager list of
+     * parsed audit records) or `.stream()` (`AsyncIterable`).
+     */
+    audit(): AuditQuery;
+    /**
+     * Subscribe to the runtime's log ring. Returns an
+     * `AsyncIterable<LogRecord>`. Filter fields are all optional
+     * — missing fields match every record.
+     */
+    subscribeLogs(filter?: LogFilter): Promise<AsyncIterable<LogRecord> & {
+        close: () => Promise<void>;
+    }>;
+    /**
+     * Subscribe to the executor failure ring starting at
+     * `sinceSeq + 1`. Pass `0n` (or omit) to start from whatever
+     * is still in the ring.
+     */
+    subscribeFailures(sinceSeq?: bigint): Promise<AsyncIterable<FailureRecord> & {
+        close: () => Promise<void>;
+    }>;
+}
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+export interface LogFilter {
+    minLevel?: LogLevel;
+    daemonId?: bigint;
+    nodeId?: bigint;
+    sinceSeq?: bigint;
+}
+export interface LogRecord {
+    seq: bigint;
+    tsMs: bigint;
+    level: LogLevel;
+    daemonId: bigint | null;
+    nodeId: bigint | null;
+    message: string;
+}
+export interface FailureRecord {
+    seq: bigint;
+    source: string;
+    reason: string;
+    recordedAtMs: bigint;
+}
+export type AdminAuditRecord = Record<string, unknown>;
+/**
+ * Fluent admin-audit query builder.
+ *
+ * @example
+ * ```ts
+ * const records = await client.audit()
+ *   .recent(100)
+ *   .byOperator(operatorId)
+ *   .forceOnly()
+ *   .collect();
+ *
+ * for await (const record of (await client.audit().since(lastSeq).stream())) {
+ *   handle(record);
+ * }
+ * ```
+ */
+export declare class AuditQuery {
+    private readonly raw;
+    constructor(raw: NapiAuditQuery);
+    recent(limit: number): AuditQuery;
+    byOperator(operatorId: bigint): AuditQuery;
+    between(startMs: bigint, endMs: bigint): AuditQuery;
+    forceOnly(): AuditQuery;
+    since(seq: bigint): AuditQuery;
+    /** Eager — returns a list of audit records (JSON-parsed into
+     * native objects). */
+    collect(): Promise<AdminAuditRecord[]>;
+    /** Async iterator over audit records. */
+    stream(): Promise<AsyncIterable<AdminAuditRecord> & {
+        close: () => Promise<void>;
+    }>;
+}
+/** Avoid-list flush scope discriminated union. */
+export type AvoidScope = {
+    kind: 'global';
+} | {
+    kind: 'local';
+    node: bigint;
+} | {
+    kind: 'onPeer';
+    peer: bigint;
+};
+/** Signature pair carried by ICE commits. `signature` must be 64
+ * ed25519 bytes (the substrate verifier rejects malformed sigs
+ * with kind `signature_invalid`). */
+export interface OperatorSignature {
+    operatorId: bigint;
+    signature: Buffer;
+}
+export type BlastRadius = Record<string, unknown>;
+export declare class IceCommands {
+    private readonly raw;
+    constructor(raw: NapiIceCommands);
+    freezeCluster(ttlMs: bigint): IceProposal;
+    flushAvoidLists(scope: AvoidScope): IceProposal;
+    forceEvictReplica(chain: bigint, victim: bigint): IceProposal;
+    /** Propose force-restarting a daemon. `id` is the registry-
+     * local daemon id; `name` is `MeshDaemon::name()`. */
+    forceRestartDaemon(id: bigint, name: string): IceProposal;
+    forceCutover(chain: bigint, target: bigint): IceProposal;
+    killMigration(migration: bigint): IceProposal;
+    thawCluster(): IceProposal;
+}
+/** Pre-simulation ICE proposal. No `commit` method —
+ * `simulate()` must run first. */
+export declare class IceProposal {
+    private readonly raw;
+    constructor(raw: NapiIceProposal);
+    get issuedAtMs(): bigint;
+    /** Pre-execution preview. Consumes the proposal — subsequent
+     * `simulate()` calls throw `DeckSdkError(kind: "already_simulated")`. */
+    simulate(): Promise<SimulatedIceProposal>;
+}
+/** A simulated ICE proposal. Only class exposing `commit`. */
+export declare class SimulatedIceProposal {
+    private readonly raw;
+    constructor(raw: NapiSimulatedIceProposal);
+    get issuedAtMs(): bigint;
+    /** Pre-execution blast radius, parsed from the binding's JSON. */
+    blastRadius(): Promise<BlastRadius>;
+    /** Blake3 digest of the blast radius (32 bytes). */
+    blastHash(): Promise<Buffer>;
+    /** Commit with operator signatures. Consumes the proposal —
+     * subsequent calls throw `already_committed`. */
+    commit(signatures: OperatorSignature[]): Promise<ChainCommit>;
+}
+/** Cluster operator-policy registry. Authoring tool for the
+ * substrate's known-operator set; offline-friendly verifier for
+ * bundles before invoking
+ * {@link SimulatedIceProposal.commit}.
+ *
+ * Mutations are thread-safe at the napi binding layer. */
+export declare class OperatorRegistry {
+    constructor(raw?: NapiOperatorRegistry);
+    /** Insert an operator's 32-byte ed25519 public key under
+     * `operatorId`. */
+    insert(operatorId: bigint, publicKey: Buffer): void;
+    /** Register an `OperatorIdentity`'s public key under its
+     * derived operator id. */
+    register(identity: OperatorIdentity): void;
+    /** `true` iff `operatorId` is registered. */
+    contains(operatorId: bigint): boolean;
+    /** Number of registered operators. */
+    get size(): number;
+    /** `true` iff no operators are registered. */
+    isEmpty(): boolean;
+    /** Verify a single signature over `payload`. Throws
+     * `DeckSdkError` with the substrate's stable kind discriminator
+     * (`not_authorized`, `signature_invalid`, etc.). */
+    verify(signature: OperatorSignature, payload: Buffer): void;
+    /** Verify every signature in the bundle and confirm at least
+     * `threshold` *distinct* operator ids signed `payload`. */
+    verifyBundle(signatures: OperatorSignature[], payload: Buffer, threshold: number): void;
+}
+/** Substrate-side admin commit verifier. Bundles an
+ * {@link OperatorRegistry} snapshot with the cluster's signature
+ * threshold + freshness/skew/ICE-cooldown windows. Useful for
+ * offline unit testing of operator-policy decisions.
+ *
+ * Constructors snapshot the registry at build time — later
+ * mutations on the source registry are not reflected. Rebuild
+ * the verifier after every policy change. */
+export declare class AdminVerifier {
+    private readonly raw;
+    private constructor();
+    /** Build a verifier with `threshold` minimum signatures and
+     * the substrate defaults (300s freshness, 30s future-skew,
+     * 300s ICE cooldown). `threshold = 0` is clamped to `1`. */
+    static new(registry: OperatorRegistry, threshold: number): AdminVerifier;
+    /** Build with explicit freshness + future-skew windows and
+     * the default ICE cooldown. */
+    static withFreshness(registry: OperatorRegistry, threshold: number, freshnessWindowMs: bigint, futureSkewMs: bigint): AdminVerifier;
+    /** Build with every policy knob explicit. Primarily for tests
+     * that need a short cooldown window. */
+    static withFullPolicy(registry: OperatorRegistry, threshold: number, freshnessWindowMs: bigint, futureSkewMs: bigint, iceCooldownMs: bigint): AdminVerifier;
+    get threshold(): number;
+    get freshnessWindowMs(): bigint;
+    get futureSkewMs(): bigint;
+    get iceCooldownMs(): bigint;
+}