@netgreener/runtime 0.1.0

package/dist/fastify.d.ts

@@ -0,0 +1,53 @@
+import { type NetGreenerRuntime, type NetGreenerRuntimeOptions } from './runtime.js';
+/** Minimal Fastify-compatible request shape (avoid hard dependency). */
+export type FastifyRequestLike = {
+    method?: string;
+    url?: string;
+    /** Fastify 3/4 route pattern when routing has matched. */
+    routerPath?: string;
+    /** Fastify 4.16+ / 5 route config url (template). */
+    routeOptions?: {
+        url?: string;
+    };
+    headers?: Record<string, unknown>;
+};
+export type FastifyReplyLike = {
+    statusCode?: number;
+};
+export type FastifyDone = (err?: Error) => void;
+export type FastifyLike = {
+    addHook: (name: 'onRequest' | 'onResponse' | 'onError' | string, handler: (...args: unknown[]) => unknown) => unknown;
+    register?: (plugin: unknown, opts?: unknown) => Promise<unknown> | unknown;
+};
+/**
+ * Bounded template for service_unit attribution.
+ * Never fall back to raw customer paths, query strings, or url.
+ */
+export declare function fastifyRouteTemplate(req: FastifyRequestLike): string;
+/**
+ * Bind tenant on the Fastify request-scoped store (and ALS when active).
+ * Prefer this after auth in Fastify handlers — ``setTenantContext`` alone may
+ * not update the store captured at ``onRequest`` when ALS does not span the route.
+ */
+export declare function bindFastifyTenant(request: object, ctx: import('./tenantContext.js').TenantContext): void;
+/**
+ * Fastify plugin: record per-route latency/status into NetGreenerRuntime.
+ *
+ * Register with ``await fastify.register(netgreenerFastifyPlugin())`` (or
+ * ``fastify.register(netgreenerFastifyPlugin({ config }))``).
+ *
+ * The plugin breaks Fastify encapsulation (skip-override) so hooks apply to
+ * routes registered on the same instance after ``register``, matching Express
+ * middleware scope.
+ *
+ * Enable with NETGREENER_SERVICE_RUNTIME=1 and credentials (see README).
+ * Installs outbound ``fetch`` metering when runtime is enabled (via getRuntime.start).
+ *
+ * Route identity prefers ``routeOptions.url`` / ``routerPath`` at response time.
+ * Raw ``url`` is never a metering fallback.
+ *
+ * Tenant/attribution use ``enterWith`` so ALS spans Fastify's hook → route gap
+ * (unlike Express, where ``next()`` stays inside ``run()``).
+ */
+export declare function netgreenerFastifyPlugin(opts?: NetGreenerRuntimeOptions): (fastify: FastifyLike) => Promise<void>;
+export declare function getFastifyRuntime(): NetGreenerRuntime;

package/dist/fastify.js

@@ -0,0 +1,148 @@
+import { getRuntime, } from './runtime.js';
+import { enterTenantStore, resolveTenantFromHttpRequest, runWithTenantContext, setTenantContext, tenantConfigFromRuntime, } from './tenantContext.js';
+import { enterRequestAttribution } from './requestContext.js';
+import { UNKNOWN_ROUTE_TEMPLATE } from './express.js';
+import { beginProcessResourceSample, endProcessResourceSample, } from './processResources.js';
+const MAX_ROUTE_TEMPLATE_LEN = 512;
+const REQ_STATE = Symbol.for('netgreener.fastify.requestState');
+/**
+ * Bounded template for service_unit attribution.
+ * Never fall back to raw customer paths, query strings, or url.
+ */
+export function fastifyRouteTemplate(req) {
+    const candidates = [req.routeOptions?.url, req.routerPath];
+    for (const route of candidates) {
+        if (typeof route !== 'string')
+            continue;
+        const template = route.trim();
+        if (!template ||
+            template.length > MAX_ROUTE_TEMPLATE_LEN ||
+            template.includes('?') ||
+            template.includes('#')) {
+            continue;
+        }
+        return template;
+    }
+    return UNKNOWN_ROUTE_TEMPLATE;
+}
+function httpServiceUnit(method, req) {
+    return `${method} ${fastifyRouteTemplate(req)}`;
+}
+function getRequestState(req) {
+    return req[REQ_STATE];
+}
+function setRequestState(req, state) {
+    ;
+    req[REQ_STATE] = state;
+}
+/**
+ * Bind tenant on the Fastify request-scoped store (and ALS when active).
+ * Prefer this after auth in Fastify handlers — ``setTenantContext`` alone may
+ * not update the store captured at ``onRequest`` when ALS does not span the route.
+ */
+export function bindFastifyTenant(request, ctx) {
+    const state = getRequestState(request);
+    if (state)
+        state.tenantStore.current = ctx;
+    setTenantContext(ctx);
+}
+/**
+ * Fastify plugin: record per-route latency/status into NetGreenerRuntime.
+ *
+ * Register with ``await fastify.register(netgreenerFastifyPlugin())`` (or
+ * ``fastify.register(netgreenerFastifyPlugin({ config }))``).
+ *
+ * The plugin breaks Fastify encapsulation (skip-override) so hooks apply to
+ * routes registered on the same instance after ``register``, matching Express
+ * middleware scope.
+ *
+ * Enable with NETGREENER_SERVICE_RUNTIME=1 and credentials (see README).
+ * Installs outbound ``fetch`` metering when runtime is enabled (via getRuntime.start).
+ *
+ * Route identity prefers ``routeOptions.url`` / ``routerPath`` at response time.
+ * Raw ``url`` is never a metering fallback.
+ *
+ * Tenant/attribution use ``enterWith`` so ALS spans Fastify's hook → route gap
+ * (unlike Express, where ``next()`` stays inside ``run()``).
+ */
+export function netgreenerFastifyPlugin(opts = {}) {
+    const runtime = getRuntime({
+        collector: 'fastify_middleware',
+        framework: 'fastify',
+        ...opts,
+    });
+    runtime.start();
+    const onSignal = () => {
+        void runtime.shutdown();
+    };
+    process.once('beforeExit', onSignal);
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    const tenantConfig = tenantConfigFromRuntime(runtime.config);
+    const plugin = async function netgreenerFastify(fastify) {
+        if (!runtime.enabled)
+            return;
+        fastify.addHook('onRequest', function netgreenerOnRequest(request, _reply, done) {
+            const req = request;
+            const entryTenant = resolveTenantFromHttpRequest(req, tenantConfig);
+            const method = (req.method || 'GET').toUpperCase();
+            const resolveServiceUnit = () => httpServiceUnit(method, req);
+            const tenantStore = enterTenantStore(entryTenant);
+            enterRequestAttribution({
+                resolveServiceUnit,
+                serviceUnit: resolveServiceUnit(),
+            });
+            setRequestState(req, {
+                tenantStore,
+                method,
+                started: process.hrtime.bigint(),
+                resourceMark: beginProcessResourceSample(),
+                recorded: false,
+            });
+            if (typeof done === 'function') {
+                ;
+                done();
+            }
+        });
+        const finish = (request, reply, done) => {
+            const req = request;
+            const state = getRequestState(req);
+            if (!state || state.recorded) {
+                if (typeof done === 'function')
+                    done();
+                return;
+            }
+            state.recorded = true;
+            const durationMs = Number(process.hrtime.bigint() - state.started) / 1e6;
+            const resources = endProcessResourceSample(state.resourceMark);
+            const path = fastifyRouteTemplate(req);
+            const statusCode = typeof reply?.statusCode === 'number'
+                ? reply.statusCode
+                : 200;
+            runWithTenantContext(state.tenantStore.current, () => {
+                runtime.recordHttp({
+                    method: state.method,
+                    path,
+                    statusCode,
+                    durationMs,
+                    cpuTimeMs: resources.cpuTimeMs,
+                    peakRssKb: resources.rssKb,
+                });
+            });
+            if (typeof done === 'function')
+                done();
+        };
+        fastify.addHook('onResponse', function netgreenerOnResponse(request, reply, done) {
+            finish(request, reply, done);
+        });
+    };
+    // Break Fastify encapsulation so root `register(plugin)` meters sibling routes
+    // (same intent as `fastify-plugin` without a hard dependency).
+    const pluginMeta = plugin;
+    pluginMeta[Symbol.for('skip-override')] = true;
+    pluginMeta[Symbol.for('fastify.display-name')] = 'netgreener-fastify';
+    return plugin;
+}
+export function getFastifyRuntime() {
+    return getRuntime({ collector: 'fastify_middleware', framework: 'fastify' });
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @netgreener/runtime — Node emitter for NetGreener.
+ *
+ * N0: contracts · N1: Express/Fastify/Nest-via-adapter + RunSession flush
+ * N2: outbound fetch meter · N3: BullMQ worker + process/cron runtime
+ * Does not modify Python CLI/runtime capability.
+ */
+export type { AllocationReconciliationV0, EvidenceGrades, ExternalApiModelBucket, ExternalApiProvider, ExternalApiTenantBucket, ExternalApiV0, MeasurementProvenance, RunContext, RuntimeSessionMetadata, ServiceRuntimeTenantBucket, ServiceRuntimeUnit, ServiceRuntimeV0, TenantId, } from './types.js';
+export { validateExternalApiV0, validateMeasurementProvenance, validateRuntimeSessionMetadata, validateServiceRuntimeV0, type ContractIssue, type ContractResult, } from './contract/index.js';
+export { loadRuntimeConfig, configReady, type RuntimeConfig } from './config.js';
+export { COMPATIBLE_COLLECTOR_METADATA, COLLECTOR_METADATA_NOTES, isCompatibleCollectorMetadata, type CompatibleCollectorMetadata, } from './collectorMetadata.js';
+export { validateObservationEnvelope, classifyObservationDelivery, projectSemanticEnvelopeToProtobufView, validateObservationProtobufView, validateObservationDualView, } from './contract/observation-v1.mjs';
+export { ServiceRuntimeAggregator } from './aggregator.js';
+export { beginProcessResourceSample, endProcessResourceSample, currentRssKb, type ProcessResourceMark, type ProcessResourceSample, } from './processResources.js';
+export { buildRuntimeHealthV0, mergeHealthIntoMetadata, markHooksActive, type RuntimeHealthV0, type RuntimeHealthStatus, } from './runtimeHealth.js';
+export { newRuntimeWindowId } from './windowId.js';
+export { uploadRunSession, type RunSessionCreatePayload, type UploadResult, } from './uploader.js';
+export { resolveObservationExporter, exportModeFromEnv, DirectRunSessionExporter, ThinRunSessionExporter, CollectorRunSessionExporter, type ExportMode, type ExportResult, type ObservationExporter, type ObservationBatchDocument, } from './exporter.js';
+export { detectServerlessPlatformSignals, flushModeRequestsThin, type ServerlessPlatformHint, type ServerlessPlatformSignal, } from './serverlessHints.js';
+export { sendCollectorEvent, encodeCollectorFrame, normalizeCollectorEndpoint, type CollectorIpcAck, } from './collectorIpc.js';
+export { NetGreenerRuntime, getRuntime, _resetRuntimeForTests, type FlushKind, type NetGreenerRuntimeOptions, } from './runtime.js';
+export { netgreenerExpressMiddleware, getExpressRuntime, type ExpressRequest, type ExpressResponse, type ExpressNext, } from './express.js';
+export { netgreenerFastifyPlugin, getFastifyRuntime, fastifyRouteTemplate, bindFastifyTenant, type FastifyLike, type FastifyRequestLike, type FastifyReplyLike, } from './fastify.js';
+export { applyNetGreenerNestHooks, detectNestHttpAdapter, getNestRuntime, netgreenerNestExpressMiddleware, netgreenerNestFastifyPlugin, type NestApplicationLike, type NestHttpAdapterKind, } from './nest.js';
+export { attachWindowTenantToRunContext, getTenantContext, loadTenantConfig, normalizeTenantId, resolveTenantFromHttpRequest, resolveTenantFromTaskData, runWithTenantContext, setTenantContext, tenantConfigFromRuntime, type TenantConfig, type TenantContext, } from './tenantContext.js';
+export { ExternalApiAggregator, buildExternalV0, clearExternalAggregator, getExternalAggregator, installOutboundInstrumentation, providerForHost, usageFromClientBody, _resetOutboundInstrumentationForTests, } from './externalApiMeter.js';
+export { attributionServiceUnit, getRequestAttribution, runWithRequestAttribution, } from './requestContext.js';
+export { getBullMqRuntime, netgreenerBullMqProcessor, runBullMqJobWithNetGreener, type BullMqJobLike, type BullMqProcessorOptions, } from './bullmq.js';
+export { bindProcessTenant, flushProcessRuntime, runWithProcessTenant, startProcessRuntime, type ProcessRuntimeOptions, } from './processRuntime.js';
+export { buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, buildServiceManifestFromPaths, listCandidateSourceFiles, NON_RESOURCE_CATEGORIES, RESOURCE_DOMAINS, admitAnalyzeCandidate, isNonResourceCategory, languageForPath, toResourceFindingCandidate, detectRetryAmplificationHits, detectApiOverconsumptionHits, detectUnboundedParallelismHits, detectPollingIdleHits, detectProcessChurnHits, detectRepeatedWorkHits, detectPerItemInsteadOfBatchHits, detectModelLoadInLoopHits, detectFullDatasetInMemoryHits, detectRepeatedFileReadHits, detectAllHitsAst, detectHotPathHitsAst, detectApiOverconsumptionHitsAst, detectPollingIdleHitsAst, detectProcessChurnHitsAst, detectRepeatedFileReadHitsAst, detectRepeatedWorkHitsAst, detectRetryAmplificationHitsAst, detectUnboundedParallelismHitsAst, detectFullDatasetInMemoryHitsAst, detectPerItemInsteadOfBatchHitsAst, detectModelLoadInLoopHitsAst, collectPreferAstHits, detectApiOverconsumptionHitsPreferAst, detectPollingIdleHitsPreferAst, detectProcessChurnHitsPreferAst, detectRepeatedFileReadHitsPreferAst, detectRepeatedWorkHitsPreferAst, detectRetryAmplificationHitsPreferAst, detectUnboundedParallelismHitsPreferAst, detectFullDatasetInMemoryHitsPreferAst, detectPerItemInsteadOfBatchHitsPreferAst, detectModelLoadInLoopHitsPreferAst, isTypescriptAnalyzeAvailable, tryLoadTypescript, allResourceFindingsValid, filterValidResourceFindings, validateResourceFindingCandidate, countGateFindings, findingsExceedFailThreshold, formatAnalyzeGateFailureMessage, resolveAnalyzeGateLimit, buildAnalyzeGateSummary, buildResourceAnalyzeResultFromPaths, buildResourceFindingsFromSources, type ServiceEndpointUnit, type ServiceFileExtraction, type ServiceManifestV0, type ServiceTaskUnit, type ListCandidateSourceFilesOptions, type AdmissionDecision, type NonResourceCategory, type ResourceDomain, type ResourceCandidateHit, type ResourceFindingCandidateV1, type ResourcePrimaryDomain, type BuildResourceFindingsOptions, type ResourceAnalyzeResultV0, type ResourceFindingValidation, type ResourceFindingValidationError, type AnalyzeGateLimit, type AnalyzeGateSummaryV0, type AstHitBundle, } from './analyze/index.js';
+export { assertNoFalseCgroupClaim, CPU_SOURCE_DURATION_PROXY, CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS, missingnessByStatus, NODE_DIRECT_MISSINGNESS_INVENTORY, type MeasurementStatus, type MissingnessEntry, } from './n4/missingnessInventory.js';
+export { NODE_DEPLOYMENT_MATRIX, claimedDeployModes, assertProductionScopeIsExplicit, type DeployModeEntry, type DeployModeStatus, } from './n4/deploymentMatrix.js';

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * @netgreener/runtime — Node emitter for NetGreener.
+ *
+ * N0: contracts · N1: Express/Fastify/Nest-via-adapter + RunSession flush
+ * N2: outbound fetch meter · N3: BullMQ worker + process/cron runtime
+ * Does not modify Python CLI/runtime capability.
+ */
+export { validateExternalApiV0, validateMeasurementProvenance, validateRuntimeSessionMetadata, validateServiceRuntimeV0, } from './contract/index.js';
+export { loadRuntimeConfig, configReady } from './config.js';
+export { COMPATIBLE_COLLECTOR_METADATA, COLLECTOR_METADATA_NOTES, isCompatibleCollectorMetadata, } from './collectorMetadata.js';
+export { validateObservationEnvelope, classifyObservationDelivery, projectSemanticEnvelopeToProtobufView, validateObservationProtobufView, validateObservationDualView, } from './contract/observation-v1.mjs';
+export { ServiceRuntimeAggregator } from './aggregator.js';
+export { beginProcessResourceSample, endProcessResourceSample, currentRssKb, } from './processResources.js';
+export { buildRuntimeHealthV0, mergeHealthIntoMetadata, markHooksActive, } from './runtimeHealth.js';
+export { newRuntimeWindowId } from './windowId.js';
+export { uploadRunSession, } from './uploader.js';
+export { resolveObservationExporter, exportModeFromEnv, DirectRunSessionExporter, ThinRunSessionExporter, CollectorRunSessionExporter, } from './exporter.js';
+export { detectServerlessPlatformSignals, flushModeRequestsThin, } from './serverlessHints.js';
+export { sendCollectorEvent, encodeCollectorFrame, normalizeCollectorEndpoint, } from './collectorIpc.js';
+export { NetGreenerRuntime, getRuntime, _resetRuntimeForTests, } from './runtime.js';
+export { netgreenerExpressMiddleware, getExpressRuntime, } from './express.js';
+export { netgreenerFastifyPlugin, getFastifyRuntime, fastifyRouteTemplate, bindFastifyTenant, } from './fastify.js';
+export { applyNetGreenerNestHooks, detectNestHttpAdapter, getNestRuntime, netgreenerNestExpressMiddleware, netgreenerNestFastifyPlugin, } from './nest.js';
+export { attachWindowTenantToRunContext, getTenantContext, loadTenantConfig, normalizeTenantId, resolveTenantFromHttpRequest, resolveTenantFromTaskData, runWithTenantContext, setTenantContext, tenantConfigFromRuntime, } from './tenantContext.js';
+export { ExternalApiAggregator, buildExternalV0, clearExternalAggregator, getExternalAggregator, installOutboundInstrumentation, providerForHost, usageFromClientBody, _resetOutboundInstrumentationForTests, } from './externalApiMeter.js';
+export { attributionServiceUnit, getRequestAttribution, runWithRequestAttribution, } from './requestContext.js';
+export { getBullMqRuntime, netgreenerBullMqProcessor, runBullMqJobWithNetGreener, } from './bullmq.js';
+export { bindProcessTenant, flushProcessRuntime, runWithProcessTenant, startProcessRuntime, } from './processRuntime.js';
+export { buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, buildServiceManifestFromPaths, listCandidateSourceFiles, NON_RESOURCE_CATEGORIES, RESOURCE_DOMAINS, admitAnalyzeCandidate, isNonResourceCategory, languageForPath, toResourceFindingCandidate, detectRetryAmplificationHits, detectApiOverconsumptionHits, detectUnboundedParallelismHits, detectPollingIdleHits, detectProcessChurnHits, detectRepeatedWorkHits, detectPerItemInsteadOfBatchHits, detectModelLoadInLoopHits, detectFullDatasetInMemoryHits, detectRepeatedFileReadHits, detectAllHitsAst, detectHotPathHitsAst, detectApiOverconsumptionHitsAst, detectPollingIdleHitsAst, detectProcessChurnHitsAst, detectRepeatedFileReadHitsAst, detectRepeatedWorkHitsAst, detectRetryAmplificationHitsAst, detectUnboundedParallelismHitsAst, detectFullDatasetInMemoryHitsAst, detectPerItemInsteadOfBatchHitsAst, detectModelLoadInLoopHitsAst, collectPreferAstHits, detectApiOverconsumptionHitsPreferAst, detectPollingIdleHitsPreferAst, detectProcessChurnHitsPreferAst, detectRepeatedFileReadHitsPreferAst, detectRepeatedWorkHitsPreferAst, detectRetryAmplificationHitsPreferAst, detectUnboundedParallelismHitsPreferAst, detectFullDatasetInMemoryHitsPreferAst, detectPerItemInsteadOfBatchHitsPreferAst, detectModelLoadInLoopHitsPreferAst, isTypescriptAnalyzeAvailable, tryLoadTypescript, allResourceFindingsValid, filterValidResourceFindings, validateResourceFindingCandidate, countGateFindings, findingsExceedFailThreshold, formatAnalyzeGateFailureMessage, resolveAnalyzeGateLimit, buildAnalyzeGateSummary, buildResourceAnalyzeResultFromPaths, buildResourceFindingsFromSources, } from './analyze/index.js';
+export { assertNoFalseCgroupClaim, CPU_SOURCE_DURATION_PROXY, CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS, missingnessByStatus, NODE_DIRECT_MISSINGNESS_INVENTORY, } from './n4/missingnessInventory.js';
+export { NODE_DEPLOYMENT_MATRIX, claimedDeployModes, assertProductionScopeIsExplicit, } from './n4/deploymentMatrix.js';

package/dist/n4/deploymentMatrix.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CAP-R6 deployment-mode matrix (Node Runtime production scope).
+ *
+ * Freezes what we **claim** vs **exercise** vs **exclude**. Does not invent
+ * Kubernetes/container live evidence. Does not flip export defaults.
+ */
+export type DeployModeStatus = 'claimed_and_exercised' | 'documented_degraded' | 'not_claimed' | 'open';
+export type DeployModeEntry = {
+    check_id: string;
+    mode: string;
+    status: DeployModeStatus;
+    evidence: string;
+    notes: string;
+};
+/**
+ * Production claim scope for Node Runtime (2026-09-24):
+ * long-running process / VM-like host with default ``direct`` export.
+ * Container/K8s/CI/serverless are **not** silently included.
+ */
+export declare const NODE_DEPLOYMENT_MATRIX: readonly DeployModeEntry[];
+export declare function claimedDeployModes(): DeployModeEntry[];
+export declare function assertProductionScopeIsExplicit(): boolean;

package/dist/n4/deploymentMatrix.js

@@ -0,0 +1,57 @@
+/**
+ * CAP-R6 deployment-mode matrix (Node Runtime production scope).
+ *
+ * Freezes what we **claim** vs **exercise** vs **exclude**. Does not invent
+ * Kubernetes/container live evidence. Does not flip export defaults.
+ */
+/**
+ * Production claim scope for Node Runtime (2026-09-24):
+ * long-running process / VM-like host with default ``direct`` export.
+ * Container/K8s/CI/serverless are **not** silently included.
+ */
+export const NODE_DEPLOYMENT_MATRIX = [
+    {
+        check_id: 'CHK-R6.vm-process',
+        mode: 'long_running_process',
+        status: 'claimed_and_exercised',
+        evidence: 'LIVE_ACCEPTANCE_EVIDENCE.md (HTTP dogfood, BullMQ 40654/55, process 40660/61)',
+        notes: 'Primary production claim surface for Node Runtime',
+    },
+    {
+        check_id: 'CHK-R6.container',
+        mode: 'container',
+        status: 'not_claimed',
+        evidence: 'none retained as production gate',
+        notes: 'May work identically to process; do not claim until dedicated live gate',
+    },
+    {
+        check_id: 'CHK-R6.kubernetes',
+        mode: 'kubernetes',
+        status: 'not_claimed',
+        evidence: 'none',
+        notes: 'Out of Node Runtime production claim until exercised',
+    },
+    {
+        check_id: 'CHK-R6.ci-job',
+        mode: 'ci_job',
+        status: 'documented_degraded',
+        evidence: 'unit/integration in CI; not a customer Runtime deployment claim',
+        notes: 'CI proves library; not a production Runtime deploy mode',
+    },
+    {
+        check_id: 'CHK-R6.serverless-degraded',
+        mode: 'serverless_thin',
+        status: 'documented_degraded',
+        evidence: 'serverlessHints unit tests; EXPORT_MODE=thin explicit only',
+        notes: 'Best-effort thin flush; no auto-cutover; not durable collector',
+    },
+];
+export function claimedDeployModes() {
+    return NODE_DEPLOYMENT_MATRIX.filter((e) => e.status === 'claimed_and_exercised');
+}
+export function assertProductionScopeIsExplicit() {
+    const claimed = claimedDeployModes();
+    if (claimed.length !== 1)
+        return false;
+    return claimed[0].mode === 'long_running_process';
+}

package/dist/n4/missingnessInventory.d.ts

@@ -0,0 +1,22 @@
+/**
+ * N4 / N5 missingness inventory — Node Runtime (direct emitter).
+ *
+ * Documents what is measured vs proxy vs not measured. Does not invent
+ * cgroup/process-tree values or change the upload pipeline.
+ */
+import { CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS } from '../processResources.js';
+export type MeasurementStatus = 'measured' | 'proxy' | 'derived_estimate' | 'not_measured' | 'absent';
+export type MissingnessEntry = {
+    signal_id: string;
+    status: MeasurementStatus;
+    /** Provenance string when present on session_metadata (e.g. cpu_source). */
+    provenance?: string;
+    notes: string;
+};
+export { CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS };
+/** Fallback when a sample omits measured CPU (tests / bare recordHttp). */
+export declare const CPU_SOURCE_DURATION_PROXY = "request_duration_proxy";
+/** Frozen inventory for `@netgreener/runtime` default direct path (2026-09-24). */
+export declare const NODE_DIRECT_MISSINGNESS_INVENTORY: readonly MissingnessEntry[];
+export declare function missingnessByStatus(status: MeasurementStatus): MissingnessEntry[];
+export declare function assertNoFalseCgroupClaim(cpuSource: string | undefined): boolean;

package/dist/n4/missingnessInventory.js

@@ -0,0 +1,72 @@
+/**
+ * N4 / N5 missingness inventory — Node Runtime (direct emitter).
+ *
+ * Documents what is measured vs proxy vs not measured. Does not invent
+ * cgroup/process-tree values or change the upload pipeline.
+ */
+import { CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS, } from '../processResources.js';
+export { CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS };
+/** Fallback when a sample omits measured CPU (tests / bare recordHttp). */
+export const CPU_SOURCE_DURATION_PROXY = 'request_duration_proxy';
+/** Frozen inventory for `@netgreener/runtime` default direct path (2026-09-24). */
+export const NODE_DIRECT_MISSINGNESS_INVENTORY = [
+    {
+        signal_id: 'service_unit.calls_errors_duration',
+        status: 'measured',
+        notes: 'Adapter samples from HTTP middleware / BullMQ / process helpers',
+    },
+    {
+        signal_id: 'tenant.by_tenant',
+        status: 'measured',
+        notes: 'When tenant bind is configured; otherwise absent',
+    },
+    {
+        signal_id: 'external_api_v0',
+        status: 'measured',
+        notes: 'When outbound instrumentation is installed',
+    },
+    {
+        signal_id: 'unit.cpu_seconds_total',
+        status: 'measured',
+        provenance: CPU_SOURCE_PROCESS,
+        notes: 'process.cpuUsage delta on Express/Fastify/BullMQ/process hooks; duration proxy only if sample omits CPU',
+    },
+    {
+        signal_id: 'unit.peak_rss_kb_max',
+        status: 'measured',
+        provenance: MEMORY_SOURCE_PROCESS,
+        notes: 'process.memoryUsage().rss at sample end (KiB)',
+    },
+    {
+        signal_id: 'unit.energy_kwh_carbon_g',
+        status: 'derived_estimate',
+        notes: 'Emitter-side TDP util estimate (prefers measured CPU when present); cloud policy ownership open',
+    },
+    {
+        signal_id: 'collector.process_tree_cgroup',
+        status: 'not_measured',
+        notes: 'Requires shared MP2 collector sampler + Node launcher — still open',
+    },
+    {
+        signal_id: 'runtime_health_v0',
+        status: 'measured',
+        notes: 'Export attempt/ok/fail/in-flight-skip counters + hooks_active on each flush (CAP-R5 honesty)',
+    },
+    {
+        signal_id: 'host_gpu_energy_meters',
+        status: 'not_measured',
+        notes: 'Out of thin-adapter scope',
+    },
+];
+export function missingnessByStatus(status) {
+    return NODE_DIRECT_MISSINGNESS_INVENTORY.filter((e) => e.status === status);
+}
+export function assertNoFalseCgroupClaim(cpuSource) {
+    if (!cpuSource)
+        return true;
+    const lowered = cpuSource.toLowerCase();
+    if (lowered.includes('cgroup') || lowered.includes('process_tree')) {
+        return false;
+    }
+    return true;
+}

package/dist/nest.d.ts

@@ -0,0 +1,42 @@
+/**
+ * NestJS via underlying HTTP adapter (experimental N1 v0).
+ *
+ * Nest does not need a separate interception stack: apply Express middleware or
+ * the Fastify plugin on the adapter Nest already uses. No hard ``@nestjs/*``
+ * dependency.
+ */
+import { type ExpressNext, type ExpressRequest, type ExpressResponse } from './express.js';
+import { type FastifyLike } from './fastify.js';
+import { type NetGreenerRuntime, type NetGreenerRuntimeOptions } from './runtime.js';
+/** Duck-typed Nest application surface used for adapter detection. */
+export type NestApplicationLike = {
+    getHttpAdapter?: () => {
+        getType?: () => string;
+        getInstance?: () => FastifyLike | unknown;
+    };
+    use?: (middleware: unknown) => unknown;
+};
+export type NestHttpAdapterKind = 'express' | 'fastify' | 'unknown';
+/**
+ * Detect whether a Nest app is backed by Express or Fastify.
+ * Uses ``HttpAdapter.getType()`` when present (Nest public API).
+ */
+export declare function detectNestHttpAdapter(app: NestApplicationLike): NestHttpAdapterKind;
+/**
+ * Express-adapter Nest apps: ``app.use(netgreenerNestExpressMiddleware())``
+ * after ``NestFactory.create`` (same place you add other Express middleware).
+ */
+export declare function netgreenerNestExpressMiddleware(opts?: NetGreenerRuntimeOptions): (req: ExpressRequest, res: ExpressResponse, next: ExpressNext) => void;
+/**
+ * Fastify-adapter Nest apps: register on the underlying Fastify instance::
+ *
+ *   const instance = app.getHttpAdapter().getInstance()
+ *   await instance.register(netgreenerNestFastifyPlugin())
+ */
+export declare function netgreenerNestFastifyPlugin(opts?: NetGreenerRuntimeOptions): (fastify: FastifyLike) => Promise<void>;
+/**
+ * Convenience: apply the matching hook for the Nest HTTP adapter in use.
+ * Returns the detected adapter kind. Fastify path is async (``register``).
+ */
+export declare function applyNetGreenerNestHooks(app: NestApplicationLike, opts?: NetGreenerRuntimeOptions): Promise<NestHttpAdapterKind>;
+export declare function getNestRuntime(kind?: 'express' | 'fastify'): NetGreenerRuntime;

package/dist/nest.js

@@ -0,0 +1,87 @@
+/**
+ * NestJS via underlying HTTP adapter (experimental N1 v0).
+ *
+ * Nest does not need a separate interception stack: apply Express middleware or
+ * the Fastify plugin on the adapter Nest already uses. No hard ``@nestjs/*``
+ * dependency.
+ */
+import { netgreenerExpressMiddleware, } from './express.js';
+import { netgreenerFastifyPlugin } from './fastify.js';
+import { getRuntime, } from './runtime.js';
+/**
+ * Detect whether a Nest app is backed by Express or Fastify.
+ * Uses ``HttpAdapter.getType()`` when present (Nest public API).
+ */
+export function detectNestHttpAdapter(app) {
+    try {
+        const adapter = app.getHttpAdapter?.();
+        const raw = (adapter?.getType?.() || '').toLowerCase().trim();
+        if (raw === 'express')
+            return 'express';
+        if (raw === 'fastify')
+            return 'fastify';
+        const name = adapter?.constructor?.name || '';
+        const lower = name.toLowerCase();
+        if (lower.includes('fastify'))
+            return 'fastify';
+        if (lower.includes('express'))
+            return 'express';
+    }
+    catch {
+        /* ignore */
+    }
+    return 'unknown';
+}
+/**
+ * Express-adapter Nest apps: ``app.use(netgreenerNestExpressMiddleware())``
+ * after ``NestFactory.create`` (same place you add other Express middleware).
+ */
+export function netgreenerNestExpressMiddleware(opts = {}) {
+    return netgreenerExpressMiddleware({
+        ...opts,
+        collector: opts.collector ?? 'nest_express_middleware',
+        framework: opts.framework ?? 'nest',
+    });
+}
+/**
+ * Fastify-adapter Nest apps: register on the underlying Fastify instance::
+ *
+ *   const instance = app.getHttpAdapter().getInstance()
+ *   await instance.register(netgreenerNestFastifyPlugin())
+ */
+export function netgreenerNestFastifyPlugin(opts = {}) {
+    return netgreenerFastifyPlugin({
+        ...opts,
+        collector: opts.collector ?? 'nest_fastify_middleware',
+        framework: opts.framework ?? 'nest',
+    });
+}
+/**
+ * Convenience: apply the matching hook for the Nest HTTP adapter in use.
+ * Returns the detected adapter kind. Fastify path is async (``register``).
+ */
+export async function applyNetGreenerNestHooks(app, opts = {}) {
+    const kind = detectNestHttpAdapter(app);
+    if (kind === 'express') {
+        if (typeof app.use !== 'function') {
+            throw new Error('Nest Express adapter expected app.use(...)');
+        }
+        app.use(netgreenerNestExpressMiddleware(opts));
+        return kind;
+    }
+    if (kind === 'fastify') {
+        const instance = app.getHttpAdapter?.()?.getInstance?.();
+        if (!instance || typeof instance.register !== 'function') {
+            throw new Error('Nest Fastify adapter expected getInstance().register(...)');
+        }
+        await instance.register(netgreenerNestFastifyPlugin(opts));
+        return kind;
+    }
+    throw new Error('Unknown Nest HTTP adapter — use netgreenerNestExpressMiddleware or netgreenerNestFastifyPlugin explicitly');
+}
+export function getNestRuntime(kind = 'express') {
+    if (kind === 'fastify') {
+        return getRuntime({ collector: 'nest_fastify_middleware', framework: 'nest' });
+    }
+    return getRuntime({ collector: 'nest_express_middleware', framework: 'nest' });
+}

package/dist/processResources.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Process-level CPU / RSS sampling for Node Runtime (CAP-R4 / N5).
+ *
+ * Mirrors Python ASGI middleware: ``time.process_time()`` + ``psutil`` RSS.
+ * Uses Node ``process.cpuUsage`` / ``process.memoryUsage().rss`` only —
+ * never invents cgroup or process-tree values.
+ */
+export declare const CPU_SOURCE_PROCESS = "node_process_cpu_usage";
+export declare const MEMORY_SOURCE_PROCESS = "node_process_memory_rss";
+export type ProcessResourceMark = {
+    /** ``process.cpuUsage()`` snapshot at begin. */
+    cpuStart: NodeJS.CpuUsage;
+};
+export type ProcessResourceSample = {
+    /** Process CPU time attributed to the interval (milliseconds). */
+    cpuTimeMs: number;
+    /** Current RSS in KiB at end of interval. */
+    rssKb: number;
+};
+/** Start a CPU interval (call at request/task entry). */
+export declare function beginProcessResourceSample(): ProcessResourceMark;
+/**
+ * End a CPU interval and read current RSS.
+ * ``cpuUsage(previous)`` returns user+system microseconds since ``previous``.
+ */
+export declare function endProcessResourceSample(mark: ProcessResourceMark): ProcessResourceSample;
+/** Point-in-time RSS (KiB) when no interval mark is available. */
+export declare function currentRssKb(): number;

package/dist/processResources.js

@@ -0,0 +1,31 @@
+/**
+ * Process-level CPU / RSS sampling for Node Runtime (CAP-R4 / N5).
+ *
+ * Mirrors Python ASGI middleware: ``time.process_time()`` + ``psutil`` RSS.
+ * Uses Node ``process.cpuUsage`` / ``process.memoryUsage().rss`` only —
+ * never invents cgroup or process-tree values.
+ */
+export const CPU_SOURCE_PROCESS = 'node_process_cpu_usage';
+export const MEMORY_SOURCE_PROCESS = 'node_process_memory_rss';
+/** Start a CPU interval (call at request/task entry). */
+export function beginProcessResourceSample() {
+    return { cpuStart: process.cpuUsage() };
+}
+/**
+ * End a CPU interval and read current RSS.
+ * ``cpuUsage(previous)`` returns user+system microseconds since ``previous``.
+ */
+export function endProcessResourceSample(mark) {
+    const delta = process.cpuUsage(mark.cpuStart);
+    const cpuTimeMs = (delta.user + delta.system) / 1000;
+    const rssKb = Math.round(process.memoryUsage().rss / 1024);
+    return {
+        cpuTimeMs: Number.isFinite(cpuTimeMs) && cpuTimeMs >= 0 ? cpuTimeMs : 0,
+        rssKb: Number.isFinite(rssKb) && rssKb >= 0 ? rssKb : 0,
+    };
+}
+/** Point-in-time RSS (KiB) when no interval mark is available. */
+export function currentRssKb() {
+    const rssKb = Math.round(process.memoryUsage().rss / 1024);
+    return Number.isFinite(rssKb) && rssKb >= 0 ? rssKb : 0;
+}