@origintrail-official/dkg-agent 10.0.20 → 10.0.21

package/dist/vm-recovery-phase-timing.js

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: Apache-2.0
+import { diffRpcRequestTiming, snapshotProcessRpcUsage, snapshotRpcRequestTiming, } from '@origintrail-official/dkg-chain';
+/**
+ * Observation-only attribution of where one exact VM recovery pass spends wall
+ * clock and background RPC capacity. Nothing here is consulted by a recovery
+ * decision: measuring or formatting must never change an outcome, so every
+ * entry point is total and swallows its own errors.
+ *
+ * Background-class attempt counts are process-wide. They attribute reliably
+ * only while recovery is the node's main background RPC consumer, and they also
+ * include any speculative preparation that runs inside the same interval.
+ */
+export const VM_RECOVERY_PHASES = [
+    /** Curator roster and preferred-peer resolution. */
+    'roster',
+    /** Advertised-protocol checks of the connected providers for the stream wire. */
+    'transport',
+    /** Registered-public authority read that gates the stream wire. */
+    'authority',
+    /** Connect, sync-protocol readiness and network admission of the provider. */
+    'peer-ready',
+    /** Chain sizing hints for packing (live reads or consumed preparations). */
+    'sizing',
+    /** Network exchange plus verified materialization of the requested assets. */
+    'exchange',
+    /** Per-ordinal chain revalidation that follows the exchange. */
+    'post-fetch',
+];
+const EMPTY_USAGE = Object.freeze({
+    ms: 0,
+    backgroundAttempts: 0,
+    backgroundAdmissionWaitMs: 0,
+    backgroundEndpointMs: 0,
+});
+function emptyTotals() {
+    return Object.fromEntries(VM_RECOVERY_PHASES.map((phase) => [phase, EMPTY_USAGE]));
+}
+const DEFAULT_SOURCES = {
+    clock: () => performance.now(),
+    timing: () => snapshotRpcRequestTiming(),
+    usage: () => snapshotProcessRpcUsage(),
+};
+function safeTiming(sources) {
+    try {
+        return sources.timing();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Accumulates monotonic wall clock and background RPC usage per phase, twice over: per batch
+ * (drained by {@link VmRecoveryPhaseRecorder.take}) and for the whole pass (never drained).
+ */
+export class VmRecoveryPhaseRecorder {
+    sources;
+    /** Since the last `take()`: one batch. */
+    #totals = emptyTotals();
+    /** Since this recorder was created: the whole pass. */
+    #cumulative = emptyTotals();
+    constructor(sources = DEFAULT_SOURCES) {
+        this.sources = sources;
+    }
+    /** Time `run`, charging the elapsed time and background usage to `phase`. */
+    async measure(phase, run) {
+        const startedAt = this.sources.clock();
+        const before = safeTiming(this.sources);
+        try {
+            return await run();
+        }
+        finally {
+            this.#charge(phase, startedAt, before);
+        }
+    }
+    /** Charge the interval since `startedAt` for code that cannot be wrapped as a closure. */
+    chargeSince(phase, startedAt, before) {
+        this.#charge(phase, startedAt, before);
+    }
+    /** Capture the start of a manually bracketed interval. */
+    begin() {
+        return { startedAt: this.sources.clock(), before: safeTiming(this.sources) };
+    }
+    /** Read and reset the totals accumulated since the previous call (one batch). */
+    take() {
+        const taken = this.#totals;
+        this.#totals = emptyTotals();
+        return Object.freeze(taken);
+    }
+    /** The totals accumulated since this recorder was created (the whole pass); never reset. */
+    cumulative() {
+        return Object.freeze({ ...this.#cumulative });
+    }
+    #charge(phase, startedAt, before) {
+        try {
+            const elapsed = this.sources.clock() - startedAt;
+            let attempts = 0;
+            let waitMs = 0;
+            let endpointMs = 0;
+            const after = before === undefined ? undefined : safeTiming(this.sources);
+            if (before !== undefined && after !== undefined) {
+                const delta = diffRpcRequestTiming(before, after).background;
+                attempts = delta.admissionWait.count;
+                waitMs = delta.admissionWait.totalMs;
+                endpointMs = delta.endpointLatency.totalMs;
+            }
+            const ms = Number.isFinite(elapsed) && elapsed > 0 ? elapsed : 0;
+            for (const totals of [this.#totals, this.#cumulative]) {
+                const previous = totals[phase];
+                totals[phase] = Object.freeze({
+                    ms: previous.ms + ms,
+                    backgroundAttempts: previous.backgroundAttempts + attempts,
+                    backgroundAdmissionWaitMs: previous.backgroundAdmissionWaitMs + waitMs,
+                    backgroundEndpointMs: previous.backgroundEndpointMs + endpointMs,
+                });
+            }
+        }
+        catch { /* observation only */ }
+    }
+}
+/** Run an observation callback; a failure to observe never changes recovery. */
+export function observeVmRecoveryTiming(callback) {
+    try {
+        callback();
+    }
+    catch { /* observation only */ }
+}
+/** Capture the cumulative counters; `undefined` when they cannot be read. */
+export function markVmRecoveryRpc(sources = DEFAULT_SOURCES) {
+    try {
+        const usage = sources.usage();
+        return {
+            methods: usage.cumulative.methods,
+            consumers: usage.cumulative.consumers,
+            timing: sources.timing(),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+const TOP_CONSUMERS = 8;
+function distributionSummary(prefix, distribution) {
+    if (distribution.count <= 0)
+        return `${prefix}Count=0`;
+    const meanMs = distribution.totalMs / distribution.count;
+    const slow = distribution.buckets.slice(3).reduce((sum, value) => sum + value, 0);
+    return `${prefix}Count=${distribution.count} ${prefix}TotalMs=${Math.round(distribution.totalMs)} `
+        + `${prefix}MeanMs=${Math.round(meanMs)} ${prefix}Over1sCount=${slow}`;
+}
+/**
+ * One logfmt-style fragment describing the physical RPC work between `mark`
+ * and now: totals by method, the most used bounded consumer labels, and the
+ * split between local admission wait and endpoint latency for background
+ * attempts. Secret-free by construction.
+ */
+export function describeVmRecoveryRpcSince(mark, sources = DEFAULT_SOURCES) {
+    if (mark === undefined)
+        return 'rpcTotal=unknown';
+    try {
+        const now = markVmRecoveryRpc(sources);
+        if (now === undefined)
+            return 'rpcTotal=unknown';
+        let total = 0;
+        const byMethod = [];
+        for (const [method, count] of Object.entries(now.methods)) {
+            const delta = count - (mark.methods[method] ?? 0);
+            if (delta > 0) {
+                total += delta;
+                byMethod.push(`${method}:${delta}`);
+            }
+        }
+        const consumers = [];
+        for (const [method, byConsumer] of Object.entries(now.consumers)) {
+            for (const [consumer, count] of Object.entries(byConsumer)) {
+                const delta = count - (mark.consumers[method]?.[consumer] ?? 0);
+                if (delta > 0)
+                    consumers.push([`${method}/${consumer}`, delta]);
+            }
+        }
+        consumers.sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+        const timing = diffRpcRequestTiming(mark.timing, now.timing);
+        return [
+            `rpcTotal=${total}`,
+            `rpcByMethod=${byMethod.sort().join(',') || '-'}`,
+            `rpcTop=${consumers.slice(0, TOP_CONSUMERS).map(([name, count]) => `${name}:${count}`).join(',') || '-'}`,
+            distributionSummary('bgAdmission', timing.background.admissionWait),
+            distributionSummary('bgEndpoint', timing.background.endpointLatency),
+            `bgEndpointFailures=${timing.background.endpointFailures}`,
+            distributionSummary('fgEndpoint', timing.foreground.endpointLatency),
+        ].join(' ');
+    }
+    catch {
+        return 'rpcTotal=unknown';
+    }
+}
+/** Render phase totals as `phase{Ms,BgReq,BgWaitMs,BgEndpointMs}` pairs in a stable order. */
+export function formatVmRecoveryPhases(totals) {
+    return VM_RECOVERY_PHASES.map((phase) => {
+        const usage = totals[phase];
+        const label = phase.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
+        return `${label}Ms=${Math.round(usage.ms)} ${label}BgReq=${usage.backgroundAttempts} `
+            + `${label}BgWaitMs=${Math.round(usage.backgroundAdmissionWaitMs)}`;
+    }).join(' ');
+}
+const MAX_TRACKED_GRAPHS = 256;
+const passEndedAt = new WeakMap();
+/** Milliseconds since this owner's previous reconcile pass for the graph ended. */
+export function vmReconcilePassGapMs(owner, localCgId, startedAt) {
+    try {
+        const endedAt = passEndedAt.get(owner)?.get(localCgId);
+        return endedAt === undefined ? undefined : Math.max(0, startedAt - endedAt);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Remember when a reconcile pass for the graph ended (bounded, observation only). */
+export function noteVmReconcilePassEnd(owner, localCgId, endedAt) {
+    try {
+        let byGraph = passEndedAt.get(owner);
+        if (!byGraph) {
+            byGraph = new Map();
+            passEndedAt.set(owner, byGraph);
+        }
+        byGraph.delete(localCgId);
+        byGraph.set(localCgId, endedAt);
+        while (byGraph.size > MAX_TRACKED_GRAPHS) {
+            const oldest = byGraph.keys().next().value;
+            if (oldest === undefined)
+                break;
+            byGraph.delete(oldest);
+        }
+    }
+    catch { /* observation only */ }
+}
+//# sourceMappingURL=vm-recovery-phase-timing.js.map

package/dist/vm-recovery-phase-timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vm-recovery-phase-timing.js","sourceRoot":"","sources":["../src/vm-recovery-phase-timing.ts"],"names":[],"mappings":"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"}

package/dist/vm-recovery-preparation.d.ts

@@ -0,0 +1,143 @@
+import { type VmRecoveryFootprintSizingReader, type VmRecoveryPreparedHints } from './vm-recovery-footprint.js';
+import type { VmRecoveryChainFootprint } from './vm-recovery-types.js';
+/**
+ * Advisory preparation of the NEXT recovery batch's sizing metadata.
+ *
+ * While one exact batch transfers and commits, this owner reads the update
+ * context of a bounded stable prefix of the still-pending candidates, so the
+ * next planning pass finds those hints ready instead of re-reading them (or
+ * losing them to the local RPC governor's queue and truncating the batch).
+ *
+ * What it is NOT. A hint is planning evidence of exactly the kind a live
+ * `latest-bounded` read yields: it can change how work is packed and nothing
+ * else. It earns no holder credit, consumes no peer attempt, records no
+ * admission, touches no negative cache and marks no ordinal handled, attempted,
+ * reconciled or materialized. The chain root count/version/binding and the
+ * guarded atomic write that follow authenticate every asset independently.
+ *
+ * Bounds. One prepared batch (at most {@link MAX_EXACT_SYNC_ASSETS} KAs) is
+ * retained at a time; at most `maxSpeculativeReads` speculative reads are in
+ * flight, each a single RPC in the BACKGROUND class bound to the owner's
+ * signal; descriptors hold a handful of scalars (no quads or payloads) and are
+ * byte-accounted. Hints are single-use and expire; a stale generation, a lost
+ * recovery ownership or an abort turns every hint into a miss, and the caller's
+ * live path runs unchanged.
+ */
+export declare const VM_RECOVERY_PREPARATION_LIMITS: Readonly<{
+    /** One future batch, never more than the exact-asset hard selector limit. */
+    maxPreparedAssets: 10;
+    /** Speculative KA-read tasks in flight at once (each is one RPC). */
+    maxSpeculativeReads: 2;
+    /**
+     * Per-read deadline of a speculative read. It runs off the critical path, so
+     * it may wait out a busy local RPC governor longer than a planning read could.
+     */
+    readTimeoutMs: number;
+    /** A hint older than this at consumption is a miss. */
+    maxHintAgeMs: 60000;
+    /** Explicit ceiling for retained descriptor memory. */
+    maxRetainedBytes: number;
+    /** Live planning reads in flight at once when preparation is enabled. */
+    planningReadConcurrency: 3;
+    /**
+     * Deadline of a live planning read when preparation is enabled. Admission
+     * wait in the local RPC governor counts inside it, and one unresolved first
+     * candidate truncates the whole batch to a single asset, so a busy lane is
+     * given longer than the unprepared path's limit before a read is abandoned.
+     */
+    planningReadTimeoutMs: number;
+    /**
+     * Minimum spacing between reads of the registered-public observation that gates the
+     * stream wire when an earlier read in the same pass was unavailable.
+     */
+    authorityRetryMinIntervalMs: 5000;
+}>;
+export type VmRecoveryPreparationLimits = {
+    -readonly [K in keyof typeof VM_RECOVERY_PREPARATION_LIMITS]: number;
+};
+/** The recovery operation a hint belongs to. */
+export interface VmRecoveryPreparationScope {
+    readonly localCgId: string;
+    readonly onChainCgId: bigint;
+    /** `vmReconcileLifecycleGeneration` at the time the owning pass started. */
+    readonly generation: number;
+    /** The recovery operation's cancellation signal. */
+    readonly signal?: AbortSignal;
+    /** Recovery ownership at call time (lifecycle, binding, target). */
+    readonly isCurrent: () => boolean;
+}
+export interface VmRecoveryPreparationCandidate {
+    readonly kaId: string;
+    /** A footprint the caller already holds is retained as-is instead of re-read. */
+    readonly footprint?: VmRecoveryChainFootprint;
+}
+export type VmRecoveryPrepareRefusal = 'disabled' | 'closed' | 'stale-scope' | 'busy' | 'no-reader' | 'no-candidates';
+export interface VmRecoveryPrepareResult {
+    readonly accepted: number;
+    readonly refused?: VmRecoveryPrepareRefusal;
+}
+/** Cumulative, bounded, secret-free counters. */
+export interface VmRecoveryPreparationStats {
+    readonly prepareCalls: number;
+    readonly refused: number;
+    /** Candidates accepted into a prepared batch. */
+    readonly accepted: number;
+    /** Speculative reads started / finished with a usable hint / ended without one. */
+    readonly readsStarted: number;
+    readonly readsReady: number;
+    readonly readsUnusable: number;
+    /** Hints handed to a consumer (single use). */
+    readonly hits: number;
+    /** Consumer lookups that found nothing usable. */
+    readonly misses: number;
+    readonly staleMisses: number;
+    /** Prepared entries dropped without being consumed. */
+    readonly discardedUnused: number;
+    /** Speculative results that completed after their batch was gone. */
+    readonly lateDropped: number;
+    readonly maxActiveReads: number;
+    readonly maxRetainedBytes: number;
+    readonly retainedBytes: number;
+    readonly activeReads: number;
+}
+/** Typed opt-in switch: env `DKG_VM_RECOVERY_PREFETCH_ENABLED`, then config, default off. */
+export declare function resolveVmRecoveryPrefetchEnabled(configValue?: boolean): boolean;
+export declare class VmRecoveryPreparation {
+    #private;
+    constructor(sizing: VmRecoveryFootprintSizingReader | null, limits?: Partial<VmRecoveryPreparationLimits>, now?: () => number);
+    get limits(): Readonly<VmRecoveryPreparationLimits>;
+    /**
+     * Begin preparing hints for a stable prefix of future candidates. Never
+     * throws and never blocks; a refusal leaves the caller's live path intact.
+     * No second batch is accepted until the first is consumed or discarded.
+     */
+    prepare(scope: VmRecoveryPreparationScope, candidates: readonly VmRecoveryPreparationCandidate[]): VmRecoveryPrepareResult;
+    /** Hints bound to `scope`, for the planner. Hints are single-use; see {@link release}. */
+    hintsFor(scope: VmRecoveryPreparationScope): VmRecoveryPreparedHints;
+    /**
+     * The consumer is done with its prepared hints: whatever it did not take is
+     * discarded (and any read still in flight is cancelled), freeing the single
+     * batch slot for the next preparation.
+     */
+    release(scope: VmRecoveryPreparationScope): void;
+    /**
+     * Drop the prepared batch (generation change, unsubscribe, binding change,
+     * shutdown). With a `localCgId` only that graph's batch is dropped.
+     */
+    discard(localCgId?: string): void;
+    get closed(): boolean;
+    /**
+     * Stop for good: cancel speculative reads, drop hints and wait for every
+     * physical read this owner started to settle. Late results are never applied.
+     */
+    close(): Promise<void>;
+    stats(): VmRecoveryPreparationStats;
+}
+export { vmRecoveryRetryDelay } from './vm-recovery-pass-authority.js';
+/** The host's preparation owner, created on first use and replaced after a close. */
+export declare function vmRecoveryPreparationFor(host: object, sizing: VmRecoveryFootprintSizingReader | null, limits?: Partial<VmRecoveryPreparationLimits>, now?: () => number): VmRecoveryPreparation;
+/** The host's owner if one was ever created; never creates one. */
+export declare function existingVmRecoveryPreparation(host: object): VmRecoveryPreparation | undefined;
+/** Cumulative preparation counters as one logfmt-style fragment (secret-free). */
+export declare function formatVmRecoveryPreparationStats(stats: VmRecoveryPreparationStats): string;
+//# sourceMappingURL=vm-recovery-preparation.d.ts.map

package/dist/vm-recovery-preparation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vm-recovery-preparation.d.ts","sourceRoot":"","sources":["../src/vm-recovery-preparation.ts"],"names":[],"mappings":"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"}