@bli-cockpit/telemetry-core 0.1.37 → 0.1.38

package/dist/collector-heartbeat.d.ts

@@ -109,6 +109,9 @@ export declare const CollectorHeartbeatSchema: z.ZodObject<{
         hook_via_direct_24h: z.ZodOptional<z.ZodNumber>;
         hook_skipped_trivial_24h: z.ZodOptional<z.ZodNumber>;
         hook_billing_exhausted_24h: z.ZodOptional<z.ZodNumber>;
+        hook_chars_p50: z.ZodOptional<z.ZodNumber>;
+        hook_chars_p95: z.ZodOptional<z.ZodNumber>;
+        hook_chars_samples: 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">;

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

@@ -29,6 +29,42 @@ export declare const MEMORY_HOOK_STATS_FILE_NAME = "memory-hook-stats.json";
 /** The three hook events, spelled as the bin's subcommands are. */
 export declare const MEMORY_HOOK_STAT_EVENTS: readonly ["session-start", "prompt", "stop"];
 export type MemoryHookStatEvent = (typeof MEMORY_HOOK_STAT_EVENTS)[number];
+/**
+ * THE CHARACTER HISTOGRAM (ticket 3934).
+ *
+ * 250 characters a bin, 41 bins: `[0,250)`, … `[9750,10000)`, `[10000,∞)`.
+ *
+ * The width is chosen against what the hook can actually print, not against a
+ * round number: a recall is at most `RECALL_LIMIT` (5) memories truncated to
+ * `RECALL_LINE_CHARS` (300) each, plus at most `RECALL_TOWER_LIMIT` (3) Tower
+ * lines and the two block wrappers — call it 2,000 characters in the ordinary
+ * case. 250 puts eight bins across that range, which is enough resolution for
+ * a p50 to move visibly, and the open top bin catches a SessionStart profile
+ * block, which has no such limit and can be far larger.
+ */
+export declare const MEMORY_HOOK_CHARS_BIN_WIDTH = 250;
+export declare const MEMORY_HOOK_CHARS_BIN_COUNT = 41;
+/** A fresh all-zero character histogram. */
+export declare function blankCharsHistogram(): number[];
+/**
+ * The bin one sample falls in. Clamped at both ends rather than throwing: this
+ * runs inside a hook, and a counter must never be the thing that fails a
+ * person's turn. A negative or non-finite length is impossible from
+ * `stdout.length` and is floored at bin 0 if it ever happens.
+ */
+export declare function memoryHookCharsBin(chars: number): number;
+/**
+ * The nearest-rank percentile of a character histogram, as BIN BOUNDS.
+ *
+ * `null` when nothing was sampled — which is the honest answer for a machine
+ * whose hooks never printed, and is never rendered as a zero. The top bin is
+ * open, so its `upper` is `null` too: "10,000 or more" is what the data says
+ * and inventing a ceiling would be a claim nobody measured.
+ */
+export declare function memoryHookCharsPercentile(histogram: readonly number[], percentile: number): {
+    lower: number;
+    upper: number | null;
+} | null;
 /**
  * One hour of one event.
  *
@@ -49,6 +85,7 @@ export declare const MemoryHookCountsSchema: z.ZodObject<{
     via_direct: z.ZodOptional<z.ZodNumber>;
     skipped_trivial: z.ZodOptional<z.ZodNumber>;
     billing_exhausted: z.ZodOptional<z.ZodNumber>;
+    chars: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
 }, z.core.$strict>;
 export type MemoryHookCounts = z.infer<typeof MemoryHookCountsSchema>;
 /** `YYYY-MM-DDTHH` in UTC — the bucket key, and the reason the window is exact. */
@@ -70,6 +107,7 @@ export declare const MemoryHookStatsFileSchema: z.ZodObject<{
         via_direct: z.ZodOptional<z.ZodNumber>;
         skipped_trivial: z.ZodOptional<z.ZodNumber>;
         billing_exhausted: z.ZodOptional<z.ZodNumber>;
+        chars: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type MemoryHookStatsFile = z.infer<typeof MemoryHookStatsFileSchema>;
@@ -101,6 +139,16 @@ export interface MemoryHookWindow {
      * older runs to zero.
      */
     billingExhausted: number;
+    /**
+     * Ticket 3934: the CHARACTERS injected per recall, summed bin by bin over
+     * buckets that CARRY the field. `charsMeasured` is false when no bucket in
+     * the window recorded one — a machine on an older memory-mcp — so a reader
+     * says "not recorded" rather than printing a percentile of nothing.
+     */
+    chars: number[];
+    charsMeasured: boolean;
+    /** Runs that contributed a character sample. Never assumed equal to `printed`. */
+    charsSamples: number;
     /** Buckets that were inside the window and had something in them. */
     hours: number;
 }

package/dist/memory-hook-stats.js

@@ -29,6 +29,71 @@ export const MEMORY_HOOK_STATS_SCHEMA_VERSION = "memory-hook-stats.v1";
 export const MEMORY_HOOK_STATS_FILE_NAME = "memory-hook-stats.json";
 /** The three hook events, spelled as the bin's subcommands are. */
 export const MEMORY_HOOK_STAT_EVENTS = ["session-start", "prompt", "stop"];
+/**
+ * THE CHARACTER HISTOGRAM (ticket 3934).
+ *
+ * 250 characters a bin, 41 bins: `[0,250)`, … `[9750,10000)`, `[10000,∞)`.
+ *
+ * The width is chosen against what the hook can actually print, not against a
+ * round number: a recall is at most `RECALL_LIMIT` (5) memories truncated to
+ * `RECALL_LINE_CHARS` (300) each, plus at most `RECALL_TOWER_LIMIT` (3) Tower
+ * lines and the two block wrappers — call it 2,000 characters in the ordinary
+ * case. 250 puts eight bins across that range, which is enough resolution for
+ * a p50 to move visibly, and the open top bin catches a SessionStart profile
+ * block, which has no such limit and can be far larger.
+ */
+export const MEMORY_HOOK_CHARS_BIN_WIDTH = 250;
+export const MEMORY_HOOK_CHARS_BIN_COUNT = 41;
+/** A fresh all-zero character histogram. */
+export function blankCharsHistogram() {
+    return Array.from({ length: MEMORY_HOOK_CHARS_BIN_COUNT }, () => 0);
+}
+/**
+ * The bin one sample falls in. Clamped at both ends rather than throwing: this
+ * runs inside a hook, and a counter must never be the thing that fails a
+ * person's turn. A negative or non-finite length is impossible from
+ * `stdout.length` and is floored at bin 0 if it ever happens.
+ */
+export function memoryHookCharsBin(chars) {
+    // NaN has no size, so it goes in the smallest bin; a positive infinity is
+    // enormous and goes in the open top one. Collapsing both to bin 0 would file
+    // an impossibly large recall as the smallest thing on the machine.
+    if (Number.isNaN(chars) || chars <= 0)
+        return 0;
+    if (!Number.isFinite(chars))
+        return MEMORY_HOOK_CHARS_BIN_COUNT - 1;
+    return Math.min(Math.floor(chars / MEMORY_HOOK_CHARS_BIN_WIDTH), MEMORY_HOOK_CHARS_BIN_COUNT - 1);
+}
+/**
+ * The nearest-rank percentile of a character histogram, as BIN BOUNDS.
+ *
+ * `null` when nothing was sampled — which is the honest answer for a machine
+ * whose hooks never printed, and is never rendered as a zero. The top bin is
+ * open, so its `upper` is `null` too: "10,000 or more" is what the data says
+ * and inventing a ceiling would be a claim nobody measured.
+ */
+export function memoryHookCharsPercentile(histogram, percentile) {
+    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: index * MEMORY_HOOK_CHARS_BIN_WIDTH,
+                upper: index === MEMORY_HOOK_CHARS_BIN_COUNT - 1
+                    ? null
+                    : (index + 1) * MEMORY_HOOK_CHARS_BIN_WIDTH,
+            };
+        }
+    }
+    return null;
+}
 /**
  * One hour of one event.
  *
@@ -93,6 +158,28 @@ export const MemoryHookCountsSchema = z
      * `hook_stats_unrecognised_shape` overnight.
      */
     billing_exhausted: z.number().int().min(0).optional(),
+    /**
+     * HOW BIG WAS THE RECALL? (ticket 3934) — a counts-only histogram of the
+     * CHARACTERS the hook injected, one sample per run that printed a block.
+     *
+     * The timing histogram beside it (`memory-hook-performance.ts`) says how
+     * long a recall took. Nothing anywhere said how MUCH it put into a
+     * person's context, and that is the number behind two questions the fleet
+     * cannot otherwise answer: is the recall a line or a page, and is a slow
+     * turn slow because the door was slow or because the block was enormous.
+     *
+     * BINS, NEVER A LENGTH. A histogram of counts cannot leak a memory; a
+     * stored length could not either, but a bin is the smaller claim and the
+     * percentile is all any surface prints. The block's TEXT never comes near
+     * this file — see the header's prohibition, which this does not weaken.
+     *
+     * OPTIONAL, and it must stay optional. This schema is strict, a file
+     * written by an older memory-mcp has no such key, and a required field
+     * would make every existing machine's history `hook_stats_unrecognised_shape`
+     * overnight — the same rule `skipped_trivial` and `billing_exhausted` are
+     * kept under. Absent means NOT RECORDED, never "the recalls were empty".
+     */
+    chars: z.array(z.number().int().min(0)).length(MEMORY_HOOK_CHARS_BIN_COUNT).optional(),
 })
     .strict();
 /** `YYYY-MM-DDTHH` in UTC — the bucket key, and the reason the window is exact. */
@@ -125,6 +212,10 @@ export function emptyMemoryHookCounts() {
         skipped: 0,
         skipped_trivial: 0,
         billing_exhausted: 0,
+        // `chars` is deliberately NOT here (ticket 3934). An hour in which the
+        // hook ran and never printed has no recall to measure, and seeding 41
+        // zeroes into every event of every bucket would both bloat the file and
+        // make `charsMeasured` true for a machine that has measured nothing.
     };
 }
 /**
@@ -149,6 +240,9 @@ export function summariseMemoryHookWindow(file, event, options) {
         viaMeasured: false,
         skippedTrivial: 0,
         billingExhausted: 0,
+        chars: blankCharsHistogram(),
+        charsMeasured: false,
+        charsSamples: 0,
         hours: 0,
     };
     for (const [bucket, events] of Object.entries(file.buckets)) {
@@ -175,6 +269,16 @@ export function summariseMemoryHookWindow(file, event, options) {
         // which sums as zero and is honest — that machine genuinely had none it
         // could name.
         total.billingExhausted += counts.billing_exhausted ?? 0;
+        // Ticket 3934: summed only over buckets that CARRY the histogram, so a
+        // window spanning an upgrade reports what was measured rather than
+        // crediting the older hours with zero-length recalls.
+        if (counts.chars) {
+            total.charsMeasured = true;
+            for (let index = 0; index < total.chars.length; index += 1) {
+                total.chars[index] = (total.chars[index] ?? 0) + (counts.chars[index] ?? 0);
+                total.charsSamples += counts.chars[index] ?? 0;
+            }
+        }
         total.hours += 1;
     }
     return total;

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

@@ -117,6 +117,9 @@ export declare const MemoryInstallReceiptSchema: z.ZodObject<{
     hook_via_direct_24h: z.ZodOptional<z.ZodNumber>;
     hook_skipped_trivial_24h: z.ZodOptional<z.ZodNumber>;
     hook_billing_exhausted_24h: z.ZodOptional<z.ZodNumber>;
+    hook_chars_p50: z.ZodOptional<z.ZodNumber>;
+    hook_chars_p95: z.ZodOptional<z.ZodNumber>;
+    hook_chars_samples: 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">;

package/dist/memory-install-receipt.js

@@ -163,6 +163,23 @@ export const MemoryInstallReceiptSchema = z
      * Optional like the counts above — absent reads as "not reported".
      */
     hook_billing_exhausted_24h: z.number().int().min(0).optional(),
+    /**
+     * HOW BIG WAS A RECALL (ticket 3934) — the p50 and p95 CHARACTERS the
+     * prompt hook injected over the same 24 hours, as the lower bound of the
+     * bin each percentile fell in, with the number of runs behind them.
+     *
+     * The timing counters above say whether a recall ARRIVED. These say how
+     * much of a person's context it took when it did, which is the other half
+     * of "is the recall worth its budget" and had no surface anywhere.
+     *
+     * All three optional, and ABSENT on a machine whose memory-mcp is older
+     * than the histogram — which reads as "not recorded", never as "the
+     * recalls were empty". They are not derivable from the counts above and
+     * must never be inferred from them.
+     */
+    hook_chars_p50: z.number().int().min(0).optional(),
+    hook_chars_p95: z.number().int().min(0).optional(),
+    hook_chars_samples: 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. */

package/package.json

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