@genn-inc/cluebase-frontend-sdk 0.0.1

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

@@ -0,0 +1,103 @@
+import { z } from "zod";
+declare const ingestRetryStrategySchema: z.ZodEnum<{
+    split_batch: "split_batch";
+    retry_same_batch: "retry_same_batch";
+    stop_and_report: "stop_and_report";
+    mark_failed: "mark_failed";
+    drop_event: "drop_event";
+}>;
+export declare const ingestPrivacyPolicySchema: z.ZodObject<{
+    token: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        method: z.ZodString;
+        path_template: z.ZodString;
+        direction: z.ZodEnum<{
+            request: "request";
+            response: "response";
+        }>;
+        field_path: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type IngestPrivacyPolicy = z.output<typeof ingestPrivacyPolicySchema>;
+export declare const observationSourceEventBatchResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    accepted: z.ZodLiteral<true>;
+    observation_ingest_batch_id: z.ZodString;
+    status: z.ZodLiteral<"received">;
+    submitted_event_count: z.ZodNumber;
+    accepted_event_count: z.ZodNumber;
+    dropped_event_count: z.ZodNumber;
+    dropped_events: z.ZodArray<z.ZodObject<{
+        event_index: z.ZodNumber;
+        reason: z.ZodString;
+        source_event_payload_fingerprint: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    duplicate: z.ZodBoolean;
+    governor: z.ZodOptional<z.ZodObject<{
+        disabledCapabilities: z.ZodArray<z.ZodEnum<{
+            event_collection: "event_collection";
+            replay_storage: "replay_storage";
+            ai_generation: "ai_generation";
+            raw_observation_storage: "raw_observation_storage";
+            retention_growth: "retention_growth";
+        }>>;
+        limitReasons: z.ZodArray<z.ZodObject<{
+            limitKind: z.ZodEnum<{
+                monthly_overage_amount_limit: "monthly_overage_amount_limit";
+                internal_cost_limit: "internal_cost_limit";
+                internal_limit: "internal_limit";
+                operator_global_monthly_cost_limit: "operator_global_monthly_cost_limit";
+            }>;
+            meterKey: z.ZodString;
+            thresholdStage: z.ZodEnum<{
+                info: "info";
+                warning: "warning";
+                urgent: "urgent";
+                reached: "reached";
+            }>;
+            currentValue: z.ZodNumber;
+            limitValue: z.ZodNumber;
+            retryAfterAt: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        retryAfterAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    privacy_policy: z.ZodOptional<z.ZodObject<{
+        token: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            method: z.ZodString;
+            path_template: z.ZodString;
+            direction: z.ZodEnum<{
+                request: "request";
+                response: "response";
+            }>;
+            field_path: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>, z.ZodObject<{
+    accepted: z.ZodLiteral<false>;
+    status: z.ZodEnum<{
+        rejected: "rejected";
+        failed: "failed";
+    }>;
+    reason: z.ZodString;
+    retry_strategy: z.ZodEnum<{
+        split_batch: "split_batch";
+        retry_same_batch: "retry_same_batch";
+        stop_and_report: "stop_and_report";
+        mark_failed: "mark_failed";
+        drop_event: "drop_event";
+    }>;
+    submitted_event_count: z.ZodOptional<z.ZodNumber>;
+    accepted_event_count: z.ZodOptional<z.ZodNumber>;
+    dropped_event_count: z.ZodOptional<z.ZodNumber>;
+    dropped_events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        event_index: z.ZodNumber;
+        reason: z.ZodString;
+        source_event_payload_fingerprint: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>;
+    limits: z.ZodOptional<z.ZodObject<{
+        hard_max_payload_bytes: z.ZodNumber;
+        max_event_bytes: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "accepted">;
+export type IngestRetryStrategy = z.infer<typeof ingestRetryStrategySchema>;
+export {};

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

@@ -0,0 +1,147 @@
+// 止める対象と上限の種類は正本から生成した部品を読みます。
+import { COST_CAPABILITIES, LIMIT_KINDS } from "../_generated/usage-governor-tables.js";
+import { z } from "zod";
+const MAX_INGEST_EVENTS_PER_BATCH = 10000;
+const ingestRetryStrategySchema = z.enum([
+    "split_batch",
+    "retry_same_batch",
+    "stop_and_report",
+    "mark_failed",
+    "drop_event",
+]);
+const ingestDroppedEventSchema = z
+    .object({
+    event_index: z.number().int().nonnegative(),
+    reason: z.string().trim().min(1).max(128),
+    source_event_payload_fingerprint: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .nullable(),
+})
+    .strict();
+const ingestUsageGovernorFeedbackSchema = z.object({
+    disabledCapabilities: z.array(z.enum(COST_CAPABILITIES)),
+    limitReasons: z.array(z.object({
+        limitKind: z.enum(LIMIT_KINDS),
+        meterKey: z.string().trim().min(1),
+        thresholdStage: z.enum(["info", "warning", "urgent", "reached"]),
+        currentValue: z.number().nonnegative(),
+        limitValue: z.number().nonnegative(),
+        retryAfterAt: z.string().datetime({ offset: true }).nullable(),
+    })),
+    retryAfterAt: z.string().datetime({ offset: true }).nullable(),
+});
+const boundedCount = z.number().int().nonnegative().max(MAX_INGEST_EVENTS_PER_BATCH);
+const positiveCount = boundedCount.refine((count) => count > 0);
+// 顧客が画面で平文にした項目。**受付側の合印と違う時だけ載ります。**
+// 封筒の契約は受付側が正本 (`ingest-privacy-policy-delivery.schema.ts`)。この配る
+// 部品は `@cluebase/schema` を実行時に持てない (= 顧客の bundle に入れない) ので、
+// この file が受け取る形を持ちます。ここと正本がずれたら、届いた方針は形が
+// 合わずに捨てられ、**全部伏せた側へ倒れます。**
+export const ingestPrivacyPolicySchema = z
+    .object({
+    token: z.string().trim().min(1).max(200),
+    entries: z
+        .array(z
+        .object({
+        method: z.string().trim().min(1).max(200),
+        path_template: z.string().trim().min(1).max(1024),
+        direction: z.enum(["request", "response"]),
+        field_path: z.string().trim().min(1).max(1024),
+    })
+        .strict())
+        .max(500),
+})
+    .strict();
+const observationSourceEventBatchAcceptedResponseSchema = z
+    .object({
+    accepted: z.literal(true),
+    observation_ingest_batch_id: z.string().trim().min(1),
+    status: z.literal("received"),
+    submitted_event_count: positiveCount,
+    accepted_event_count: positiveCount,
+    dropped_event_count: boundedCount,
+    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) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["submitted_event_count"],
+            message: "submitted count must equal accepted plus dropped counts",
+        });
+    }
+    if (!value.duplicate || value.dropped_events.length > 0) {
+        validateDroppedEventDetails(value.submitted_event_count, value.dropped_event_count, value.dropped_events, ctx);
+    }
+});
+const observationSourceEventBatchRejectedResponseSchema = z
+    .object({
+    accepted: z.literal(false),
+    status: z.enum(["rejected", "failed"]),
+    reason: z.string().trim().min(1),
+    retry_strategy: ingestRetryStrategySchema,
+    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(),
+    limits: z
+        .object({
+        hard_max_payload_bytes: z.number().int().positive(),
+        max_event_bytes: z.number().int().positive(),
+    })
+        .refine((limits) => limits.max_event_bytes <= limits.hard_max_payload_bytes)
+        .optional(),
+})
+    .superRefine((value, ctx) => {
+    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" });
+        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 (value.retry_strategy === "drop_event") {
+        if (!hasAllCounts) {
+            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" });
+            }
+            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" });
+    }
+    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", [
+    observationSourceEventBatchAcceptedResponseSchema,
+    observationSourceEventBatchRejectedResponseSchema,
+]);
+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" });
+    }
+    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" });
+        }
+        indexes.add(detail.event_index);
+    }
+}

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

@@ -0,0 +1,37 @@
+import { type IngestRetryStrategy } from "./delivery-response-contract.js";
+import type { IngestUsageGovernorFeedback } from "../provider/types.js";
+export declare const BROWSER_REJECTION_STRATEGIES: Readonly<Record<string, IngestRetryStrategy>>;
+export type { IngestRetryStrategy } from "./delivery-response-contract.js";
+export type BrowserDeliveryDecision = {
+    readonly ok: boolean;
+    /** 受付側が返した方針。合印が同じなら来ない。 */
+    readonly privacyPolicy?: unknown;
+    readonly retryStrategy: IngestRetryStrategy | null;
+    readonly governor: IngestUsageGovernorFeedback | null;
+    readonly observationIngestBatchId?: string;
+    readonly droppedEventCount: number;
+    readonly acceptedEventCount: number;
+    readonly acceptedPartial: boolean;
+    readonly reason: string | null;
+};
+export declare const evaluateBrowserDeliveryResponse: (input: {
+    readonly status: number;
+    readonly bodyText: string;
+    readonly localSubmittedCount: number;
+}) => BrowserDeliveryDecision;
+/**
+ * Decide from the HTTP status alone whether a failed exchange with Cluebase is
+ * worth replaying.
+ *
+ * This is the single owner of that judgement. Batch delivery consults it when
+ * the body carries no usable verdict, and browser-token acquisition consults it
+ * because that endpoint carries no verdict at all. Without one owner the same
+ * status is permanent on one path and transient on the other, and a request
+ * that can never succeed is replayed until the customer's events expire.
+ *
+ * A status is only replayed when it says "the same request may succeed later".
+ * That is the rule the SDK's own core already applies — OpenTelemetry's OTLP
+ * exporter retries 429/502/503/504 and nothing else (`isExportRetryable`) —
+ * widened here to the statuses this ingest contract additionally defines.
+ */
+export declare const classifyIngestHttpStatus: (status: number) => IngestRetryStrategy;

package/dist/exporter/delivery-response.js

@@ -0,0 +1,151 @@
+import { observationSourceEventBatchResponseSchema, } from "./delivery-response-contract.js";
+import { parseGovernorFeedbackEnvelope } from "../provider/usage-governor.js";
+export const BROWSER_REJECTION_STRATEGIES = {
+    invalid_request: "stop_and_report",
+    unsupported_source_schema_version: "stop_and_report",
+    missing_project_key: "stop_and_report",
+    project_key_mismatch: "stop_and_report",
+    unresolved_project_or_environment: "stop_and_report",
+    missing_browser_token: "stop_and_report",
+    invalid_browser_token: "stop_and_report",
+    expired_browser_token: "retry_same_batch",
+    stale_browser_token: "retry_same_batch",
+    origin_not_allowed: "stop_and_report",
+    authorization_denied: "stop_and_report",
+    idempotency_conflict: "mark_failed",
+    batch_too_large: "split_batch",
+    all_events_dropped: "drop_event",
+    usage_governor_denied: "retry_same_batch",
+    all_events_rejected_by_ingest_controls: "retry_same_batch",
+    route_throttled: "retry_same_batch",
+    raw_ingest_produce_failed: "retry_same_batch",
+    raw_ingest_ack_unknown: "retry_same_batch",
+    raw_ingest_receipt_metadata_failed: "retry_same_batch",
+    ingest_config_changed_retryable: "retry_same_batch",
+    usage_meter_unavailable: "retry_same_batch",
+};
+export const evaluateBrowserDeliveryResponse = (input) => {
+    const decoded = decode(input.bodyText);
+    if (decoded !== null && hasAcceptedDiscriminator(decoded)) {
+        const parsed = observationSourceEventBatchResponseSchema.safeParse(decoded);
+        if (parsed.success &&
+            submittedCountMatches(parsed.data, input.localSubmittedCount) &&
+            hasPublicDropDetails(parsed.data)) {
+            if (parsed.data.accepted) {
+                if (input.status < 200 || input.status >= 300) {
+                    return invalidResponse();
+                }
+                const partial = parsed.data.dropped_event_count > 0;
+                return {
+                    ok: true,
+                    retryStrategy: null,
+                    privacyPolicy: parsed.data.privacy_policy,
+                    governor: parseGovernorFeedbackEnvelope(parsed.data),
+                    observationIngestBatchId: parsed.data.observation_ingest_batch_id,
+                    droppedEventCount: parsed.data.dropped_event_count,
+                    acceptedEventCount: parsed.data.accepted_event_count,
+                    acceptedPartial: partial,
+                    reason: partial ? "accepted_partial" : null,
+                };
+            }
+            if (BROWSER_REJECTION_STRATEGIES[parsed.data.reason] !==
+                parsed.data.retry_strategy) {
+                return invalidResponse();
+            }
+            return {
+                ok: false,
+                retryStrategy: parsed.data.retry_strategy,
+                governor: null,
+                droppedEventCount: parsed.data.dropped_event_count ?? 0,
+                acceptedEventCount: parsed.data.accepted_event_count ?? 0,
+                acceptedPartial: false,
+                reason: parsed.data.reason,
+            };
+        }
+        return invalidResponse();
+    }
+    return fallback(input.status);
+};
+const submittedCountMatches = (value, localSubmittedCount) => value.submitted_event_count === undefined ||
+    value.submitted_event_count === localSubmittedCount;
+const hasPublicDropDetails = (value) => (value.dropped_events ?? []).every((detail) => detail.source_event_payload_fingerprint === null);
+const decode = (bodyText) => {
+    if (!bodyText.trim())
+        return null;
+    try {
+        return JSON.parse(bodyText);
+    }
+    catch {
+        return null;
+    }
+};
+const hasAcceptedDiscriminator = (value) => value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.prototype.hasOwnProperty.call(value, "accepted");
+const invalidResponse = () => ({
+    ok: false,
+    retryStrategy: "retry_same_batch",
+    governor: null,
+    droppedEventCount: 0,
+    acceptedEventCount: 0,
+    acceptedPartial: false,
+    reason: "invalid_response",
+});
+/**
+ * Decide from the HTTP status alone whether a failed exchange with Cluebase is
+ * worth replaying.
+ *
+ * This is the single owner of that judgement. Batch delivery consults it when
+ * the body carries no usable verdict, and browser-token acquisition consults it
+ * because that endpoint carries no verdict at all. Without one owner the same
+ * status is permanent on one path and transient on the other, and a request
+ * that can never succeed is replayed until the customer's events expire.
+ *
+ * A status is only replayed when it says "the same request may succeed later".
+ * That is the rule the SDK's own core already applies — OpenTelemetry's OTLP
+ * exporter retries 429/502/503/504 and nothing else (`isExportRetryable`) —
+ * widened here to the statuses this ingest contract additionally defines.
+ */
+export const classifyIngestHttpStatus = (status) => {
+    // A 2xx that got this far means the body did not match the contract. That can
+    // be a transient rewrite in transit, so it stays replayable.
+    if (status >= 200 && status < 300)
+        return "retry_same_batch";
+    if (status === 409)
+        return "mark_failed";
+    if (status === 413)
+        return "split_batch";
+    // Deterministic refusals: the request is wrong, unauthorized, or aimed at
+    // something that is not there. Replaying it changes nothing.
+    if ([400, 401, 403, 404, 405, 406, 410, 415].includes(status)) {
+        return "stop_and_report";
+    }
+    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) => ({
+    ok: false,
+    retryStrategy,
+    governor: null,
+    droppedEventCount: 0,
+    acceptedEventCount: 0,
+    acceptedPartial: false,
+    reason: `http_${status}`,
+});

package/dist/exporter/diagnostics.d.ts

@@ -0,0 +1,42 @@
+import type { IngestRetryStrategy } from "./delivery-response.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;
+export type DiagnosticCloseOutcome = "clean" | "retryable_failure" | "terminal_failure" | null;
+export type DiagnosticRecentEntry = {
+    readonly occurred_at: string;
+    readonly code: DiagnosticCode;
+    readonly strategy?: IngestRetryStrategy;
+    readonly http_status?: number;
+    readonly reason?: string;
+    readonly attempt?: number;
+    readonly count?: number;
+    readonly batch_fingerprint?: string;
+    readonly event_fingerprint?: string;
+};
+export type DiagnosticsSnapshot = {
+    readonly schema_version: 1;
+    readonly lifecycle: DiagnosticLifecycle;
+    readonly last_flush_outcome: DiagnosticFlushOutcome;
+    readonly last_close_outcome: DiagnosticCloseOutcome;
+    readonly counters: Readonly<Record<DiagnosticCode, number>>;
+    readonly recent: readonly DiagnosticRecentEntry[];
+};
+export declare class DiagnosticStore {
+    private key;
+    private lifecycle;
+    private lastFlushOutcome;
+    private lastCloseOutcome;
+    private readonly counters;
+    private recent;
+    constructor(key?: Uint8Array);
+    record(entry: Omit<DiagnosticRecentEntry, "occurred_at">): void;
+    setLifecycle(value: DiagnosticLifecycle): void;
+    setFlushOutcome(value: DiagnosticFlushOutcome): void;
+    setCloseOutcome(value: DiagnosticCloseOutcome): void;
+    rotateForConsentPurge(count: number): void;
+    batchFingerprint(ownedCanonicalBytes: string): string;
+    eventFingerprint(ownedCanonicalBytes: string): string;
+    snapshot(): DiagnosticsSnapshot;
+    private fingerprint;
+}

package/dist/exporter/diagnostics.js

@@ -0,0 +1,148 @@
+import { hmac } from "@noble/hashes/hmac";
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex, randomBytes, utf8ToBytes } from "@noble/hashes/utils";
+const CODES = [
+    "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",
+];
+const CODE_SET = new Set(CODES);
+const STRATEGIES = new Set([
+    "split_batch",
+    "retry_same_batch",
+    "stop_and_report",
+    "mark_failed",
+    "drop_event",
+]);
+const SAFE_REASONS = new Set([
+    "all_events_dropped",
+    "all_events_rejected_by_ingest_controls",
+    "authorization_denied",
+    "batch_too_large",
+    "expired_browser_token",
+    "idempotency_conflict",
+    "invalid_api_key",
+    "invalid_browser_token",
+    "invalid_request",
+    "missing_browser_token",
+    "missing_project_key",
+    "origin_not_allowed",
+    "project_key_mismatch",
+    "raw_ingest_ack_unknown",
+    "raw_ingest_produce_failed",
+    "raw_ingest_receipt_metadata_failed",
+    "route_throttled",
+    "stale_browser_token",
+    "unresolved_project_or_environment",
+    "unsupported_source_schema_version",
+    "usage_governor_denied",
+    "usage_meter_unavailable",
+]);
+const FINGERPRINT = /^diag_hmac_v1_[0-9a-f]{64}$/;
+const RECENT_LIMIT = 100;
+export class DiagnosticStore {
+    constructor(key = randomBytes(32)) {
+        this.lifecycle = "open";
+        this.lastFlushOutcome = null;
+        this.lastCloseOutcome = null;
+        this.counters = Object.fromEntries(CODES.map((code) => [code, 0]));
+        this.recent = [];
+        if (key.byteLength !== 32)
+            throw new Error("diagnostic_key_invalid");
+        this.key = new Uint8Array(key);
+    }
+    record(entry) {
+        const safe = normalize(entry);
+        if (!safe)
+            return;
+        this.counters[safe.code] += safe.count ?? 1;
+        this.recent = [...this.recent.slice(-(RECENT_LIMIT - 1)), safe];
+    }
+    setLifecycle(value) {
+        this.lifecycle = value;
+    }
+    setFlushOutcome(value) {
+        this.lastFlushOutcome = value;
+    }
+    setCloseOutcome(value) {
+        this.lastCloseOutcome = value;
+    }
+    rotateForConsentPurge(count) {
+        this.key.fill(0);
+        this.key = randomBytes(32);
+        this.recent = [];
+        if (count > 0)
+            this.record({ code: "consent_purge", count });
+    }
+    batchFingerprint(ownedCanonicalBytes) {
+        return this.fingerprint("batch", ownedCanonicalBytes);
+    }
+    eventFingerprint(ownedCanonicalBytes) {
+        return this.fingerprint("event", ownedCanonicalBytes);
+    }
+    snapshot() {
+        return Object.freeze({
+            schema_version: 1,
+            lifecycle: this.lifecycle,
+            last_flush_outcome: this.lastFlushOutcome,
+            last_close_outcome: this.lastCloseOutcome,
+            counters: Object.freeze({ ...this.counters }),
+            recent: Object.freeze(this.recent.map((entry) => Object.freeze({ ...entry }))),
+        });
+    }
+    fingerprint(domain, value) {
+        return `diag_hmac_v1_${bytesToHex(hmac(sha256, this.key, utf8ToBytes(`${domain}\0${value}`)))}`;
+    }
+}
+const normalize = (input) => {
+    if (!CODE_SET.has(input.code))
+        return null;
+    const entry = { occurred_at: new Date().toISOString(), code: input.code };
+    if (input.strategy && STRATEGIES.has(input.strategy)) {
+        entry.strategy = input.strategy;
+    }
+    const httpStatus = input.http_status;
+    if (typeof httpStatus === "number" &&
+        Number.isInteger(httpStatus) &&
+        httpStatus >= 100 &&
+        httpStatus <= 599) {
+        entry.http_status = httpStatus;
+    }
+    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) {
+        entry.attempt = attempt;
+    }
+    const count = input.count;
+    if (typeof count === "number" && Number.isSafeInteger(count) && count >= 0) {
+        entry.count = count;
+    }
+    if (input.batch_fingerprint && FINGERPRINT.test(input.batch_fingerprint)) {
+        entry.batch_fingerprint = input.batch_fingerprint;
+    }
+    if (input.event_fingerprint && FINGERPRINT.test(input.event_fingerprint)) {
+        entry.event_fingerprint = input.event_fingerprint;
+    }
+    return Object.freeze(entry);
+};

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

@@ -0,0 +1,10 @@
+export declare const generateMonotonicId: (prefix?: string) => string;
+export declare const generateTraceId: () => string;
+export declare const generateEventId: () => string;
+export declare const generateAnonymousId: () => string;
+export declare const generateSessionId: () => string;
+export declare const generateTabId: () => string;
+export declare const generateRequestId: () => string;
+export declare const generateRequestSpanId: () => string;
+export declare const generateInteractionId: () => string;
+export declare const generateViewId: () => string;