@indigoai-us/hq-cli 5.106.2 → 5.107.0

package/dist/unhandled-rejection-boundary.js

@@ -0,0 +1,106 @@
+// src/unhandled-rejection-boundary.ts
+//
+// A process-level unhandledRejection boundary for the CLI entrypoint.
+//
+// @sentry/node's onUnhandledRejection integration defaults to mode 'warn': it
+// CAPTURES a floated rejection but does NOT rethrow it. hq-cli installs no
+// rejection handler of its own, so without this boundary ANY floated rejection
+// (the class that produced Sentry HQ-CLI-W) leaves process.exitCode unset, the
+// event loop drains, and Node exits 0 — a silent success in which the command
+// never ran. index.ts's own comment ("Rejections still become unhandled and
+// preserve a genuine non-zero failure") described the pre-Sentry world and is
+// no longer true; this boundary restores it.
+//
+// The logic is factored out of index.ts so it is unit-testable: importing
+// index.ts for a test would trigger the real command dispatch.
+import { isEpipe } from "./utils/epipe.js";
+// Sticky once a non-EPIPE floated rejection has been handled. `process.exitCode`
+// alone is not enough: a command path that later calls `process.exit(0)` — e.g.
+// `hq run`'s child-`close` handler after a child that exited 0 — would erase the
+// failure. Exit paths that propagate their own status consult this to force a
+// non-zero code instead (see src/commands/run.ts).
+let fatalRejectionSeen = false;
+export function hadFatalRejection() {
+    return fatalRejectionSeen;
+}
+// Rejections a scoped handler (e.g. resolveEnvValuesOrThrow) has already claimed
+// and will surface through the normal command path. The process-wide boundary
+// defers to the claimer so one failure yields exactly one diagnostic rather than
+// both a scoped throw AND a boundary report of the same rejection.
+const claimedRejections = new Set();
+export function claimRejection(reason) {
+    claimedRejections.add(reason);
+}
+export function releaseRejection(reason) {
+    claimedRejections.delete(reason);
+}
+/** Reset the process-level rejection state. Test-only. */
+export function __resetRejectionStateForTests() {
+    fatalRejectionSeen = false;
+    claimedRejections.clear();
+}
+/**
+ * Handle one floated rejection. Synchronously fixes the exit code — a broken
+ * pipe (EPIPE) is a clean close (0), anything else is a failure (1) — WITHOUT
+ * downgrading a non-zero code a command path already set, then kicks off a
+ * best-effort actionable report. Never calls process.exit, so the command's
+ * finally block (release-health session end + bounded Sentry flush) still runs.
+ */
+export function handleFatalRejection(reason, deps) {
+    // A scoped handler already owns this exact rejection and will surface it
+    // through the normal command path; do not exit-code or report it twice.
+    if (claimedRejections.has(reason))
+        return;
+    if (isEpipe(reason)) {
+        // A clean downstream close. Only assert 0 when nothing has already failed.
+        if (deps.getExitCode() === undefined)
+            deps.setExitCode(0);
+    }
+    else {
+        // A genuine fatal rejection: mark it sticky, and mark the run failed unless
+        // a command already set a non-zero code (e.g. a child's exit status).
+        fatalRejectionSeen = true;
+        if (!deps.getExitCode())
+            deps.setExitCode(1);
+    }
+    deps.report(reason);
+}
+let installed = false;
+/**
+ * Register the boundary on `process`, once, before index.ts dispatches into the
+ * command graph. Idempotent so repeated imports/installs add a single listener.
+ * The actionable report routes through main.ts's existing handleTopLevelError
+ * with a NO-OP capture: @sentry/node's integration has already captured the
+ * rejection, so this only adds the classified `hq:` line (and its EPIPE / typed
+ * carve-outs) without a second Sentry event.
+ */
+export function installProcessRejectionBoundary() {
+    if (installed)
+        return;
+    installed = true;
+    process.on("unhandledRejection", (reason) => {
+        handleFatalRejection(reason, {
+            getExitCode: () => process.exitCode,
+            setExitCode: (code) => {
+                process.exitCode = code;
+            },
+            report: (r) => {
+                void import("./main.js")
+                    .then(({ handleTopLevelError }) => handleTopLevelError(r, {
+                    sentry: { captureException: () => undefined },
+                    stderr: process.stderr,
+                    // Print-only. handleFatalRejection already set the authoritative,
+                    // downgrade-guarded exit code synchronously; letting the async
+                    // report re-set it would let handleTopLevelError's EPIPE branch
+                    // (setExitCode(0)) reset an earlier failure to success.
+                    setExitCode: () => { },
+                }))
+                    .catch(() => {
+                    // main.js could not be loaded (a rejection on a path that never
+                    // imported it). The synchronous exit code above still stands.
+                });
+            },
+        });
+    });
+}
+//# sourceMappingURL=unhandled-rejection-boundary.js.map

package/dist/utils/client-health-contract.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Client-health wire contract (client-sync-health-control-plane US-000).
+ *
+ * ONE versioned contract shared in spirit across four adapters:
+ *
+ *   - hq-pro            src/sync/server/client-health-contract.ts   (reference)
+ *   - hq-desktop-app    crates/hq-desktop-core/src/client_health.rs
+ *   - hq-cli            src/utils/client-health-contract.ts         (this file)
+ *   - indigo-gtm-hq     src/lib/client-health.ts
+ *
+ * Every adapter uses the SAME field names and the SAME enum values, verified
+ * per-repo against byte-equivalent canonical fixtures (here embedded in
+ * src/utils/client-health-contract.test.ts). The interface, not repository
+ * internals, is the shared test surface.
+ *
+ * Design rules (PRD notes + securityNotes):
+ *
+ *   - ADDITIVE + tolerant of older clients: every non-identity field is
+ *     optional-friendly, and unknown EXTRA fields are ignored (a newer client
+ *     talking to an older server must not fail). Absence of `updaterState`
+ *     means "an older client that never reported it"; the closed value
+ *     "unchecked" means "the updater has not run yet" — the two are distinct
+ *     and must survive the wire.
+ *   - FAIL CLOSED on values: enums are closed sets. Free-form shell text,
+ *     customer file paths, secret-shaped values, raw logs, and unknown repair
+ *     kinds are rejected with a typed {@link ClientHealthContractError}.
+ *   - Device identity: clients send only the stable random `installationId`.
+ *     HMAC'ing of device identifiers happens server-side (US-001, modeled on
+ *     scope-sync-mode-repository.ts) and never crosses this wire contract.
+ *   - Monotonic `sequence`: the server keeps the highest sequence seen per
+ *     installation and drops older/replayed heartbeats
+ *     ({@link shouldApplyHeartbeat}).
+ */
+export declare const CLIENT_HEALTH_CONTRACT_VERSION = 1;
+export declare const CLIENT_HEALTH_PLATFORMS: readonly ["macos", "windows", "linux"];
+export type ClientHealthPlatform = (typeof CLIENT_HEALTH_PLATFORMS)[number];
+export declare const CLIENT_HEALTH_ARCHS: readonly ["x64", "arm64"];
+export type ClientHealthArch = (typeof CLIENT_HEALTH_ARCHS)[number];
+/** Which client produced the heartbeat. Desktop is always-on; CLI contributes per invocation. */
+export declare const CLIENT_HEALTH_SOURCES: readonly ["desktop", "cli"];
+export type ClientHealthSource = (typeof CLIENT_HEALTH_SOURCES)[number];
+/**
+ * Current sync state of the installation. `paused` and `conflict_blocked` are
+ * first-class states (not failures folded into `error`) because support treats
+ * them differently: pause may be intentional and conflicts are user-owned.
+ */
+export declare const CLIENT_HEALTH_SYNC_STATES: readonly ["idle", "syncing", "paused", "conflict_blocked", "error", "never_synced"];
+export type ClientHealthSyncState = (typeof CLIENT_HEALTH_SYNC_STATES)[number];
+/**
+ * Updater state. ABSENCE of the field means the client is too old to report
+ * it; `"unchecked"` means the updater exists but has not checked yet. Do not
+ * collapse the two (US-000 acceptance: Unchecked vs Absent must survive).
+ */
+export declare const CLIENT_HEALTH_UPDATER_STATES: readonly ["unchecked", "up_to_date", "update_available", "update_downloading", "update_ready", "update_failed", "unsupported"];
+export type ClientHealthUpdaterState = (typeof CLIENT_HEALTH_UPDATER_STATES)[number];
+/** Closed failure/blocker reason codes — the ONLY reasons that cross the wire. */
+export declare const CLIENT_HEALTH_FAILURE_REASONS: readonly ["SYNC_PAUSED", "CONFLICT_BLOCKED", "DESKTOP_OUTDATED", "CLI_OUTDATED", "CORE_OUTDATED", "AUTH_EXPIRED", "UPDATE_FAILED", "RUNNER_FAILED", "PERMISSION_DENIED", "DISK_FULL", "HEARTBEAT_STALE"];
+export type ClientHealthFailureReason = (typeof CLIENT_HEALTH_FAILURE_REASONS)[number];
+/**
+ * Repair/diagnostic command allowlist (US-006/US-009 consume these shapes).
+ * A desired-state interface, never a remote shell — any kind outside this set
+ * fails closed.
+ */
+export declare const CLIENT_HEALTH_REPAIR_KINDS: readonly ["CHECK_NOW", "RETRY_SYNC", "RESUME_SYNC", "REPAIR_CLI", "UPDATE_CORE", "APPLY_DESKTOP_UPDATE", "RESTART_APP"];
+export type ClientHealthRepairKind = (typeof CLIENT_HEALTH_REPAIR_KINDS)[number];
+/** Command/receipt lifecycle states (queued → acknowledged → running → terminal). */
+export declare const CLIENT_HEALTH_COMMAND_STATES: readonly ["queued", "acknowledged", "running", "succeeded", "failed", "expired"];
+export type ClientHealthCommandState = (typeof CLIENT_HEALTH_COMMAND_STATES)[number];
+/** Closed diagnostic probe identifiers (US-007). */
+export declare const CLIENT_HEALTH_DIAGNOSTIC_CHECKS: readonly ["auth", "runner", "cli", "core", "updater", "sync", "conflicts", "storage", "permissions"];
+export type ClientHealthDiagnosticCheck = (typeof CLIENT_HEALTH_DIAGNOSTIC_CHECKS)[number];
+export declare const CLIENT_HEALTH_CHECK_STATUSES: readonly ["pass", "fail", "skip"];
+export type ClientHealthCheckStatus = (typeof CLIENT_HEALTH_CHECK_STATUSES)[number];
+export declare const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
+export declare const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100000;
+export declare const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100000;
+export declare const CLIENT_HEALTH_MAX_CHECKS = 16;
+/**
+ * The four client versions. All optional: a CLI-only installation has no
+ * desktop/syncRunner version, and older clients may omit any of them.
+ */
+export interface ClientHealthVersions {
+    desktop?: string;
+    cli?: string;
+    core?: string;
+    syncRunner?: string;
+}
+export interface ClientHealthHeartbeat {
+    contractVersion: number;
+    /** Stable random installation identity — NOT a hardware fingerprint. */
+    installationId: string;
+    source: ClientHealthSource;
+    platform: ClientHealthPlatform;
+    arch: ClientHealthArch;
+    /** Client-side emit time (liveness); the server also stamps receive time. */
+    sentAt: string;
+    /** Monotonic per-installation sequence — older/replayed values never overwrite newer state. */
+    sequence: number;
+    versions: ClientHealthVersions;
+    syncState: ClientHealthSyncState;
+    /** Last time a sync RUN started — distinct from success. */
+    lastSyncAttemptAt?: string;
+    /** Advances only on genuine success (including no-change runs). */
+    lastSyncSuccessAt?: string;
+    consecutiveFailures: number;
+    conflictCount?: number;
+    updaterState?: ClientHealthUpdaterState;
+    failureReason?: ClientHealthFailureReason;
+}
+export interface ClientHealthCheckResult {
+    check: ClientHealthDiagnosticCheck;
+    status: ClientHealthCheckStatus;
+    /** Present only on `fail` — a closed reason code, never prose. */
+    reason?: ClientHealthFailureReason;
+}
+/**
+ * Receipt for a diagnostic or repair command (US-006+ store these). `checks`
+ * is only meaningful for `CHECK_NOW`.
+ */
+export interface ClientHealthCommandReceipt {
+    contractVersion: number;
+    commandId: string;
+    installationId: string;
+    kind: ClientHealthRepairKind;
+    state: ClientHealthCommandState;
+    /** Monotonic per-command revision — out-of-order receipt updates fail closed downstream. */
+    revision: number;
+    occurredAt: string;
+    checks?: ClientHealthCheckResult[];
+    failureReason?: ClientHealthFailureReason;
+}
+export type ClientHealthContractErrorCode = "MISSING_FIELD" | "INVALID_TYPE" | "UNKNOWN_ENUM_VALUE" | "UNSAFE_VALUE" | "OUT_OF_BOUNDS" | "UNSUPPORTED_CONTRACT_VERSION";
+export declare class ClientHealthContractError extends Error {
+    readonly code: ClientHealthContractErrorCode;
+    readonly field: string;
+    constructor(code: ClientHealthContractErrorCode, field: string, detail?: string);
+}
+/**
+ * Parse + validate one heartbeat. Unknown extra fields are ignored (additive
+ * tolerance); every consumed value fails closed on unsafe content.
+ */
+export declare function parseClientHealthHeartbeat(input: unknown): ClientHealthHeartbeat;
+/** Parse + validate one diagnostic/repair command receipt. Unknown kinds fail closed. */
+export declare function parseClientHealthCommandReceipt(input: unknown): ClientHealthCommandReceipt;
+/**
+ * True when an incoming heartbeat sequence may replace the stored snapshot.
+ * Equal or older sequences are late deliveries/replays: drop them (the server
+ * answers idempotently and the current snapshot remains unchanged).
+ */
+export declare function shouldApplyHeartbeat(storedSequence: number | undefined, incomingSequence: number): boolean;
+//# sourceMappingURL=client-health-contract.d.ts.map

package/dist/utils/client-health-contract.js

@@ -0,0 +1,306 @@
+/**
+ * Client-health wire contract (client-sync-health-control-plane US-000).
+ *
+ * ONE versioned contract shared in spirit across four adapters:
+ *
+ *   - hq-pro            src/sync/server/client-health-contract.ts   (reference)
+ *   - hq-desktop-app    crates/hq-desktop-core/src/client_health.rs
+ *   - hq-cli            src/utils/client-health-contract.ts         (this file)
+ *   - indigo-gtm-hq     src/lib/client-health.ts
+ *
+ * Every adapter uses the SAME field names and the SAME enum values, verified
+ * per-repo against byte-equivalent canonical fixtures (here embedded in
+ * src/utils/client-health-contract.test.ts). The interface, not repository
+ * internals, is the shared test surface.
+ *
+ * Design rules (PRD notes + securityNotes):
+ *
+ *   - ADDITIVE + tolerant of older clients: every non-identity field is
+ *     optional-friendly, and unknown EXTRA fields are ignored (a newer client
+ *     talking to an older server must not fail). Absence of `updaterState`
+ *     means "an older client that never reported it"; the closed value
+ *     "unchecked" means "the updater has not run yet" — the two are distinct
+ *     and must survive the wire.
+ *   - FAIL CLOSED on values: enums are closed sets. Free-form shell text,
+ *     customer file paths, secret-shaped values, raw logs, and unknown repair
+ *     kinds are rejected with a typed {@link ClientHealthContractError}.
+ *   - Device identity: clients send only the stable random `installationId`.
+ *     HMAC'ing of device identifiers happens server-side (US-001, modeled on
+ *     scope-sync-mode-repository.ts) and never crosses this wire contract.
+ *   - Monotonic `sequence`: the server keeps the highest sequence seen per
+ *     installation and drops older/replayed heartbeats
+ *     ({@link shouldApplyHeartbeat}).
+ */
+// ─── Contract version ────────────────────────────────────────────────────────
+export const CLIENT_HEALTH_CONTRACT_VERSION = 1;
+// ─── Closed enums ────────────────────────────────────────────────────────────
+export const CLIENT_HEALTH_PLATFORMS = ["macos", "windows", "linux"];
+export const CLIENT_HEALTH_ARCHS = ["x64", "arm64"];
+/** Which client produced the heartbeat. Desktop is always-on; CLI contributes per invocation. */
+export const CLIENT_HEALTH_SOURCES = ["desktop", "cli"];
+/**
+ * Current sync state of the installation. `paused` and `conflict_blocked` are
+ * first-class states (not failures folded into `error`) because support treats
+ * them differently: pause may be intentional and conflicts are user-owned.
+ */
+export const CLIENT_HEALTH_SYNC_STATES = [
+    "idle",
+    "syncing",
+    "paused",
+    "conflict_blocked",
+    "error",
+    "never_synced",
+];
+/**
+ * Updater state. ABSENCE of the field means the client is too old to report
+ * it; `"unchecked"` means the updater exists but has not checked yet. Do not
+ * collapse the two (US-000 acceptance: Unchecked vs Absent must survive).
+ */
+export const CLIENT_HEALTH_UPDATER_STATES = [
+    "unchecked",
+    "up_to_date",
+    "update_available",
+    "update_downloading",
+    "update_ready",
+    "update_failed",
+    "unsupported",
+];
+/** Closed failure/blocker reason codes — the ONLY reasons that cross the wire. */
+export const CLIENT_HEALTH_FAILURE_REASONS = [
+    "SYNC_PAUSED",
+    "CONFLICT_BLOCKED",
+    "DESKTOP_OUTDATED",
+    "CLI_OUTDATED",
+    "CORE_OUTDATED",
+    "AUTH_EXPIRED",
+    "UPDATE_FAILED",
+    "RUNNER_FAILED",
+    "PERMISSION_DENIED",
+    "DISK_FULL",
+    "HEARTBEAT_STALE",
+];
+/**
+ * Repair/diagnostic command allowlist (US-006/US-009 consume these shapes).
+ * A desired-state interface, never a remote shell — any kind outside this set
+ * fails closed.
+ */
+export const CLIENT_HEALTH_REPAIR_KINDS = [
+    "CHECK_NOW",
+    "RETRY_SYNC",
+    "RESUME_SYNC",
+    "REPAIR_CLI",
+    "UPDATE_CORE",
+    "APPLY_DESKTOP_UPDATE",
+    "RESTART_APP",
+];
+/** Command/receipt lifecycle states (queued → acknowledged → running → terminal). */
+export const CLIENT_HEALTH_COMMAND_STATES = [
+    "queued",
+    "acknowledged",
+    "running",
+    "succeeded",
+    "failed",
+    "expired",
+];
+/** Closed diagnostic probe identifiers (US-007). */
+export const CLIENT_HEALTH_DIAGNOSTIC_CHECKS = [
+    "auth",
+    "runner",
+    "cli",
+    "core",
+    "updater",
+    "sync",
+    "conflicts",
+    "storage",
+    "permissions",
+];
+export const CLIENT_HEALTH_CHECK_STATUSES = ["pass", "fail", "skip"];
+// ─── Bounds ──────────────────────────────────────────────────────────────────
+export const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
+export const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100_000;
+export const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100_000;
+export const CLIENT_HEALTH_MAX_CHECKS = 16;
+export class ClientHealthContractError extends Error {
+    code;
+    field;
+    constructor(code, field, detail) {
+        super(`client-health contract violation [${code}] at ${field}${detail ? `: ${detail}` : ""}`);
+        this.name = "ClientHealthContractError";
+        this.code = code;
+        this.field = field;
+    }
+}
+// ─── Value validators (fail closed) ──────────────────────────────────────────
+const INSTALLATION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{7,63}$/;
+const COMMAND_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{7,63}$/;
+/** Same shape sync-auth-middleware.ts enforces on x-hq-*-version headers. */
+const SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+/**
+ * Secret-shaped prefixes rejected outright even when the charset is otherwise
+ * legal (JWTs, cloud keys, PATs, bot tokens fit in 64 bounded chars).
+ */
+const SECRET_PREFIXES = ["AKIA", "ASIA", "ghp_", "gho_", "github_pat_", "xox", "sk-", "eyJ", "-----BEGIN"];
+function assertSafeBoundedString(field, value) {
+    if (value === undefined || value === null)
+        throw new ClientHealthContractError("MISSING_FIELD", field);
+    if (typeof value !== "string")
+        throw new ClientHealthContractError("INVALID_TYPE", field, "expected string");
+    if (value.length === 0 || value.length > CLIENT_HEALTH_MAX_STRING_LENGTH) {
+        throw new ClientHealthContractError("OUT_OF_BOUNDS", field, `length must be 1..${CLIENT_HEALTH_MAX_STRING_LENGTH}`);
+    }
+    // Raw logs / free-form shell text: any whitespace, newline, or shell metacharacter.
+    if (/[\s;|&$<>`'"(){}*?!#=,]/.test(value)) {
+        throw new ClientHealthContractError("UNSAFE_VALUE", field, "free-form text is not a contract value");
+    }
+    // Customer paths: separators, home refs, drive letters.
+    if (value.includes("/") || value.includes("\\") || value.startsWith("~") || /^[A-Za-z]:/.test(value)) {
+        throw new ClientHealthContractError("UNSAFE_VALUE", field, "path-shaped value rejected");
+    }
+    for (const prefix of SECRET_PREFIXES) {
+        if (value.startsWith(prefix)) {
+            throw new ClientHealthContractError("UNSAFE_VALUE", field, "secret-shaped value rejected");
+        }
+    }
+    return value;
+}
+function assertVersion(field, value) {
+    const safe = assertSafeBoundedString(field, value);
+    if (!SEMVER.test(safe))
+        throw new ClientHealthContractError("UNSAFE_VALUE", field, "expected a SemVer version");
+    return safe;
+}
+function assertIsoUtc(field, value) {
+    const safe = assertSafeBoundedString(field, value);
+    if (!ISO_UTC.test(safe) || !Number.isFinite(Date.parse(safe))) {
+        throw new ClientHealthContractError("UNSAFE_VALUE", field, "expected ISO-8601 UTC timestamp");
+    }
+    return safe;
+}
+function assertEnum(field, value, allowed) {
+    const safe = assertSafeBoundedString(field, value);
+    if (!allowed.includes(safe)) {
+        throw new ClientHealthContractError("UNKNOWN_ENUM_VALUE", field, `"${safe.slice(0, 32)}" is not allowed`);
+    }
+    return safe;
+}
+function assertBoundedInt(field, value, max) {
+    if (value === undefined || value === null)
+        throw new ClientHealthContractError("MISSING_FIELD", field);
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new ClientHealthContractError("INVALID_TYPE", field, "expected integer");
+    }
+    if (value < 0 || value > max)
+        throw new ClientHealthContractError("OUT_OF_BOUNDS", field);
+    return value;
+}
+function asRecord(field, value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ClientHealthContractError("INVALID_TYPE", field, "expected object");
+    }
+    return value;
+}
+// ─── Parsers ─────────────────────────────────────────────────────────────────
+/**
+ * Parse + validate one heartbeat. Unknown extra fields are ignored (additive
+ * tolerance); every consumed value fails closed on unsafe content.
+ */
+export function parseClientHealthHeartbeat(input) {
+    const raw = asRecord("heartbeat", input);
+    const contractVersion = assertBoundedInt("contractVersion", raw.contractVersion, 1_000);
+    if (contractVersion < 1 || contractVersion > CLIENT_HEALTH_CONTRACT_VERSION) {
+        throw new ClientHealthContractError("UNSUPPORTED_CONTRACT_VERSION", "contractVersion");
+    }
+    const installationId = assertSafeBoundedString("installationId", raw.installationId);
+    if (!INSTALLATION_ID.test(installationId)) {
+        throw new ClientHealthContractError("UNSAFE_VALUE", "installationId");
+    }
+    const rawVersions = asRecord("versions", raw.versions);
+    const versions = {};
+    for (const key of ["desktop", "cli", "core", "syncRunner"]) {
+        if (rawVersions[key] !== undefined)
+            versions[key] = assertVersion(`versions.${key}`, rawVersions[key]);
+    }
+    const heartbeat = {
+        contractVersion,
+        installationId,
+        source: assertEnum("source", raw.source, CLIENT_HEALTH_SOURCES),
+        platform: assertEnum("platform", raw.platform, CLIENT_HEALTH_PLATFORMS),
+        arch: assertEnum("arch", raw.arch, CLIENT_HEALTH_ARCHS),
+        sentAt: assertIsoUtc("sentAt", raw.sentAt),
+        sequence: assertBoundedInt("sequence", raw.sequence, Number.MAX_SAFE_INTEGER),
+        versions,
+        syncState: assertEnum("syncState", raw.syncState, CLIENT_HEALTH_SYNC_STATES),
+        consecutiveFailures: assertBoundedInt("consecutiveFailures", raw.consecutiveFailures, CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES),
+    };
+    if (raw.lastSyncAttemptAt !== undefined)
+        heartbeat.lastSyncAttemptAt = assertIsoUtc("lastSyncAttemptAt", raw.lastSyncAttemptAt);
+    if (raw.lastSyncSuccessAt !== undefined)
+        heartbeat.lastSyncSuccessAt = assertIsoUtc("lastSyncSuccessAt", raw.lastSyncSuccessAt);
+    if (raw.conflictCount !== undefined) {
+        heartbeat.conflictCount = assertBoundedInt("conflictCount", raw.conflictCount, CLIENT_HEALTH_MAX_CONFLICT_COUNT);
+    }
+    if (raw.updaterState !== undefined) {
+        heartbeat.updaterState = assertEnum("updaterState", raw.updaterState, CLIENT_HEALTH_UPDATER_STATES);
+    }
+    if (raw.failureReason !== undefined) {
+        heartbeat.failureReason = assertEnum("failureReason", raw.failureReason, CLIENT_HEALTH_FAILURE_REASONS);
+    }
+    return heartbeat;
+}
+/** Parse + validate one diagnostic/repair command receipt. Unknown kinds fail closed. */
+export function parseClientHealthCommandReceipt(input) {
+    const raw = asRecord("receipt", input);
+    const contractVersion = assertBoundedInt("contractVersion", raw.contractVersion, 1_000);
+    if (contractVersion < 1 || contractVersion > CLIENT_HEALTH_CONTRACT_VERSION) {
+        throw new ClientHealthContractError("UNSUPPORTED_CONTRACT_VERSION", "contractVersion");
+    }
+    const commandId = assertSafeBoundedString("commandId", raw.commandId);
+    if (!COMMAND_ID.test(commandId))
+        throw new ClientHealthContractError("UNSAFE_VALUE", "commandId");
+    const installationId = assertSafeBoundedString("installationId", raw.installationId);
+    if (!INSTALLATION_ID.test(installationId))
+        throw new ClientHealthContractError("UNSAFE_VALUE", "installationId");
+    const receipt = {
+        contractVersion,
+        commandId,
+        installationId,
+        kind: assertEnum("kind", raw.kind, CLIENT_HEALTH_REPAIR_KINDS),
+        state: assertEnum("state", raw.state, CLIENT_HEALTH_COMMAND_STATES),
+        revision: assertBoundedInt("revision", raw.revision, Number.MAX_SAFE_INTEGER),
+        occurredAt: assertIsoUtc("occurredAt", raw.occurredAt),
+    };
+    if (raw.failureReason !== undefined) {
+        receipt.failureReason = assertEnum("failureReason", raw.failureReason, CLIENT_HEALTH_FAILURE_REASONS);
+    }
+    if (raw.checks !== undefined) {
+        if (!Array.isArray(raw.checks))
+            throw new ClientHealthContractError("INVALID_TYPE", "checks", "expected array");
+        if (raw.checks.length > CLIENT_HEALTH_MAX_CHECKS)
+            throw new ClientHealthContractError("OUT_OF_BOUNDS", "checks");
+        receipt.checks = raw.checks.map((entry, index) => {
+            const check = asRecord(`checks[${index}]`, entry);
+            const result = {
+                check: assertEnum(`checks[${index}].check`, check.check, CLIENT_HEALTH_DIAGNOSTIC_CHECKS),
+                status: assertEnum(`checks[${index}].status`, check.status, CLIENT_HEALTH_CHECK_STATUSES),
+            };
+            if (check.reason !== undefined) {
+                result.reason = assertEnum(`checks[${index}].reason`, check.reason, CLIENT_HEALTH_FAILURE_REASONS);
+            }
+            return result;
+        });
+    }
+    return receipt;
+}
+// ─── Sequence discipline ─────────────────────────────────────────────────────
+/**
+ * True when an incoming heartbeat sequence may replace the stored snapshot.
+ * Equal or older sequences are late deliveries/replays: drop them (the server
+ * answers idempotently and the current snapshot remains unchanged).
+ */
+export function shouldApplyHeartbeat(storedSequence, incomingSequence) {
+    if (storedSequence === undefined)
+        return true;
+    return incomingSequence > storedSequence;
+}
+//# sourceMappingURL=client-health-contract.js.map