@bli-cockpit/telemetry-core 0.1.16 → 0.1.17

package/dist/evidence-upload.d.ts

@@ -448,6 +448,7 @@ export declare const CodexSessionAttributionSchema: z.ZodObject<{
         upload_failed: "upload_failed";
         not_uploaded: "not_uploaded";
     }>>;
+    upload_reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type CodexSessionAttribution = z.infer<typeof CodexSessionAttributionSchema>;
 export declare const CodexSessionAttributionReportRequestSchema: z.ZodObject<{
@@ -516,6 +517,7 @@ export declare const CodexSessionAttributionReportRequestSchema: z.ZodObject<{
             upload_failed: "upload_failed";
             not_uploaded: "not_uploaded";
         }>>;
+        upload_reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type CodexSessionAttributionReportRequest = z.infer<typeof CodexSessionAttributionReportRequestSchema>;

package/dist/evidence-upload.js

@@ -217,6 +217,23 @@ export const CodexSessionAttributionSchema = z
         .optional(),
     raw_evidence_pointer_id: NonEmptyStringSchema.optional(),
     upload_state: CodexSessionUploadStateSchema.optional(),
+    /**
+     * Why this session has no durable pointer.
+     *
+     * `attribution_reason` is required, so a session that fails attribution
+     * always says why. Until BLI-2107 the upload half had no such field, and
+     * `not_uploaded` was written as the branch of last resort — the state
+     * meaning "we did not upload it and we are not saying why". 1,118 of the
+     * 2,400 sessions missing a durable pointer on 2026-07-28 sat in exactly
+     * that hole, 87 of them fully `attributed` with no ambiguity at all.
+     *
+     * That is unfixable and un-retryable by construction: you cannot tell a
+     * dropped network from a file we will never accept, so a retry either
+     * repeats a doomed attempt forever or gives up on a recoverable one.
+     * Optional only because already-published CLI versions do not send it;
+     * every write path in this repo sets it.
+     */
+    upload_reason: SafeLabelSchema.optional(),
 })
     .strict();
 export const CodexSessionAttributionReportRequestSchema = z

package/dist/index.d.ts

@@ -13,4 +13,5 @@ export * from "./secret-guards.js";
 export * from "./source-adapter.js";
 export * from "./ticket-id.js";
 export * from "./trace-sink.js";
+export * from "./upload-failure-class.js";
 export * from "./work-context.js";

package/dist/index.js

@@ -13,4 +13,5 @@ export * from "./secret-guards.js";
 export * from "./source-adapter.js";
 export * from "./ticket-id.js";
 export * from "./trace-sink.js";
+export * from "./upload-failure-class.js";
 export * from "./work-context.js";

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

@@ -0,0 +1,63 @@
+/**
+ * What a caller should do about it.
+ *
+ * - `transient` — something outside the run interfered. The identical retry is
+ *   the right retry.
+ * - `deterministic` — the run completed and the answer was no. Repeating it
+ *   changes nothing; this needs a different method or a human.
+ * - `withheld_by_policy` — collection worked and we chose not to upload. Not a
+ *   failure, and emphatically not something to "fix" by retrying: that would be
+ *   defeating a redaction guard.
+ * - `unknown` — an unlisted reason. Not silently lumped in with the others,
+ *   because the fleet contract's whole point is that a green status must never
+ *   hide missing collection.
+ */
+export type UploadFailureClass = "transient" | "deterministic" | "withheld_by_policy" | "unknown";
+/**
+ * The reason written when nothing in the pipeline explained itself.
+ *
+ * This is the honest name for the hole BLI-2107 found. It is expected to be
+ * non-zero on the first release and to fall toward zero as each path that can
+ * reach it learns to say why — a session carrying this label means the collector
+ * declined to upload and no code on the way there recorded a cause.
+ */
+export declare const NO_UPLOAD_ATTEMPT_RECORDED = "no_upload_attempt_recorded";
+/**
+ * Storage refused the finished object because of its size.
+ *
+ * Named here rather than at the commit route so the label the server writes and
+ * the label the collector classifies are the same string by construction. They
+ * drifted apart once already: the collector could say `file_too_large` about a
+ * file it declined to send, and had no word at all for storage declining to
+ * keep one it had already received.
+ */
+export declare const STORAGE_REJECTED_OBJECT_TOO_LARGE = "storage_rejected_object_too_large";
+/** Storage refused the finished object because of its declared media type. */
+export declare const STORAGE_REJECTED_MEDIA_TYPE = "storage_rejected_media_type";
+/** Classify a persisted upload reason. Unlisted reasons stay `unknown`. */
+export declare function classifyUploadFailure(reason: string | null | undefined): UploadFailureClass;
+/**
+ * Whether repeating the identical attempt could plausibly succeed.
+ *
+ * `unknown` answers false. An unclassified reason is one nobody has reasoned
+ * about yet, and retrying on that basis is the loop this ticket exists to end;
+ * it should surface for a decision instead.
+ */
+export declare function isRetryableUploadFailure(reason: string | null | undefined): boolean;
+/**
+ * Whether repeating the attempt is known to be pointless.
+ *
+ * The deliberate mirror image of `isRetryableUploadFailure`, and not its
+ * negation: `unknown` answers false here and false there. The two questions
+ * are asked in different places and an unlisted reason has to answer them
+ * differently.
+ *
+ * `isRetryableUploadFailure` decides whether to *claim* a retry will help, so
+ * silence means no. This one decides whether to *stop* retrying, so silence
+ * means keep going — the labels the collector composes on the fly
+ * (`commit_failed_http_503`, `chunk_7_failed_http_500`) are unlisted by
+ * construction, and treating them as permanent would abandon a sync over a
+ * storage blip. Only a reason somebody has classified as deterministic or
+ * withheld ends the loop.
+ */
+export declare function isPermanentUploadFailure(reason: string | null | undefined): boolean;

package/dist/upload-failure-class.js

@@ -0,0 +1,109 @@
+// BLI-2107: what to do about a session that has no durable pointer.
+//
+// A retry that repeats the same call is only correct when something outside the
+// run interfered — the network dropped, a budget was exhausted, a lock was
+// held. If the run completed and the answer was still no, repeating it produces
+// the same no, forever, and the only signal that anything is wrong is a number
+// that never improves. That is how 1,118 sessions reached 2026-07-28 with no
+// pointer and no explanation.
+//
+// So the reason is not just recorded, it is classified, and the class decides
+// the response. Deliberately a flat lookup rather than pattern matching on the
+// label: a rule like "contains `failed` means retry" quietly reclassifies every
+// future reason somebody adds, which is the same class of guessing the person
+// resolver refuses to do. An unlisted reason is `unknown` and stays visible
+// until a human decides which bucket it belongs in.
+/**
+ * The reason written when nothing in the pipeline explained itself.
+ *
+ * This is the honest name for the hole BLI-2107 found. It is expected to be
+ * non-zero on the first release and to fall toward zero as each path that can
+ * reach it learns to say why — a session carrying this label means the collector
+ * declined to upload and no code on the way there recorded a cause.
+ */
+export const NO_UPLOAD_ATTEMPT_RECORDED = "no_upload_attempt_recorded";
+/**
+ * Storage refused the finished object because of its size.
+ *
+ * Named here rather than at the commit route so the label the server writes and
+ * the label the collector classifies are the same string by construction. They
+ * drifted apart once already: the collector could say `file_too_large` about a
+ * file it declined to send, and had no word at all for storage declining to
+ * keep one it had already received.
+ */
+export const STORAGE_REJECTED_OBJECT_TOO_LARGE = "storage_rejected_object_too_large";
+/** Storage refused the finished object because of its declared media type. */
+export const STORAGE_REJECTED_MEDIA_TYPE = "storage_rejected_media_type";
+const UPLOAD_FAILURE_CLASSES = {
+    // Budgets and locks: the file was fine and the run simply ran out of room or
+    // was beaten to it. The next pass has room.
+    deferred_object_budget: "transient",
+    deferred_byte_budget: "transient",
+    sync_already_running: "transient",
+    // Delivery. The bytes never reached the other end, or the run died on the way.
+    upload_failed: "transient",
+    collection_failed: "transient",
+    file_read_failed: "transient",
+    git_diff_failed: "transient",
+    // 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",
+    // 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
+    // objects retry for 57 days without one of them ever landing.
+    [STORAGE_REJECTED_OBJECT_TOO_LARGE]: "deterministic",
+    [STORAGE_REJECTED_MEDIA_TYPE]: "deterministic",
+    // 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",
+    // 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",
+    cwd_not_a_repo: "deterministic",
+    no_repo_signals: "deterministic",
+    multiple_worktrees_close_scores: "deterministic",
+    // Working as designed. Never retry these — a retry here is an attempt to get
+    // a redaction guard to change its mind.
+    secret_like_content_guard: "withheld_by_policy",
+    secret_like_file_name: "withheld_by_policy",
+    secret_redaction_failed: "withheld_by_policy",
+    // The server-side name for the same guard, returned by the commit route.
+    secret_guard_rejected: "withheld_by_policy",
+};
+/** Classify a persisted upload reason. Unlisted reasons stay `unknown`. */
+export function classifyUploadFailure(reason) {
+    if (!reason)
+        return "unknown";
+    return UPLOAD_FAILURE_CLASSES[reason] ?? "unknown";
+}
+/**
+ * Whether repeating the identical attempt could plausibly succeed.
+ *
+ * `unknown` answers false. An unclassified reason is one nobody has reasoned
+ * about yet, and retrying on that basis is the loop this ticket exists to end;
+ * it should surface for a decision instead.
+ */
+export function isRetryableUploadFailure(reason) {
+    return classifyUploadFailure(reason) === "transient";
+}
+/**
+ * Whether repeating the attempt is known to be pointless.
+ *
+ * The deliberate mirror image of `isRetryableUploadFailure`, and not its
+ * negation: `unknown` answers false here and false there. The two questions
+ * are asked in different places and an unlisted reason has to answer them
+ * differently.
+ *
+ * `isRetryableUploadFailure` decides whether to *claim* a retry will help, so
+ * silence means no. This one decides whether to *stop* retrying, so silence
+ * means keep going — the labels the collector composes on the fly
+ * (`commit_failed_http_503`, `chunk_7_failed_http_500`) are unlisted by
+ * construction, and treating them as permanent would abandon a sync over a
+ * storage blip. Only a reason somebody has classified as deterministic or
+ * withheld ends the loop.
+ */
+export function isPermanentUploadFailure(reason) {
+    const failureClass = classifyUploadFailure(reason);
+    return failureClass === "deterministic" || failureClass === "withheld_by_policy";
+}

package/package.json

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