@camstack/system 1.2.102 → 1.2.103

package/dist/logging/partitioned-log-buffer.d.ts

@@ -1,14 +1,52 @@
 import { LogEntry, LogFilter, LogLevel } from '@camstack/types';
+/**
+ * Default ceiling on retained entries across every bucket.
+ *
+ * This used to be `null` — no aggregate bound at all — and the only thing
+ * holding hub-main's log memory was `perAddonCapacity x buckets`, a product
+ * that grows with the roster. Measured on the live cluster: 37 forked runners
+ * on the hub plus its in-process builtins, and hub-main additionally ingests
+ * every line from both agents, so ~60 buckets is the ordinary case and
+ * 60 x 5000 = 300k retained entries.
+ *
+ * A realistic entry (timestamp, level, scope, ~70-char message, three tags, no
+ * `meta`) measures **~306 B retained** in V8. So the old unbounded case is
+ * ~92MB of a hub process that is being asked to fit inside a cgroup with a
+ * neighbour to protect, and 50_000 is **~15MB**.
+ *
+ * 50_000 across a ~60-bucket roster is ~830 entries per addon on average while
+ * still letting a single chatty addon hold its full 5000-entry ring — the
+ * partitioning is not weakened, only the total is held.
+ */
+export declare const DEFAULT_MAX_TOTAL_LOG_ENTRIES = 50000;
+/**
+ * Default ceiling on the NUMBER of buckets.
+ *
+ * Buckets were created on first write and never removed, so every addon id
+ * that ever logged — a removed addon, a renamed one, a one-off worker id —
+ * kept a ring alive for the life of the process. {@link DEFAULT_MAX_TOTAL_LOG_ENTRIES}
+ * alone does not fix that: the total sweep may only discard entries at or below
+ * `pruneLevel`, so a dead addon's 5000 `info` lines are untouchable by it.
+ *
+ * 128 is ~2x the ~60-bucket live roster, so no real deployment ever evicts on
+ * bucket count alone; it exists to make an unbounded id space impossible.
+ */
+export declare const DEFAULT_MAX_LOG_BUCKETS = 128;
 export interface PartitionedLogBufferOptions {
     /** Hard ring size for EACH addon's bucket. */
     readonly perAddonCapacity?: number;
     /**
-     * Soft ceiling on entries across all buckets. `null` (the default) means the
-     * only bound is the per-addon rings.
+     * Soft ceiling on entries across all buckets. `null` means the only bound is
+     * the per-addon rings. Defaults to {@link DEFAULT_MAX_TOTAL_LOG_ENTRIES}.
      */
     readonly maxTotalEntries?: number | null;
     /** Highest severity the total-cap sweep may discard. Default `debug`. */
     readonly pruneLevel?: LogLevel;
+    /**
+     * Hard ceiling on the number of buckets. `null` means unbounded. Defaults to
+     * {@link DEFAULT_MAX_LOG_BUCKETS}.
+     */
+    readonly maxBuckets?: number | null;
 }
 /**
  * A log buffer partitioned into one fixed-capacity {@link LogRingBuffer} per
@@ -19,32 +57,48 @@ export interface PartitionedLogBufferOptions {
  * Drop-in for {@link LogRingBuffer} from {@link LogManager}'s perspective —
  * exposes the same `push` / `getAll` / `query` / `clear` surface.
  *
- * ## Two bounds, doing different jobs
+ * ## Three bounds, doing different jobs
  *
  * **`perAddonCapacity`** is a HARD bound: each bucket is a fixed-size ring, so
  * total memory can never exceed `perAddonCapacity × buckets` whatever else
  * happens. This is the safety net.
  *
- * **`maxTotalEntries`** is a SOFT target across all buckets, and it exists because
- * the hard bound scales with addon count — 70 addons × 5000 is a lot of retained
- * entries on a small box. When the total is exceeded, the sweep discards only
- * entries at or below `pruneLevel` (default `debug`), oldest first, from the
+ * **`maxTotalEntries`** targets the total across all buckets, and it exists because
+ * the hard bound scales with addon count — 60 buckets × 5000 was 300k retained
+ * entries on the live hub. When the total is exceeded, the sweep first discards
+ * only entries at or below `pruneLevel` (default `debug`), oldest first, from the
  * largest buckets first.
  *
- * It is deliberately soft. Meeting a total cap by discarding `warn` and `error`
- * would trade the entries that explain an incident for entries about frame
- * timings; if pruning every prunable entry still leaves the total above the cap,
- * the buffer stays above it and the hard per-bucket bound is what holds. A cap
- * that can evict an error is not a feature.
+ * It is deliberately soft ON A LIVE BUCKET. Meeting a total cap by discarding
+ * `warn` and `error` from an addon that is still logging would trade the entries
+ * that explain an incident for entries about frame timings. A cap that can evict
+ * a live addon's error is not a feature.
  *
  * Largest-bucket-first because the noisy addon is the one creating the pressure —
  * the same principle that motivated partitioning in the first place.
+ *
+ * **`maxBuckets`, and bucket eviction, are the hard backstop.** Pruning alone
+ * cannot bound this structure: it may only discard at or below `pruneLevel`, so
+ * a bucket full of `info` from an addon that no longer exists was immortal, and
+ * the roster the product scales with is not fixed. When pruning cannot reach the
+ * target — or the bucket count exceeds `maxBuckets` — whole buckets are dropped
+ * **least-recently-WRITTEN first**, and never the bucket currently being written
+ * to. That is precisely the dead addon's bucket, and it is precisely not the
+ * bucket of the addon whose incident is in progress.
  */
 export declare class PartitionedLogBuffer {
     private readonly buffers;
+    /**
+     * Bucket key → the write ordinal of its last `push`. A monotonic counter, not
+     * a clock: eviction order must follow the order writes actually happened, and
+     * a wall clock that steps backwards would pick the wrong victim.
+     */
+    private readonly lastWriteSeq;
+    private writeSeq;
     private perAddonCapacity;
     private maxTotalEntries;
     private pruneLevel;
+    private maxBuckets;
     /** Running total, so `push` does not walk every bucket to decide. */
     private totalEntries;
     constructor(perAddonCapacity?: number, options?: PartitionedLogBufferOptions);
@@ -59,18 +113,40 @@ export declare class PartitionedLogBuffer {
         readonly perAddonCapacity?: number;
         readonly maxTotalEntries?: number | null;
         readonly pruneLevel?: LogLevel;
+        readonly maxBuckets?: number | null;
     }): void;
     private bufferFor;
     push(entry: LogEntry): void;
     /**
-     * Bring the total down to `PRUNE_TARGET_RATIO × cap` by discarding prunable
-     * entries, largest bucket first. Stops early when nothing prunable is left —
-     * see the class docblock on why that is the correct outcome rather than a
-     * failure to enforce.
+     * Bring the total down to `PRUNE_TARGET_RATIO × cap`.
+     *
+     * Two passes, in this order and no other: first discard prunable entries,
+     * largest bucket first, which is free of information cost. Only if that
+     * cannot reach the target does the second pass drop WHOLE buckets,
+     * least-recently-written first — the bound has to hold even when every
+     * retained entry is above `pruneLevel`, and a bucket nobody has written to is
+     * the cheapest thing in the structure to lose.
      */
     private enforceTotalCap;
+    /**
+     * Drop whole buckets, least-recently-WRITTEN first, until the total is at or
+     * below `target`. Never touches `protectedKey` (the bucket being written to
+     * right now) and always leaves at least one bucket standing.
+     */
+    private evictBucketsUntil;
+    /** Drop exactly `count` buckets, least-recently-written first. */
+    private evictBuckets;
+    /** Bucket keys ordered least-recently-written first, excluding `protectedKey`.
+     *  A bucket with no recorded write sorts first — it can only be a leftover. */
+    private evictionOrder;
+    /** Remove a bucket and everything that indexes it. An empty ring left behind
+     *  is the leak this class shipped with — the map only ever grew. */
+    private dropBucket;
     /** Entries retained across every bucket. */
     size(): number;
+    /** Buckets currently retained. Observability for the aggregate bound — an
+     *  addon roster that only ever grows is what this class had to stop doing. */
+    bucketCount(): number;
     /** Every retained entry across all buckets, newest-first (mirrors
      *  {@link LogRingBuffer.getAll}). Used to replay history to a destination. */
     getAll(): LogEntry[];
@@ -83,6 +159,9 @@ export declare class PartitionedLogBuffer {
      */
     query(filter: LogFilter): LogEntry[];
     clear(filter?: LogFilter): number;
+    /** An emptied bucket is removed rather than left as an empty ring: the map
+     *  used to grow with every addon id that ever logged and never shrink. */
+    private dropIfEmpty;
     /** The bucket key a filter pins to via `tags.addonId`, or null when the
      *  filter doesn't constrain the addon (→ scan all buckets). */
     private pinnedAddonKey;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.102",
+  "version": "1.2.103",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",