@camstack/types 1.2.115 → 1.2.116

package/dist/interfaces/addon.d.ts

@@ -1178,6 +1178,34 @@ export interface AddonExecution {
      * `0` means "no ceiling for this addon" and, being the maximum, lifts the whole runner's cap.
      */
     readonly maxOldSpaceMb?: number;
+    /**
+     * Whole-process RSS budget in MB — the number the memory watchdog alarms on.
+     *
+     * This is NOT a second heap ceiling and it enforces nothing: it is the
+     * footprint this addon's role considers legitimate, and crossing it emits one
+     * WARN carrying the breakdown (`heapUsed` / `external` / native residue) so the
+     * operator learns WHICH KIND of growth it is.
+     *
+     * It exists because every other bound is blind to most of a process.
+     * {@link AddonExecution.maxOldSpaceMb} bounds V8's old space and nothing else,
+     * and the watchdog's `stranded` metric subtracts `external` by construction.
+     * `hub/pipeline-analytics` was OOM-killed at 11.4GB on 2026-08-27 with a
+     * 1024MB old-space ceiling in force the entire time, holding a 536MB heap and
+     * 4264MB of `external` — 96% of the growth was never V8's, and nothing warned.
+     * RSS is what the host's OOM killer reads, so RSS is what needs a declared
+     * ceiling.
+     *
+     * OMITTED (the common case) → this addon declares no budget. If NO co-located
+     * addon declares one, the runner reports itself UNWATCHED once at boot; there
+     * is deliberately no class default, because the legitimate footprint differs by
+     * an order of magnitude by role (a recorder holding a 1.5GB segment index is
+     * behaving correctly; analytics holding 1.5GB is not). Declare it from a
+     * MEASURED peak RSS, never from a heap number.
+     *
+     * A runner's budget is the MAXIMUM declared by any co-located addon —
+     * co-location must never silence the hungriest member (D2/D29).
+     */
+    readonly rssBudgetMb?: number;
     /**
      * `@camstack/system` builtin ONLY: run this builtin in its OWN forked runner
      * instead of in-process on the hub root.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.115",
+  "version": "1.2.116",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",