@bli-cockpit/cli 0.2.45 → 0.2.47

package/dist/sync-health-class.js

@@ -0,0 +1,242 @@
+/**
+ * What bucket a sync failure goes in, decided from structure — never from the
+ * words in a message.
+ *
+ * BLI-3551. The old classifier ran one regex,
+ * `/auth|token|session|unauthorized|forbidden|401|403/iu`, over the failure
+ * text. The sync's own reason label `session_report_unposted:no_successful_sync`
+ * contains the word "session", so a machine whose only problem was that it had
+ * nothing inside its approved roots reported `auth_failed` on every tick —
+ * 377 ticks in 38 hours on one device whose token was valid for another eleven
+ * weeks, 111 on another. The receipt did not merely lack detail; it named the
+ * wrong subsystem, and the operator's first move was to re-pair a device that
+ * was fine.
+ *
+ * So the bucket is now read off one of two structured things:
+ *
+ * - a **failure record** — the label the deciding branch wrote down, plus the
+ *   HTTP status it observed, carried beside the rendered string rather than
+ *   parsed back out of it;
+ * - a **typed error** — `SyncDeliveryError` (`reason` + `httpStatus`),
+ *   `CollectionRootRequiredError`, or a Node error with a `code`/`name` the
+ *   runtime set.
+ *
+ * `auth_failed` is reachable ONLY from an observed 401/403 or a named token
+ * failure. Anything unclassified is `sync_failed`, which is honest: an
+ * unrecognised failure is a failure whose subsystem nobody has named yet.
+ *
+ * Adding a reason label to the sync is adding an entry here — the class-lock
+ * test in `sync-health-class.test.ts` reads the reason literals out of
+ * `commands/session-sync.ts` and fails if one of them has no class.
+ */
+import { CollectionRootRequiredError } from "./onboarding-roots.js";
+import { SyncDeliveryError } from "./upload-failure-reason.js";
+/** The coarse bucket a `sync_complete` receipt carries as its `error_code`. */
+export const SYNC_HEALTH_ERROR_CODES = [
+    "auth_failed",
+    "network_failed",
+    "collection_root_failed",
+    "sync_failed",
+];
+/**
+ * Every reason label a sync run is allowed to fail with.
+ *
+ * The rendered string a person reads may carry a scope or a nested cause
+ * (`bli-cockpit:ingest_rejected: http_500`, `raw_evidence:upload_failed`); the
+ * LABEL is what classification reads, and it is drawn from this list only.
+ */
+export const SYNC_FAILURE_LABELS = [
+    // Delivery buckets, mirrored from SYNC_FAILURE_REASONS in
+    // upload-failure-reason.ts — a spooled worktree carries one of these.
+    "ingest_transport_error",
+    "ingest_rejected",
+    "ingest_receipt_not_202",
+    "ingest_receipt_incomplete",
+    "sync_failed_local",
+    /** A worktree finished in a state that is neither uploaded nor spooled. */
+    "upload_not_completed",
+    /** One or more raw-evidence objects failed to upload. */
+    "raw_evidence_upload_failed",
+    /** Raw evidence landed only partly and the gap is retryable. */
+    "raw_evidence_retry_required",
+    "deferred_byte_budget",
+    "deferred_object_budget",
+    "codex_session_limit_applied",
+    "claude_session_limit_applied",
+    "codex_session_read_failed",
+    "claude_session_read_failed",
+    /** The session store itself could not be read during the scan. */
+    "codex_scan_read_failed",
+    "claude_scan_read_failed",
+    /** Sessions were observed and their metadata report did not reach the door. */
+    "session_report_unposted",
+    /** The gate is real and this file forgot to say why — a bug, made visible. */
+    "sync_failed_reason_not_recorded",
+];
+/**
+ * The class each label belongs to.
+ *
+ * `ingest_rejected` is deliberately NOT auth by default: a 500 from the ingest
+ * route and a 401 from it are the same label, and only the observed status
+ * tells them apart (see {@link classifySyncFailureRecords}).
+ */
+export const SYNC_FAILURE_LABEL_CLASSES = {
+    // The request never reached an answer, or something in the path answered
+    // instead of the route. Both are the network, not this machine's state.
+    ingest_transport_error: "network_failed",
+    ingest_receipt_not_202: "network_failed",
+    // The route answered and refused, or answered and disagreed about what
+    // landed. Server-side; the status decides whether it was about credentials.
+    ingest_rejected: "sync_failed",
+    ingest_receipt_incomplete: "sync_failed",
+    // Everything below is this machine's own doing: budgets, caps, local reads,
+    // an unposted report. None of them is an authentication problem and none of
+    // them is a network problem.
+    sync_failed_local: "sync_failed",
+    upload_not_completed: "sync_failed",
+    raw_evidence_upload_failed: "sync_failed",
+    raw_evidence_retry_required: "sync_failed",
+    deferred_byte_budget: "sync_failed",
+    deferred_object_budget: "sync_failed",
+    codex_session_limit_applied: "sync_failed",
+    claude_session_limit_applied: "sync_failed",
+    codex_session_read_failed: "sync_failed",
+    claude_session_read_failed: "sync_failed",
+    codex_scan_read_failed: "sync_failed",
+    claude_scan_read_failed: "sync_failed",
+    session_report_unposted: "sync_failed",
+    sync_failed_reason_not_recorded: "sync_failed",
+};
+/** HTTP statuses that mean the credential, and nothing else. */
+const AUTH_HTTP_STATUSES = new Set([401, 403]);
+/**
+ * Reason labels that name a credential failure outright.
+ *
+ * Kept as an exact-match set, not a pattern: the word "token" appearing inside
+ * some other reason is what produced the lie this module exists to end.
+ */
+const AUTH_FAILURE_LABELS = new Set([
+    "device_token_invalid",
+    "device_token_revoked",
+    "device_token_expired",
+    "device_not_paired",
+    "unauthorized",
+    "forbidden",
+]);
+/** Node error codes that mean the request never got out or never got back. */
+const NETWORK_ERROR_CODES = new Set([
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ETIMEDOUT",
+    "EPIPE",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+/**
+ * The class one record belongs to.
+ *
+ * The status wins over the label where the two disagree, because a 401 is an
+ * observation and a label is a categorisation.
+ */
+export function classifySyncFailureRecord(record) {
+    if (typeof record.http_status === "number" &&
+        AUTH_HTTP_STATUSES.has(record.http_status)) {
+        return "auth_failed";
+    }
+    return SYNC_FAILURE_LABEL_CLASSES[record.label] ?? "sync_failed";
+}
+/**
+ * The class a whole run belongs to.
+ *
+ * A run fails for several reasons at once more often than not, so the most
+ * actionable one wins: a credential problem is worth waking up for, a network
+ * one is worth waiting out, and a missing collection root is a setup step. The
+ * generic bucket is the floor, never a tie-breaker.
+ */
+export function classifySyncFailureRecords(records) {
+    const classes = new Set(records.map(classifySyncFailureRecord));
+    for (const candidate of [
+        "auth_failed",
+        "collection_root_failed",
+        "network_failed",
+    ]) {
+        if (classes.has(candidate))
+            return candidate;
+    }
+    return "sync_failed";
+}
+/**
+ * The class a thrown error belongs to.
+ *
+ * Reads only structure the code itself set: the delivery error's own `reason`
+ * and `httpStatus`, the collection-root error's type, the runtime's `code` and
+ * `name`. A message is never inspected — that is the whole point of BLI-3551.
+ */
+export function classifySyncHealthError(error) {
+    if (error instanceof CollectionRootRequiredError) {
+        return "collection_root_failed";
+    }
+    if (error instanceof SyncDeliveryError) {
+        return classifySyncFailureRecord({
+            label: error.reason,
+            rendered: error.message,
+            http_status: error.httpStatus,
+        });
+    }
+    const structured = structuredErrorFields(error);
+    if (typeof structured.httpStatus === "number" &&
+        AUTH_HTTP_STATUSES.has(structured.httpStatus)) {
+        return "auth_failed";
+    }
+    if (structured.reason && AUTH_FAILURE_LABELS.has(structured.reason)) {
+        return "auth_failed";
+    }
+    if (structured.reason &&
+        isSyncFailureLabel(structured.reason)) {
+        return SYNC_FAILURE_LABEL_CLASSES[structured.reason];
+    }
+    if (structured.name === "AbortError" || structured.name === "TimeoutError") {
+        return "network_failed";
+    }
+    if (structured.code && NETWORK_ERROR_CODES.has(structured.code)) {
+        return "network_failed";
+    }
+    // Nothing structured said anything. That is not evidence of an auth problem,
+    // a network problem or a setup problem — it is an unclassified failure, and
+    // the receipt says so instead of guessing from vocabulary.
+    return "sync_failed";
+}
+export function isSyncFailureLabel(value) {
+    return Object.hasOwn(SYNC_FAILURE_LABEL_CLASSES, value);
+}
+/**
+ * Fields an error carries as data rather than as prose.
+ *
+ * Duck-typed on purpose: an error crossing a package boundary (or rebuilt from
+ * a worker) loses its prototype but keeps its own enumerable fields, and a
+ * `reason` written by our code is still structure.
+ */
+function structuredErrorFields(error) {
+    if (!error || typeof error !== "object") {
+        return { name: null, code: null, reason: null, httpStatus: null };
+    }
+    const record = error;
+    const status = typeof record["httpStatus"] === "number"
+        ? record["httpStatus"]
+        : typeof record["http_status"] === "number"
+            ? record["http_status"]
+            : typeof record["status"] === "number"
+                ? record["status"]
+                : null;
+    return {
+        name: typeof record["name"] === "string" ? record["name"] : null,
+        code: typeof record["code"] === "string" ? record["code"] : null,
+        reason: typeof record["reason"] === "string" ? record["reason"] : null,
+        httpStatus: status,
+    };
+}

package/dist/upload.js

@@ -170,6 +170,8 @@ export async function syncLocalAmbientEnvelope(options = {}) {
             source_scan_count: built.source_scan_count,
             risk_flag_count: built.risk_flag_count,
             failure_reason: spooledFailureReason,
+            failure_class: classified.reason,
+            failure_http_status: classified.http_status,
             spool_entry_id: entry.spool_id,
             retry_command: entry.retry_command,
             ...summarizeRawEvidenceDelivery(built, uploadOutcomes, uploadedChunkCount, cursor, staging, attemptedDate),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.45",
+  "version": "0.2.47",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,6 +27,6 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.25"
+    "@bli-cockpit/telemetry-core": "0.1.26"
   }
 }