@dexcost/sdk 0.2.0

package/dist/core/models.js

@@ -0,0 +1,226 @@
+/**
+ * Core data models for dexcost TypeScript SDK.
+ *
+ * These interfaces match the Dexcost Standard Event Schema v1
+ * and mirror the Python SDK's Task and Event dataclasses.
+ */
+/**
+ * Serialise a Date to the canonical wire format. Sprint 3 Theme F /
+ * §4.1.1 (P1): RFC3339 with microsecond precision (6 fractional
+ * digits) + "Z" suffix, matching the Python canonical.
+ *
+ * `Date.toISOString()` only gives 3-digit millisecond precision, so
+ * we pad with three trailing zeros. Customer-visible Date objects
+ * carry no sub-millisecond data anyway, so the pad is information-
+ * preserving — it just aligns the wire string for cross-SDK parity.
+ */
+function isoCanonical(d) {
+    const iso = d.toISOString();
+    // iso is `YYYY-MM-DDTHH:mm:ss.sssZ` (24 chars); pad to .sssNNNZ
+    return iso.slice(0, -1) + "000Z";
+}
+/** Create a default Task with required fields. */
+export function createTask(overrides) {
+    return {
+        taskType: "",
+        status: "pending",
+        startedAt: new Date(),
+        metadata: {},
+        llmCostUsd: 0,
+        externalCostUsd: 0,
+        computeCostUsd: 0,
+        networkCostUsd: 0,
+        gpuCostUsd: 0,
+        totalCostUsd: 0,
+        totalInputTokens: 0,
+        totalOutputTokens: 0,
+        totalCachedTokens: 0,
+        retryCount: 0,
+        retryCostUsd: 0,
+        failureCount: 0,
+        networkBytesIn: 0,
+        networkBytesOut: 0,
+        networkCallCount: 0,
+        networkByHost: { hosts: [] },
+        schemaVersion: "1",
+        ...overrides,
+    };
+}
+/** Create a default CostEvent with required fields. */
+export function createCostEvent(overrides) {
+    return {
+        eventType: "llm_call",
+        occurredAt: new Date(),
+        costUsd: 0,
+        costConfidence: "exact",
+        isRetry: false,
+        details: {},
+        schemaVersion: "1",
+        ...overrides,
+    };
+}
+/**
+ * Serialise a Task to a JSON-safe dictionary matching the Standard Event Schema v1.
+ * Costs are serialised as strings to preserve precision.
+ */
+export function taskToDict(task) {
+    return {
+        task_id: task.taskId,
+        task_type: task.taskType,
+        status: task.status,
+        started_at: isoCanonical(task.startedAt),
+        ended_at: task.endedAt ? isoCanonical(task.endedAt) : null,
+        metadata: task.metadata,
+        customer_id: task.customerId ?? null,
+        project_id: task.projectId ?? null,
+        parent_task_id: task.parentTaskId ?? null,
+        experiment_id: task.experimentId ?? null,
+        variant: task.variant ?? null,
+        llm_cost_usd: String(task.llmCostUsd),
+        external_cost_usd: String(task.externalCostUsd),
+        compute_cost_usd: String(task.computeCostUsd),
+        network_cost_usd: String(task.networkCostUsd),
+        gpu_cost_usd: String(task.gpuCostUsd),
+        total_cost_usd: String(task.totalCostUsd),
+        total_input_tokens: task.totalInputTokens,
+        total_output_tokens: task.totalOutputTokens,
+        total_cached_tokens: task.totalCachedTokens,
+        retry_count: task.retryCount,
+        retry_cost_usd: String(task.retryCostUsd),
+        failure_count: task.failureCount,
+        network_bytes_in: task.networkBytesIn,
+        network_bytes_out: task.networkBytesOut,
+        network_call_count: task.networkCallCount,
+        network_by_host: task.networkByHost,
+        schema_version: task.schemaVersion,
+    };
+}
+/**
+ * Serialise a CostEvent to a JSON-safe dictionary matching the Standard Event Schema v1.
+ * Costs are serialised as strings to preserve precision.
+ */
+export function eventToDict(event) {
+    return {
+        event_id: event.eventId,
+        task_id: event.taskId,
+        event_type: event.eventType,
+        occurred_at: isoCanonical(event.occurredAt),
+        cost_usd: String(event.costUsd),
+        cost_confidence: event.costConfidence,
+        pricing_source: event.pricingSource ?? null,
+        pricing_version: event.pricingVersion ?? null,
+        provider: event.provider ?? null,
+        model: event.model ?? null,
+        input_tokens: event.inputTokens ?? null,
+        output_tokens: event.outputTokens ?? null,
+        cached_tokens: event.cachedTokens ?? null,
+        latency_ms: event.latencyMs ?? null,
+        service_name: event.serviceName ?? null,
+        is_retry: event.isRetry,
+        retry_reason: event.retryReason ?? null,
+        retry_of: event.retryOf ?? null,
+        details: event.details,
+        schema_version: event.schemaVersion,
+    };
+}
+// ---------------------------------------------------------------------------
+// Deserialisation helpers (inverse of taskToDict / eventToDict)
+// ---------------------------------------------------------------------------
+function _requireString(data, key) {
+    const value = data[key];
+    if (typeof value !== "string") {
+        throw new Error(`Invalid task/event data: missing or non-string field "${key}"`);
+    }
+    return value;
+}
+function _optString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function _toNumber(value, fallback = 0) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const n = Number(value);
+        if (!Number.isNaN(n))
+            return n;
+    }
+    return fallback;
+}
+/**
+ * Deserialise a Task from a JSON-safe dictionary (inverse of `taskToDict`).
+ *
+ * Mirrors the Python SDK's `Task.from_dict`. Throws an Error when required
+ * fields are missing or malformed.
+ */
+export function taskFromDict(data) {
+    const startedAtRaw = _requireString(data, "started_at");
+    const endedAtRaw = data["ended_at"];
+    return {
+        taskId: _requireString(data, "task_id"),
+        taskType: typeof data["task_type"] === "string" ? data["task_type"] : "",
+        status: _requireString(data, "status"),
+        startedAt: new Date(startedAtRaw),
+        endedAt: typeof endedAtRaw === "string" ? new Date(endedAtRaw) : undefined,
+        metadata: data["metadata"] && typeof data["metadata"] === "object"
+            ? data["metadata"]
+            : {},
+        customerId: _optString(data["customer_id"]),
+        projectId: _optString(data["project_id"]),
+        parentTaskId: _optString(data["parent_task_id"]),
+        experimentId: _optString(data["experiment_id"]),
+        variant: _optString(data["variant"]),
+        llmCostUsd: _toNumber(data["llm_cost_usd"]),
+        externalCostUsd: _toNumber(data["external_cost_usd"]),
+        computeCostUsd: _toNumber(data["compute_cost_usd"]),
+        networkCostUsd: _toNumber(data["network_cost_usd"]),
+        gpuCostUsd: _toNumber(data["gpu_cost_usd"]),
+        totalCostUsd: _toNumber(data["total_cost_usd"]),
+        totalInputTokens: _toNumber(data["total_input_tokens"]),
+        totalOutputTokens: _toNumber(data["total_output_tokens"]),
+        totalCachedTokens: _toNumber(data["total_cached_tokens"]),
+        retryCount: _toNumber(data["retry_count"]),
+        retryCostUsd: _toNumber(data["retry_cost_usd"]),
+        failureCount: _toNumber(data["failure_count"]),
+        networkBytesIn: _toNumber(data["network_bytes_in"]),
+        networkBytesOut: _toNumber(data["network_bytes_out"]),
+        networkCallCount: _toNumber(data["network_call_count"]),
+        networkByHost: data["network_by_host"] && typeof data["network_by_host"] === "object"
+            ? data["network_by_host"]
+            : { hosts: [] },
+        schemaVersion: _optString(data["schema_version"]) ?? "1",
+    };
+}
+/**
+ * Deserialise a CostEvent from a JSON-safe dictionary (inverse of `eventToDict`).
+ *
+ * Mirrors the Python SDK's `Event.from_dict`. Throws an Error when required
+ * fields are missing or malformed.
+ */
+export function eventFromDict(data) {
+    const occurredAtRaw = _requireString(data, "occurred_at");
+    return {
+        eventId: _requireString(data, "event_id"),
+        taskId: _requireString(data, "task_id"),
+        eventType: _requireString(data, "event_type"),
+        occurredAt: new Date(occurredAtRaw),
+        costUsd: _toNumber(data["cost_usd"]),
+        costConfidence: _requireString(data, "cost_confidence"),
+        pricingSource: _optString(data["pricing_source"]),
+        pricingVersion: _optString(data["pricing_version"]),
+        provider: _optString(data["provider"]),
+        model: _optString(data["model"]),
+        inputTokens: typeof data["input_tokens"] === "number" ? data["input_tokens"] : undefined,
+        outputTokens: typeof data["output_tokens"] === "number" ? data["output_tokens"] : undefined,
+        cachedTokens: typeof data["cached_tokens"] === "number" ? data["cached_tokens"] : undefined,
+        latencyMs: typeof data["latency_ms"] === "number" ? data["latency_ms"] : undefined,
+        serviceName: _optString(data["service_name"]),
+        isRetry: data["is_retry"] === true,
+        retryReason: _optString(data["retry_reason"]),
+        retryOf: _optString(data["retry_of"]),
+        details: data["details"] && typeof data["details"] === "object"
+            ? data["details"]
+            : {},
+        schemaVersion: _optString(data["schema_version"]) ?? "1",
+    };
+}
+//# sourceMappingURL=models.js.map

package/dist/core/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/core/models.ts"],"names":[],"mappings":"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"}

package/dist/core/nvml-reader.d.ts

@@ -0,0 +1,114 @@
+/**
+ * NVML reader — Phase 2 GPU foundation.
+ *
+ * **TypeScript architectural deviation from Python**: there is no maintained
+ * native NVML binding for Node in 2026. This module shells out to the
+ * `nvidia-smi` CLI via `child_process.spawnSync` and parses CSV output.
+ * Functions still return typed objects (ProcessInfo, UtilSample, MemInfo)
+ * so downstream callers see the same shape as the Python `pynvml`
+ * wrapper. Per-probe overhead is ~50ms (acceptable for finalize-time use;
+ * not suitable for hot-path sampling — but neither is NVML).
+ *
+ * Fail-silent contract (convention §9) identical to Python:
+ * every reader returns `null` (or `false` for booleans) on missing binary,
+ * non-zero exit, or parse failure — the caller (GpuAccountant) decides
+ * the fallback policy per Decision #1's classification table.
+ *
+ * **Browser safety**: nvmlAvailable() short-circuits to false off-Node.
+ *
+ * Decision #4: getProductName applies NFC + lowercase + whitespace collapse
+ * on the raw nvidia-smi product-name output before returning — catalog
+ * alias matching depends on byte-level equality after normalization.
+ *
+ * Decision #8: getProcessUtilization takes a mutable `lastSeenTimestamps`
+ * dict and updates it in place. The TS implementation uses
+ * `process.hrtime.bigint() → ms` for the per-PID timestamp (nvidia-smi pmon
+ * does not expose NVML's sample-buffer timestamp). The accountant uses
+ * (endTs - startTs) ms as the per-PID active window proxy.
+ */
+import type { SpawnSyncReturns } from "node:child_process";
+type SpawnFn = (cmd: string, args: string[], options: {
+    encoding: "utf-8";
+    timeout: number;
+}) => SpawnSyncReturns<string>;
+/** Test-only — override the spawnSync implementation. Pass `null` to restore. */
+export declare function _setSpawnFnForTests(fn: SpawnFn | null): void;
+export declare function _resetWarningStateForTests(): void;
+/** Test-only — override the nvidia-smi binary path. Pass `null` to restore. */
+export declare function _setNvidiaSmiPathForTests(p: string | null): void;
+export interface ProcessInfo {
+    /** PID of the process holding the GPU. */
+    pid: number;
+    /** VRAM used by this process in bytes (0 when nvidia-smi reports N/A). */
+    usedGpuMemory: number;
+}
+export interface UtilSample {
+    pid: number;
+    /** 0–100; percent of time SMs had ≥1 kernel running during the sample window. */
+    smUtil: number;
+    /** 0–100; percent of time memory subsystem was busy. */
+    memUtil: number;
+    /** Per-PID timestamp (milliseconds since process start) for Decision #8 state. */
+    timeStamp: number;
+}
+export interface MemInfo {
+    usedBytes: number;
+    totalBytes: number;
+}
+/**
+ * True when `nvidia-smi` is invokable and exits 0 on the count query.
+ *
+ * The TS-SDK definition of "available" is "binary works"; in Python this
+ * was "pynvml importable AND nvmlInit succeeds". Same end behaviour:
+ * downstream code checks this predicate before calling readers.
+ */
+export declare function nvmlAvailable(): boolean;
+/** Call `nvidia-smi --query-gpu=count` once. True on success, false on any failure. */
+export declare function initNvml(): boolean;
+/** No-op on TS; the CLI has no persistent handle. Provided for API parity. */
+export declare function shutdownNvml(): void;
+/** Number of NVIDIA devices visible to nvidia-smi. `null` on failure. */
+export declare function getDeviceCount(): number | null;
+/**
+ * Return the nvidia-smi product-name for `index`, NFC-normalized + lowercased.
+ *
+ * Decision #4 — alias matching against the catalog depends on byte-level
+ * equality post-normalization.
+ */
+export declare function getProductName(index: number): string | null;
+/**
+ * List of PIDs currently holding GPU `index` + their VRAM usage in bytes.
+ *
+ * Returns `null` on permission denied / failure — the Decision #1
+ * load-bearing case for non-root containers. The accountant's cgroup walk
+ * then degrades to self-PID-only.
+ */
+export declare function getComputeRunningProcesses(index: number): ProcessInfo[] | null;
+/**
+ * Per-PID utilization sampled from `nvidia-smi pmon -c 1 -s u`.
+ *
+ * Decision #8 — TS uses `Date.now()` as the per-PID timestamp proxy
+ * because nvidia-smi pmon does not expose the NVML sample-buffer epoch.
+ * The accountant uses (endTs - startTs) ms as the active-GPU-time
+ * approximation between snapshots.
+ *
+ * Updates `lastSeenTimestamps` in place — callers persist across snapshots.
+ */
+/**
+ * Returns multi-sample-per-PID utilization data.
+ *
+ * Sprint 2 Theme C / §3.1.1 (B2 TS port). Pre-fix the return type
+ * was `Record<number, UtilSample>` — single-latest-sample-per-PID,
+ * collapsing the integration data the accountant needs. Now returns
+ * `Record<number, UtilSample[]>` with samples sorted by `timeStamp`
+ * ascending. nvidia-smi pmon returns one snapshot per call, so the
+ * array length is 1 in practice; the type accommodates future
+ * sampling implementations that batch multiple observations.
+ */
+export declare function getProcessUtilization(index: number, lastSeenTimestamps: Record<number, number>): Record<number, UtilSample[]> | null;
+/** Device-level used / total VRAM (bytes). `null` on failure. */
+export declare function getMemoryInfo(index: number): MemInfo | null;
+/** True when MIG is enabled on this device (Decision #2 detection). */
+export declare function getMigMode(index: number): boolean;
+export {};
+//# sourceMappingURL=nvml-reader.d.ts.map

package/dist/core/nvml-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nvml-reader.d.ts","sourceRoot":"","sources":["../../src/core/nvml-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAI3D,KAAK,OAAO,GAAG,CACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAC5C,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAK9B,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAK5D;AAMD,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAmBD,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEhE;AAID,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AA6BD;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAYvC;AAED,uFAAuF;AACvF,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAID,yEAAyE;AACzE,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAc9C;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkB3D;AAID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,IAAI,CA8B9E;AAID;;;;;;;;;GASG;AACH;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,GAAG,IAAI,CAmDrC;AAID,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA0B3D;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAejD"}

package/dist/core/nvml-reader.js

@@ -0,0 +1,323 @@
+/**
+ * NVML reader — Phase 2 GPU foundation.
+ *
+ * **TypeScript architectural deviation from Python**: there is no maintained
+ * native NVML binding for Node in 2026. This module shells out to the
+ * `nvidia-smi` CLI via `child_process.spawnSync` and parses CSV output.
+ * Functions still return typed objects (ProcessInfo, UtilSample, MemInfo)
+ * so downstream callers see the same shape as the Python `pynvml`
+ * wrapper. Per-probe overhead is ~50ms (acceptable for finalize-time use;
+ * not suitable for hot-path sampling — but neither is NVML).
+ *
+ * Fail-silent contract (convention §9) identical to Python:
+ * every reader returns `null` (or `false` for booleans) on missing binary,
+ * non-zero exit, or parse failure — the caller (GpuAccountant) decides
+ * the fallback policy per Decision #1's classification table.
+ *
+ * **Browser safety**: nvmlAvailable() short-circuits to false off-Node.
+ *
+ * Decision #4: getProductName applies NFC + lowercase + whitespace collapse
+ * on the raw nvidia-smi product-name output before returning — catalog
+ * alias matching depends on byte-level equality after normalization.
+ *
+ * Decision #8: getProcessUtilization takes a mutable `lastSeenTimestamps`
+ * dict and updates it in place. The TS implementation uses
+ * `process.hrtime.bigint() → ms` for the per-PID timestamp (nvidia-smi pmon
+ * does not expose NVML's sample-buffer timestamp). The accountant uses
+ * (endTs - startTs) ms as the per-PID active window proxy.
+ */
+import { spawnSync as nodeSpawnSync } from "node:child_process";
+let _spawnFn = (cmd, args, options) => nodeSpawnSync(cmd, args, options);
+/** Test-only — override the spawnSync implementation. Pass `null` to restore. */
+export function _setSpawnFnForTests(fn) {
+    _spawnFn =
+        fn ??
+            ((cmd, args, options) => nodeSpawnSync(cmd, args, options));
+}
+// ─── Warn-once tracking (single-threaded JS → no lock) ──────────────────────
+const _warnedModes = new Set();
+export function _resetWarningStateForTests() {
+    _warnedModes.clear();
+}
+function _warnOnce(mode, message) {
+    if (_warnedModes.has(mode))
+        return;
+    _warnedModes.add(mode);
+    // eslint-disable-next-line no-console
+    console.warn(message);
+}
+// ─── Browser-safety guard ───────────────────────────────────────────────────
+function _isNode() {
+    return typeof process !== "undefined" && !!process.versions?.node;
+}
+// ─── Test-only nvidia-smi path override ─────────────────────────────────────
+let _nvidiaSmiPath = "nvidia-smi";
+/** Test-only — override the nvidia-smi binary path. Pass `null` to restore. */
+export function _setNvidiaSmiPathForTests(p) {
+    _nvidiaSmiPath = p ?? "nvidia-smi";
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function _runSmi(args) {
+    if (!_isNode())
+        return { stdout: "", ok: false };
+    try {
+        const r = _spawnFn(_nvidiaSmiPath, args, {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        if (r.error || r.status !== 0) {
+            return { stdout: "", ok: false };
+        }
+        return { stdout: r.stdout ?? "", ok: true };
+    }
+    catch {
+        return { stdout: "", ok: false };
+    }
+}
+function _normalizeProductName(raw) {
+    // NFC → lowercase → whitespace collapse (incl. NBSP / NNBSP / zero-width).
+    const nfc = raw.normalize("NFC");
+    // String.split(/\s+/) treats Unicode whitespace incl. U+00A0 NBSP as a delimiter.
+    return nfc.toLowerCase().split(/\s+/).filter(Boolean).join(" ");
+}
+// ─── Availability + init ────────────────────────────────────────────────────
+/**
+ * True when `nvidia-smi` is invokable and exits 0 on the count query.
+ *
+ * The TS-SDK definition of "available" is "binary works"; in Python this
+ * was "pynvml importable AND nvmlInit succeeds". Same end behaviour:
+ * downstream code checks this predicate before calling readers.
+ */
+export function nvmlAvailable() {
+    if (!_isNode())
+        return false;
+    const r = _runSmi(["--query-gpu=count", "--format=csv,noheader"]);
+    if (!r.ok) {
+        _warnOnce("gpu_nvidia_smi_not_found", "nvidia-smi not on PATH or exited non-zero; GPU capture disabled. " +
+            "Install NVIDIA driver + container toolkit for GPU cost attribution.");
+        return false;
+    }
+    return true;
+}
+/** Call `nvidia-smi --query-gpu=count` once. True on success, false on any failure. */
+export function initNvml() {
+    return nvmlAvailable();
+}
+/** No-op on TS; the CLI has no persistent handle. Provided for API parity. */
+export function shutdownNvml() {
+    /* no-op */
+}
+// ─── Device enumeration ─────────────────────────────────────────────────────
+/** Number of NVIDIA devices visible to nvidia-smi. `null` on failure. */
+export function getDeviceCount() {
+    if (!_isNode())
+        return null;
+    const r = _runSmi(["--query-gpu=count", "--format=csv,noheader"]);
+    if (!r.ok)
+        return null;
+    // nvidia-smi --query-gpu=count emits one line per GPU, all with the same count value.
+    // Take the first non-empty line.
+    const first = r.stdout.split("\n").map((s) => s.trim()).find((s) => s);
+    if (!first)
+        return null;
+    const n = parseInt(first, 10);
+    if (Number.isNaN(n)) {
+        _warnOnce("gpu_device_count_parse", `nvidia-smi count unparseable: ${first}`);
+        return null;
+    }
+    return n;
+}
+// ─── Decision #4: NFC-normalized productName ────────────────────────────────
+/**
+ * Return the nvidia-smi product-name for `index`, NFC-normalized + lowercased.
+ *
+ * Decision #4 — alias matching against the catalog depends on byte-level
+ * equality post-normalization.
+ */
+export function getProductName(index) {
+    if (!_isNode())
+        return null;
+    const r = _runSmi([
+        `--query-gpu=name`,
+        `--format=csv,noheader`,
+        `-i`,
+        String(index),
+    ]);
+    if (!r.ok) {
+        _warnOnce("gpu_product_name_failed", `nvidia-smi --query-gpu=name failed for device ${index}`);
+        return null;
+    }
+    const line = r.stdout.split("\n").map((s) => s.trim()).find((s) => s);
+    if (!line)
+        return null;
+    return _normalizeProductName(line);
+}
+// ─── Per-PID compute processes (Decision #1 measurement-side primitive) ────
+/**
+ * List of PIDs currently holding GPU `index` + their VRAM usage in bytes.
+ *
+ * Returns `null` on permission denied / failure — the Decision #1
+ * load-bearing case for non-root containers. The accountant's cgroup walk
+ * then degrades to self-PID-only.
+ */
+export function getComputeRunningProcesses(index) {
+    if (!_isNode())
+        return null;
+    const r = _runSmi([
+        `--query-compute-apps=pid,used_memory`,
+        `--format=csv,noheader,nounits`,
+        `-i`,
+        String(index),
+    ]);
+    if (!r.ok) {
+        _warnOnce("gpu_nvml_permission_denied", `nvidia-smi --query-compute-apps failed for device ${index}; ` +
+            `GpuAccountant will degrade to self-PID-only`);
+        return null;
+    }
+    const out = [];
+    for (const line of r.stdout.split("\n")) {
+        const s = line.trim();
+        if (!s)
+            continue;
+        const parts = s.split(",").map((p) => p.trim());
+        if (parts.length < 2)
+            continue;
+        const pid = parseInt(parts[0], 10);
+        if (Number.isNaN(pid))
+            continue;
+        let memMib = parseInt(parts[1], 10);
+        if (Number.isNaN(memMib))
+            memMib = 0;
+        // nounits ⇒ used_memory is MiB.
+        out.push({ pid, usedGpuMemory: memMib * 1024 * 1024 });
+    }
+    return out;
+}
+// ─── Per-PID utilization (Decision #8 persistent timestamps) ────────────────
+/**
+ * Per-PID utilization sampled from `nvidia-smi pmon -c 1 -s u`.
+ *
+ * Decision #8 — TS uses `Date.now()` as the per-PID timestamp proxy
+ * because nvidia-smi pmon does not expose the NVML sample-buffer epoch.
+ * The accountant uses (endTs - startTs) ms as the active-GPU-time
+ * approximation between snapshots.
+ *
+ * Updates `lastSeenTimestamps` in place — callers persist across snapshots.
+ */
+/**
+ * Returns multi-sample-per-PID utilization data.
+ *
+ * Sprint 2 Theme C / §3.1.1 (B2 TS port). Pre-fix the return type
+ * was `Record<number, UtilSample>` — single-latest-sample-per-PID,
+ * collapsing the integration data the accountant needs. Now returns
+ * `Record<number, UtilSample[]>` with samples sorted by `timeStamp`
+ * ascending. nvidia-smi pmon returns one snapshot per call, so the
+ * array length is 1 in practice; the type accommodates future
+ * sampling implementations that batch multiple observations.
+ */
+export function getProcessUtilization(index, lastSeenTimestamps) {
+    if (!_isNode())
+        return null;
+    const r = _runSmi([
+        `pmon`,
+        `-c`,
+        `1`,
+        `-s`,
+        `u`,
+        `-o`,
+        `T`,
+        `-i`,
+        String(index),
+    ]);
+    if (!r.ok) {
+        _warnOnce("gpu_process_utilization_failed", `nvidia-smi pmon failed for device ${index}`);
+        return null;
+    }
+    const out = {};
+    const nowMs = Date.now();
+    for (const rawLine of r.stdout.split("\n")) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        // Skip header lines and N/A rows.
+        if (line.startsWith("#"))
+            continue;
+        // Whitespace-separated columns: gpu pid type sm mem enc dec command
+        const parts = line.split(/\s+/);
+        if (parts.length < 5)
+            continue;
+        const pid = parseInt(parts[1], 10);
+        if (Number.isNaN(pid))
+            continue;
+        const sm = parseInt(parts[3], 10);
+        const mem = parseInt(parts[4], 10);
+        if (Number.isNaN(sm) || Number.isNaN(mem))
+            continue;
+        const sample = { pid, smUtil: sm, memUtil: mem, timeStamp: nowMs };
+        if (out[pid]) {
+            out[pid].push(sample);
+        }
+        else {
+            out[pid] = [sample];
+        }
+        if (nowMs > (lastSeenTimestamps[pid] ?? 0)) {
+            lastSeenTimestamps[pid] = nowMs;
+        }
+    }
+    // Sort each PID's samples by timestamp ascending — the integrator
+    // assumes monotonic ordering.
+    for (const pid in out) {
+        out[pid].sort((a, b) => a.timeStamp - b.timeStamp);
+    }
+    return out;
+}
+// ─── Memory + MIG ───────────────────────────────────────────────────────────
+/** Device-level used / total VRAM (bytes). `null` on failure. */
+export function getMemoryInfo(index) {
+    if (!_isNode())
+        return null;
+    const r = _runSmi([
+        `--query-gpu=memory.used,memory.total`,
+        `--format=csv,noheader,nounits`,
+        `-i`,
+        String(index),
+    ]);
+    if (!r.ok) {
+        _warnOnce("gpu_memory_info_failed", `nvidia-smi --query-gpu=memory.used,memory.total failed for device ${index}`);
+        return null;
+    }
+    const line = r.stdout.split("\n").map((s) => s.trim()).find((s) => s);
+    if (!line)
+        return null;
+    const parts = line.split(",").map((s) => s.trim());
+    if (parts.length < 2)
+        return null;
+    const usedMib = parseInt(parts[0], 10);
+    const totalMib = parseInt(parts[1], 10);
+    if (Number.isNaN(usedMib) || Number.isNaN(totalMib))
+        return null;
+    return {
+        usedBytes: usedMib * 1024 * 1024,
+        totalBytes: totalMib * 1024 * 1024,
+    };
+}
+/** True when MIG is enabled on this device (Decision #2 detection). */
+export function getMigMode(index) {
+    if (!_isNode())
+        return false;
+    const r = _runSmi([
+        `--query-gpu=mig.mode.current`,
+        `--format=csv,noheader`,
+        `-i`,
+        String(index),
+    ]);
+    if (!r.ok) {
+        // Older GPUs without MIG support → fail-silent (NOT an error).
+        return false;
+    }
+    const line = r.stdout.split("\n").map((s) => s.trim()).find((s) => s);
+    if (!line)
+        return false;
+    return line.toLowerCase() === "enabled";
+}
+//# sourceMappingURL=nvml-reader.js.map