@camstack/types 1.2.115 → 1.2.117

package/dist/process/child-cost-registry.d.ts

@@ -0,0 +1,105 @@
+import type { LoadContribution, LoadContributionAttribution, LoadContributionRole } from '../capabilities/load-contribution.cap.js';
+/** What a spawn site knows about the child it just started. */
+export interface ChildCostClaimInput {
+    readonly role: LoadContributionRole;
+    /**
+     * The NUMERIC device id, or `null` when this child genuinely serves no
+     * single camera. A spawn site that cannot name its camera should not claim
+     * at all: an unnamed per-camera claim is indistinguishable from a shared one
+     * and would turn one camera's cost into everybody's.
+     */
+    readonly deviceId: number | null;
+    /** What this one child is, in the contributor's own words: `615/high`. */
+    readonly unit: string;
+    /**
+     * Defaults to `measured` — the ordinary case for a child that serves exactly
+     * one camera. Set it explicitly for a shared resource that reports itself as
+     * unattributable.
+     */
+    readonly attribution?: LoadContributionAttribution;
+    /**
+     * The child's pid. `undefined` is accepted and the claim is then INERT: the
+     * cost cannot be measured and the entry would be a role and a camera with no
+     * numbers, which the unattributed bucket already covers more honestly.
+     */
+    readonly pid: number | undefined;
+}
+/** The only way to remove a claim. See the module docblock. */
+export interface ChildCostClaimHandle {
+    /** Idempotent: releasing twice, or after the registry was cleared, is safe. */
+    readonly release: () => void;
+}
+/**
+ * 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.
+ */
+export declare const NO_COST_CLAIM: ChildCostClaimHandle;
+/** Injectable procfs surface — the whole reason this module is testable. */
+export interface ProcStatReader {
+    /** `/proc/<pid>/stat` */
+    readonly readStat: (pid: number) => Promise<string>;
+    /** `/proc/<pid>/statm` */
+    readonly readStatm: (pid: number) => Promise<string>;
+}
+export declare const nodeProcStatReader: ProcStatReader;
+/**
+ * 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.
+ */
+export declare function parseProcCpuSeconds(line: string): number | null;
+/**
+ * Resident bytes from a `/proc/<pid>/statm` line — field 2 is the resident set
+ * in pages. `null` when the line does not parse.
+ */
+export declare function parseProcRssBytes(line: string): number | null;
+/**
+ * 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.
+ */
+export declare function readProcessCost(pid: number, reader?: ProcStatReader): Promise<{
+    readonly cpuSeconds?: number;
+    readonly rssBytes?: number;
+}>;
+export declare class ChildCostRegistry {
+    private readonly reader;
+    private readonly now;
+    private claims;
+    constructor(reader?: ProcStatReader, now?: () => number);
+    /**
+     * 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: ChildCostClaimInput): ChildCostClaimHandle;
+    /** Live claims, in claim order. Diagnostics and tests; not a contribution. */
+    list(): readonly ChildCostClaimInput[];
+    /**
+     * 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.
+     */
+    contributions(): Promise<readonly LoadContribution[]>;
+}

package/dist/{sleep-CSodb2vQ.js → sleep-9d8tJRbO.js}

@@ -1,4 +1,4 @@
-const require_event_category = require("./event-category-EY0GNjV9.js");
+const require_event_category = require("./event-category-BaEgqJNv.js");
 let zod = require("zod");
 //#region src/interfaces/config-ui.ts
 /** Predefined tabs with standard label, icon, and sort order.

package/dist/{sleep-CdbM8ge4.mjs → sleep-Dolp38qx.mjs}

@@ -1,4 +1,4 @@
-import { t as EventCategory } from "./event-category-CIa_iT6b.mjs";
+import { t as EventCategory } from "./event-category-BZL-fdNj.mjs";
 import { z } from "zod";
 //#region src/interfaces/config-ui.ts
 /** Predefined tabs with standard label, icon, and sort order.

package/package.json

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