harnery 0.38.0 → 0.40.0

package/dist/core/diagnostics/pressure-contract.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Pressure assessment: the one explained answer to "is this machine under
+ * contention, and what should an agent do about it?"
+ *
+ * Two rules are structural rather than advisory. State comes only from
+ * contention evidence the kernel reports (stall time, kills, reclaim rates,
+ * exhausted capacity); attribution findings name who is using a resource and
+ * are carried as contributors that can never raise or lower the state. And a
+ * dimension the platform does not expose is reported as unavailable, never
+ * silently read as healthy.
+ */
+import type { ResourceSnapshot } from "../resources/contract.js";
+export declare const PRESSURE_ASSESSMENT_SCHEMA_VERSION: 1;
+export type PressureState = "normal" | "elevated" | "critical" | "unknown";
+export type PressureScope = "guest" | "native" | "windows-host";
+export type PressureLimitingResource = "memory" | "cpu" | "io" | "storage" | "none" | "unknown";
+export type PressureTrend = "rising" | "steady" | "falling" | "unknown";
+export type PressureRecommendedAction = "proceed" | "limit-heavy-work" | "avoid-new-heavy-work" | "unknown";
+/** What an agent is about to do, so guidance can differ by the resource it consumes. */
+export type PressureWorkloadClass = "lightweight" | "cpu-heavy" | "memory-heavy" | "storage-heavy";
+/** One measurable contention dimension. Each maps to exactly one snapshot field. */
+export type PressureDimension = "memory_stall" | "io_stall" | "cpu_stall" | "oom_kills" | "swap_activity" | "direct_reclaim" | "memory_available" | "disk_available" | "host_memory";
+export type PressureUnit = "percent" | "bytes" | "bytes-per-second" | "pages-per-second" | "count" | "milliseconds";
+export interface PressureEvidenceDimension {
+    dimension: PressureDimension;
+    state: "supported" | "unavailable";
+    observed_value: number | null;
+    unit: PressureUnit | null;
+    /** Consecutive samples this dimension has held its current side of a threshold. */
+    sample_count: number;
+    reason_code?: string;
+}
+export type PressureReasonCode = "memory_full_stall_critical" | "memory_full_stall_elevated" | "io_full_stall_critical" | "io_full_stall_elevated" | "cpu_stall_elevated" | "new_oom_kill" | "swap_out_rate_critical" | "swap_out_rate_elevated" | "direct_reclaim_with_memory_signal" | "direct_reclaim_elevated" | "memory_and_swap_exhausted" | "memory_available_low" | "disk_space_critical" | "disk_space_low" | "host_memory_pressure" | "recovering_within_dwell" | "no_contention_evidence" | "evidence_unavailable" | "snapshot_stale";
+export interface PressureReason {
+    code: PressureReasonCode;
+    dimension: PressureDimension | null;
+    summary: string;
+    observed_value: number | null;
+    threshold_value: number | null;
+    unit: PressureUnit | null;
+    sample_count: number;
+    contributes_to: PressureState;
+}
+/**
+ * A finding that names who is consuming a resource. Present so an operator can
+ * see the likely owner; never an input to `state`.
+ */
+export interface PressureContributor {
+    finding_id: string;
+    finding_kind: string;
+    finding_class: "contention" | "attribution" | "diagnostic";
+    severity: "info" | "warning" | "critical";
+    summary: string;
+    scope_kind: string;
+    scope_id: string;
+    occurrence_count: number;
+    attribution_state: "attributed" | "unattributed" | "unknown";
+    /** `exact` is the only value that may be rendered as a named owner. */
+    attribution_confidence: "exact" | "none";
+    owner_kind?: "agent" | "service";
+    owner_id?: string;
+    workload_relationship?: "active-work" | "unexpected-idle-growth" | "unknown";
+}
+export interface PressureWorkloadGuidance {
+    workload_class: PressureWorkloadClass;
+    recommendation: PressureRecommendedAction;
+    summary: string;
+}
+/**
+ * The carried-forward inputs a later sample needs to reproduce a hysteresis
+ * transition. Frozen in advice v2 and in diagnostic bundles so a replay is
+ * deterministic without the observer's memory.
+ */
+export interface PressureHysteresisState {
+    state: PressureState;
+    state_since: string;
+    /** Consecutive samples clear of every elevated threshold. */
+    consecutive_clear_samples: number;
+    /** Per-dimension consecutive samples above the elevated threshold. */
+    dimension_streaks: Readonly<Partial<Record<PressureDimension, number>>>;
+    /** Baseline for the OOM counter, so historical kills never open a finding. */
+    oom_baseline_total_kills: number | null;
+    /** While set, a new OOM kill holds `critical` until this instant. */
+    oom_hold_until: string | null;
+    /**
+     * Identity of the observer run that produced this state. A change resets
+     * every streak, because counters and PSI averages restart with it.
+     */
+    observer_generation: string | null;
+}
+export interface PressureAssessment {
+    schema_version: typeof PRESSURE_ASSESSMENT_SCHEMA_VERSION;
+    observer_only: true;
+    state: PressureState;
+    scope: PressureScope;
+    limiting_resource: PressureLimitingResource;
+    trend: PressureTrend;
+    observed_at: string;
+    sample_age_ms: number | null;
+    evidence_state: "complete" | "partial" | "unavailable";
+    evidence: readonly PressureEvidenceDimension[];
+    reasons: readonly PressureReason[];
+    contributors: readonly PressureContributor[];
+    omitted_contributor_count: number;
+    /** Share of machine memory held by processes with no validated owner. */
+    unattributed_memory_percent: number | null;
+    recommended_action: PressureRecommendedAction;
+    summary: string;
+    guidance: readonly PressureWorkloadGuidance[];
+    /** The state this sample carries forward; also the replay input of the next. */
+    hysteresis: PressureHysteresisState;
+    policy_version: typeof PRESSURE_POLICY.policy_version;
+}
+/**
+ * Every numeric threshold the assessment uses. Included in the diagnostic
+ * bundle `threshold_digest`, so tuning any value invalidates a frozen replay
+ * instead of silently changing its expected result.
+ */
+export declare const PRESSURE_POLICY: {
+    readonly policy_version: 2;
+    /** A snapshot older than this cannot support any state but `unknown`. */
+    readonly sample_staleness_ms: 15000;
+    /**
+     * A snapshot may carry a sample time slightly ahead of the assessment clock,
+     * because the observer samples and then assesses. Within this tolerance the
+     * age reads as zero; beyond it the clock is untrustworthy and the state is
+     * `unknown`. A negative age is never published.
+     */
+    readonly sample_future_tolerance_ms: 1000;
+    /** Samples of recent history the assessment may consider. */
+    readonly max_history_samples: 12;
+    readonly memory_stall: {
+        readonly critical_avg10: 50;
+        readonly elevated_avg10: 20;
+        readonly elevated_samples: 2;
+    };
+    /**
+     * Full I/O stalls are noisier than memory stalls on virtual disks, where a
+     * checkout or a bundler cache write alone can hold `avg10` in the twenties
+     * for several seconds. Elevated therefore needs a higher bar held across a
+     * longer streak than memory does.
+     */
+    readonly io_stall: {
+        readonly critical_avg10: 50;
+        readonly elevated_avg10: 30;
+        readonly elevated_samples: 5;
+    };
+    readonly cpu_stall: {
+        readonly elevated_some_avg60: 40;
+        readonly elevated_samples: 3;
+    };
+    readonly oom: {
+        readonly critical_hold_ms: 60000;
+    };
+    readonly swap_activity: {
+        readonly critical_out_bytes_per_second: number;
+        readonly critical_samples: 3;
+        readonly elevated_out_bytes_per_second: number;
+        readonly elevated_samples: 3;
+    };
+    readonly direct_reclaim: {
+        readonly elevated_pages_per_second: 100000;
+        readonly elevated_samples: 3;
+    };
+    readonly memory_available: {
+        readonly critical_available_percent: 5;
+        readonly critical_swap_used_percent: 90;
+        readonly elevated_available_percent: 10;
+        readonly elevated_samples: 3;
+    };
+    readonly disk: {
+        readonly critical_available_bytes: number;
+        readonly critical_used_percent: 97;
+        readonly elevated_available_bytes: number;
+        readonly elevated_used_percent: 90;
+    };
+    /**
+     * A state leaves only after this many consecutive samples in which no
+     * dimension sits at or above its entry threshold. The dwell is the whole of
+     * the exit hysteresis: there is no lower exit threshold, because one would
+     * hold a state open indefinitely on a reading the policy itself calls normal.
+     */
+    readonly recovery: {
+        readonly critical_exit_samples: 3;
+        readonly elevated_exit_samples: 5;
+    };
+    readonly limits: {
+        readonly max_reasons: 6;
+        readonly max_contributors: 8;
+        readonly max_evidence: 12;
+    };
+};
+/**
+ * Everything the assessment is allowed to read. Pure input: no clock, no
+ * filesystem, no findings store. `now_ms` and `observer_generation` are
+ * supplied by the caller so a fixture can drive a fake clock and a restart.
+ */
+export interface AssessPressureInput {
+    /** The latest snapshot, or null when it is missing, corrupt, or too large. */
+    snapshot: ResourceSnapshot | null;
+    /** Why the snapshot is absent, when it is. */
+    snapshot_reason?: string | null;
+    /**
+     * Recent samples, oldest first, bounded by `PRESSURE_POLICY.max_history_samples`.
+     * Used only for trend; consecutive-sample streaks come from `prior`.
+     */
+    history: readonly PressureHistorySample[];
+    /** Active findings, for contributors only. */
+    findings: readonly PressureFindingInput[];
+    findings_capability: PressureCapabilityInput;
+    /** The state the previous sample carried forward, or null on a cold start. */
+    prior: PressureHysteresisState | null;
+    observer_generation: string;
+    now_ms: number;
+}
+/**
+ * The finding fields a contributor is built from. Structurally satisfied by
+ * `SupervisorFinding`; declared here so this module stays a leaf and so the
+ * assessment cannot reach any finding field that could set state.
+ */
+export interface PressureFindingInput {
+    id: string;
+    finding_kind: string;
+    finding_class: "contention" | "attribution" | "diagnostic";
+    severity: "info" | "warning" | "critical";
+    state: "opened" | "resolved";
+    summary: string;
+    scope_kind: string;
+    scope_id: string;
+    observed_at: string;
+    occurrence_count: number;
+    attribution?: {
+        state: "attributed" | "unattributed";
+        owner_kind?: "agent" | "service";
+        owner_id?: string;
+    };
+    workload_context?: {
+        relationship: "active-work" | "unexpected-idle-growth" | "unknown";
+    };
+}
+export interface PressureCapabilityInput {
+    source_kind: string;
+    state: string;
+    reason_code?: string;
+}
+/** The subset of a past sample the trend calculation needs. */
+export interface PressureHistorySample {
+    sampled_at: string;
+    memory_full_avg10: number | null;
+    io_full_avg10: number | null;
+    cpu_some_avg60: number | null;
+    memory_available_percent: number | null;
+    swap_out_bytes_per_second: number | null;
+}
+/**
+ * Compute one explained assessment. Deterministic in its input: the same input
+ * always yields the same output, which is what makes a frozen bundle replayable.
+ */
+export type AssessPressure = (input: AssessPressureInput) => PressureAssessment;
+//# sourceMappingURL=pressure-contract.d.ts.map

package/dist/core/diagnostics/pressure-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pressure-contract.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/pressure-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,eAAO,MAAM,kCAAkC,EAAG,CAAU,CAAC;AAE7D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAC3E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,cAAc,CAAC;AAChE,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAChG,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AACxE,MAAM,MAAM,yBAAyB,GACjC,SAAS,GACT,kBAAkB,GAClB,sBAAsB,GACtB,SAAS,CAAC;AAEd,wFAAwF;AACxF,MAAM,MAAM,qBAAqB,GAAG,aAAa,GAAG,WAAW,GAAG,cAAc,GAAG,eAAe,CAAC;AAEnG,oFAAoF;AACpF,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,UAAU,GACV,WAAW,GACX,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,CAAC;AAElB,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,OAAO,GACP,kBAAkB,GAClB,kBAAkB,GAClB,OAAO,GACP,cAAc,CAAC;AAEnB,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,KAAK,EAAE,WAAW,GAAG,aAAa,CAAC;IACnC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,kBAAkB,GAC1B,4BAA4B,GAC5B,4BAA4B,GAC5B,wBAAwB,GACxB,wBAAwB,GACxB,oBAAoB,GACpB,cAAc,GACd,wBAAwB,GACxB,wBAAwB,GACxB,mCAAmC,GACnC,yBAAyB,GACzB,2BAA2B,GAC3B,sBAAsB,GACtB,qBAAqB,GACrB,gBAAgB,GAChB,sBAAsB,GACtB,yBAAyB,GACzB,wBAAwB,GACxB,sBAAsB,GACtB,gBAAgB,CAAC;AAErB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,aAAa,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,YAAY,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,YAAY,GAAG,cAAc,GAAG,SAAS,CAAC;IAC7D,uEAAuE;IACvE,sBAAsB,EAAE,OAAO,GAAG,MAAM,CAAC;IACzC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB,CAAC,EAAE,aAAa,GAAG,wBAAwB,GAAG,SAAS,CAAC;CAC9E;AAED,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,qBAAqB,CAAC;IACtC,cAAc,EAAE,yBAAyB,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,aAAa,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,yBAAyB,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,iBAAiB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACxE,8EAA8E;IAC9E,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,qEAAqE;IACrE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;OAGG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,OAAO,kCAAkC,CAAC;IAC1D,aAAa,EAAE,IAAI,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE,aAAa,CAAC;IACrB,iBAAiB,EAAE,wBAAwB,CAAC;IAC5C,KAAK,EAAE,aAAa,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,UAAU,GAAG,SAAS,GAAG,aAAa,CAAC;IACvD,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC/C,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC7C,yBAAyB,EAAE,MAAM,CAAC;IAClC,yEAAyE;IACzE,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,kBAAkB,EAAE,yBAAyB,CAAC;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC9C,gFAAgF;IAChF,UAAU,EAAE,uBAAuB,CAAC;IACpC,cAAc,EAAE,OAAO,eAAe,CAAC,cAAc,CAAC;CACvD;AAKD;;;;GAIG;AACH,eAAO,MAAM,eAAe;;IAE1B,yEAAyE;;IAEzE;;;;;OAKG;;IAEH,6DAA6D;;;;;;;IAG7D;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuBH;;;;;OAKG;;;;;;;;;;CAGK,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAClC,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;OAGG;IACH,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1C,8CAA8C;IAC9C,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC1C,mBAAmB,EAAE,uBAAuB,CAAC;IAC7C,8EAA8E;IAC9E,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACtC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,YAAY,GAAG,aAAa,GAAG,YAAY,CAAC;IAC3D,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAC1C,KAAK,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE;QACZ,KAAK,EAAE,YAAY,GAAG,cAAc,CAAC;QACrC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,gBAAgB,CAAC,EAAE;QAAE,YAAY,EAAE,aAAa,GAAG,wBAAwB,GAAG,SAAS,CAAA;KAAE,CAAC;CAC3F;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,kBAAkB,CAAC"}

package/dist/core/diagnostics/pressure-contract.js

@@ -0,0 +1,70 @@
+/**
+ * Pressure assessment: the one explained answer to "is this machine under
+ * contention, and what should an agent do about it?"
+ *
+ * Two rules are structural rather than advisory. State comes only from
+ * contention evidence the kernel reports (stall time, kills, reclaim rates,
+ * exhausted capacity); attribution findings name who is using a resource and
+ * are carried as contributors that can never raise or lower the state. And a
+ * dimension the platform does not expose is reported as unavailable, never
+ * silently read as healthy.
+ */
+export const PRESSURE_ASSESSMENT_SCHEMA_VERSION = 1;
+const MIB = 1_024 * 1_024;
+const GIB = 1_024 * MIB;
+/**
+ * Every numeric threshold the assessment uses. Included in the diagnostic
+ * bundle `threshold_digest`, so tuning any value invalidates a frozen replay
+ * instead of silently changing its expected result.
+ */
+export const PRESSURE_POLICY = {
+    policy_version: 2,
+    /** A snapshot older than this cannot support any state but `unknown`. */
+    sample_staleness_ms: 15_000,
+    /**
+     * A snapshot may carry a sample time slightly ahead of the assessment clock,
+     * because the observer samples and then assesses. Within this tolerance the
+     * age reads as zero; beyond it the clock is untrustworthy and the state is
+     * `unknown`. A negative age is never published.
+     */
+    sample_future_tolerance_ms: 1_000,
+    /** Samples of recent history the assessment may consider. */
+    max_history_samples: 12,
+    memory_stall: { critical_avg10: 50, elevated_avg10: 20, elevated_samples: 2 },
+    /**
+     * Full I/O stalls are noisier than memory stalls on virtual disks, where a
+     * checkout or a bundler cache write alone can hold `avg10` in the twenties
+     * for several seconds. Elevated therefore needs a higher bar held across a
+     * longer streak than memory does.
+     */
+    io_stall: { critical_avg10: 50, elevated_avg10: 30, elevated_samples: 5 },
+    cpu_stall: { elevated_some_avg60: 40, elevated_samples: 3 },
+    oom: { critical_hold_ms: 60_000 },
+    swap_activity: {
+        critical_out_bytes_per_second: 50 * MIB,
+        critical_samples: 3,
+        elevated_out_bytes_per_second: 5 * MIB,
+        elevated_samples: 3,
+    },
+    direct_reclaim: { elevated_pages_per_second: 100_000, elevated_samples: 3 },
+    memory_available: {
+        critical_available_percent: 5,
+        critical_swap_used_percent: 90,
+        elevated_available_percent: 10,
+        elevated_samples: 3,
+    },
+    disk: {
+        critical_available_bytes: 1 * GIB,
+        critical_used_percent: 97,
+        elevated_available_bytes: 5 * GIB,
+        elevated_used_percent: 90,
+    },
+    /**
+     * A state leaves only after this many consecutive samples in which no
+     * dimension sits at or above its entry threshold. The dwell is the whole of
+     * the exit hysteresis: there is no lower exit threshold, because one would
+     * hold a state open indefinitely on a reading the policy itself calls normal.
+     */
+    recovery: { critical_exit_samples: 3, elevated_exit_samples: 5 },
+    limits: { max_reasons: 6, max_contributors: 8, max_evidence: 12 },
+};

package/dist/core/diagnostics/pressure.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The deterministic pressure assessment.
+ *
+ * Two rules shape everything below. State is derived only from contention
+ * dimensions the kernel measures, so a large process or a heavy hook can never
+ * make the machine look critical on its own; those findings are carried as
+ * contributors instead. And a dimension the platform does not expose is
+ * reported as unavailable rather than read as healthy, so an unavailable
+ * measurement can never pull a known critical signal down to normal.
+ *
+ * The module is pure. It reads no clock, no filesystem, and no findings store,
+ * and it imports only the frozen contract. `now_ms`, `observer_generation`, and
+ * `prior` come from the caller, which is what makes a frozen bundle replayable.
+ *
+ * Every numeric threshold is read from `PRESSURE_POLICY`. The only literals
+ * here are unit conversions used to phrase a summary in readable units.
+ *
+ * Exit is a dwell, not a second threshold. A sample counts as clear when no
+ * dimension sits at or above its entry threshold, and a state leaves after the
+ * policy's run of consecutive clear samples. A reading below the entry bar is
+ * normal by definition, so it can never hold a state open on its own.
+ */
+import { type AssessPressure } from "./pressure-contract.js";
+export declare const assessPressure: AssessPressure;
+//# sourceMappingURL=pressure.d.ts.map

package/dist/core/diagnostics/pressure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pressure.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/pressure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EACL,KAAK,cAAc,EAmBpB,MAAM,wBAAwB,CAAC;AAoFhC,eAAO,MAAM,cAAc,EAAE,cA0Z5B,CAAC"}