@camstack/types 1.2.115 → 1.2.117

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/dist/interfaces/event-bus.d.ts

@@ -1172,7 +1172,7 @@ export interface EventCatalog {
     };
     /**
      * Periodic per-node process-tree snapshot (`NodeProcess[]` —
-     * camstack-related pids with ghost / managed / root classification).
+     * camstack-related pids with root / managed / system classification).
      * One event per node per tick. Replaces polling on
      * `metricsProvider.listNodeProcesses`.
      */

package/dist/interfaces/metrics-provider.d.ts

@@ -1,5 +1,5 @@
 import type { z } from 'zod';
-import type { CpuBreakdownSchema, MemoryInfoSchema, DiskIoSnapshotSchema, NetworkIoSnapshotSchema, MetricsGpuInfoSchema, ProcessResourceInfoSchema, PressureInfoSchema, SystemResourceSnapshotSchema, DiskSpaceInfoSchema, PidResourceStatsSchema, AddonInstanceSchema, NodeProcessSchema, KillProcessInputSchema, KillProcessResultSchema, DumpHeapSnapshotInputSchema, DumpHeapSnapshotResultSchema } from '../capabilities/metrics-provider.cap.js';
+import type { CpuBreakdownSchema, MemoryInfoSchema, DiskIoSnapshotSchema, NetworkIoSnapshotSchema, MetricsGpuInfoSchema, ProcessResourceInfoSchema, PressureInfoSchema, SystemResourceSnapshotSchema, DiskSpaceInfoSchema, PidResourceStatsSchema, AddonInstanceSchema, NodeProcessSchema, DumpHeapSnapshotInputSchema, DumpHeapSnapshotResultSchema, LoadPointSchema, LoadFunctionSeriesSchema, NodeLoadSeriesSchema, GetLoadSeriesInputSchema } from '../capabilities/metrics-provider.cap.js';
 export type CpuBreakdown = z.infer<typeof CpuBreakdownSchema>;
 export type MemoryInfo = z.infer<typeof MemoryInfoSchema>;
 export type DiskIoSnapshot = z.infer<typeof DiskIoSnapshotSchema>;
@@ -12,7 +12,9 @@ export type DiskSpaceInfo = z.infer<typeof DiskSpaceInfoSchema>;
 export type PidResourceStats = z.infer<typeof PidResourceStatsSchema>;
 export type AddonInstance = z.infer<typeof AddonInstanceSchema>;
 export type NodeProcess = z.infer<typeof NodeProcessSchema>;
-export type KillProcessInput = z.infer<typeof KillProcessInputSchema>;
-export type KillProcessResult = z.infer<typeof KillProcessResultSchema>;
 export type DumpHeapSnapshotInput = z.infer<typeof DumpHeapSnapshotInputSchema>;
 export type DumpHeapSnapshotResult = z.infer<typeof DumpHeapSnapshotResultSchema>;
+export type LoadSeriesPoint = z.infer<typeof LoadPointSchema>;
+export type LoadFunctionSeries = z.infer<typeof LoadFunctionSeriesSchema>;
+export type NodeLoadSeries = z.infer<typeof NodeLoadSeriesSchema>;
+export type GetLoadSeriesInput = z.infer<typeof GetLoadSeriesInputSchema>;

package/dist/metrics/load-series-fold.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Folding a process snapshot into per-FUNCTION load points, and reducing a
+ * long series to a drawable number of them WITHOUT losing a peak.
+ *
+ * ## Why this lives in `@camstack/types`
+ *
+ * Two processes need the identical arithmetic and neither may import the
+ * other: the hub's `native-metrics` folds the retained series before it leaves
+ * the node (server-side reduction — the browser must never be handed 2 160
+ * points per series to throw away), and the admin UI folds the LIVE
+ * `metrics.node-processes-snapshot` events it is already subscribed to. Two
+ * copies of a fold is two charts that disagree about the same node.
+ *
+ * Browser-safe by construction: no imports at all, so it stays on the root
+ * `@camstack/types` entry (the node-only surface is `@camstack/types/node`).
+ *
+ * ## The reduction, and why min/max rather than a mean
+ *
+ * Six hours at the 10 s cadence is 2 160 points per series. A chart a few
+ * hundred pixels wide has to reduce them, and the reduction is exactly where a
+ * chart lies:
+ *
+ * - a **mean per bucket** smears the peak across the bucket and it disappears;
+ * - **one sample every N** skips the peak outright.
+ *
+ * Either way the tool built to find peaks stops showing peaks. So a bucket
+ * carries `min`, `max` and the number of samples that landed in it, and the
+ * REPRESENTATIVE value of a bucket — the field the chart already reads — is
+ * the **max**. A mean is still derivable where it is wanted; a lost peak is
+ * not recoverable from anything.
+ *
+ * An unreduced series is a series of one-sample buckets, where `min === max`
+ * and every field equals the raw value. Reduced and unreduced are therefore
+ * the same shape, and the caller cannot tell which it is looking at — which is
+ * the whole reason there is one reader.
+ *
+ * ## An empty bucket stays empty
+ *
+ * A bucket with no samples is ABSENT from the output. It is never emitted with
+ * zeros, never interpolated, and never carried forward from the previous
+ * point. Emission is fixed-cadence, so a gap means one thing only: **nobody
+ * reported**. Filling it would destroy the single property that fixed cadence
+ * was adopted to buy.
+ */
+/**
+ * One process row as both tiers carry it.
+ *
+ * Deliberately NOT the full `NodeProcess`. `command` is absent because it is
+ * the fattest field in a snapshot and the same identical string on every
+ * runner — the runner id travels in the environment, not in argv — while
+ * `addonId` is the short identifier that already names the process. Nothing
+ * that draws or reduces this series has ever read `command`.
+ */
+export interface LoadProcessRow {
+    readonly pid: number;
+    readonly addonId: string | null;
+    readonly classification: string;
+    /** `ps pcpu` — a LIFETIME average, not a rate. Always present. */
+    readonly cpuPercent: number;
+    readonly memoryRssBytes: number;
+    /** Instantaneous main-thread CPU%, or `null` when unknown — never zero. */
+    readonly cpuMainPercent: number | null;
+    /** Instantaneous V8-helper-pool CPU%, or `null` under the same rule. */
+    readonly cpuGcPercent: number | null;
+}
+/**
+ * The bucket a process is attributed to.
+ *
+ * `addon` is the only attributed kind. `root` is the node's own supervisor and
+ * `unattributed` is everything the cluster cannot name. They are separate
+ * buckets rather than folded into a nearby addon precisely because nothing
+ * licenses attributing them.
+ */
+export type LoadBucketKind = 'addon' | 'root' | 'unattributed';
+/** Bucket key for rows no addon owns. Stable, so its series is continuous. */
+export declare const UNATTRIBUTED_BUCKET_KEY = "__unattributed__";
+export declare const ROOT_BUCKET_KEY = "__root__";
+/**
+ * One point of one function's series.
+ *
+ * The unsuffixed fields are the bucket's **maximum** — the peak-preserving
+ * representative. `...Min` carries the other end so a caller can draw a band,
+ * and `samples` says how many raw snapshots the bucket folded. For an
+ * unreduced series `samples === 1` and each `...Min` equals its unsuffixed
+ * twin.
+ */
+export interface LoadPoint {
+    /** Bucket START, or the snapshot's own timestamp when unreduced. */
+    readonly atMs: number;
+    /** Raw snapshots folded into this point. Never 0 — an empty bucket is absent. */
+    readonly samples: number;
+    /**
+     * Instantaneous CPU% of the function's own threads, or `null`.
+     *
+     * `null` PROPAGATES: a bucket is `null` unless every process in every
+     * snapshot it covers reported a split. Summing only the processes that
+     * answered produces a smaller number that is indistinguishable, on a chart,
+     * from a complete one — the exact failure this surface exists to prevent.
+     */
+    readonly cpuMainPercent: number | null;
+    readonly cpuMainPercentMin: number | null;
+    readonly cpuGcPercent: number | null;
+    readonly cpuGcPercentMin: number | null;
+    /** Lifetime-average CPU%, summed. Always known — and never a rate. */
+    readonly cpuLifetimePercent: number;
+    readonly cpuLifetimePercentMin: number;
+    readonly memoryRssBytes: number;
+    readonly memoryRssBytesMin: number;
+    readonly processCount: number;
+    readonly processCountMin: number;
+}
+export interface LoadBucket {
+    readonly key: string;
+    readonly kind: LoadBucketKind;
+    readonly point: LoadPoint;
+}
+/**
+ * Fold one snapshot into one point per function.
+ *
+ * Produces a ONE-SAMPLE point: `min === max` on every field, `samples === 1`.
+ * That is what lets a live event and a reduced server bucket sit in the same
+ * series without the consumer knowing which is which.
+ */
+export declare function foldSnapshotByFunction(rows: readonly LoadProcessRow[], atMs: number): readonly LoadBucket[];
+/**
+ * The bucket width that brings `spanMs` down to at most `maxPoints` points,
+ * snapped up to a whole multiple of the sampling cadence.
+ *
+ * Returns `cadenceMs` (no reduction) when the span already fits. A caller that
+ * asks for a `maxPoints` of 0 or less gets no reduction rather than an
+ * infinite bucket — a nonsensical request must not produce a plausible chart.
+ */
+export declare function resolveBucketMs(spanMs: number, cadenceMs: number, maxPoints: number): number;
+/**
+ * Reduce one function's points into buckets of `bucketMs`, preserving the
+ * extremes.
+ *
+ * Points are expected oldest-first and are returned oldest-first. A bucket
+ * with no samples is ABSENT — not zero, not interpolated, not the previous
+ * value held over.
+ */
+export declare function reducePoints(points: readonly LoadPoint[], bucketMs: number, origin: number): readonly LoadPoint[];

package/dist/node.d.ts

@@ -2,6 +2,8 @@ export { ensureBinary, downloadBinary, findInPath, getPlatformInfo, buildBinaryP
 export type { PlatformInfo } from './deps/binary-downloader.js';
 export { ensureFfmpeg, getFfmpegDownloadUrl } from './deps/ffmpeg-downloader.js';
 export { ensurePython, installPythonPackages, installPythonRequirements, getPythonDownloadUrl, PYTHON_VERSION, } from './deps/python-downloader.js';
+export { ChildCostRegistry, NO_COST_CLAIM, nodeProcStatReader, parseProcCpuSeconds, parseProcRssBytes, readProcessCost, } from './process/child-cost-registry.js';
+export type { ChildCostClaimHandle, ChildCostClaimInput, ProcStatReader, } from './process/child-cost-registry.js';
 export { FilesystemStorageProvider } from './storage/filesystem-storage-provider.js';
 export { canonicalHash } from './utils/canonical-hash.js';
 export { signExpiringUrl, verifyExpiringUrl } from './utils/expiring-url-signature.js';

package/dist/node.js

@@ -31,6 +31,7 @@ node_path = __toESM(node_path);
 let node_stream_promises = require("node:stream/promises");
 let node_stream = require("node:stream");
 let node_child_process = require("node:child_process");
+let node_fs_promises = require("node:fs/promises");
 //#region src/deps/binary-downloader.ts
 /**
 * Recursively find the first file named exactly `name` under `dir`. Used as the
@@ -457,6 +458,190 @@ async function installPythonRequirements(pythonPath, requirementsFile, logger) {
 	} });
 }
 //#endregion
+//#region src/process/child-cost-registry.ts
+/**
+* The registry an addon claims its OWN child processes in — the spawn-site
+* half of `load-contribution.cap.ts`.
+*
+* ## Where a claim is made, and where it is released
+*
+* At the spawn site, and nowhere else. It is the only place that knows both
+* halves: the recorder's controller knows it is starting ffmpeg for camera 615
+* profile `high`; the decode coordinator knows the session it is forking a
+* worker for. Nothing has to deduce it afterwards, and no entity needs a
+* global list of which pid belongs to which camera.
+*
+* {@link ChildCostRegistry.claim} returns a HANDLE, and the handle is the only
+* way to release. That is not decoration: the alternative — `release(pid)` —
+* lets a late release from a dead generation delete the live claim of a
+* process that inherited the same pid, which is precisely how a per-camera
+* chart charges one camera for another camera's work. A handle can only ever
+* remove the entry it created.
+*
+* ## What the registry does NOT do
+*
+* It keeps no history, no counters and no timers. It holds live claims and
+* answers questions about them; when the process holding it dies, every claim
+* in it dies with it, which is correct — those children were its children.
+*
+* ## The numbers
+*
+* {@link ChildCostRegistry.contributions} reads each claimed child's
+* CUMULATIVE CPU seconds and resident bytes out of `/proc/<pid>` at the moment
+* it is asked. On demand, never on a timer: a new periodic per-node sampler is
+* the defect half of `docs/architecture/load-ledger.md` documents. A counter
+* can be differenced by whoever already keeps a history; a rate cannot be
+* un-averaged.
+*
+* Where `/proc` does not exist (macOS, Windows) or the read fails, the numbers
+* are ABSENT — never zero. Zero would say the camera cost nothing.
+*/
+/**
+* Kernel jiffies per second (`USER_HZ`). Same constant, same reasoning, as
+* `packages/system/src/builtins/native-metrics/thread-cpu-sampler.ts`:
+* `sysconf(_SC_CLK_TCK)` is not exposed to Node and this has been 100 on every
+* kernel configuration we ship to. A wrong value would scale every CPU number
+* by a constant — visible immediately, not a silent skew.
+*/
+var CLOCK_TICKS_PER_SEC = 100;
+/** Bytes per page, for `/proc/<pid>/statm`'s page counts. */
+var PAGE_BYTES = 4096;
+/**
+* The handle a spawn site gets when nobody is collecting — a test harness, or
+* a runner built before its addon registered a registry. Reporting nothing is
+* the correct behaviour: the process still appears in the node's process
+* snapshot, unclaimed, which is exactly what "nobody reported this" should
+* look like.
+*/
+var NO_COST_CLAIM = { release: () => void 0 };
+var nodeProcStatReader = {
+	readStat: (pid) => (0, node_fs_promises.readFile)(`/proc/${pid}/stat`, "utf8"),
+	readStatm: (pid) => (0, node_fs_promises.readFile)(`/proc/${pid}/statm`, "utf8")
+};
+/**
+* Cumulative CPU seconds from a `/proc/<pid>/stat` line.
+*
+* The `comm` field is field 2, wrapped in parentheses, and can itself contain
+* spaces and parentheses — so the only correct parse cuts at the LAST `)` and
+* indexes from there. After the cut, field 3 (`state`) is index 0, so `utime`
+* (field 14) is index 11 and `stime` (field 15) is index 12.
+*
+* `null` for a line that does not parse: a process that exited between the
+* claim and the read leaves a truncated or empty file, and that is normal.
+*/
+function parseProcCpuSeconds(line) {
+	const close = line.lastIndexOf(")");
+	if (close < 0) return null;
+	const rest = line.slice(close + 1).trim().split(/\s+/);
+	const utime = Number(rest[11]);
+	const stime = Number(rest[12]);
+	if (!Number.isFinite(utime) || !Number.isFinite(stime)) return null;
+	return (utime + stime) / CLOCK_TICKS_PER_SEC;
+}
+/**
+* Resident bytes from a `/proc/<pid>/statm` line — field 2 is the resident set
+* in pages. `null` when the line does not parse.
+*/
+function parseProcRssBytes(line) {
+	const fields = line.trim().split(/\s+/);
+	const residentPages = Number(fields[1]);
+	if (!Number.isFinite(residentPages)) return null;
+	return residentPages * PAGE_BYTES;
+}
+/**
+* What the OS will say about one process right now: cumulative CPU seconds and
+* resident bytes, each ABSENT when it cannot be read.
+*
+* Exported because not every cost has a spawn site inside a registry. The
+* shared inference pool is the case that forced it: its process is created
+* deep inside the engine factory and belongs to no camera, so it is reported
+* as an `unattributable` contribution built from the live pool's pids rather
+* than from a claim — but its numbers must be read the same way, by the same
+* parsers, or two "CPU seconds" in one payload would mean two things.
+*/
+async function readProcessCost(pid, reader = nodeProcStatReader) {
+	let cpuSeconds = null;
+	let rssBytes = null;
+	try {
+		cpuSeconds = parseProcCpuSeconds(await reader.readStat(pid));
+	} catch {
+		cpuSeconds = null;
+	}
+	try {
+		rssBytes = parseProcRssBytes(await reader.readStatm(pid));
+	} catch {
+		rssBytes = null;
+	}
+	return {
+		...cpuSeconds === null ? {} : { cpuSeconds },
+		...rssBytes === null ? {} : { rssBytes }
+	};
+}
+var ChildCostRegistry = class {
+	reader;
+	now;
+	claims = /* @__PURE__ */ new Map();
+	constructor(reader = nodeProcStatReader, now = Date.now) {
+		this.reader = reader;
+		this.now = now;
+	}
+	/**
+	* Record one child. The returned handle is the only way to remove it.
+	*
+	* A claim with no pid is dropped rather than stored: it could carry no
+	* measurement, and an entry with a camera and no numbers reads on a chart as
+	* a camera that cost nothing.
+	*/
+	claim(input) {
+		const pid = input.pid;
+		if (pid === void 0 || !Number.isInteger(pid) || pid <= 0) return NO_COST_CLAIM;
+		const key = Symbol("child-cost-claim");
+		this.claims.set(key, {
+			role: input.role,
+			deviceId: input.deviceId,
+			unit: input.unit,
+			attribution: input.attribution ?? "measured",
+			pid,
+			startedAtMs: this.now()
+		});
+		return { release: () => {
+			this.claims.delete(key);
+		} };
+	}
+	/** Live claims, in claim order. Diagnostics and tests; not a contribution. */
+	list() {
+		return [...this.claims.values()].map((c) => ({
+			role: c.role,
+			deviceId: c.deviceId,
+			unit: c.unit,
+			attribution: c.attribution,
+			pid: c.pid
+		}));
+	}
+	/**
+	* This addon's contribution: one entry per live claim, with whatever the OS
+	* will tell us about that child right now.
+	*
+	* A child that has exited between the claim and this read contributes an
+	* entry with no numbers rather than no entry — the unit exists, the addon
+	* believes it is running, and hiding it would make a dying writer look like
+	* a writer that was never started.
+	*/
+	async contributions() {
+		const out = [];
+		for (const claim of this.claims.values()) out.push({
+			role: claim.role,
+			deviceId: claim.deviceId,
+			attribution: claim.attribution,
+			unit: claim.unit,
+			pid: claim.pid,
+			startedAtMs: claim.startedAtMs,
+			...await readProcessCost(claim.pid, this.reader)
+		});
+		return out;
+	}
+};
+//#endregion
 //#region src/storage/filesystem-storage-provider.ts
 var STORAGE_LOCATION_TYPES = [
 	"data",
@@ -1481,10 +1666,12 @@ var Fmp4FragmentChild = class {
 	}
 };
 //#endregion
+exports.ChildCostRegistry = ChildCostRegistry;
 exports.FfmpegProcess = FfmpegProcess;
 exports.FilesystemStorageProvider = FilesystemStorageProvider;
 exports.Fmp4FragmentChild = Fmp4FragmentChild;
 exports.Fmp4FragmentPlane = Fmp4FragmentPlane;
+exports.NO_COST_CLAIM = NO_COST_CLAIM;
 exports.PYTHON_VERSION = PYTHON_VERSION;
 exports.buildBinaryPath = buildBinaryPath;
 exports.canonicalDeviceFingerprint = canonicalDeviceFingerprint;
@@ -1500,6 +1687,10 @@ exports.getPlatformInfo = getPlatformInfo;
 exports.getPythonDownloadUrl = getPythonDownloadUrl;
 exports.installPythonPackages = installPythonPackages;
 exports.installPythonRequirements = installPythonRequirements;
+exports.nodeProcStatReader = nodeProcStatReader;
+exports.parseProcCpuSeconds = parseProcCpuSeconds;
+exports.parseProcRssBytes = parseProcRssBytes;
+exports.readProcessCost = readProcessCost;
 exports.resolveExportFingerprint = resolveExportFingerprint;
 exports.signExpiringUrl = signExpiringUrl;
 exports.verifyExpiringUrl = verifyExpiringUrl;

package/dist/node.mjs

@@ -8,6 +8,7 @@ import { basename, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { execFileSync, spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
 //#region src/deps/binary-downloader.ts
 /**
 * Recursively find the first file named exactly `name` under `dir`. Used as the
@@ -434,6 +435,190 @@ async function installPythonRequirements(pythonPath, requirementsFile, logger) {
 	} });
 }
 //#endregion
+//#region src/process/child-cost-registry.ts
+/**
+* The registry an addon claims its OWN child processes in — the spawn-site
+* half of `load-contribution.cap.ts`.
+*
+* ## Where a claim is made, and where it is released
+*
+* At the spawn site, and nowhere else. It is the only place that knows both
+* halves: the recorder's controller knows it is starting ffmpeg for camera 615
+* profile `high`; the decode coordinator knows the session it is forking a
+* worker for. Nothing has to deduce it afterwards, and no entity needs a
+* global list of which pid belongs to which camera.
+*
+* {@link ChildCostRegistry.claim} returns a HANDLE, and the handle is the only
+* way to release. That is not decoration: the alternative — `release(pid)` —
+* lets a late release from a dead generation delete the live claim of a
+* process that inherited the same pid, which is precisely how a per-camera
+* chart charges one camera for another camera's work. A handle can only ever
+* remove the entry it created.
+*
+* ## What the registry does NOT do
+*
+* It keeps no history, no counters and no timers. It holds live claims and
+* answers questions about them; when the process holding it dies, every claim
+* in it dies with it, which is correct — those children were its children.
+*
+* ## The numbers
+*
+* {@link ChildCostRegistry.contributions} reads each claimed child's
+* CUMULATIVE CPU seconds and resident bytes out of `/proc/<pid>` at the moment
+* it is asked. On demand, never on a timer: a new periodic per-node sampler is
+* the defect half of `docs/architecture/load-ledger.md` documents. A counter
+* can be differenced by whoever already keeps a history; a rate cannot be
+* un-averaged.
+*
+* Where `/proc` does not exist (macOS, Windows) or the read fails, the numbers
+* are ABSENT — never zero. Zero would say the camera cost nothing.
+*/
+/**
+* Kernel jiffies per second (`USER_HZ`). Same constant, same reasoning, as
+* `packages/system/src/builtins/native-metrics/thread-cpu-sampler.ts`:
+* `sysconf(_SC_CLK_TCK)` is not exposed to Node and this has been 100 on every
+* kernel configuration we ship to. A wrong value would scale every CPU number
+* by a constant — visible immediately, not a silent skew.
+*/
+var CLOCK_TICKS_PER_SEC = 100;
+/** Bytes per page, for `/proc/<pid>/statm`'s page counts. */
+var PAGE_BYTES = 4096;
+/**
+* The handle a spawn site gets when nobody is collecting — a test harness, or
+* a runner built before its addon registered a registry. Reporting nothing is
+* the correct behaviour: the process still appears in the node's process
+* snapshot, unclaimed, which is exactly what "nobody reported this" should
+* look like.
+*/
+var NO_COST_CLAIM = { release: () => void 0 };
+var nodeProcStatReader = {
+	readStat: (pid) => readFile(`/proc/${pid}/stat`, "utf8"),
+	readStatm: (pid) => readFile(`/proc/${pid}/statm`, "utf8")
+};
+/**
+* Cumulative CPU seconds from a `/proc/<pid>/stat` line.
+*
+* The `comm` field is field 2, wrapped in parentheses, and can itself contain
+* spaces and parentheses — so the only correct parse cuts at the LAST `)` and
+* indexes from there. After the cut, field 3 (`state`) is index 0, so `utime`
+* (field 14) is index 11 and `stime` (field 15) is index 12.
+*
+* `null` for a line that does not parse: a process that exited between the
+* claim and the read leaves a truncated or empty file, and that is normal.
+*/
+function parseProcCpuSeconds(line) {
+	const close = line.lastIndexOf(")");
+	if (close < 0) return null;
+	const rest = line.slice(close + 1).trim().split(/\s+/);
+	const utime = Number(rest[11]);
+	const stime = Number(rest[12]);
+	if (!Number.isFinite(utime) || !Number.isFinite(stime)) return null;
+	return (utime + stime) / CLOCK_TICKS_PER_SEC;
+}
+/**
+* Resident bytes from a `/proc/<pid>/statm` line — field 2 is the resident set
+* in pages. `null` when the line does not parse.
+*/
+function parseProcRssBytes(line) {
+	const fields = line.trim().split(/\s+/);
+	const residentPages = Number(fields[1]);
+	if (!Number.isFinite(residentPages)) return null;
+	return residentPages * PAGE_BYTES;
+}
+/**
+* What the OS will say about one process right now: cumulative CPU seconds and
+* resident bytes, each ABSENT when it cannot be read.
+*
+* Exported because not every cost has a spawn site inside a registry. The
+* shared inference pool is the case that forced it: its process is created
+* deep inside the engine factory and belongs to no camera, so it is reported
+* as an `unattributable` contribution built from the live pool's pids rather
+* than from a claim — but its numbers must be read the same way, by the same
+* parsers, or two "CPU seconds" in one payload would mean two things.
+*/
+async function readProcessCost(pid, reader = nodeProcStatReader) {
+	let cpuSeconds = null;
+	let rssBytes = null;
+	try {
+		cpuSeconds = parseProcCpuSeconds(await reader.readStat(pid));
+	} catch {
+		cpuSeconds = null;
+	}
+	try {
+		rssBytes = parseProcRssBytes(await reader.readStatm(pid));
+	} catch {
+		rssBytes = null;
+	}
+	return {
+		...cpuSeconds === null ? {} : { cpuSeconds },
+		...rssBytes === null ? {} : { rssBytes }
+	};
+}
+var ChildCostRegistry = class {
+	reader;
+	now;
+	claims = /* @__PURE__ */ new Map();
+	constructor(reader = nodeProcStatReader, now = Date.now) {
+		this.reader = reader;
+		this.now = now;
+	}
+	/**
+	* Record one child. The returned handle is the only way to remove it.
+	*
+	* A claim with no pid is dropped rather than stored: it could carry no
+	* measurement, and an entry with a camera and no numbers reads on a chart as
+	* a camera that cost nothing.
+	*/
+	claim(input) {
+		const pid = input.pid;
+		if (pid === void 0 || !Number.isInteger(pid) || pid <= 0) return NO_COST_CLAIM;
+		const key = Symbol("child-cost-claim");
+		this.claims.set(key, {
+			role: input.role,
+			deviceId: input.deviceId,
+			unit: input.unit,
+			attribution: input.attribution ?? "measured",
+			pid,
+			startedAtMs: this.now()
+		});
+		return { release: () => {
+			this.claims.delete(key);
+		} };
+	}
+	/** Live claims, in claim order. Diagnostics and tests; not a contribution. */
+	list() {
+		return [...this.claims.values()].map((c) => ({
+			role: c.role,
+			deviceId: c.deviceId,
+			unit: c.unit,
+			attribution: c.attribution,
+			pid: c.pid
+		}));
+	}
+	/**
+	* This addon's contribution: one entry per live claim, with whatever the OS
+	* will tell us about that child right now.
+	*
+	* A child that has exited between the claim and this read contributes an
+	* entry with no numbers rather than no entry — the unit exists, the addon
+	* believes it is running, and hiding it would make a dying writer look like
+	* a writer that was never started.
+	*/
+	async contributions() {
+		const out = [];
+		for (const claim of this.claims.values()) out.push({
+			role: claim.role,
+			deviceId: claim.deviceId,
+			attribution: claim.attribution,
+			unit: claim.unit,
+			pid: claim.pid,
+			startedAtMs: claim.startedAtMs,
+			...await readProcessCost(claim.pid, this.reader)
+		});
+		return out;
+	}
+};
+//#endregion
 //#region src/storage/filesystem-storage-provider.ts
 var STORAGE_LOCATION_TYPES = [
 	"data",
@@ -1458,4 +1643,4 @@ var Fmp4FragmentChild = class {
 	}
 };
 //#endregion
-export { FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, resolveExportFingerprint, signExpiringUrl, verifyExpiringUrl };
+export { ChildCostRegistry, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, nodeProcStatReader, parseProcCpuSeconds, parseProcRssBytes, readProcessCost, resolveExportFingerprint, signExpiringUrl, verifyExpiringUrl };