@bli-cockpit/telemetry-core 0.1.24 → 0.1.26

package/dist/collector-heartbeat.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The proof that a collector is alive, and what it is allowed to look at.
+ *
+ * BLI-3551. Until now the ONLY writer of
+ * `ambient_collector_devices.last_seen_at` was the ambient ingest path
+ * (`apps/dashboard/src/lib/ambient/ingest.ts`), which runs when there is an
+ * envelope to send. A machine whose operator works entirely outside the
+ * approved roots sends no envelope, so it goes quiet — and a quiet machine and
+ * a dead machine look exactly the same from the dashboard. One device ticked
+ * 377 times in 38 hours and the last-seen column did not move once.
+ *
+ * The heartbeat closes that. It is deliberately NOT an ambient envelope: the
+ * envelope requires a work context, a session reference and at least one event,
+ * and inventing all three per tick would create a work-session row every 15
+ * minutes for a machine that collected nothing. A separate door with its own
+ * tiny schema costs less and says only what it means.
+ *
+ * The approved roots ride along as LABELS and never as paths. A root is
+ * `{ basename, path_sha256 }`: the basename is the folder name a person would
+ * recognise (`BLI`, `repos`), the hash is the stable identity of the normalized
+ * absolute path, so two machines pointing at the same folder are comparable
+ * without either path leaving the device. This is the same rule the session
+ * rows already follow with `cwd_basename` / `cwd_hash`.
+ */
+import { z } from "zod";
+export declare const COLLECTOR_HEARTBEAT_SCHEMA_VERSION = "collector-heartbeat.v1";
+/** The most roots one machine may declare. Well above any real operator. */
+export declare const COLLECTOR_HEARTBEAT_MAX_ROOTS = 40;
+export declare const CollectorRootLabelSchema: z.ZodObject<{
+    basename: z.ZodString;
+    path_sha256: z.ZodString;
+}, z.core.$strict>;
+export type CollectorRootLabel = z.infer<typeof CollectorRootLabelSchema>;
+/** What the last collection tick decided, in the collector's own vocabulary. */
+export declare const CollectorHeartbeatSyncStatusSchema: z.ZodEnum<{
+    skipped: "skipped";
+    ok: "ok";
+    fail: "fail";
+    not_run: "not_run";
+}>;
+export declare const CollectorHeartbeatSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"collector-heartbeat.v1">;
+    generated_at: z.ZodString;
+    collector_version: z.ZodString;
+    os_platform: z.ZodOptional<z.ZodString>;
+    roots: z.ZodArray<z.ZodObject<{
+        basename: z.ZodString;
+        path_sha256: z.ZodString;
+    }, z.core.$strict>>;
+    last_sync_status: z.ZodDefault<z.ZodEnum<{
+        skipped: "skipped";
+        ok: "ok";
+        fail: "fail";
+        not_run: "not_run";
+    }>>;
+    last_sync_reason: z.ZodOptional<z.ZodString>;
+    sessions_observed: z.ZodOptional<z.ZodNumber>;
+    sessions_outside_root: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type CollectorHeartbeat = z.infer<typeof CollectorHeartbeatSchema>;
+/**
+ * What the device row's `metadata.roots` holds after a heartbeat lands.
+ *
+ * Stored as its own key rather than merged into the row's top level so an
+ * older reader of `metadata` is unaffected, and so "which folders is this
+ * machine allowed to see, and when did it last say so" is one lookup.
+ */
+export declare const CollectorDeviceRootsMetadataSchema: z.ZodObject<{
+    observed_at: z.ZodString;
+    labels: z.ZodArray<z.ZodObject<{
+        basename: z.ZodString;
+        path_sha256: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CollectorDeviceRootsMetadata = z.infer<typeof CollectorDeviceRootsMetadataSchema>;

package/dist/collector-heartbeat.js

@@ -0,0 +1,106 @@
+/**
+ * The proof that a collector is alive, and what it is allowed to look at.
+ *
+ * BLI-3551. Until now the ONLY writer of
+ * `ambient_collector_devices.last_seen_at` was the ambient ingest path
+ * (`apps/dashboard/src/lib/ambient/ingest.ts`), which runs when there is an
+ * envelope to send. A machine whose operator works entirely outside the
+ * approved roots sends no envelope, so it goes quiet — and a quiet machine and
+ * a dead machine look exactly the same from the dashboard. One device ticked
+ * 377 times in 38 hours and the last-seen column did not move once.
+ *
+ * The heartbeat closes that. It is deliberately NOT an ambient envelope: the
+ * envelope requires a work context, a session reference and at least one event,
+ * and inventing all three per tick would create a work-session row every 15
+ * minutes for a machine that collected nothing. A separate door with its own
+ * tiny schema costs less and says only what it means.
+ *
+ * The approved roots ride along as LABELS and never as paths. A root is
+ * `{ basename, path_sha256 }`: the basename is the folder name a person would
+ * recognise (`BLI`, `repos`), the hash is the stable identity of the normalized
+ * absolute path, so two machines pointing at the same folder are comparable
+ * without either path leaving the device. This is the same rule the session
+ * rows already follow with `cwd_basename` / `cwd_hash`.
+ */
+import { z } from "zod";
+import { IsoDateTimeSchema, Sha256Schema, VersionStringSchema } from "./common.js";
+export const COLLECTOR_HEARTBEAT_SCHEMA_VERSION = "collector-heartbeat.v1";
+/** The most roots one machine may declare. Well above any real operator. */
+export const COLLECTOR_HEARTBEAT_MAX_ROOTS = 40;
+const RootBasenameSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(160)
+    // A basename, never a path: a separator here would mean somebody sent the
+    // whole location of someone's work folder.
+    .regex(/^[^/\\]+$/u);
+export const CollectorRootLabelSchema = z
+    .object({
+    basename: RootBasenameSchema,
+    /** sha256 of the normalized absolute path. The path itself never travels. */
+    path_sha256: Sha256Schema,
+})
+    .strict();
+/** What the last collection tick decided, in the collector's own vocabulary. */
+export const CollectorHeartbeatSyncStatusSchema = z.enum([
+    "ok",
+    "fail",
+    "skipped",
+    "not_run",
+]);
+export const CollectorHeartbeatSchema = z
+    .object({
+    schema_version: z.literal(COLLECTOR_HEARTBEAT_SCHEMA_VERSION),
+    generated_at: IsoDateTimeSchema,
+    collector_version: VersionStringSchema,
+    /** The DEVICE's platform (darwin/win32); the server's would be the runtime's. */
+    os_platform: z
+        .string()
+        .trim()
+        .min(1)
+        .max(32)
+        .regex(/^[a-z0-9_-]+$/iu)
+        .optional(),
+    roots: z.array(CollectorRootLabelSchema).max(COLLECTOR_HEARTBEAT_MAX_ROOTS),
+    /**
+     * How the tick that produced this heartbeat went, so a machine that is
+     * alive AND failing is distinguishable from one that is alive and idle
+     * without waiting for the install-events outbox to drain.
+     */
+    last_sync_status: CollectorHeartbeatSyncStatusSchema.default("not_run"),
+    /**
+     * A reason label, never prose: `nothing_in_root:47`, `auth_failed`,
+     * `sync_already_running`. Bounded and charset-restricted so nothing
+     * content-bearing can ride in on it.
+     */
+    last_sync_reason: z
+        .string()
+        .trim()
+        .min(1)
+        .max(120)
+        .regex(/^[a-z0-9_:.-]+$/iu)
+        .optional(),
+    /** Counts only — how many sessions the tick saw, and how many were outside. */
+    sessions_observed: z.number().int().nonnegative().max(1_000_000).optional(),
+    sessions_outside_root: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(1_000_000)
+        .optional(),
+})
+    .strict();
+/**
+ * What the device row's `metadata.roots` holds after a heartbeat lands.
+ *
+ * Stored as its own key rather than merged into the row's top level so an
+ * older reader of `metadata` is unaffected, and so "which folders is this
+ * machine allowed to see, and when did it last say so" is one lookup.
+ */
+export const CollectorDeviceRootsMetadataSchema = z
+    .object({
+    observed_at: IsoDateTimeSchema,
+    labels: z.array(CollectorRootLabelSchema).max(COLLECTOR_HEARTBEAT_MAX_ROOTS),
+})
+    .strict();

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./agent-artifacts.js";
+export * from "./collector-heartbeat.js";
 export * from "./common.js";
 export * from "./decision-event.js";
 export * from "./decision-event-id.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./agent-artifacts.js";
+export * from "./collector-heartbeat.js";
 export * from "./common.js";
 export * from "./decision-event.js";
 export * from "./decision-event-id.js";

package/dist/upload-failure-class.d.ts

@@ -92,6 +92,54 @@ export declare const DELIVERY_BACKOFF_HOLDING = "delivery_backoff_holding";
  * retry.
  */
 export declare const NOT_UPLOADABLE_ATTRIBUTION_STATE = "not_uploadable_attribution_state";
+/**
+ * The four answers `begin` gives when an object key is already spoken for.
+ *
+ * They are the route's own strings
+ * (`apps/dashboard/src/app/api/ambient/evidence/upload/begin/route.ts`), named
+ * here so the label the server writes and the label the collector classifies
+ * are the same string by construction — the same rule as
+ * `STORAGE_REJECTED_OBJECT_TOO_LARGE`.
+ *
+ * All four are `deterministic`: `begin` compared what is already durable
+ * against what this sync is offering and said no. The identical offer gets the
+ * identical no, on every tick, forever — which is exactly what four machines
+ * did for 38 hours (BLI-3552: ian 157 ticks, veetesh 196, rushik 45, viet 30).
+ * They were `unknown` before, and `unknown` is retried.
+ *
+ * They are NOT interchangeable in what resolves them, and
+ * `isRekeyableUploadConflict` is where that difference lives.
+ */
+export declare const HASH_MISMATCH_COMMITTED_OBJECT = "hash_mismatch_committed_object";
+export declare const BYTE_SIZE_MISMATCH_COMMITTED_OBJECT = "byte_size_mismatch_committed_object";
+export declare const COMMITTED_OBJECT_RECEIPT_MISMATCH = "committed_object_receipt_mismatch";
+export declare const OBJECT_KEY_OWNED_BY_OTHER_OPERATOR = "object_key_owned_by_other_operator";
+/**
+ * Whether a different NAME would settle this conflict.
+ *
+ * True for exactly one reason. `hash_mismatch_committed_object` means the key
+ * holds other bytes that are already durable and these bytes have never been
+ * stored anywhere: nobody is wrong, the key was simply not specific enough to
+ * tell the two apart. Re-keying to a name that carries this content's own hash
+ * stores it beside the old object without touching it — and a committed object
+ * is never deleted to make room, in this or any other path.
+ *
+ * False for the other three, and each for its own reason:
+ * - `byte_size_mismatch_committed_object` — same hash, different size. One of
+ *   the two receipts is lying about bytes nobody can re-derive; a second copy
+ *   under a second name would not say which.
+ * - `committed_object_receipt_mismatch` — the ledger and Storage disagree about
+ *   an object that is already there. That is a server-side repair (the drain),
+ *   not a client-side rename.
+ * - `object_key_owned_by_other_operator` — a key inside another person's
+ *   namespace. Renaming around an ownership boundary is precisely what the
+ *   boundary exists to stop.
+ *
+ * Those three are terminal for this object: the collector records the reason
+ * and stops offering it, which is what makes the failure visible instead of
+ * infinite.
+ */
+export declare function isRekeyableUploadConflict(reason: string | null | undefined): boolean;
 /**
  * Compose the withheld-by-attribution reason for one session.
  *

package/dist/upload-failure-class.js

@@ -98,6 +98,58 @@ export const DELIVERY_BACKOFF_HOLDING = "delivery_backoff_holding";
  * retry.
  */
 export const NOT_UPLOADABLE_ATTRIBUTION_STATE = "not_uploadable_attribution_state";
+/**
+ * The four answers `begin` gives when an object key is already spoken for.
+ *
+ * They are the route's own strings
+ * (`apps/dashboard/src/app/api/ambient/evidence/upload/begin/route.ts`), named
+ * here so the label the server writes and the label the collector classifies
+ * are the same string by construction — the same rule as
+ * `STORAGE_REJECTED_OBJECT_TOO_LARGE`.
+ *
+ * All four are `deterministic`: `begin` compared what is already durable
+ * against what this sync is offering and said no. The identical offer gets the
+ * identical no, on every tick, forever — which is exactly what four machines
+ * did for 38 hours (BLI-3552: ian 157 ticks, veetesh 196, rushik 45, viet 30).
+ * They were `unknown` before, and `unknown` is retried.
+ *
+ * They are NOT interchangeable in what resolves them, and
+ * `isRekeyableUploadConflict` is where that difference lives.
+ */
+export const HASH_MISMATCH_COMMITTED_OBJECT = "hash_mismatch_committed_object";
+export const BYTE_SIZE_MISMATCH_COMMITTED_OBJECT = "byte_size_mismatch_committed_object";
+export const COMMITTED_OBJECT_RECEIPT_MISMATCH = "committed_object_receipt_mismatch";
+export const OBJECT_KEY_OWNED_BY_OTHER_OPERATOR = "object_key_owned_by_other_operator";
+/**
+ * Whether a different NAME would settle this conflict.
+ *
+ * True for exactly one reason. `hash_mismatch_committed_object` means the key
+ * holds other bytes that are already durable and these bytes have never been
+ * stored anywhere: nobody is wrong, the key was simply not specific enough to
+ * tell the two apart. Re-keying to a name that carries this content's own hash
+ * stores it beside the old object without touching it — and a committed object
+ * is never deleted to make room, in this or any other path.
+ *
+ * False for the other three, and each for its own reason:
+ * - `byte_size_mismatch_committed_object` — same hash, different size. One of
+ *   the two receipts is lying about bytes nobody can re-derive; a second copy
+ *   under a second name would not say which.
+ * - `committed_object_receipt_mismatch` — the ledger and Storage disagree about
+ *   an object that is already there. That is a server-side repair (the drain),
+ *   not a client-side rename.
+ * - `object_key_owned_by_other_operator` — a key inside another person's
+ *   namespace. Renaming around an ownership boundary is precisely what the
+ *   boundary exists to stop.
+ *
+ * Those three are terminal for this object: the collector records the reason
+ * and stops offering it, which is what makes the failure visible instead of
+ * infinite.
+ */
+export function isRekeyableUploadConflict(reason) {
+    if (!reason)
+        return false;
+    return baseUploadFailureReason(reason) === HASH_MISMATCH_COMMITTED_OBJECT;
+}
 /** Longest label the ambient envelope's `SafeLabelSchema` accepts. */
 const MAX_UPLOAD_REASON_LENGTH = 120;
 /**
@@ -149,6 +201,17 @@ const UPLOAD_FAILURE_CLASSES = {
     // The file itself is the problem, and it will be the same size and the same
     // shape on the next pass. Retrying is a promise nobody can keep.
     file_too_large: "deterministic",
+    // A declared image above IMAGE_EVIDENCE_MAX_VALIDATION_BYTES (BLI-3067). The
+    // commit route deliberately KEEPS the staged chunks for these so that raising
+    // the bound turns the identical row into a commit that works — and
+    // `docs/runbooks/cockpit-stuck-evidence-uploads.md` has always documented it
+    // as deterministic. The entry was missing here, so it classified `unknown`,
+    // `isPermanentUploadFailure` answered false, and `begin`'s terminal-failure
+    // guard fell through to the reset that deletes those very chunk receipts —
+    // destroying the retained staging on the next sync and re-uploading the same
+    // oversized image forever. That is the BLI-2528 loop reappearing inside the
+    // code written to end it (BLI-3408).
+    image_too_large_to_validate: "deterministic",
     // Storage looked at the finished object and said no. The bytes are already
     // final and content-addressed, so the next attempt presents the identical
     // object to the identical rule (BLI-2528). Retrying these is what let 76
@@ -158,6 +221,22 @@ const UPLOAD_FAILURE_CLASSES = {
     // The content-addressed key already holds different bytes. One of the two is
     // wrong and repeating the write cannot decide which; a human has to look.
     object_conflict: "deterministic",
+    // `begin`'s four committed-object conflicts (BLI-3552). Deterministic for the
+    // same reason as `object_conflict` above — the route looked at both sides and
+    // answered no — and the difference between them is not the class but the
+    // remedy, which `isRekeyableUploadConflict` holds. Before this entry existed
+    // they classified `unknown`, `retryableFailedOutcomes` counted them as
+    // rescuable, and four machines re-offered the identical bytes every 15
+    // minutes while every one of those syncs was marked failed.
+    [HASH_MISMATCH_COMMITTED_OBJECT]: "deterministic",
+    [BYTE_SIZE_MISMATCH_COMMITTED_OBJECT]: "deterministic",
+    [COMMITTED_OBJECT_RECEIPT_MISMATCH]: "deterministic",
+    [OBJECT_KEY_OWNED_BY_OTHER_OPERATOR]: "deterministic",
+    // The drain's terminal answer for a stranded row whose key is already held by
+    // a different durable object (BLI-3552). Nothing on the server can finish it:
+    // the final write uses `upsert: false` on purpose, so the row would loop as
+    // `skipped_storage_error` for as long as anyone kept running the pass.
+    object_key_holds_other_content: "deterministic",
     // Attribution never produced a target, so there is nowhere to put the object.
     // Widening discovery can change this; running the same scan again cannot.
     cwd_outside_scanned_worktrees: "deterministic",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/telemetry-core",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",