@genn-inc/cluebase-frontend-sdk 0.0.2 → 0.0.6

package/dist/exporter/browser-outbox-records.js

@@ -188,7 +188,9 @@ export const withoutChecksum = (record) => {
 export const parseRecord = (raw, projectHash) => {
     try {
         const value = JSON.parse(raw);
-        if (!isRecord(value) || value.storageVersion !== 2 || value.projectHash !== projectHash)
+        if (!isRecord(value) ||
+            value.storageVersion !== 2 ||
+            value.projectHash !== projectHash)
             return null;
         const checksumSha256 = value.checksumSha256;
         if (typeof checksumSha256 !== "string")
@@ -204,11 +206,14 @@ export const parseRecord = (raw, projectHash) => {
 };
 const isValidRecord = (value) => {
     const base = typeof value.createdAt === "string" &&
-        (typeof value.recordVerifierSha256 === "string" || value.recordVerifierSha256 === null);
+        (typeof value.recordVerifierSha256 === "string" ||
+            value.recordVerifierSha256 === null);
     if (!base)
         return false;
     if (value.kind === "consent") {
-        return ((value.state === "granted" || value.state === "denied" || value.state === "unknown") &&
+        return ((value.state === "granted" ||
+            value.state === "denied" ||
+            value.state === "unknown") &&
             typeof value.collectionGeneration === "string" &&
             typeof value.legacyImportBlocked === "boolean" &&
             typeof value.updatedAt === "string" &&
@@ -225,7 +230,8 @@ const isValidRecord = (value) => {
             isBrowserSourceSignalEvent(value.event));
     }
     if (value.kind === "legacy_tombstone") {
-        return typeof value.eventKeyHash === "string" && typeof value.importedAt === "string";
+        return (typeof value.eventKeyHash === "string" &&
+            typeof value.importedAt === "string");
     }
     if (value.kind === "pending" || value.kind === "split_plan") {
         if (typeof value.batchId !== "string" ||
@@ -291,7 +297,8 @@ export const draftRecordKey = (prefix, eventKeyHash) => `${prefix}draft:${eventK
 export const pendingRecordKey = (prefix, batchId) => `${prefix}pending:${keyHash(batchId)}`;
 export const tombstoneRecordKey = (prefix, eventKeyHash) => `${prefix}legacy-tombstone:${eventKeyHash}`;
 export const browserEventsByteLength = (events) => events.reduce((total, event) => total + new TextEncoder().encode(JSON.stringify(event)).byteLength, 0);
-export const outboxEventCount = (drafts, pending) => drafts.length + pending.reduce((count, record) => count + record.events.length, 0);
+export const outboxEventCount = (drafts, pending) => drafts.length +
+    pending.reduce((count, record) => count + record.events.length, 0);
 export const hasLegacyTombstone = (draft, tombstones) => tombstones.some((record) => record.eventKeyHash === draft.eventKeyHash &&
     record.recordVerifierSha256 === draft.recordVerifierSha256);
 export const createGeneration = () => typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
@@ -299,7 +306,9 @@ export const createGeneration = () => typeof crypto !== "undefined" && typeof cr
     : `${Date.now()}-${Math.random()}`;
 export const readStorage = () => {
     try {
-        return typeof localStorage === "undefined" ? null : localStorage;
+        return typeof localStorage === "undefined"
+            ? null
+            : localStorage;
     }
     catch {
         return null;

package/dist/exporter/browser-outbox.d.ts

@@ -1,10 +1,10 @@
 import type { InternalMetricsStore } from "../internal/metrics.js";
 import type { CluebaseConsentState } from "../provider/types.js";
+import { type CollectionPermit, type PendingBrowserBatch, type StorageLike } from "./browser-outbox-records.js";
 import type { BatchEnvelopeMetadata } from "./client.js";
 import { DiagnosticStore } from "./diagnostics.js";
 import type { BrowserSourceEvent } from "./source-event.js";
-import { type CollectionPermit, type PendingBrowserBatch, type StorageLike } from "./browser-outbox-records.js";
-export type { CollectionPermit, OwnedBrowserEvent, PendingBrowserBatch } from "./browser-outbox-records.js";
+export type { CollectionPermit, OwnedBrowserEvent, PendingBrowserBatch, } from "./browser-outbox-records.js";
 export type ConsentTransition = {
     readonly state: CluebaseConsentState;
     readonly generation: string;
@@ -62,6 +62,7 @@ export declare class BrowserOutbox {
     private persistCommittedConsent;
     addDraft(event: BrowserSourceEvent, permit?: CollectionPermit): boolean;
     estimatedDraftBytes(measure: (events: readonly BrowserSourceEvent[], metadata: BatchEnvelopeMetadata) => number, metadata: BatchEnvelopeMetadata): number;
+    draftCount(): number;
     prepareFence(input: {
         readonly maxPayloadBytes: number;
         readonly createMetadata: () => BatchEnvelopeMetadata;
@@ -85,6 +86,8 @@ export declare class BrowserOutbox {
     private resolvePermit;
     private initializeConsentForDelivery;
     private enforceCapacity;
+    private dropOldestPendingForCapacity;
+    private forciblyRemovePendingRecord;
     private purgeAll;
     clearMemory(): void;
     private restore;

package/dist/exporter/browser-outbox.js

@@ -1,7 +1,7 @@
+import { canonicalize as canonicalJsonStringify } from "json-canonicalize";
+import { addStorageListener, browserEventsByteLength, consentRecordKey, createConsentChannel, createConsentRecord, createDraft, createGeneration, createLegacyTombstone, createPending, draftRecordKey, hasLegacyTombstone, LEGACY_TOMBSTONE_LIMIT, largestFittingPrefix, nowIso, outboxEventCount, parseRecord, pendingRecordKey, readLocks, readStorage, recordBatchId, sha256Hex, splitPendingRecord, toHeadBatch, tombstoneRecordKey, UNANCHORED_COLLECTION_GENERATION, verifyHash, withChecksum, withoutChecksum, } from "./browser-outbox-records.js";
 import { DiagnosticStore } from "./diagnostics.js";
 import { isBrowserSourceSignalEvent } from "./source-event.js";
-import { canonicalize as canonicalJsonStringify } from "json-canonicalize";
-import { addStorageListener, browserEventsByteLength, createConsentChannel, createConsentRecord, createDraft, createGeneration, createLegacyTombstone, createPending, consentRecordKey, draftRecordKey, hasLegacyTombstone, largestFittingPrefix, nowIso, outboxEventCount, parseRecord, readLocks, readStorage, recordBatchId, sha256Hex, toHeadBatch, splitPendingRecord, pendingRecordKey, tombstoneRecordKey, UNANCHORED_COLLECTION_GENERATION, verifyHash, withChecksum, withoutChecksum, LEGACY_TOMBSTONE_LIMIT, } from "./browser-outbox-records.js";
 export class BrowserOutbox {
     constructor(options) {
         this.drafts = [];
@@ -21,7 +21,8 @@ export class BrowserOutbox {
         this.consentKey = consentRecordKey(this.prefix);
         this.legacyKey = `cluebase:source_event_outbox:${options.projectKey}`;
         this.lockName = `cluebase:source-event-outbox:v2:${this.projectHash}`;
-        this.storage = "storage" in options ? options.storage ?? null : readStorage();
+        this.storage =
+            "storage" in options ? (options.storage ?? null) : readStorage();
         this.durableOutboxSupported = readLocks() !== null;
         this.maxBytes = Math.max(1024, options.maxBytes);
         this.maxEvents = Math.max(1, options.maxEvents);
@@ -78,7 +79,10 @@ export class BrowserOutbox {
             this.generation = createGeneration();
             this.legacyImportBlocked = true;
             this.diagnostics.rotateForConsentPurge(purged);
-            this.consentChannel?.postMessage({ type: "denied", generation: this.generation });
+            this.consentChannel?.postMessage({
+                type: "denied",
+                generation: this.generation,
+            });
             this.clearMemory();
             return Object.freeze({
                 state: this.consent,
@@ -214,6 +218,9 @@ export class BrowserOutbox {
     estimatedDraftBytes(measure, metadata) {
         return measure(this.drafts.map((draft) => draft.event), metadata);
     }
+    draftCount() {
+        return this.drafts.length;
+    }
     prepareFence(input) {
         const claimedEventKeyHashes = new Set(this.pending.flatMap((record) => record.eventKeyHashes));
         const candidates = this.drafts.filter((draft) => !claimedEventKeyHashes.has(draft.eventKeyHash) &&
@@ -438,16 +445,46 @@ export class BrowserOutbox {
         while (this.pendingEventCount() > this.maxEvents ||
             this.pendingBytes() > this.maxBytes) {
             const dropped = this.drafts.shift();
-            if (!dropped)
+            if (dropped) {
+                this.removeRecord(draftRecordKey(this.prefix, dropped.eventKeyHash));
+                this.metrics?.increment("dropped_count");
+                this.diagnostics.record({
+                    code: "queue_overflow",
+                    event_fingerprint: this.diagnostics.eventFingerprint(canonicalJsonStringify(dropped.event)),
+                });
+                continue;
+            }
+            if (!this.dropOldestPendingForCapacity())
                 return;
-            this.removeRecord(draftRecordKey(this.prefix, dropped.eventKeyHash));
-            this.metrics?.increment("dropped_count");
-            this.diagnostics.record({
-                code: "queue_overflow",
-                event_fingerprint: this.diagnostics.eventFingerprint(canonicalJsonStringify(dropped.event)),
-            });
         }
     }
+    dropOldestPendingForCapacity() {
+        if (this.pending.length === 0)
+            return false;
+        const oldest = this.pending.reduce((oldestSoFar, item) => item.ordinal < oldestSoFar.ordinal ? item : oldestSoFar);
+        const headBatch = toHeadBatch(oldest, pendingRecordKey(this.prefix, oldest.batchId));
+        const droppedCount = oldest.events.length;
+        this.forciblyRemovePendingRecord(oldest);
+        if (droppedCount > 0) {
+            this.metrics?.increment("dropped_count", droppedCount);
+        }
+        this.diagnostics.record({
+            code: "queue_overflow",
+            count: droppedCount,
+            batch_fingerprint: headBatch
+                ? this.diagnostics.batchFingerprint(headBatch.diagnosticCanonicalBytes)
+                : undefined,
+        });
+        return true;
+    }
+    forciblyRemovePendingRecord(record) {
+        let removed = this.removeClaimedDraftRecords(record);
+        removed =
+            this.removeRecord(pendingRecordKey(this.prefix, record.batchId)) &&
+                removed;
+        this.pending = this.pending.filter((item) => item !== record);
+        return removed;
+    }
     purgeAll() {
         const count = this.pendingEventCount();
         let removed = this.clear();

package/dist/exporter/client.d.ts

@@ -1,8 +1,8 @@
 import type { InternalMetricsStore } from "../internal/metrics.js";
-import { type BrowserSourceEvent } from "./source-event.js";
+import type { IngestUsageGovernorFeedback } from "../provider/types.js";
 import { type IngestRetryStrategy } from "./delivery-response.js";
 import type { DiagnosticStore } from "./diagnostics.js";
-import type { IngestUsageGovernorFeedback } from "../provider/types.js";
+import { type BrowserSourceEvent } from "./source-event.js";
 export declare const CLUEBASE_SDK_REQUEST_HEADER = "x-cluebase-sdk-request";
 export declare const CLUEBASE_SDK_VERSION_HEADER = "x-cluebase-sdk-version";
 export declare const CLUEBASE_SOURCE_SCHEMA_VERSION_HEADER = "x-cluebase-source-schema-version";

package/dist/exporter/client.js

@@ -1,10 +1,10 @@
 import { canonicalize as canonicalJsonStringify } from "json-canonicalize";
 import { CONSENT_DENIED_ABORT_REASON, DEFAULT_FRONTEND_SOURCE_IDENTIFIER, } from "../provider/constants.js";
-import { SDK_SOURCE_SIGNAL_EVENT_NAME, SDK_SOURCE_SIGNAL_EVENT_TYPE, isBrowserSourceSignalEvent, } from "./source-event.js";
-import { generateEventId } from "./event-id.js";
+import { appliedPrivacyPolicyToken, applyDeliveredPrivacyPolicy, } from "../provider/privacy-policy-store.js";
 import { classifyIngestHttpStatus, evaluateBrowserDeliveryResponse, } from "./delivery-response.js";
+import { generateEventId } from "./event-id.js";
 import { computeRetryDelay, RETRY_CONFIG } from "./retry.js";
-import { appliedPrivacyPolicyToken, applyDeliveredPrivacyPolicy, } from "../provider/privacy-policy-store.js";
+import { isBrowserSourceSignalEvent, SDK_SOURCE_SIGNAL_EVENT_NAME, SDK_SOURCE_SIGNAL_EVENT_TYPE, } from "./source-event.js";
 export const CLUEBASE_SDK_REQUEST_HEADER = "x-cluebase-sdk-request";
 export const CLUEBASE_SDK_VERSION_HEADER = "x-cluebase-sdk-version";
 export const CLUEBASE_SOURCE_SCHEMA_VERSION_HEADER = "x-cluebase-source-schema-version";
@@ -32,8 +32,7 @@ export const resolveCanonicalIngestEndpoint = (endpoint) => {
             return parsed.toString();
         }
     }
-    catch {
-    }
+    catch { }
     return endpoint;
 };
 const BROWSER_TOKEN_REFRESH_LEEWAY_MS = 60000;
@@ -105,16 +104,7 @@ export class IngestClient {
         const payloadSize = new TextEncoder().encode(payload).byteLength;
         this.metrics?.increment("payload_size_bytes", payloadSize);
         if (payloadSize > maxPayloadBytes) {
-            this.metrics?.increment("dropped_count", events.length);
-            this.metrics?.increment("send_failure_count");
-            this.metrics?.increment("transport_failed_count");
-            return {
-                ok: false,
-                status: null,
-                attempts: 0,
-                governor: null,
-                retryStrategy: null,
-            };
+            return this.failedSend(null, 0, "split_batch");
         }
         const browserTokenResult = await this.safeEnsureBrowserToken({
             signal: options.signal,
@@ -269,23 +259,16 @@ export class IngestClient {
         return { ok: false, status, attempts, governor, retryStrategy };
     }
     recordDecision(decision, status, attempt, payload) {
-        if (!this.diagnostics)
+        const diagnostics = this.diagnostics;
+        if (!diagnostics)
             return;
-        if (decision.reason === "invalid_response") {
-            this.diagnostics.record({
-                code: "invalid_response",
+        for (const code of decision.diagnosticCodes) {
+            diagnostics.record({
+                code,
+                count: code === "intentional_drop" ? decision.droppedEventCount : 1,
                 http_status: status ?? undefined,
                 attempt,
-                batch_fingerprint: this.diagnostics.batchFingerprint(diagnosticCanonicalPayload(payload)),
-            });
-            return;
-        }
-        if (status !== null && status >= 300 && status < 400) {
-            this.diagnostics.record({
-                code: "protocol_redirect",
-                http_status: status,
-                attempt,
-                batch_fingerprint: this.diagnostics.batchFingerprint(diagnosticCanonicalPayload(payload)),
+                batch_fingerprint: diagnostics.batchFingerprint(diagnosticCanonicalPayload(payload)),
             });
         }
     }
@@ -334,6 +317,7 @@ export class IngestClient {
                     reason: isConsentAbort(input.signal)
                         ? "consent_denied"
                         : "transport_timeout",
+                    diagnosticCodes: [],
                 },
             };
         }
@@ -416,7 +400,8 @@ export class IngestClient {
             if (isConsentAbort(options.signal)) {
                 return { ok: false, retryStrategy: "drop_event" };
             }
-            if (!(error instanceof BrowserTokenRequestError) || error.status === null) {
+            if (!(error instanceof BrowserTokenRequestError) ||
+                error.status === null) {
                 return { ok: false, retryStrategy: "retry_same_batch" };
             }
             return {

package/dist/exporter/delivery-response-contract.js

@@ -1,5 +1,5 @@
-import { COST_CAPABILITIES, LIMIT_KINDS } from "../_generated/usage-governor-tables.js";
 import { z } from "zod";
+import { COST_CAPABILITIES, LIMIT_KINDS, } from "../_generated/usage-governor-tables.js";
 const MAX_INGEST_EVENTS_PER_BATCH = 10000;
 const ingestRetryStrategySchema = z.enum([
     "split_batch",
@@ -30,7 +30,11 @@ const ingestUsageGovernorFeedbackSchema = z.object({
     })),
     retryAfterAt: z.string().datetime({ offset: true }).nullable(),
 });
-const boundedCount = z.number().int().nonnegative().max(MAX_INGEST_EVENTS_PER_BATCH);
+const boundedCount = z
+    .number()
+    .int()
+    .nonnegative()
+    .max(MAX_INGEST_EVENTS_PER_BATCH);
 const positiveCount = boundedCount.refine((count) => count > 0);
 export const ingestPrivacyPolicySchema = z
     .object({
@@ -55,13 +59,16 @@ const observationSourceEventBatchAcceptedResponseSchema = z
     submitted_event_count: positiveCount,
     accepted_event_count: positiveCount,
     dropped_event_count: boundedCount,
-    dropped_events: z.array(ingestDroppedEventSchema).max(MAX_INGEST_EVENTS_PER_BATCH),
+    dropped_events: z
+        .array(ingestDroppedEventSchema)
+        .max(MAX_INGEST_EVENTS_PER_BATCH),
     duplicate: z.boolean(),
     governor: ingestUsageGovernorFeedbackSchema.optional(),
     privacy_policy: ingestPrivacyPolicySchema.optional(),
 })
     .superRefine((value, ctx) => {
-    if (value.submitted_event_count !== value.accepted_event_count + value.dropped_event_count) {
+    if (value.submitted_event_count !==
+        value.accepted_event_count + value.dropped_event_count) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["submitted_event_count"],
@@ -81,7 +88,10 @@ const observationSourceEventBatchRejectedResponseSchema = z
     submitted_event_count: positiveCount.optional(),
     accepted_event_count: boundedCount.optional(),
     dropped_event_count: boundedCount.optional(),
-    dropped_events: z.array(ingestDroppedEventSchema).max(MAX_INGEST_EVENTS_PER_BATCH).optional(),
+    dropped_events: z
+        .array(ingestDroppedEventSchema)
+        .max(MAX_INGEST_EVENTS_PER_BATCH)
+        .optional(),
     limits: z
         .object({
         hard_max_payload_bytes: z.number().int().positive(),
@@ -91,36 +101,67 @@ const observationSourceEventBatchRejectedResponseSchema = z
         .optional(),
 })
     .superRefine((value, ctx) => {
-    const counts = [value.submitted_event_count, value.accepted_event_count, value.dropped_event_count];
+    const counts = [
+        value.submitted_event_count,
+        value.accepted_event_count,
+        value.dropped_event_count,
+    ];
     const hasAnyCount = counts.some((count) => count !== undefined);
     const hasAllCounts = counts.every((count) => count !== undefined);
     if (hasAnyCount !== hasAllCounts) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["submitted_event_count"], message: "rejected response counts must be all present or all absent" });
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["submitted_event_count"],
+            message: "rejected response counts must be all present or all absent",
+        });
         return;
     }
     if (hasAllCounts) {
         const [submitted, accepted, dropped] = counts;
-        if (accepted > submitted || dropped > submitted || accepted + dropped > submitted) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["dropped_event_count"], message: "rejected counts must not exceed submitted count" });
+        if (accepted > submitted ||
+            dropped > submitted ||
+            accepted + dropped > submitted) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["dropped_event_count"],
+                message: "rejected counts must not exceed submitted count",
+            });
         }
     }
     if (value.retry_strategy === "drop_event") {
         if (!hasAllCounts) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["submitted_event_count"], message: "drop rejection requires all counts" });
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["submitted_event_count"],
+                message: "drop rejection requires all counts",
+            });
         }
         else {
             const [submitted, accepted, dropped] = counts;
             if (accepted !== 0 || dropped !== submitted) {
-                ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["dropped_event_count"], message: "drop rejection must reject every submitted event" });
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["dropped_event_count"],
+                    message: "drop rejection must reject every submitted event",
+                });
             }
             validateDroppedEventDetails(submitted, dropped, value.dropped_events ?? [], ctx);
         }
     }
     else if ((value.dropped_events?.length ?? 0) > 0) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["dropped_events"], message: "non-drop rejection must not contain dropped event details" });
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["dropped_events"],
+            message: "non-drop rejection must not contain dropped event details",
+        });
     }
-    if ((value.retry_strategy === "split_batch") !== (value.limits !== undefined)) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["limits"], message: "byte limits are valid only for split rejection" });
+    if ((value.retry_strategy === "split_batch") !==
+        (value.limits !== undefined)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["limits"],
+            message: "byte limits are valid only for split rejection",
+        });
     }
 });
 export const observationSourceEventBatchResponseSchema = z.discriminatedUnion("accepted", [
@@ -129,12 +170,21 @@ export const observationSourceEventBatchResponseSchema = z.discriminatedUnion("a
 ]);
 function validateDroppedEventDetails(submittedCount, droppedCount, droppedEvents, ctx) {
     if (droppedEvents.length !== droppedCount) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["dropped_events"], message: "dropped event details must match dropped count" });
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["dropped_events"],
+            message: "dropped event details must match dropped count",
+        });
     }
     const indexes = new Set();
     for (const [detailIndex, detail] of droppedEvents.entries()) {
-        if (detail.event_index >= submittedCount || indexes.has(detail.event_index)) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["dropped_events", detailIndex, "event_index"], message: "dropped event indexes must be valid and unique" });
+        if (detail.event_index >= submittedCount ||
+            indexes.has(detail.event_index)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["dropped_events", detailIndex, "event_index"],
+                message: "dropped event indexes must be valid and unique",
+            });
         }
         indexes.add(detail.event_index);
     }

package/dist/exporter/delivery-response.d.ts

@@ -1,5 +1,6 @@
-import { type IngestRetryStrategy } from "./delivery-response-contract.js";
 import type { IngestUsageGovernorFeedback } from "../provider/types.js";
+import { type IngestRetryStrategy } from "./delivery-response-contract.js";
+import type { DiagnosticCode } from "./diagnostics.js";
 export declare const BROWSER_REJECTION_STRATEGIES: Readonly<Record<string, IngestRetryStrategy>>;
 export type { IngestRetryStrategy } from "./delivery-response-contract.js";
 export type BrowserDeliveryDecision = {
@@ -12,6 +13,7 @@ export type BrowserDeliveryDecision = {
     readonly acceptedEventCount: number;
     readonly acceptedPartial: boolean;
     readonly reason: string | null;
+    readonly diagnosticCodes: readonly DiagnosticCode[];
 };
 export declare const evaluateBrowserDeliveryResponse: (input: {
     readonly status: number;

package/dist/exporter/delivery-response.js

@@ -1,5 +1,5 @@
-import { observationSourceEventBatchResponseSchema, } from "./delivery-response-contract.js";
 import { parseGovernorFeedbackEnvelope } from "../provider/usage-governor.js";
+import { observationSourceEventBatchResponseSchema, } from "./delivery-response-contract.js";
 export const BROWSER_REJECTION_STRATEGIES = {
     invalid_request: "stop_and_report",
     unsupported_source_schema_version: "stop_and_report",
@@ -21,6 +21,7 @@ export const BROWSER_REJECTION_STRATEGIES = {
     raw_ingest_produce_failed: "retry_same_batch",
     raw_ingest_ack_unknown: "retry_same_batch",
     raw_ingest_receipt_metadata_failed: "retry_same_batch",
+    raw_ingest_receipt_unprocessable: "stop_and_report",
     ingest_config_changed_retryable: "retry_same_batch",
     usage_meter_unavailable: "retry_same_batch",
 };
@@ -36,6 +37,15 @@ export const evaluateBrowserDeliveryResponse = (input) => {
                     return invalidResponse();
                 }
                 const partial = parsed.data.dropped_event_count > 0;
+                const diagnosticCodes = [];
+                if (partial) {
+                    diagnosticCodes.push(parsed.data.dropped_events.length > 0
+                        ? "intentional_drop"
+                        : "duplicate_drop_details_unavailable");
+                }
+                if (input.status !== 202) {
+                    diagnosticCodes.push("non_canonical_success_status");
+                }
                 return {
                     ok: true,
                     retryStrategy: null,
@@ -46,6 +56,7 @@ export const evaluateBrowserDeliveryResponse = (input) => {
                     acceptedEventCount: parsed.data.accepted_event_count,
                     acceptedPartial: partial,
                     reason: partial ? "accepted_partial" : null,
+                    diagnosticCodes,
                 };
             }
             if (BROWSER_REJECTION_STRATEGIES[parsed.data.reason] !==
@@ -60,6 +71,7 @@ export const evaluateBrowserDeliveryResponse = (input) => {
                 acceptedEventCount: parsed.data.accepted_event_count ?? 0,
                 acceptedPartial: false,
                 reason: parsed.data.reason,
+                diagnosticCodes: [],
             };
         }
         return invalidResponse();
@@ -91,6 +103,7 @@ const invalidResponse = () => ({
     acceptedEventCount: 0,
     acceptedPartial: false,
     reason: "invalid_response",
+    diagnosticCodes: ["invalid_response"],
 });
 export const classifyIngestHttpStatus = (status) => {
     if (status >= 200 && status < 300)
@@ -104,29 +117,27 @@ export const classifyIngestHttpStatus = (status) => {
     }
     return "retry_same_batch";
 };
-const fallback = (status) => {
-    const retryStrategy = classifyIngestHttpStatus(status);
-    if (status >= 200 && status < 300)
-        return invalidResponse();
-    if (retryStrategy === "retry_same_batch")
-        return retry(status);
-    return terminal(retryStrategy, status);
-};
-const retry = (status) => ({
-    ok: false,
-    retryStrategy: "retry_same_batch",
-    governor: null,
-    droppedEventCount: 0,
-    acceptedEventCount: 0,
-    acceptedPartial: false,
-    reason: `http_${status}`,
-});
-const terminal = (retryStrategy, status) => ({
+const RETRYABLE_CLIENT_STATUSES = [408, 422, 425, 429];
+const fallback = (status) => ({
     ok: false,
-    retryStrategy,
+    retryStrategy: classifyIngestHttpStatus(status),
     governor: null,
     droppedEventCount: 0,
     acceptedEventCount: 0,
     acceptedPartial: false,
     reason: `http_${status}`,
+    diagnosticCodes: fallbackDiagnosticCodes(status),
 });
+const fallbackDiagnosticCodes = (status) => {
+    if (classifyIngestHttpStatus(status) !== "retry_same_batch")
+        return [];
+    if (status >= 200 && status <= 299)
+        return ["invalid_response"];
+    if (status >= 300 && status <= 399)
+        return ["protocol_redirect"];
+    if (status >= 500 && status <= 599)
+        return [];
+    if (RETRYABLE_CLIENT_STATUSES.includes(status))
+        return ["invalid_response"];
+    return ["unknown_status"];
+};

package/dist/exporter/diagnostics.d.ts

@@ -1,4 +1,4 @@
-import type { IngestRetryStrategy } from "./delivery-response.js";
+import type { IngestRetryStrategy } from "./delivery-response-contract.js";
 export type DiagnosticCode = "batch_split" | "consent_persistence_failed" | "consent_purge" | "consent_purge_failed" | "consent_state_unavailable" | "durable_outbox_unavailable" | "duplicate_drop_details_unavailable" | "event_oversize" | "intentional_drop" | "invalid_response" | "legacy_pre_revocation_event_blocked" | "legacy_bridge_capacity_reached" | "legacy_writer_detected" | "non_canonical_success_status" | "outbox_key_collision" | "outbox_record_corrupt" | "protocol_redirect" | "queue_overflow" | "retry_exhausted" | "retry_scheduled" | "shutdown_failure" | "terminal_rejection" | "unknown_status";
 export type DiagnosticLifecycle = "open" | "closing" | "closing_failed" | "closed";
 export type DiagnosticFlushOutcome = "clean" | "failed" | null;

package/dist/exporter/diagnostics.js

@@ -51,6 +51,7 @@ const SAFE_REASONS = new Set([
     "raw_ingest_ack_unknown",
     "raw_ingest_produce_failed",
     "raw_ingest_receipt_metadata_failed",
+    "raw_ingest_receipt_unprocessable",
     "route_throttled",
     "stale_browser_token",
     "unresolved_project_or_environment",
@@ -131,7 +132,9 @@ const normalize = (input) => {
     if (input.reason && SAFE_REASONS.has(input.reason))
         entry.reason = input.reason;
     const attempt = input.attempt;
-    if (typeof attempt === "number" && Number.isSafeInteger(attempt) && attempt > 0) {
+    if (typeof attempt === "number" &&
+        Number.isSafeInteger(attempt) &&
+        attempt > 0) {
         entry.attempt = attempt;
     }
     const count = input.count;

package/dist/exporter/event-id.js

@@ -20,9 +20,7 @@ const nextMonotonicParts = () => {
         typeof globalThis.performance.now === "function"
         ? Math.floor(globalThis.performance.now() * 1000)
         : Date.now();
-    const monotonicTime = performanceNow > lastMonotonicTime
-        ? performanceNow
-        : lastMonotonicTime + 1;
+    const monotonicTime = performanceNow > lastMonotonicTime ? performanceNow : lastMonotonicTime + 1;
     lastMonotonicTime = monotonicTime;
     monotonicCounter = (monotonicCounter + 1) % Number.MAX_SAFE_INTEGER;
     return { monotonicTime, counter: monotonicCounter };

package/dist/exporter/frontend-resource.js

@@ -1,7 +1,7 @@
-import { isDeniedKey } from "./sanitize.js";
+import { CLUEBASE_OTEL_ALLOWED_RESOURCE_KEYS, CLUEBASE_OTEL_SDK_SOURCE_REQUIRED_RESOURCE_KEYS, } from "../_generated/otel-resource-keys.js";
 import { SDK_VERSION } from "../provider/constants.js";
-import { CLUEBASE_OTEL_SDK_SOURCE_REQUIRED_RESOURCE_KEYS, CLUEBASE_OTEL_SDK_SOURCE_RESOURCE_KEYS, } from "../_generated/otel-resource-keys.js";
-const FRONTEND_RESOURCE_KEYS = new Set(CLUEBASE_OTEL_SDK_SOURCE_RESOURCE_KEYS);
+import { isDeniedKey } from "./sanitize.js";
+const FRONTEND_RESOURCE_KEYS = new Set(CLUEBASE_OTEL_ALLOWED_RESOURCE_KEYS);
 const FRONTEND_REQUIRED_RESOURCE_KEYS = new Set(CLUEBASE_OTEL_SDK_SOURCE_REQUIRED_RESOURCE_KEYS);
 const MAX_RESOURCE_VALUE_BYTES = 512;
 export const createFrontendResourceAttributes = (resolved) => ({
@@ -27,7 +27,8 @@ export const toFrontendSourceResource = (resource, deniedKeys = []) => {
     }
     for (const [key, value] of entries) {
         if (!FRONTEND_RESOURCE_KEYS.has(key) ||
-            (isDeniedKey(key, deniedKeys) && !FRONTEND_REQUIRED_RESOURCE_KEYS.has(key))) {
+            (isDeniedKey(key, deniedKeys) &&
+                !FRONTEND_REQUIRED_RESOURCE_KEYS.has(key))) {
             continue;
         }
         if (key === "cluebase.service_type" && value !== "frontend") {

package/dist/exporter/observation-source-event-exporter.d.ts

@@ -30,6 +30,7 @@ export declare class ObservationSourceEventExporter implements SpanExporter {
     private ignoreSpanReason;
     enqueue(event: BrowserSourceSignalEvent): void;
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    private exportAsync;
     forceFlush(): Promise<void>;
     shutdown(): Promise<void>;
     internalMetrics(): {

package/dist/exporter/observation-source-event-exporter.js

@@ -55,6 +55,9 @@ export class ObservationSourceEventExporter {
             });
             return;
         }
+        void this.exportAsync(spans, resultCallback);
+    }
+    async exportAsync(spans, resultCallback) {
         try {
             const context = this.getContext();
             for (const span of spans) {
@@ -71,7 +74,7 @@ export class ObservationSourceEventExporter {
                         this.droppedSpanCount += 1;
                         continue;
                     }
-                    const sourceSignal = spanToSourceSignalEvent(span, {
+                    const sourceSignal = await spanToSourceSignalEvent(span, {
                         context,
                         deniedKeys: this.deniedKeys,
                     });
@@ -85,7 +88,7 @@ export class ObservationSourceEventExporter {
                     });
                 }
             }
-            void this.flushImpl()
+            await this.flushImpl()
                 .then(() => resultCallback({ code: ExportResultCode.SUCCESS }))
                 .catch((cause) => resultCallback({
                 code: ExportResultCode.FAILED,