@bli-cockpit/telemetry-core 0.1.15 → 0.1.17

package/dist/decision-event-id.d.ts

@@ -26,10 +26,24 @@ export declare function normalizeActorLabel(rawLabel: string): string;
 export declare function unresolvedActorId(rawLabel: string): string;
 export interface DecisionEventIdInput {
     captureSource: string;
-    /** Hash of the file this was read out of; null for a live hook firing. */
-    sourceArtifactHashSha256: string | null;
-    /** Line within that file; null when the artifact is not line-oriented. */
-    sourceLineNumber: number | null;
+    /**
+     * Hash of exactly the bytes that make up this one decision; null for a live
+     * hook firing, which has no artifact at all.
+     *
+     * "This one decision" and not "the file it arrived in", which is the whole
+     * point. A verdict JSON holds one decision, so its record is the file and the
+     * two hashes coincide. `merge-log.jsonl` holds thousands and gains another
+     * every time somebody merges, so its record is the single line — hashing the
+     * file there would change every id in it on the next append, and a re-import
+     * would write a second copy of the ledger instead of updating the rows it
+     * already has.
+     *
+     * Which snapshot of which file the record came out of is still worth knowing;
+     * it is kept as `source_artifact_hash_sha256`, beside `source_line_number`, as
+     * provenance. Neither is an identity input. Conflating the two jobs in one
+     * field is what made a growing ledger un-re-importable.
+     */
+    sourceRecordHashSha256: string | null;
     kind: string;
     /**
      * Only for a live firing, which has no artifact to hash and no line to point
@@ -43,10 +57,19 @@ export interface DecisionEventIdInput {
 /**
  * The id of one decision event.
  *
- * Two consequences worth stating. Re-running the backfill is idempotent, because
- * the same line of the same file always yields the same id. And an *edited*
- * artifact produces a new id rather than mutating an old one, which keeps the
- * store append-only in the same way jarvis_corrections is — history is added to,
- * never rewritten.
+ * Three consequences worth stating. Re-running the backfill is idempotent,
+ * because the same record always yields the same id no matter how much the file
+ * around it has grown or how far down it has been pushed. An *edited* record
+ * produces a new id rather than mutating an old one, which keeps the store
+ * append-only in the same way jarvis_corrections is — history is added to, never
+ * rewritten. And two byte-identical records collapse onto one row, which is the
+ * intended reading: in a ledger, identical bytes mean a hook wrote the same
+ * decision twice. If that is ever false the ledger format is underspecified, and
+ * the fix belongs there rather than in a tiebreaker here.
+ *
+ * The line number is deliberately absent. It is the one part of a record's
+ * position that a rotation or a compaction can change without the decision
+ * itself changing at all, and an id that moves when a file is renumbered is
+ * worse than a duplicate: it silently lands on some other decision's row.
  */
 export declare function decisionEventId(input: DecisionEventIdInput): string;

package/dist/decision-event-id.js

@@ -52,19 +52,25 @@ export function unresolvedActorId(rawLabel) {
 /**
  * The id of one decision event.
  *
- * Two consequences worth stating. Re-running the backfill is idempotent, because
- * the same line of the same file always yields the same id. And an *edited*
- * artifact produces a new id rather than mutating an old one, which keeps the
- * store append-only in the same way jarvis_corrections is — history is added to,
- * never rewritten.
+ * Three consequences worth stating. Re-running the backfill is idempotent,
+ * because the same record always yields the same id no matter how much the file
+ * around it has grown or how far down it has been pushed. An *edited* record
+ * produces a new id rather than mutating an old one, which keeps the store
+ * append-only in the same way jarvis_corrections is — history is added to, never
+ * rewritten. And two byte-identical records collapse onto one row, which is the
+ * intended reading: in a ledger, identical bytes mean a hook wrote the same
+ * decision twice. If that is ever false the ledger format is underspecified, and
+ * the fix belongs there rather than in a tiebreaker here.
+ *
+ * The line number is deliberately absent. It is the one part of a record's
+ * position that a rotation or a compaction can change without the decision
+ * itself changing at all, and an id that moves when a file is renumbered is
+ * worse than a duplicate: it silently lands on some other decision's row.
  */
 export function decisionEventId(input) {
     const parts = [
         input.captureSource,
-        input.sourceArtifactHashSha256 ?? "",
-        input.sourceLineNumber === null || input.sourceLineNumber === undefined
-            ? ""
-            : String(input.sourceLineNumber),
+        input.sourceRecordHashSha256 ?? "",
         input.kind,
         input.occurredAt ?? "",
         input.subjectDiscriminator ?? "",

package/dist/decision-event.d.ts

@@ -411,6 +411,7 @@ export declare const DecisionEventSchema: z.ZodObject<{
     source_line_number: z.ZodNullable<z.ZodNumber>;
     rule_id: z.ZodNullable<z.ZodString>;
     rulebook_version: z.ZodNullable<z.ZodString>;
+    host: z.ZodNullable<z.ZodString>;
     evidence_pointers: z.ZodArray<z.ZodObject<{
         kind: z.ZodEnum<{
             claude_state_path: "claude_state_path";
@@ -593,6 +594,7 @@ export declare const DecisionEventEnvelopeSchema: z.ZodObject<{
         source_line_number: z.ZodNullable<z.ZodNumber>;
         rule_id: z.ZodNullable<z.ZodString>;
         rulebook_version: z.ZodNullable<z.ZodString>;
+        host: z.ZodNullable<z.ZodString>;
         evidence_pointers: z.ZodArray<z.ZodObject<{
             kind: z.ZodEnum<{
                 claude_state_path: "claude_state_path";

package/dist/decision-event.js

@@ -330,7 +330,8 @@ export const DecisionEventSchema = z
     .object({
     /**
      * Deterministic, so re-running the backfill is idempotent and an edited
-     * artifact produces a new id rather than mutating an old one. See
+     * record produces a new id rather than mutating an old one. Derived from the
+     * record's own bytes, never from the file around them — see
      * `decisionEventId`.
      */
     decision_event_id: NonEmptyStringSchema.max(64),
@@ -340,7 +341,13 @@ export const DecisionEventSchema = z
     subject: DecisionSubjectSchema,
     outcome: DecisionOutcomeSchema,
     capture_source: DecisionCaptureSourceSchema,
-    /** The artifact this was read out of, so an edit is detectable. */
+    /**
+     * Which snapshot of which file this was read out of, and where in it. Both
+     * are provenance, not identity: a re-import of a ledger that has grown since
+     * refreshes them on the existing row. Identity comes from the record's own
+     * bytes instead, which is what lets that re-import update rather than
+     * duplicate — see `decisionEventId`.
+     */
     source_artifact_hash_sha256: Sha256Schema.nullable(),
     source_line_number: z.number().int().nonnegative().nullable(),
     /**
@@ -350,6 +357,20 @@ export const DecisionEventSchema = z
      */
     rule_id: NonEmptyStringSchema.max(40).nullable(),
     rulebook_version: VersionStringSchema.nullable(),
+    /**
+     * Which machine the decision was made on, straight from the ledger line.
+     *
+     * A column rather than an `attributes` key, and deliberately beside
+     * `rulebook_version`: both are provenance about the *decision* rather than
+     * about the actor, and "did the laptop behave differently from the desktop"
+     * is a group-by question. A jsonb key would answer it by digging.
+     *
+     * Nullable because both ledgers only started stamping `host` on 2026-08-04
+     * (BLI-2435). Every line before that legitimately has none, so absence is
+     * history rather than an error, and a record without one must ingest
+     * cleanly.
+     */
+    host: NonEmptyStringSchema.max(253).nullable(),
     evidence_pointers: z.array(DecisionEvidencePointerSchema).max(20),
     /**
      * Small, flat, non-narrative extras. Enforced as scalar-or-scalar-array by

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.15",
+  "version": "0.1.17",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",