@origintrail-official/dkg-core 10.0.11 → 10.0.13

package/dist/backpressure-observability.d.ts

@@ -0,0 +1,273 @@
+export type BackpressureState = 'healthy' | 'degraded' | 'saturated' | 'stalled';
+export type SchedulerPressureOutcome = 'completed' | 'failed' | 'cancelled' | 'released';
+/**
+ * How a scheduler's capacity is divided between its lanes.
+ *
+ * `partitioned` (the default): every lane owns a private allocation, declared
+ * in `lanes`, and fills independently of its neighbours —
+ * `StorePriorityScheduler`. Nothing validates the scheduler-level `queueLimit`
+ * against the lane allocations: a scheduler may publish their sum (the store
+ * scheduler does), or cap its total below what its lanes could hold between
+ * them, and `sumLaneLimits` falls back to the sum when no scheduler ceiling is
+ * published at all. So read a lane's own limit for lane pressure and the
+ * scheduler's for the rollup, and derive neither from the other.
+ *
+ * `shared`: every lane draws on ONE pool bounded by the scheduler-level
+ * `queueLimit`/`inflightLimit`. There is no private allocation to declare, so a
+ * lane's ceiling *is* the pool's ceiling, lane ceilings must never be summed,
+ * and the depth a lane's queued work is waiting behind is the pool's, not that
+ * lane's own share of it — `PriorityAdmissionQueue`.
+ */
+export type SchedulerLaneCapacityModel = 'partitioned' | 'shared';
+interface SchedulerPressureCapacityLimits {
+    queueLimit?: number | null;
+    inflightLimit?: number | null;
+}
+/**
+ * The two models are mutually exclusive at the type level rather than by
+ * convention: a shared pool has no private allocations, so it cannot carry
+ * `lanes`. Omitting `capacityModel` keeps the pre-existing `partitioned` shape,
+ * so every current caller is unaffected.
+ */
+export type SchedulerPressureCapacity = (SchedulerPressureCapacityLimits & {
+    capacityModel?: 'partitioned';
+    /**
+     * Private per-lane allocations. Independent of the scheduler-level limits
+     * above — see {@link SchedulerLaneCapacityModel}; they are not summed and
+     * not validated against them.
+     */
+    lanes?: Record<string, {
+        queueLimit?: number | null;
+        inflightLimit?: number | null;
+    }>;
+}) | (SchedulerPressureCapacityLimits & {
+    capacityModel: 'shared';
+    /** A shared pool has no private allocation to declare. */
+    lanes?: never;
+});
+export interface SchedulerPressureThresholds {
+    /** Queue age that turns otherwise-low utilization into degraded pressure. */
+    degradedQueueAgeMs?: number;
+    /** Active-work age that indicates an admitted operation may be stuck. */
+    stalledActiveAgeMs?: number;
+    /** Fraction of a bounded queue that marks a lane as degraded. */
+    degradedQueueUtilization?: number;
+    /** Keep a recent admission rejection visible as saturation for this long. */
+    rejectionStateWindowMs?: number;
+}
+export interface SchedulerPressureWork {
+    lane: string;
+    operation: string;
+}
+export interface SchedulerPressureTicket {
+    readonly id: number;
+}
+export interface BackpressureOperationSummary {
+    operation: string;
+    count: number;
+    oldestAgeMs: number;
+}
+export interface BackpressureLaneSnapshot {
+    lane: string;
+    state: BackpressureState;
+    /**
+     * How to read `queueLimit` on this row. Under `shared` it is the
+     * scheduler-wide pool this lane draws on rather than a private allocation —
+     * the same number on every lane, never to be summed.
+     *
+     * Optional so an existing hand-built `BackpressureSource` still satisfies
+     * this type; absent means `partitioned`. `SchedulerPressureTracker` always
+     * emits it.
+     */
+    capacityModel?: SchedulerLaneCapacityModel;
+    /** This lane's own backlog. The attribution signal: whose work is waiting. */
+    queued: number;
+    /**
+     * The depth `state` was actually classified against, and the numerator that
+     * goes with `queueLimit` — equal to `queued` for a private allocation, and
+     * the pool's whole depth for a shared one. Read this, not `queued`, to
+     * compute utilization, so a consumer never has to special-case the model.
+     *
+     * Optional for the same backward-compatibility reason as `capacityModel`;
+     * absent means `queued`.
+     */
+    pressureQueued?: number;
+    queueLimit: number | null;
+    /** This lane's own admitted work. The attribution signal, like `queued`. */
+    inflight: number;
+    /**
+     * The admitted count that goes with `inflightLimit`: this lane's own under a
+     * private allocation, and on a shared row **the pool's occupancy, always** —
+     * unlike `pressureQueued`, which falls back to the lane's own backlog where
+     * no depth was classified (an idle lane, or a pool with no ceiling). The
+     * asymmetry is deliberate: `pressureQueued` must equal the classifier's
+     * numerator or a row contradicts its own state, while no branch reads
+     * `inflight` or `inflightLimit` — this pair is reported, never judged — so on
+     * a shared row the ratio is a pool ratio by construction. Gating it on queued
+     * work would make the series step 0 -> N on an unrelated enqueue with no
+     * change in real concurrency. Absent means `inflight`.
+     */
+    pressureInflight?: number;
+    inflightLimit: number | null;
+    oldestQueuedAgeMs: number;
+    oldestActiveAgeMs: number;
+    queuedOperations: BackpressureOperationSummary[];
+    activeOperations: BackpressureOperationSummary[];
+    events: Record<string, number>;
+    rejectedTotal: number;
+    rejectedByReason: Record<string, number>;
+    /** Age of the latest rejection; safe for monotonic or epoch-based clocks. */
+    lastRejectedAgeMs: number | null;
+}
+export interface BackpressureSnapshot {
+    scheduler: string;
+    state: BackpressureState;
+    /**
+     * How this scheduler divides capacity between its lanes. It is a **scheduler**
+     * invariant — every lane of one scheduler shares it — so read it here; the
+     * copy on each lane row is derived, and exists so a single row still explains
+     * its own `queueLimit` when it travels alone (a log line, one metric series).
+     *
+     * Optional so a hand-built `BackpressureSource` still satisfies this type;
+     * absent means `partitioned`.
+     */
+    capacityModel?: SchedulerLaneCapacityModel;
+    totals: {
+        queued: number;
+        queueLimit: number | null;
+        inflight: number;
+        inflightLimit: number | null;
+        oldestQueuedAgeMs: number;
+        oldestActiveAgeMs: number;
+        rejectedTotal: number;
+    };
+    lanes: BackpressureLaneSnapshot[];
+}
+export interface BackpressureSource {
+    readonly backpressureId: string;
+    getBackpressureSnapshot(): BackpressureSnapshot;
+}
+export interface BackpressureRegistrySnapshot {
+    capturedAt: string;
+    state: BackpressureState;
+    schedulers: BackpressureSnapshot[];
+    failures: Array<{
+        scheduler: string;
+        error: string;
+    }>;
+}
+/**
+ * Keep metric/log dimensions bounded and strip payload-like punctuation.
+ * Callers should still pass static operation names rather than graph, peer, or
+ * job identifiers.
+ */
+export declare function normalizeBackpressureLabel(value: string, fallback?: string): string;
+export interface SchedulerPressureTrackerOptions {
+    scheduler: string;
+    capacity?: SchedulerPressureCapacity;
+    thresholds?: SchedulerPressureThresholds;
+    now?: () => number;
+}
+/**
+ * Scheduling-policy-neutral lifecycle tracker.
+ *
+ * Queue implementations call the five transition methods at their existing
+ * admission boundaries. The tracker owns timings, state classification,
+ * bounded metrics, and diagnostic snapshots, but never decides which work may
+ * run. All observability calls are fail-open so instrumentation cannot change
+ * scheduler behaviour.
+ */
+export declare class SchedulerPressureTracker {
+    readonly scheduler: string;
+    private readonly queued;
+    private readonly active;
+    private readonly lanes;
+    private readonly now;
+    private readonly thresholds;
+    private capacity;
+    private nextTicketId;
+    constructor(options: SchedulerPressureTrackerOptions);
+    updateCapacity(capacity: SchedulerPressureCapacity): void;
+    enqueue(work: SchedulerPressureWork): SchedulerPressureTicket;
+    start(ticket: SchedulerPressureTicket): void;
+    reject(work: SchedulerPressureWork, reason: string): void;
+    rejectQueued(ticket: SchedulerPressureTicket, reason: string): void;
+    cancelQueued(ticket: SchedulerPressureTicket, reason?: string): void;
+    finish(ticket: SchedulerPressureTicket, outcome: SchedulerPressureOutcome): void;
+    snapshot(): BackpressureSnapshot;
+    private runtimeFor;
+    private recordEvent;
+    private recordRejection;
+    /**
+     * Everything the capacity model decides, in one place: which ceilings apply
+     * to a lane, what depth its state is measured against, and whether depth
+     * pressure applies at all. `laneSnapshot` stays a model-agnostic classifier,
+     * so adding a model means extending this descriptor rather than editing the
+     * classifier's branches.
+     */
+    private laneCapacityFor;
+    private laneSnapshot;
+    /**
+     * Reached only when the scheduler publishes no ceiling of its own — which is
+     * also the only case in which a `shared` lane has none either, since a shared
+     * lane's ceiling resolves from that same value. A pool ceiling can therefore
+     * never become a summand here, which it must not: summing it would report N×
+     * the real capacity and silence the rollup's own saturation branch.
+     */
+    private sumLaneLimits;
+    private safeMetric;
+}
+/**
+ * Base class for in-memory schedulers. Subclasses retain complete ownership of
+ * queue ordering, admission, coalescing, and release semantics and call these
+ * protected lifecycle methods at their existing boundaries.
+ */
+export declare abstract class ObservableScheduler implements BackpressureSource {
+    protected readonly pressure: SchedulerPressureTracker;
+    protected constructor(options: SchedulerPressureTrackerOptions);
+    get backpressureId(): string;
+    getBackpressureSnapshot(): BackpressureSnapshot;
+    protected updatePressureCapacity(capacity: SchedulerPressureCapacity): void;
+    protected pressureEnqueue(work: SchedulerPressureWork): SchedulerPressureTicket;
+    protected pressureStart(ticket: SchedulerPressureTicket): void;
+    protected pressureReject(work: SchedulerPressureWork, reason: string): void;
+    protected pressureRejectQueued(ticket: SchedulerPressureTicket, reason: string): void;
+    protected pressureCancelQueued(ticket: SchedulerPressureTicket, reason?: string): void;
+    protected pressureFinish(ticket: SchedulerPressureTicket, outcome: SchedulerPressureOutcome): void;
+}
+export declare class BackpressureRegistry {
+    private readonly sources;
+    register(source: BackpressureSource): () => void;
+    capture(): BackpressureRegistrySnapshot;
+}
+export declare const backpressureRegistry: BackpressureRegistry;
+export declare function recordBackpressureSnapshotMetrics(snapshot: BackpressureSnapshot): void;
+export interface BackpressureMonitorOptions {
+    registry?: BackpressureRegistry;
+    intervalMs?: number;
+    summaryIntervalMs?: number;
+    now?: () => number;
+    emit: (level: 'info' | 'warn', message: string, snapshot: BackpressureSnapshot, lane: BackpressureLaneSnapshot | null) => void;
+}
+/**
+ * One process-wide sampler provides transition/recovery logging and periodic
+ * summaries. It logs state changes rather than individual queue operations.
+ */
+export declare class BackpressureMonitor {
+    private readonly registry;
+    private readonly intervalMs;
+    private readonly summaryIntervalMs;
+    private readonly now;
+    private readonly emit;
+    private readonly logged;
+    private timer;
+    constructor(options: BackpressureMonitorOptions);
+    start(): void;
+    stop(): void;
+    sample(): void;
+    private observeSample;
+    private message;
+    private safeEmit;
+}
+export {};
+//# sourceMappingURL=backpressure-observability.d.ts.map

package/dist/backpressure-observability.d.ts.map

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