@bli-cockpit/telemetry-core 0.1.22 → 0.1.24

package/dist/evidence-upload.d.ts

@@ -28,7 +28,10 @@ export declare const RawEvidenceLegacyUploadResponseSchema: z.ZodObject<{
         byte_size: z.ZodNumber;
         redaction: z.ZodOptional<z.ZodObject<{
             schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-            status: z.ZodLiteral<"sanitized">;
+            status: z.ZodEnum<{
+                sanitized: "sanitized";
+                scanned_clean: "scanned_clean";
+            }>;
             mode: z.ZodLiteral<"deterministic_text_replacement">;
             applied_by: z.ZodArray<z.ZodEnum<{
                 local_collector: "local_collector";
@@ -51,6 +54,7 @@ export declare const RawEvidenceLegacyUploadResponseSchema: z.ZodObject<{
             sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
             original_byte_size: z.ZodOptional<z.ZodNumber>;
             sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+            applied_at: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -90,7 +94,10 @@ export declare const RawEvidenceUploadBeginObjectSchema: z.ZodObject<{
         redacted_summary: z.ZodOptional<z.ZodString>;
         redaction: z.ZodOptional<z.ZodObject<{
             schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-            status: z.ZodLiteral<"sanitized">;
+            status: z.ZodEnum<{
+                sanitized: "sanitized";
+                scanned_clean: "scanned_clean";
+            }>;
             mode: z.ZodLiteral<"deterministic_text_replacement">;
             applied_by: z.ZodArray<z.ZodEnum<{
                 local_collector: "local_collector";
@@ -113,6 +120,7 @@ export declare const RawEvidenceUploadBeginObjectSchema: z.ZodObject<{
             sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
             original_byte_size: z.ZodOptional<z.ZodNumber>;
             sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+            applied_at: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
     chunk_size_bytes: z.ZodNumber;
@@ -186,7 +194,10 @@ export declare const RawEvidenceUploadBeginRequestSchema: z.ZodObject<{
             redacted_summary: z.ZodOptional<z.ZodString>;
             redaction: z.ZodOptional<z.ZodObject<{
                 schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-                status: z.ZodLiteral<"sanitized">;
+                status: z.ZodEnum<{
+                    sanitized: "sanitized";
+                    scanned_clean: "scanned_clean";
+                }>;
                 mode: z.ZodLiteral<"deterministic_text_replacement">;
                 applied_by: z.ZodArray<z.ZodEnum<{
                     local_collector: "local_collector";
@@ -209,6 +220,7 @@ export declare const RawEvidenceUploadBeginRequestSchema: z.ZodObject<{
                 sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
                 original_byte_size: z.ZodOptional<z.ZodNumber>;
                 sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+                applied_at: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
         }, z.core.$strict>;
         chunk_size_bytes: z.ZodNumber;
@@ -351,7 +363,10 @@ export declare const RawEvidenceUploadCommitResponseSchema: z.ZodObject<{
     chunk_count: z.ZodNumber;
     redaction: z.ZodOptional<z.ZodObject<{
         schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-        status: z.ZodLiteral<"sanitized">;
+        status: z.ZodEnum<{
+            sanitized: "sanitized";
+            scanned_clean: "scanned_clean";
+        }>;
         mode: z.ZodLiteral<"deterministic_text_replacement">;
         applied_by: z.ZodArray<z.ZodEnum<{
             local_collector: "local_collector";
@@ -374,6 +389,7 @@ export declare const RawEvidenceUploadCommitResponseSchema: z.ZodObject<{
         sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
         original_byte_size: z.ZodOptional<z.ZodNumber>;
         sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+        applied_at: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type RawEvidenceUploadCommitResponse = z.infer<typeof RawEvidenceUploadCommitResponseSchema>;

package/dist/ingest-dto.d.ts

@@ -290,7 +290,10 @@ export declare const TelemetryIngestEventDtoSchema: z.ZodObject<{
         redacted_summary: z.ZodOptional<z.ZodString>;
         redaction: z.ZodOptional<z.ZodObject<{
             schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-            status: z.ZodLiteral<"sanitized">;
+            status: z.ZodEnum<{
+                sanitized: "sanitized";
+                scanned_clean: "scanned_clean";
+            }>;
             mode: z.ZodLiteral<"deterministic_text_replacement">;
             applied_by: z.ZodArray<z.ZodEnum<{
                 local_collector: "local_collector";
@@ -313,6 +316,7 @@ export declare const TelemetryIngestEventDtoSchema: z.ZodObject<{
             sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
             original_byte_size: z.ZodOptional<z.ZodNumber>;
             sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+            applied_at: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
     otel: z.ZodOptional<z.ZodObject<{
@@ -763,7 +767,10 @@ export declare const TelemetryIngestEnvelopeSchema: z.ZodObject<{
             redacted_summary: z.ZodOptional<z.ZodString>;
             redaction: z.ZodOptional<z.ZodObject<{
                 schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-                status: z.ZodLiteral<"sanitized">;
+                status: z.ZodEnum<{
+                    sanitized: "sanitized";
+                    scanned_clean: "scanned_clean";
+                }>;
                 mode: z.ZodLiteral<"deterministic_text_replacement">;
                 applied_by: z.ZodArray<z.ZodEnum<{
                     local_collector: "local_collector";
@@ -786,6 +793,7 @@ export declare const TelemetryIngestEnvelopeSchema: z.ZodObject<{
                 sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
                 original_byte_size: z.ZodOptional<z.ZodNumber>;
                 sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+                applied_at: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
         }, z.core.$strict>>>;
         otel: z.ZodOptional<z.ZodObject<{
@@ -913,7 +921,10 @@ export declare const TelemetryIngestEnvelopeSchema: z.ZodObject<{
                 redacted_summary: z.ZodOptional<z.ZodString>;
                 redaction: z.ZodOptional<z.ZodObject<{
                     schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-                    status: z.ZodLiteral<"sanitized">;
+                    status: z.ZodEnum<{
+                        sanitized: "sanitized";
+                        scanned_clean: "scanned_clean";
+                    }>;
                     mode: z.ZodLiteral<"deterministic_text_replacement">;
                     applied_by: z.ZodArray<z.ZodEnum<{
                         local_collector: "local_collector";
@@ -936,6 +947,7 @@ export declare const TelemetryIngestEnvelopeSchema: z.ZodObject<{
                     sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
                     original_byte_size: z.ZodOptional<z.ZodNumber>;
                     sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+                    applied_at: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>>;
             }, z.core.$strict>>>;
         }, z.core.$strict>>>;

package/dist/privacy.d.ts

@@ -68,7 +68,10 @@ export declare const RawEvidencePointerSchema: z.ZodObject<{
     redacted_summary: z.ZodOptional<z.ZodString>;
     redaction: z.ZodOptional<z.ZodObject<{
         schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-        status: z.ZodLiteral<"sanitized">;
+        status: z.ZodEnum<{
+            sanitized: "sanitized";
+            scanned_clean: "scanned_clean";
+        }>;
         mode: z.ZodLiteral<"deterministic_text_replacement">;
         applied_by: z.ZodArray<z.ZodEnum<{
             local_collector: "local_collector";
@@ -91,6 +94,7 @@ export declare const RawEvidencePointerSchema: z.ZodObject<{
         sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
         original_byte_size: z.ZodOptional<z.ZodNumber>;
         sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+        applied_at: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type RawEvidencePointer = z.infer<typeof RawEvidencePointerSchema>;

package/dist/secret-guards.d.ts

@@ -43,9 +43,27 @@ export declare const RawEvidenceRedactionRangeSchema: z.ZodObject<{
     rule_id: z.ZodString;
 }, z.core.$strict>;
 export type RawEvidenceRedactionRange = z.infer<typeof RawEvidenceRedactionRangeSchema>;
+/**
+ * The verdict of a secret scan — NOT "did the bytes change" (BLI-3277).
+ *
+ * `sanitized` means the scan matched and the uploaded bytes differ from what was
+ * read. `scanned_clean` means the same scan ran over the same bytes and matched
+ * nothing, so the uploaded bytes are the original ones. The second value exists
+ * because every reader downstream asks "was this scanned?", and for 70% of
+ * transcripts — the ones with no secret in them — the honest answer used to be
+ * an absent record, which reads identically to "nobody ever looked".
+ */
+export declare const RawEvidenceRedactionStatusSchema: z.ZodEnum<{
+    sanitized: "sanitized";
+    scanned_clean: "scanned_clean";
+}>;
+export type RawEvidenceRedactionStatus = z.infer<typeof RawEvidenceRedactionStatusSchema>;
 export declare const RawEvidenceRedactionMetadataSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-    status: z.ZodLiteral<"sanitized">;
+    status: z.ZodEnum<{
+        sanitized: "sanitized";
+        scanned_clean: "scanned_clean";
+    }>;
     mode: z.ZodLiteral<"deterministic_text_replacement">;
     applied_by: z.ZodArray<z.ZodEnum<{
         local_collector: "local_collector";
@@ -68,8 +86,35 @@ export declare const RawEvidenceRedactionMetadataSchema: z.ZodObject<{
     sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
     original_byte_size: z.ZodOptional<z.ZodNumber>;
     sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+    applied_at: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type RawEvidenceRedactionMetadata = z.infer<typeof RawEvidenceRedactionMetadataSchema>;
+/**
+ * The receipt for a file the scan cleared (BLI-3277, moved here by BLI-3280).
+ *
+ * Same schema, same `mode` — the deterministic ruleset is what ran — with the
+ * verdict `scanned_clean` and zero of everything else. The content fields are
+ * the point: an evidence ref is only readable downstream when its redaction
+ * record hashes the bytes that are actually in the bucket, and for a clean file
+ * those are the original bytes, so both halves carry the same digest and size.
+ *
+ * It lives in telemetry-core rather than in the collector because two callers
+ * now build this exact record and they must never drift: the collector writes
+ * it at upload time, and the BLI-3280 operator backfill writes it onto refs
+ * that were stored before the receipt existed. Both must satisfy the same
+ * `sanitized_content_hash_sha256 === content_hash_sha256` /
+ * `sanitized_byte_size === byte_size` equality the digest reader checks, and a
+ * second copy of this function is a second chance to get that wrong.
+ *
+ * `appliedBy` is who ran the scan, and it is not decoration: a backfill passes
+ * `legacy_upload` so a reader can tell "the collector scanned this before it
+ * uploaded" apart from "an operator scanned the stored bytes afterwards".
+ */
+export declare function scannedCleanRedactionMetadata(bytes: Uint8Array, options?: {
+    appliedBy?: RawEvidenceRedactionSource;
+    /** ISO-8601 with offset. Omitted entirely when absent (BLI-3290). */
+    appliedAt?: string;
+}): RawEvidenceRedactionMetadata;
 export interface SecretRedactionResult {
     redacted: boolean;
     text: string;

package/dist/secret-guards.js

@@ -1,4 +1,6 @@
+import { createHash } from "node:crypto";
 import { z } from "zod";
+import { IsoDateTimeSchema } from "./common.js";
 /**
  * Secret-like content + file-name guards shared by the local collector
  * (attribution, collection) and the dashboard commit-time guard. Keeping a
@@ -153,22 +155,156 @@ export const RawEvidenceRedactionRangeSchema = z
         });
     }
 });
+/**
+ * The verdict of a secret scan — NOT "did the bytes change" (BLI-3277).
+ *
+ * `sanitized` means the scan matched and the uploaded bytes differ from what was
+ * read. `scanned_clean` means the same scan ran over the same bytes and matched
+ * nothing, so the uploaded bytes are the original ones. The second value exists
+ * because every reader downstream asks "was this scanned?", and for 70% of
+ * transcripts — the ones with no secret in them — the honest answer used to be
+ * an absent record, which reads identically to "nobody ever looked".
+ */
+export const RawEvidenceRedactionStatusSchema = z.enum([
+    "sanitized",
+    "scanned_clean",
+]);
 export const RawEvidenceRedactionMetadataSchema = z
     .object({
     schema_version: z.literal("raw-evidence-redaction.v1"),
-    status: z.literal("sanitized"),
+    status: RawEvidenceRedactionStatusSchema,
     mode: z.literal("deterministic_text_replacement"),
     applied_by: z.array(RawEvidenceRedactionSourceSchema).min(1),
-    rule_counts: z.array(RawEvidenceRedactionRuleCountSchema).min(1),
-    secret_like_match_count: z.number().int().positive(),
+    rule_counts: z.array(RawEvidenceRedactionRuleCountSchema),
+    secret_like_match_count: z.number().int().nonnegative(),
     redacted_fields: z.array(z.string().trim().min(1).max(160)).default([]),
     redacted_ranges: z.array(RawEvidenceRedactionRangeSchema).max(200).default([]),
     original_content_hash_sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     sanitized_content_hash_sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     original_byte_size: z.number().int().nonnegative().optional(),
     sanitized_byte_size: z.number().int().nonnegative().optional(),
+    /**
+     * When the scan ran, ISO-8601 with an offset (BLI-3290).
+     *
+     * Optional, and it stays optional: every receipt written before this field
+     * existed is still valid, and the collector does not stamp it — at upload
+     * time the ref's own `received_at` already answers "when". It exists for
+     * receipts written over bytes that were stored long ago, where the ref's
+     * timestamps describe the ORIGINAL upload and nothing in the record would
+     * otherwise say when an operator re-scanned or re-masked the object.
+     */
+    applied_at: IsoDateTimeSchema.optional(),
 })
-    .strict();
+    .strict()
+    // The per-status invariants the old `z.literal("sanitized")` + `.min(1)` +
+    // `.positive()` shape enforced structurally. They still hold for a sanitized
+    // record; a clean one has to prove the opposite — no rule fired, no range was
+    // replaced, no field was masked, and the bytes came out the way they went in.
+    .superRefine((metadata, context) => {
+    if (metadata.status === "sanitized") {
+        if (metadata.rule_counts.length === 0) {
+            context.addIssue({
+                code: "custom",
+                message: "a sanitized redaction must name at least one rule",
+                path: ["rule_counts"],
+            });
+        }
+        if (metadata.secret_like_match_count < 1) {
+            context.addIssue({
+                code: "custom",
+                message: "a sanitized redaction must count at least one match",
+                path: ["secret_like_match_count"],
+            });
+        }
+        return;
+    }
+    if (metadata.rule_counts.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot name a rule that fired",
+            path: ["rule_counts"],
+        });
+    }
+    if (metadata.secret_like_match_count !== 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot count a match",
+            path: ["secret_like_match_count"],
+        });
+    }
+    if (metadata.redacted_ranges.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot redact a range",
+            path: ["redacted_ranges"],
+        });
+    }
+    if (metadata.redacted_fields.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot redact a field",
+            path: ["redacted_fields"],
+        });
+    }
+    if (metadata.original_content_hash_sha256 !== undefined &&
+        metadata.sanitized_content_hash_sha256 !== undefined &&
+        metadata.original_content_hash_sha256 !==
+            metadata.sanitized_content_hash_sha256) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot change the content hash",
+            path: ["sanitized_content_hash_sha256"],
+        });
+    }
+    if (metadata.original_byte_size !== undefined &&
+        metadata.sanitized_byte_size !== undefined &&
+        metadata.original_byte_size !== metadata.sanitized_byte_size) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot change the byte size",
+            path: ["sanitized_byte_size"],
+        });
+    }
+});
+/**
+ * The receipt for a file the scan cleared (BLI-3277, moved here by BLI-3280).
+ *
+ * Same schema, same `mode` — the deterministic ruleset is what ran — with the
+ * verdict `scanned_clean` and zero of everything else. The content fields are
+ * the point: an evidence ref is only readable downstream when its redaction
+ * record hashes the bytes that are actually in the bucket, and for a clean file
+ * those are the original bytes, so both halves carry the same digest and size.
+ *
+ * It lives in telemetry-core rather than in the collector because two callers
+ * now build this exact record and they must never drift: the collector writes
+ * it at upload time, and the BLI-3280 operator backfill writes it onto refs
+ * that were stored before the receipt existed. Both must satisfy the same
+ * `sanitized_content_hash_sha256 === content_hash_sha256` /
+ * `sanitized_byte_size === byte_size` equality the digest reader checks, and a
+ * second copy of this function is a second chance to get that wrong.
+ *
+ * `appliedBy` is who ran the scan, and it is not decoration: a backfill passes
+ * `legacy_upload` so a reader can tell "the collector scanned this before it
+ * uploaded" apart from "an operator scanned the stored bytes afterwards".
+ */
+export function scannedCleanRedactionMetadata(bytes, options = {}) {
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    return {
+        schema_version: "raw-evidence-redaction.v1",
+        status: "scanned_clean",
+        mode: "deterministic_text_replacement",
+        applied_by: [options.appliedBy ?? "local_collector"],
+        rule_counts: [],
+        secret_like_match_count: 0,
+        redacted_fields: [],
+        redacted_ranges: [],
+        original_content_hash_sha256: digest,
+        sanitized_content_hash_sha256: digest,
+        original_byte_size: bytes.byteLength,
+        sanitized_byte_size: bytes.byteLength,
+        ...(options.appliedAt === undefined ? {} : { applied_at: options.appliedAt }),
+    };
+}
 // Same fence as the detector (BLI-3116) — the two must agree or a prefixed
 // name would be detected and then left unredacted, which costs whole sessions
 // (see findSecretRedactionMatches).

package/dist/source-adapter.d.ts

@@ -76,7 +76,10 @@ export declare const SourceScanEventSummarySchema: z.ZodObject<{
         redacted_summary: z.ZodOptional<z.ZodString>;
         redaction: z.ZodOptional<z.ZodObject<{
             schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-            status: z.ZodLiteral<"sanitized">;
+            status: z.ZodEnum<{
+                sanitized: "sanitized";
+                scanned_clean: "scanned_clean";
+            }>;
             mode: z.ZodLiteral<"deterministic_text_replacement">;
             applied_by: z.ZodArray<z.ZodEnum<{
                 local_collector: "local_collector";
@@ -99,6 +102,7 @@ export declare const SourceScanEventSummarySchema: z.ZodObject<{
             sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
             original_byte_size: z.ZodOptional<z.ZodNumber>;
             sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+            applied_at: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
@@ -190,7 +194,10 @@ export declare const SourceScanResultSchema: z.ZodObject<{
             redacted_summary: z.ZodOptional<z.ZodString>;
             redaction: z.ZodOptional<z.ZodObject<{
                 schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-                status: z.ZodLiteral<"sanitized">;
+                status: z.ZodEnum<{
+                    sanitized: "sanitized";
+                    scanned_clean: "scanned_clean";
+                }>;
                 mode: z.ZodLiteral<"deterministic_text_replacement">;
                 applied_by: z.ZodArray<z.ZodEnum<{
                     local_collector: "local_collector";
@@ -213,6 +220,7 @@ export declare const SourceScanResultSchema: z.ZodObject<{
                 sanitized_content_hash_sha256: z.ZodOptional<z.ZodString>;
                 original_byte_size: z.ZodOptional<z.ZodNumber>;
                 sanitized_byte_size: z.ZodOptional<z.ZodNumber>;
+                applied_at: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>>;

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

@@ -66,6 +66,41 @@ export declare const COMMIT_CRASHED_PLATFORM = "commit_crashed_platform";
  * eligible sync offers the same bytes again.
  */
 export declare const DELIVERY_BACKOFF_HOLDING = "delivery_backoff_holding";
+/**
+ * Raw evidence was never offered because the session's attribution state is not
+ * one the upload policy accepts (BLI-3272).
+ *
+ * `isRawEvidenceUploadableAttributionState` refuses a session whose attribution
+ * produced neither a repository identity nor an approved-root synthetic
+ * workspace. That refusal is a real, explainable decision — but until this label
+ * existed the report builders answered it by spreading `{}`, so the row reached
+ * `ambient_codex_sessions` with `upload_state = NULL` AND `upload_reason = NULL`.
+ * 1,256 sessions sat in that hole on 2026-08-29, 197 of them first seen inside a
+ * week from current 0.2.30 machines, every one `unattributed` /
+ * `cwd_outside_scanned_worktrees`. A withheld session that says nothing is the
+ * exact failure the session-first contract forbids, and the migration comment
+ * claiming "every write path now sets it" was false for all of them.
+ *
+ * Written with the deciding attribution reason appended after a colon
+ * (`not_uploadable_attribution_state:cwd_outside_scanned_worktrees`) so the
+ * upload half of the row explains itself without a join;
+ * `baseUploadFailureReason` strips that qualifier for classification.
+ *
+ * `deterministic` for the same reason as the bare attribution labels below: the
+ * scan completed and produced no target, so repeating it changes nothing.
+ * Widening the operator's approved roots can change it — a human decision, not a
+ * retry.
+ */
+export declare const NOT_UPLOADABLE_ATTRIBUTION_STATE = "not_uploadable_attribution_state";
+/**
+ * Compose the withheld-by-attribution reason for one session.
+ *
+ * The detail is the attribution reason that decided it. Anything outside the
+ * safe-label charset — colons included, so the stem always ends at the first one
+ * — collapses to `_`, and an empty or unusable detail degrades to the bare stem
+ * rather than inventing one.
+ */
+export declare function notUploadableAttributionStateReason(attributionReason: string | null | undefined): string;
 /**
  * The listed reason a composed label is a variant of, or the label unchanged.
  *

package/dist/upload-failure-class.js

@@ -72,6 +72,53 @@ export const COMMIT_CRASHED_PLATFORM = "commit_crashed_platform";
  * eligible sync offers the same bytes again.
  */
 export const DELIVERY_BACKOFF_HOLDING = "delivery_backoff_holding";
+/**
+ * Raw evidence was never offered because the session's attribution state is not
+ * one the upload policy accepts (BLI-3272).
+ *
+ * `isRawEvidenceUploadableAttributionState` refuses a session whose attribution
+ * produced neither a repository identity nor an approved-root synthetic
+ * workspace. That refusal is a real, explainable decision — but until this label
+ * existed the report builders answered it by spreading `{}`, so the row reached
+ * `ambient_codex_sessions` with `upload_state = NULL` AND `upload_reason = NULL`.
+ * 1,256 sessions sat in that hole on 2026-08-29, 197 of them first seen inside a
+ * week from current 0.2.30 machines, every one `unattributed` /
+ * `cwd_outside_scanned_worktrees`. A withheld session that says nothing is the
+ * exact failure the session-first contract forbids, and the migration comment
+ * claiming "every write path now sets it" was false for all of them.
+ *
+ * Written with the deciding attribution reason appended after a colon
+ * (`not_uploadable_attribution_state:cwd_outside_scanned_worktrees`) so the
+ * upload half of the row explains itself without a join;
+ * `baseUploadFailureReason` strips that qualifier for classification.
+ *
+ * `deterministic` for the same reason as the bare attribution labels below: the
+ * scan completed and produced no target, so repeating it changes nothing.
+ * Widening the operator's approved roots can change it — a human decision, not a
+ * retry.
+ */
+export const NOT_UPLOADABLE_ATTRIBUTION_STATE = "not_uploadable_attribution_state";
+/** Longest label the ambient envelope's `SafeLabelSchema` accepts. */
+const MAX_UPLOAD_REASON_LENGTH = 120;
+/**
+ * Compose the withheld-by-attribution reason for one session.
+ *
+ * The detail is the attribution reason that decided it. Anything outside the
+ * safe-label charset — colons included, so the stem always ends at the first one
+ * — collapses to `_`, and an empty or unusable detail degrades to the bare stem
+ * rather than inventing one.
+ */
+export function notUploadableAttributionStateReason(attributionReason) {
+    const detail = (attributionReason ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_.-]+/gu, "_")
+        .replace(/^_+|_+$/gu, "");
+    if (!detail)
+        return NOT_UPLOADABLE_ATTRIBUTION_STATE;
+    const budget = MAX_UPLOAD_REASON_LENGTH - NOT_UPLOADABLE_ATTRIBUTION_STATE.length - 1;
+    return `${NOT_UPLOADABLE_ATTRIBUTION_STATE}:${detail.slice(0, budget)}`;
+}
 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.
@@ -117,6 +164,10 @@ const UPLOAD_FAILURE_CLASSES = {
     cwd_not_a_repo: "deterministic",
     no_repo_signals: "deterministic",
     multiple_worktrees_close_scores: "deterministic",
+    // The upload policy declined the session's attribution state outright
+    // (BLI-3272). Same shape of answer as the four above — the scan finished and
+    // there is nowhere to put the object — so the same class.
+    [NOT_UPLOADABLE_ATTRIBUTION_STATE]: "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",
@@ -137,10 +188,22 @@ const HTTP_STATUS_SUFFIX = /_http_\d{3}$/u;
  * still classifies as `unknown`, exactly as before.
  */
 export function baseUploadFailureReason(reason) {
-    const stem = reason.replace(HTTP_STATUS_SUFFIX, "");
-    if (stem === reason)
-        return reason;
-    return Object.hasOwn(UPLOAD_FAILURE_CLASSES, stem) ? stem : reason;
+    const httpStem = reason.replace(HTTP_STATUS_SUFFIX, "");
+    if (httpStem !== reason) {
+        return Object.hasOwn(UPLOAD_FAILURE_CLASSES, httpStem) ? httpStem : reason;
+    }
+    // Same contract for the `:detail` qualifier the withheld-by-attribution label
+    // carries (BLI-3272): the colon is only a separator when what precedes it is
+    // already a classified reason, so nothing an unlisted label happens to
+    // contain can smuggle it into a class.
+    const separator = reason.indexOf(":");
+    if (separator > 0) {
+        const qualifierStem = reason.slice(0, separator);
+        if (Object.hasOwn(UPLOAD_FAILURE_CLASSES, qualifierStem)) {
+            return qualifierStem;
+        }
+    }
+    return reason;
 }
 /** Classify a persisted upload reason. Unlisted reasons stay `unknown`. */
 export function classifyUploadFailure(reason) {

package/package.json

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