@netgreener/runtime 0.1.0

package/dist/processRuntime.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Process / cron / script runtime (N3) — no HTTP middleware required.
+ *
+ * Start metering, bind tenant for a job, flush on shutdown.
+ */
+import { type NetGreenerRuntime, type NetGreenerRuntimeOptions } from './runtime.js';
+import type { UploadResult } from './uploader.js';
+import { type TenantContext } from './tenantContext.js';
+export type ProcessRuntimeOptions = NetGreenerRuntimeOptions & {
+    /** Default service unit when recording a named job (e.g. scheduled_report). */
+    serviceUnit?: string;
+};
+/**
+ * Enable NetGreener runtime for a long-lived Node process (cron worker, script).
+ * Installs outbound ``fetch`` metering and periodic flush when config is ready.
+ */
+export declare function startProcessRuntime(opts?: ProcessRuntimeOptions): NetGreenerRuntime;
+/**
+ * Run ``fn`` with an explicit tenant id (batch/cron style — no JWT).
+ */
+export declare function runWithProcessTenant<T>(tenantId: string, fn: () => Promise<T> | T, opts?: {
+    source?: string;
+    label?: string;
+    serviceUnit?: string;
+    runtime?: NetGreenerRuntime;
+}): Promise<T>;
+/**
+ * Convenience: set tenant for the rest of the current async chain (enterWith).
+ * Prefer ``runWithProcessTenant`` when possible.
+ */
+export declare function bindProcessTenant(tenantId: string, opts?: {
+    source?: string;
+    label?: string;
+}): TenantContext;
+export declare function flushProcessRuntime(kind?: 'manual' | 'shutdown'): Promise<UploadResult | null>;

package/dist/processRuntime.js

@@ -0,0 +1,96 @@
+/**
+ * Process / cron / script runtime (N3) — no HTTP middleware required.
+ *
+ * Start metering, bind tenant for a job, flush on shutdown.
+ */
+import { getRuntime, } from './runtime.js';
+import { normalizeTenantId, runWithTenantContext, setTenantContext, } from './tenantContext.js';
+import { runWithRequestAttribution } from './requestContext.js';
+import { beginProcessResourceSample, endProcessResourceSample, } from './processResources.js';
+let signalsInstalled = false;
+/**
+ * Enable NetGreener runtime for a long-lived Node process (cron worker, script).
+ * Installs outbound ``fetch`` metering and periodic flush when config is ready.
+ */
+export function startProcessRuntime(opts = {}) {
+    const runtime = getRuntime({
+        collector: 'node_process',
+        framework: 'node',
+        ...opts,
+    });
+    runtime.start();
+    if (!signalsInstalled) {
+        signalsInstalled = true;
+        const shutdown = () => {
+            void runtime.shutdown();
+        };
+        process.once('beforeExit', shutdown);
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    }
+    return runtime;
+}
+/**
+ * Run ``fn`` with an explicit tenant id (batch/cron style — no JWT).
+ */
+export async function runWithProcessTenant(tenantId, fn, opts) {
+    const normalized = normalizeTenantId(tenantId);
+    if (!normalized) {
+        throw new Error('invalid tenant_id');
+    }
+    const runtime = opts?.runtime ?? startProcessRuntime();
+    const ctx = {
+        tenantId: normalized,
+        tenantSource: opts?.source || 'manual',
+        ...(opts?.label ? { tenantLabel: opts.label.slice(0, 128) } : {}),
+    };
+    const serviceUnit = opts?.serviceUnit || 'task:process';
+    const started = performance.now();
+    const resourceMark = beginProcessResourceSample();
+    let error = false;
+    const run = async () => {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            error = true;
+            throw err;
+        }
+        finally {
+            if (runtime.enabled) {
+                const resources = endProcessResourceSample(resourceMark);
+                runtime.recordTask({
+                    serviceUnit,
+                    durationMs: performance.now() - started,
+                    error,
+                    tenantId: normalized,
+                    cpuTimeMs: resources.cpuTimeMs,
+                    peakRssKb: resources.rssKb,
+                });
+            }
+        }
+    };
+    return runWithTenantContext(ctx, () => runWithRequestAttribution({ serviceUnit }, () => run()));
+}
+/**
+ * Convenience: set tenant for the rest of the current async chain (enterWith).
+ * Prefer ``runWithProcessTenant`` when possible.
+ */
+export function bindProcessTenant(tenantId, opts) {
+    const normalized = normalizeTenantId(tenantId);
+    if (!normalized)
+        throw new Error('invalid tenant_id');
+    const ctx = {
+        tenantId: normalized,
+        tenantSource: opts?.source || 'manual',
+        ...(opts?.label ? { tenantLabel: opts.label.slice(0, 128) } : {}),
+    };
+    setTenantContext(ctx);
+    return ctx;
+}
+export async function flushProcessRuntime(kind = 'manual') {
+    const runtime = getRuntime({ collector: 'node_process', framework: 'node' });
+    if (kind === 'shutdown')
+        return runtime.shutdown();
+    return runtime.flush(kind);
+}

package/dist/requestContext.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Current inbound HTTP / task unit for outbound attribution.
+ *
+ * Prefer ``resolveServiceUnit`` when route metadata may appear after middleware
+ * entry (Express). Callers that await work (outbound fetch) must snapshot
+ * ``attributionServiceUnit()`` when the call begins. Static ``serviceUnit``
+ * remains for workers/batch.
+ */
+export type RequestAttribution = {
+    serviceUnit?: string;
+    resolveServiceUnit?: () => string;
+};
+export declare function runWithRequestAttribution<T>(attribution: RequestAttribution | null, fn: () => T): T;
+/**
+ * Bind attribution for frameworks (e.g. Fastify) whose hooks return before the
+ * route runs — ``run()`` would exit too early. Cleared implicitly by the next
+ * ``run``/``enterWith`` on another request.
+ */
+export declare function enterRequestAttribution(attribution: RequestAttribution | null): void;
+export declare function getRequestAttribution(): RequestAttribution | null;
+export declare function attributionServiceUnit(): string | null;

package/dist/requestContext.js

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+export function runWithRequestAttribution(attribution, fn) {
+    return storage.run(attribution, fn);
+}
+/**
+ * Bind attribution for frameworks (e.g. Fastify) whose hooks return before the
+ * route runs — ``run()`` would exit too early. Cleared implicitly by the next
+ * ``run``/``enterWith`` on another request.
+ */
+export function enterRequestAttribution(attribution) {
+    storage.enterWith(attribution);
+}
+export function getRequestAttribution() {
+    return storage.getStore() ?? null;
+}
+export function attributionServiceUnit() {
+    const store = getRequestAttribution();
+    if (!store)
+        return null;
+    if (typeof store.resolveServiceUnit === 'function') {
+        try {
+            const resolved = store.resolveServiceUnit();
+            if (typeof resolved === 'string' && resolved.trim())
+                return resolved.trim();
+        }
+        catch {
+            // Fall through to static unit.
+        }
+    }
+    const staticUnit = (store.serviceUnit || '').trim();
+    return staticUnit || null;
+}

package/dist/runtime.d.ts

@@ -0,0 +1,60 @@
+import { type RuntimeConfig } from './config.js';
+import { type RunSessionCreatePayload, type UploadResult } from './uploader.js';
+import { type ObservationExporter } from './exporter.js';
+export type FlushKind = 'periodic' | 'shutdown' | 'manual';
+export type NetGreenerRuntimeOptions = {
+    config?: RuntimeConfig;
+    collector?: string;
+    framework?: string;
+    fetchImpl?: typeof fetch;
+    /** MP2: defaults to direct upload exporter (unchanged pipeline). */
+    exporter?: ObservationExporter;
+    onFlush?: (result: UploadResult, payload: RunSessionCreatePayload) => void;
+};
+/**
+ * Process-wide runtime controller: record samples, periodic flush, shutdown flush.
+ */
+export declare class NetGreenerRuntime {
+    readonly config: RuntimeConfig;
+    private readonly aggregator;
+    private readonly collector;
+    private readonly framework;
+    private readonly fetchImpl;
+    private readonly exporter;
+    private readonly onFlush?;
+    private timer;
+    private flushing;
+    private started;
+    private outboundInstalled;
+    constructor(opts?: NetGreenerRuntimeOptions);
+    get enabled(): boolean;
+    private ensureOutboundMeter;
+    /** Prefer unwrapped fetch so telemetry uploads are never metered. */
+    private uploadFetch;
+    start(): void;
+    stop(): void;
+    recordHttp(sample: {
+        method: string;
+        path: string;
+        statusCode: number;
+        durationMs: number;
+        /** Measured process CPU ms (from begin/endProcessResourceSample). */
+        cpuTimeMs?: number;
+        /** Measured RSS KiB at request end. */
+        peakRssKb?: number;
+    }): void;
+    /** Record a background job / worker task sample (BullMQ, cron, scripts). */
+    recordTask(sample: {
+        serviceUnit: string;
+        durationMs: number;
+        error?: boolean;
+        tenantId?: string | null;
+        cpuTimeMs?: number;
+        peakRssKb?: number;
+    }): void;
+    flush(kind?: FlushKind): Promise<UploadResult | null>;
+    shutdown(): Promise<UploadResult | null>;
+}
+export declare function getRuntime(opts?: NetGreenerRuntimeOptions): NetGreenerRuntime;
+/** Test helper — reset singleton. */
+export declare function _resetRuntimeForTests(): void;

package/dist/runtime.js

@@ -0,0 +1,289 @@
+import { hostname } from 'node:os';
+import { ServiceRuntimeAggregator } from './aggregator.js';
+import { configReady, loadRuntimeConfig, } from './config.js';
+import { resolveObservationExporter, } from './exporter.js';
+import { newRuntimeWindowId } from './windowId.js';
+import { attachWindowTenantToRunContext, getTenantContext, tenantConfigFromRuntime, } from './tenantContext.js';
+import { getExternalAggregator, getOriginalFetch, installOutboundInstrumentation, } from './externalApiMeter.js';
+import { CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS, } from './processResources.js';
+import { CPU_SOURCE_DURATION_PROXY } from './n4/missingnessInventory.js';
+import { buildRuntimeHealthV0, markHooksActive, mergeHealthIntoMetadata, noteExportAttempt, noteExportMode, noteExportResult, noteFlushSkippedInFlight, _resetRuntimeHealthForTests, } from './runtimeHealth.js';
+/**
+ * Process-wide runtime controller: record samples, periodic flush, shutdown flush.
+ */
+export class NetGreenerRuntime {
+    config;
+    aggregator = new ServiceRuntimeAggregator();
+    collector;
+    framework;
+    fetchImpl;
+    exporter;
+    onFlush;
+    timer = null;
+    flushing = false;
+    started = false;
+    outboundInstalled = false;
+    constructor(opts = {}) {
+        this.config = opts.config ?? loadRuntimeConfig();
+        this.collector = opts.collector ?? 'express_middleware';
+        this.framework = opts.framework ?? 'express';
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.exporter = opts.exporter ?? resolveObservationExporter();
+        this.onFlush = opts.onFlush;
+    }
+    get enabled() {
+        return configReady(this.config).ok;
+    }
+    ensureOutboundMeter() {
+        if (this.outboundInstalled || !this.enabled)
+            return;
+        this.outboundInstalled = true;
+        try {
+            const apiHost = new URL(this.config.apiUrl).hostname;
+            installOutboundInstrumentation({
+                excludedHosts: apiHost ? [apiHost] : [],
+            });
+        }
+        catch {
+            installOutboundInstrumentation();
+        }
+    }
+    /** Prefer unwrapped fetch so telemetry uploads are never metered. */
+    uploadFetch() {
+        return getOriginalFetch() ?? this.fetchImpl;
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        if (!this.enabled)
+            return;
+        markHooksActive({
+            processKind: this.framework,
+            exportMode: this.exporter.mode,
+        });
+        noteExportMode(this.exporter.mode);
+        this.ensureOutboundMeter();
+        this.timer = setInterval(() => {
+            void this.flush('periodic');
+        }, this.config.flushIntervalMs);
+        // Do not keep the process alive solely for the timer.
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.started = false;
+    }
+    recordHttp(sample) {
+        if (!this.enabled)
+            return;
+        this.ensureOutboundMeter();
+        markHooksActive({
+            processKind: this.framework,
+            exportMode: this.exporter.mode,
+        });
+        const serviceUnit = `${sample.method.toUpperCase()} ${sample.path}`;
+        this.aggregator.record({
+            serviceUnit,
+            unitType: 'http_route',
+            durationMs: sample.durationMs,
+            error: sample.statusCode >= 400,
+            tenantId: getTenantContext()?.tenantId ?? null,
+            ...(sample.cpuTimeMs !== undefined ? { cpuTimeMs: sample.cpuTimeMs } : {}),
+            ...(sample.peakRssKb !== undefined ? { peakRssKb: sample.peakRssKb } : {}),
+        });
+    }
+    /** Record a background job / worker task sample (BullMQ, cron, scripts). */
+    recordTask(sample) {
+        if (!this.enabled)
+            return;
+        this.ensureOutboundMeter();
+        markHooksActive({
+            processKind: this.framework,
+            exportMode: this.exporter.mode,
+        });
+        this.aggregator.record({
+            serviceUnit: sample.serviceUnit,
+            unitType: 'task',
+            durationMs: sample.durationMs,
+            error: Boolean(sample.error),
+            tenantId: sample.tenantId ?? getTenantContext()?.tenantId ?? null,
+            ...(sample.cpuTimeMs !== undefined ? { cpuTimeMs: sample.cpuTimeMs } : {}),
+            ...(sample.peakRssKb !== undefined ? { peakRssKb: sample.peakRssKb } : {}),
+        });
+    }
+    async flush(kind = 'manual') {
+        if (!this.enabled)
+            return null;
+        if (this.flushing) {
+            noteFlushSkippedInFlight();
+            return null;
+        }
+        const externalAgg = getExternalAggregator();
+        const hasRuntime = this.aggregator.hasData();
+        const hasExternal = externalAgg.hasData();
+        if (!hasRuntime && !hasExternal)
+            return null;
+        this.flushing = true;
+        noteExportMode(this.exporter.mode);
+        const snapshot = hasRuntime ? this.aggregator.takeSnapshot() : null;
+        const externalSnapshot = hasExternal ? externalAgg.takeSnapshot() : null;
+        try {
+            const windowStartedMs = snapshot
+                ? snapshot.windowStartedMs()
+                : Date.now() - 1000;
+            const windowSeconds = Math.max(0.001, (Date.now() - windowStartedMs) / 1000);
+            // Crude trend energy: TDP * utilization proxy from request busy time.
+            const busySeconds = snapshot
+                ? snapshot.hasMeasuredCpu()
+                    ? snapshot.totalMeasuredCpuMs() / 1000
+                    : snapshot.totalDurationMs() / 1000
+                : 0;
+            const util = Math.min(1, busySeconds / Math.max(windowSeconds, 0.001));
+            const windowEnergyKwh = (this.config.estimateTdpWatts * util * windowSeconds) / 1000 / 3600;
+            const runtimeV0 = snapshot
+                ? snapshot.buildV0({
+                    collector: this.collector,
+                    framework: this.framework,
+                    windowEnergyKwh,
+                    windowSeconds,
+                })
+                : null;
+            if (snapshot && !runtimeV0) {
+                this.aggregator.mergeSnapshot(snapshot);
+                if (externalSnapshot)
+                    externalAgg.mergeSnapshot(externalSnapshot);
+                return null;
+            }
+            const externalV0 = externalSnapshot ? externalSnapshot.buildV0() : null;
+            const end = new Date();
+            const start = new Date(end.getTime() - windowSeconds * 1000);
+            const windowId = newRuntimeWindowId();
+            // Prefer effective RuntimeConfig over ambient process.env.
+            const tenantConfig = tenantConfigFromRuntime(this.config);
+            const runContext = {
+                client: 'netgreener_node_runtime',
+                runtime_flush_kind: kind,
+                measured_scope: 'process',
+                resource_scope: 'process',
+                ...(this.config.deployEnvironment
+                    ? { deploy_environment: this.config.deployEnvironment }
+                    : {}),
+                ...(this.config.releaseTag ? { release_tag: this.config.releaseTag } : {}),
+            };
+            attachWindowTenantToRunContext(runContext, {
+                runtimeV0: runtimeV0 ?? undefined,
+                externalV0: externalV0 ?? undefined,
+                tenantConfig,
+                activeContext: getTenantContext(),
+            });
+            const measuredCpu = snapshot?.hasMeasuredCpu() ?? false;
+            const measuredRss = snapshot?.hasMeasuredRss() ?? false;
+            const session_metadata = {
+                run_context: runContext,
+                ...(runtimeV0 ? { service_runtime_v0: runtimeV0 } : {}),
+                ...(externalV0 ? { external_api_v0: externalV0 } : {}),
+                measurement_provenance: {
+                    cpu_source: runtimeV0
+                        ? measuredCpu
+                            ? CPU_SOURCE_PROCESS
+                            : CPU_SOURCE_DURATION_PROXY
+                        : 'unavailable',
+                    memory_source: measuredRss ? MEMORY_SOURCE_PROCESS : 'unavailable',
+                    energy_model: runtimeV0 ? 'tdp_utilization_estimate' : 'unavailable',
+                    gpu_scope: 'none',
+                    gpu_source: 'unavailable',
+                    carbon_factor: {
+                        value: 0.4,
+                        unit: 'kg_co2e_per_kwh',
+                        source: 'default_grid_factor',
+                    },
+                    evidence_grades: {
+                        schema_version: 1,
+                        policy_version: 'r9_v0',
+                        metrics: {
+                            local_energy: {
+                                metric: 'local_energy',
+                                grade: runtimeV0 ? 'G1' : 'G0',
+                                reasons: runtimeV0 ? ['estimated_power_tdp'] : ['no_runtime_units'],
+                            },
+                            local_carbon: {
+                                metric: 'local_carbon',
+                                grade: runtimeV0 ? 'G1' : 'G0',
+                                reasons: runtimeV0
+                                    ? ['estimated_power_tdp', 'default_grid_factor']
+                                    : ['no_runtime_units'],
+                            },
+                        },
+                        combined_floor_grade: runtimeV0 ? 'G1' : 'G0',
+                        notes: ['vendor_carbon_separate_ledger'],
+                    },
+                },
+            };
+            mergeHealthIntoMetadata(session_metadata, buildRuntimeHealthV0());
+            const payload = {
+                project_id: this.config.projectId,
+                start_time: start.toISOString(),
+                end_time: end.toISOString(),
+                server_name: hostname() || null,
+                energy_kwh: windowEnergyKwh,
+                runtime_window_id: windowId,
+                session_metadata,
+            };
+            noteExportAttempt(this.exporter.mode);
+            const result = await this.exporter.exportRunSessionWindow(this.config, payload, this.uploadFetch());
+            noteExportResult(result.ok, result.ok ? undefined : 'error' in result ? result.error : 'export_failed');
+            mergeHealthIntoMetadata(session_metadata, buildRuntimeHealthV0());
+            if (!result.ok) {
+                if (snapshot)
+                    this.aggregator.mergeSnapshot(snapshot);
+                if (externalSnapshot)
+                    externalAgg.mergeSnapshot(externalSnapshot);
+            }
+            this.onFlush?.(result, payload);
+            return result;
+        }
+        catch (err) {
+            noteExportResult(false, err instanceof Error ? err.message : String(err));
+            if (snapshot)
+                this.aggregator.mergeSnapshot(snapshot);
+            if (externalSnapshot)
+                externalAgg.mergeSnapshot(externalSnapshot);
+            const result = {
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+            this.onFlush?.(result, {
+                project_id: this.config.projectId,
+                start_time: new Date().toISOString(),
+                end_time: new Date().toISOString(),
+                runtime_window_id: newRuntimeWindowId(),
+                session_metadata: {},
+            });
+            return result;
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    async shutdown() {
+        this.stop();
+        return this.flush('shutdown');
+    }
+}
+let globalRuntime = null;
+export function getRuntime(opts) {
+    if (!globalRuntime) {
+        globalRuntime = new NetGreenerRuntime(opts);
+    }
+    return globalRuntime;
+}
+/** Test helper — reset singleton. */
+export function _resetRuntimeForTests() {
+    globalRuntime?.stop();
+    globalRuntime = null;
+    _resetRuntimeHealthForTests();
+}

package/dist/runtimeHealth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Runtime / export health (N6 / CAP-R5 honesty).
+ *
+ * Additive ``runtime_health_v0`` twin of Python ``netgreener.runtime_health``.
+ * Does not change upload defaults or invent collector spool metrics.
+ */
+export type RuntimeHealthStatus = 'ok' | 'degraded' | 'conflict' | 'unknown';
+export type RuntimeHealthV0 = {
+    schema_version: 1;
+    status: RuntimeHealthStatus;
+    codes: string[];
+    detail: string;
+    remediation: string[];
+    bootstrap: string;
+    hooks_active: boolean;
+    process_kind: string;
+    collector_mode: string | null;
+    export_mode: string;
+    export_attempts: number;
+    export_ok: number;
+    export_fail: number;
+    /** Flushes skipped because another flush was in flight (best-effort drop). */
+    export_skipped_in_flight: number;
+};
+export declare function _resetRuntimeHealthForTests(): void;
+export declare function markHooksActive(opts?: {
+    processKind?: string;
+    exportMode?: string;
+}): void;
+export declare function noteExportMode(mode: string): void;
+export declare function noteFlushSkippedInFlight(): void;
+export declare function noteExportAttempt(mode: string): void;
+export declare function noteExportResult(ok: boolean, error?: string): void;
+export declare function buildRuntimeHealthV0(): RuntimeHealthV0;
+export declare function mergeHealthIntoMetadata(meta: Record<string, unknown>, health?: RuntimeHealthV0): void;