@bli-cockpit/telemetry-core 0.1.32 → 0.1.33

package/dist/collector-heartbeat.d.ts

@@ -106,6 +106,47 @@ export declare const CollectorHeartbeatSchema: z.ZodObject<{
         hook_printed_24h: z.ZodOptional<z.ZodNumber>;
         hook_failed_24h: z.ZodOptional<z.ZodNumber>;
         hook_stats_reason: z.ZodOptional<z.ZodString>;
+        hook_performance: z.ZodOptional<z.ZodObject<{
+            schema_version: z.ZodLiteral<"memory-hook-performance.v1">;
+            window_start: z.ZodString;
+            window_end: z.ZodString;
+            sampling_since: z.ZodNullable<z.ZodString>;
+            samples: z.ZodNumber;
+            outcomes: z.ZodObject<{
+                printed: z.ZodNumber;
+                empty: z.ZodNumber;
+                timeouts: z.ZodNumber;
+                failed: z.ZodNumber;
+                skipped: z.ZodNumber;
+            }, z.core.$strict>;
+            duration_by_cache: z.ZodObject<{
+                hit: z.ZodArray<z.ZodNumber>;
+                miss: z.ZodArray<z.ZodNumber>;
+                shared: z.ZodArray<z.ZodNumber>;
+                unknown: z.ZodArray<z.ZodNumber>;
+            }, z.core.$strict>;
+            producer_versions: z.ZodArray<z.ZodObject<{
+                version: z.ZodString;
+                samples: z.ZodNumber;
+            }, z.core.$strict>>;
+            invalid_samples: z.ZodNumber;
+            incomplete_samples: z.ZodNumber;
+            unreadable_samples: z.ZodNumber;
+            capped: z.ZodBoolean;
+            reasons: z.ZodArray<z.ZodEnum<{
+                no_samples: "no_samples";
+                partial_window: "partial_window";
+                lease_absent: "lease_absent";
+                lease_expired: "lease_expired";
+                lease_invalid: "lease_invalid";
+                read_failed: "read_failed";
+                read_limit: "read_limit";
+                invalid_samples: "invalid_samples";
+                incomplete_samples: "incomplete_samples";
+                unreadable_samples: "unreadable_samples";
+                cleanup_failed: "cleanup_failed";
+            }>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     setup_receipt: z.ZodOptional<z.ZodObject<{
         schema_version: z.ZodLiteral<"setup-receipt.v1">;

package/dist/evidence-completeness.d.ts

@@ -2,9 +2,9 @@ import { z } from "zod";
 export declare const EvidenceCompletenessStatusSchema: z.ZodEnum<{
     unknown: "unknown";
     failed: "failed";
+    empty: "empty";
     complete: "complete";
     partial: "partial";
-    empty: "empty";
     unavailable: "unavailable";
 }>;
 export type EvidenceCompletenessStatus = z.infer<typeof EvidenceCompletenessStatusSchema>;
@@ -71,9 +71,9 @@ export declare const EvidenceCompletenessPayloadSchema: z.ZodObject<{
     status: z.ZodEnum<{
         unknown: "unknown";
         failed: "failed";
+        empty: "empty";
         complete: "complete";
         partial: "partial";
-        empty: "empty";
         unavailable: "unavailable";
     }>;
     generated_at: z.ZodString;

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";
 export * from "./local-config.js";
 export * from "./memory-hook-stats.js";
+export * from "./memory-hook-performance.js";
 export * from "./memory-install-receipt.js";
 export * from "./paths.js";
 export * from "./privacy.js";

package/dist/index.js

@@ -10,6 +10,7 @@ export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";
 export * from "./local-config.js";
 export * from "./memory-hook-stats.js";
+export * from "./memory-hook-performance.js";
 export * from "./memory-install-receipt.js";
 export * from "./paths.js";
 export * from "./privacy.js";

package/dist/ingest-dto.d.ts

@@ -105,9 +105,9 @@ export declare const TelemetryIngestEventDtoSchema: z.ZodObject<{
         status: z.ZodEnum<{
             unknown: "unknown";
             failed: "failed";
+            empty: "empty";
             complete: "complete";
             partial: "partial";
-            empty: "empty";
             unavailable: "unavailable";
         }>;
         generated_at: z.ZodString;
@@ -584,9 +584,9 @@ export declare const TelemetryIngestEnvelopeSchema: z.ZodObject<{
             status: z.ZodEnum<{
                 unknown: "unknown";
                 failed: "failed";
+                empty: "empty";
                 complete: "complete";
                 partial: "partial";
-                empty: "empty";
                 unavailable: "unavailable";
             }>;
             generated_at: z.ZodString;

package/dist/memory-hook-performance.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Content-free prompt-hook performance samples (BLI-3876).
+ *
+ * This module is the shared wire and local-file contract only. It deliberately
+ * has no filesystem effects: the hook writer and collector reader own I/O.
+ * Samples carry closed labels, durations and timestamps, never prompt text,
+ * hashes or memory content.
+ */
+import { z } from "zod";
+export declare const MEMORY_HOOK_SAMPLE_SCHEMA_VERSION = "memory-hook-sample.v1";
+export declare const MEMORY_HOOK_SAMPLING_LEASE_SCHEMA_VERSION = "memory-hook-sampling-lease.v1";
+export declare const MEMORY_HOOK_PERFORMANCE_SCHEMA_VERSION = "memory-hook-performance.v1";
+export declare const MEMORY_HOOK_CACHE_OUTCOMES: readonly ["hit", "miss", "shared", "unknown"];
+export type MemoryHookCacheOutcome = (typeof MEMORY_HOOK_CACHE_OUTCOMES)[number];
+export declare const MEMORY_HOOK_SAMPLE_OUTCOMES: readonly ["printed", "empty", "timeouts", "failed", "skipped"];
+export type MemoryHookSampleOutcome = (typeof MEMORY_HOOK_SAMPLE_OUTCOMES)[number];
+export declare const MemoryHookSampleSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"memory-hook-sample.v1">;
+    recorded_at: z.ZodString;
+    elapsed_ms: z.ZodNumber;
+    outcome: z.ZodEnum<{
+        failed: "failed";
+        skipped: "skipped";
+        printed: "printed";
+        empty: "empty";
+        timeouts: "timeouts";
+    }>;
+    embed_cache: z.ZodEnum<{
+        unknown: "unknown";
+        hit: "hit";
+        miss: "miss";
+        shared: "shared";
+    }>;
+    producer_version: z.ZodString;
+}, z.core.$strict>;
+export type MemoryHookSample = z.infer<typeof MemoryHookSampleSchema>;
+export declare const MemoryHookSamplingLeaseSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"memory-hook-sampling-lease.v1">;
+    continuous_since: z.ZodString;
+    expires_at: z.ZodString;
+}, z.core.$strict>;
+export type MemoryHookSamplingLease = z.infer<typeof MemoryHookSamplingLeaseSchema>;
+/** The samples directory below the user's existing Cockpit state directory. */
+export declare const MEMORY_HOOK_SAMPLES_DIRECTORY_NAME = "memory-hook-samples";
+export declare function memoryHookSamplesDirectory(homeDir: string): string;
+export declare const MEMORY_HOOK_HISTOGRAM_BIN_WIDTH_MS = 100;
+export declare const MEMORY_HOOK_HISTOGRAM_LENGTH = 51;
+/** A fresh [0,100), ... [4900,5000), [5000,infinity) histogram. */
+export declare function blankHistogram(): number[];
+/** Add one valid duration and return the same histogram for convenient chaining. */
+export declare function addDuration(histogram: number[], durationMs: number): number[];
+/**
+ * Return the nearest-rank bin bounds. The result never interpolates between
+ * bins, and the open-ended final bin has no finite upper bound.
+ */
+export declare function histogramPercentileBounds(histogram: number[], percentile: number): {
+    lower_ms: number;
+    upper_ms: number | null;
+} | null;
+export declare const MEMORY_HOOK_PERFORMANCE_REASONS: readonly ["no_samples", "partial_window", "lease_absent", "lease_expired", "lease_invalid", "read_failed", "read_limit", "invalid_samples", "incomplete_samples", "unreadable_samples", "cleanup_failed"];
+export declare const MemoryHookPerformanceSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"memory-hook-performance.v1">;
+    window_start: z.ZodString;
+    window_end: z.ZodString;
+    sampling_since: z.ZodNullable<z.ZodString>;
+    samples: z.ZodNumber;
+    outcomes: z.ZodObject<{
+        printed: z.ZodNumber;
+        empty: z.ZodNumber;
+        timeouts: z.ZodNumber;
+        failed: z.ZodNumber;
+        skipped: z.ZodNumber;
+    }, z.core.$strict>;
+    duration_by_cache: z.ZodObject<{
+        hit: z.ZodArray<z.ZodNumber>;
+        miss: z.ZodArray<z.ZodNumber>;
+        shared: z.ZodArray<z.ZodNumber>;
+        unknown: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>;
+    producer_versions: z.ZodArray<z.ZodObject<{
+        version: z.ZodString;
+        samples: z.ZodNumber;
+    }, z.core.$strict>>;
+    invalid_samples: z.ZodNumber;
+    incomplete_samples: z.ZodNumber;
+    unreadable_samples: z.ZodNumber;
+    capped: z.ZodBoolean;
+    reasons: z.ZodArray<z.ZodEnum<{
+        no_samples: "no_samples";
+        partial_window: "partial_window";
+        lease_absent: "lease_absent";
+        lease_expired: "lease_expired";
+        lease_invalid: "lease_invalid";
+        read_failed: "read_failed";
+        read_limit: "read_limit";
+        invalid_samples: "invalid_samples";
+        incomplete_samples: "incomplete_samples";
+        unreadable_samples: "unreadable_samples";
+        cleanup_failed: "cleanup_failed";
+    }>>;
+}, z.core.$strict>;
+export type MemoryHookPerformance = z.infer<typeof MemoryHookPerformanceSchema>;

package/dist/memory-hook-performance.js

@@ -0,0 +1,208 @@
+/**
+ * Content-free prompt-hook performance samples (BLI-3876).
+ *
+ * This module is the shared wire and local-file contract only. It deliberately
+ * has no filesystem effects: the hook writer and collector reader own I/O.
+ * Samples carry closed labels, durations and timestamps, never prompt text,
+ * hashes or memory content.
+ */
+import { z } from "zod";
+import { IsoDateTimeSchema } from "./common.js";
+import { getUserLocalCockpitPaths } from "./paths.js";
+export const MEMORY_HOOK_SAMPLE_SCHEMA_VERSION = "memory-hook-sample.v1";
+export const MEMORY_HOOK_SAMPLING_LEASE_SCHEMA_VERSION = "memory-hook-sampling-lease.v1";
+export const MEMORY_HOOK_PERFORMANCE_SCHEMA_VERSION = "memory-hook-performance.v1";
+export const MEMORY_HOOK_CACHE_OUTCOMES = [
+    "hit",
+    "miss",
+    "shared",
+    "unknown",
+];
+export const MEMORY_HOOK_SAMPLE_OUTCOMES = [
+    "printed",
+    "empty",
+    "timeouts",
+    "failed",
+    "skipped",
+];
+const CacheOutcomeSchema = z.enum(MEMORY_HOOK_CACHE_OUTCOMES);
+const SampleOutcomeSchema = z.enum(MEMORY_HOOK_SAMPLE_OUTCOMES);
+const CountSchema = z.number().int().nonnegative();
+const SemverSchema = z
+    .string()
+    .min(1)
+    .max(40)
+    .regex(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u);
+export const MemoryHookSampleSchema = z
+    .object({
+    schema_version: z.literal(MEMORY_HOOK_SAMPLE_SCHEMA_VERSION),
+    recorded_at: IsoDateTimeSchema,
+    elapsed_ms: z.number().finite().int().nonnegative().max(60_000),
+    outcome: SampleOutcomeSchema,
+    embed_cache: CacheOutcomeSchema,
+    producer_version: SemverSchema,
+})
+    .strict();
+export const MemoryHookSamplingLeaseSchema = z
+    .object({
+    schema_version: z.literal(MEMORY_HOOK_SAMPLING_LEASE_SCHEMA_VERSION),
+    continuous_since: IsoDateTimeSchema,
+    expires_at: IsoDateTimeSchema,
+})
+    .strict();
+/** The samples directory below the user's existing Cockpit state directory. */
+export const MEMORY_HOOK_SAMPLES_DIRECTORY_NAME = "memory-hook-samples";
+export function memoryHookSamplesDirectory(homeDir) {
+    const paths = getUserLocalCockpitPaths(homeDir);
+    const separator = paths.state_dir.includes("\\") ? "\\" : "/";
+    return `${paths.state_dir}${separator}${MEMORY_HOOK_SAMPLES_DIRECTORY_NAME}`;
+}
+export const MEMORY_HOOK_HISTOGRAM_BIN_WIDTH_MS = 100;
+export const MEMORY_HOOK_HISTOGRAM_LENGTH = 51;
+/** A fresh [0,100), ... [4900,5000), [5000,infinity) histogram. */
+export function blankHistogram() {
+    return Array.from({ length: MEMORY_HOOK_HISTOGRAM_LENGTH }, () => 0);
+}
+function validateHistogram(histogram) {
+    if (histogram.length !== MEMORY_HOOK_HISTOGRAM_LENGTH) {
+        throw new RangeError(`histogram must have ${MEMORY_HOOK_HISTOGRAM_LENGTH} bins`);
+    }
+    for (const count of histogram) {
+        if (!Number.isInteger(count) || count < 0) {
+            throw new RangeError("histogram counts must be non-negative integers");
+        }
+    }
+}
+/** Add one valid duration and return the same histogram for convenient chaining. */
+export function addDuration(histogram, durationMs) {
+    validateHistogram(histogram);
+    if (!Number.isFinite(durationMs) || !Number.isInteger(durationMs) || durationMs < 0) {
+        throw new RangeError("duration must be a non-negative integer");
+    }
+    if (durationMs > 60_000) {
+        throw new RangeError("duration must be at most 60000 ms");
+    }
+    const bin = Math.min(Math.floor(durationMs / MEMORY_HOOK_HISTOGRAM_BIN_WIDTH_MS), MEMORY_HOOK_HISTOGRAM_LENGTH - 1);
+    histogram[bin] += 1;
+    return histogram;
+}
+/**
+ * Return the nearest-rank bin bounds. The result never interpolates between
+ * bins, and the open-ended final bin has no finite upper bound.
+ */
+export function histogramPercentileBounds(histogram, percentile) {
+    validateHistogram(histogram);
+    if (!Number.isFinite(percentile) || percentile < 0 || percentile > 100) {
+        throw new RangeError("percentile must be between 0 and 100");
+    }
+    const samples = histogram.reduce((sum, count) => sum + count, 0);
+    if (samples === 0)
+        return null;
+    const rank = Math.max(1, Math.ceil((percentile / 100) * samples));
+    let cumulative = 0;
+    for (let index = 0; index < histogram.length; index += 1) {
+        cumulative += histogram[index] ?? 0;
+        if (cumulative >= rank) {
+            return {
+                lower_ms: index * MEMORY_HOOK_HISTOGRAM_BIN_WIDTH_MS,
+                upper_ms: index === MEMORY_HOOK_HISTOGRAM_LENGTH - 1
+                    ? null
+                    : (index + 1) * MEMORY_HOOK_HISTOGRAM_BIN_WIDTH_MS,
+            };
+        }
+    }
+    return null;
+}
+const OutcomeCountsSchema = z
+    .object({
+    printed: CountSchema,
+    empty: CountSchema,
+    timeouts: CountSchema,
+    failed: CountSchema,
+    skipped: CountSchema,
+})
+    .strict();
+const HistogramSchema = z
+    .array(CountSchema)
+    .length(MEMORY_HOOK_HISTOGRAM_LENGTH);
+const DurationByCacheSchema = z
+    .object({
+    hit: HistogramSchema,
+    miss: HistogramSchema,
+    shared: HistogramSchema,
+    unknown: HistogramSchema,
+})
+    .strict();
+const ProducerVersionCountSchema = z
+    .object({
+    version: SemverSchema,
+    samples: CountSchema,
+})
+    .strict();
+export const MEMORY_HOOK_PERFORMANCE_REASONS = [
+    "no_samples",
+    "partial_window",
+    "lease_absent",
+    "lease_expired",
+    "lease_invalid",
+    "read_failed",
+    "read_limit",
+    "invalid_samples",
+    "incomplete_samples",
+    "unreadable_samples",
+    "cleanup_failed",
+];
+const PerformanceReasonSchema = z.enum(MEMORY_HOOK_PERFORMANCE_REASONS);
+export const MemoryHookPerformanceSchema = z
+    .object({
+    schema_version: z.literal(MEMORY_HOOK_PERFORMANCE_SCHEMA_VERSION),
+    window_start: IsoDateTimeSchema,
+    window_end: IsoDateTimeSchema,
+    sampling_since: IsoDateTimeSchema.nullable(),
+    samples: CountSchema,
+    outcomes: OutcomeCountsSchema,
+    duration_by_cache: DurationByCacheSchema,
+    producer_versions: z.array(ProducerVersionCountSchema).max(16),
+    invalid_samples: CountSchema,
+    incomplete_samples: CountSchema,
+    unreadable_samples: CountSchema,
+    capped: z.boolean(),
+    reasons: z.array(PerformanceReasonSchema).max(MEMORY_HOOK_PERFORMANCE_REASONS.length),
+})
+    .strict()
+    .superRefine((value, context) => {
+    const outcomeTotal = Object.values(value.outcomes).reduce((sum, count) => sum + count, 0);
+    if (outcomeTotal !== value.samples) {
+        context.addIssue({
+            code: "custom",
+            path: ["outcomes"],
+            message: "outcome counts must sum to samples",
+        });
+    }
+    const histogramTotal = Object.values(value.duration_by_cache)
+        .flat()
+        .reduce((sum, count) => sum + count, 0);
+    if (histogramTotal !== value.samples) {
+        context.addIssue({
+            code: "custom",
+            path: ["duration_by_cache"],
+            message: "duration histograms must sum to samples",
+        });
+    }
+    const versionTotal = value.producer_versions.reduce((sum, item) => sum + item.samples, 0);
+    if (versionTotal !== value.samples) {
+        context.addIssue({
+            code: "custom",
+            path: ["producer_versions"],
+            message: "producer version counts must sum to samples",
+        });
+    }
+    const versions = value.producer_versions.map((item) => item.version);
+    if (new Set(versions).size !== versions.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["producer_versions"],
+            message: "producer versions must be unique",
+        });
+    }
+});

package/dist/memory-install-receipt.d.ts

@@ -114,6 +114,47 @@ export declare const MemoryInstallReceiptSchema: z.ZodObject<{
     hook_printed_24h: z.ZodOptional<z.ZodNumber>;
     hook_failed_24h: z.ZodOptional<z.ZodNumber>;
     hook_stats_reason: z.ZodOptional<z.ZodString>;
+    hook_performance: z.ZodOptional<z.ZodObject<{
+        schema_version: z.ZodLiteral<"memory-hook-performance.v1">;
+        window_start: z.ZodString;
+        window_end: z.ZodString;
+        sampling_since: z.ZodNullable<z.ZodString>;
+        samples: z.ZodNumber;
+        outcomes: z.ZodObject<{
+            printed: z.ZodNumber;
+            empty: z.ZodNumber;
+            timeouts: z.ZodNumber;
+            failed: z.ZodNumber;
+            skipped: z.ZodNumber;
+        }, z.core.$strict>;
+        duration_by_cache: z.ZodObject<{
+            hit: z.ZodArray<z.ZodNumber>;
+            miss: z.ZodArray<z.ZodNumber>;
+            shared: z.ZodArray<z.ZodNumber>;
+            unknown: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strict>;
+        producer_versions: z.ZodArray<z.ZodObject<{
+            version: z.ZodString;
+            samples: z.ZodNumber;
+        }, z.core.$strict>>;
+        invalid_samples: z.ZodNumber;
+        incomplete_samples: z.ZodNumber;
+        unreadable_samples: z.ZodNumber;
+        capped: z.ZodBoolean;
+        reasons: z.ZodArray<z.ZodEnum<{
+            no_samples: "no_samples";
+            partial_window: "partial_window";
+            lease_absent: "lease_absent";
+            lease_expired: "lease_expired";
+            lease_invalid: "lease_invalid";
+            read_failed: "read_failed";
+            read_limit: "read_limit";
+            invalid_samples: "invalid_samples";
+            incomplete_samples: "incomplete_samples";
+            unreadable_samples: "unreadable_samples";
+            cleanup_failed: "cleanup_failed";
+        }>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type MemoryInstallReceipt = z.infer<typeof MemoryInstallReceiptSchema>;
 /** Every piece is `ok`. The one question the board asks first. */

package/dist/memory-install-receipt.js

@@ -33,6 +33,7 @@
  */
 import { z } from "zod";
 import { IsoDateTimeSchema } from "./common.js";
+import { MemoryHookPerformanceSchema } from "./memory-hook-performance.js";
 export const MEMORY_INSTALL_RECEIPT_SCHEMA_VERSION = "memory-install-receipt.v1";
 /**
  * What one piece of the installation is.
@@ -133,6 +134,8 @@ export const MemoryInstallReceiptSchema = z
     hook_failed_24h: z.number().int().min(0).optional(),
     /** Named when the counts are absent because the file could not be read. */
     hook_stats_reason: ReasonLabelSchema.optional(),
+    /** Observed ordinary invocations, not legacy floors or a full host trace. */
+    hook_performance: MemoryHookPerformanceSchema.optional(),
 })
     .strict();
 /** Every piece is `ok`. The one question the board asks first. */

package/package.json

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