@netgreener/runtime 0.1.0

package/dist/analyze/schemas/resource-finding.schema.json

@@ -0,0 +1,352 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.netgreener.com/contracts/resource/v1/resource-finding.schema.json",
+  "title": "NetGreener resource_finding_v1 (RD1 draft)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "finding_id",
+    "project_id",
+    "evidence_state",
+    "comparison_origin",
+    "lifecycle_status",
+    "verification_outcome",
+    "primary_domain",
+    "mechanism_id",
+    "title",
+    "scope",
+    "lineage"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schema_version": { "const": "resource_finding_v1" },
+    "finding_id": { "type": "string", "minLength": 8, "maxLength": 128 },
+    "project_id": { "type": "string", "minLength": 1, "maxLength": 64 },
+    "evidence_state": {
+      "enum": ["candidate", "observed", "regression_supported", "causal_supported"]
+    },
+    "comparison_origin": {
+      "enum": ["none", "ci", "production", "benchmark", "manual_experiment"]
+    },
+    "lifecycle_status": {
+      "enum": ["pending_admission", "open", "acknowledged", "resolved", "dismissed", "reopened"]
+    },
+    "verification_outcome": {
+      "enum": [
+        "not_run",
+        "verified_improvement",
+        "no_material_change",
+        "regressed",
+        "inconclusive",
+        "not_applicable",
+        "failed_guardrail"
+      ]
+    },
+    "primary_domain": {
+      "enum": [
+        "compute.cpu",
+        "compute.gpu",
+        "memory.host",
+        "memory.gpu",
+        "storage.io",
+        "network.io",
+        "external_api"
+      ]
+    },
+    "secondary_domains": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "compute.cpu",
+          "compute.gpu",
+          "memory.host",
+          "memory.gpu",
+          "storage.io",
+          "network.io",
+          "external_api"
+        ]
+      }
+    },
+    "mechanism_id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,63}$" },
+    "title": { "type": "string", "minLength": 8, "maxLength": 200 },
+    "scope": { "$ref": "#/$defs/scope" },
+    "workload": { "$ref": "#/$defs/workload" },
+    "observed": { "$ref": "#/$defs/metricPoint" },
+    "baseline": { "$ref": "#/$defs/baseline" },
+    "impact": { "$ref": "#/$defs/impact" },
+    "materiality": { "$ref": "#/$defs/materiality" },
+    "evidence": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/evidenceItem" }
+    },
+    "confidence": { "$ref": "#/$defs/confidence" },
+    "optimization": { "$ref": "#/$defs/optimization" },
+    "lineage": { "$ref": "#/$defs/lineage" },
+    "compatibility_fingerprint": { "$ref": "#/$defs/compatibilityFingerprint" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "evidence_state": { "const": "candidate" } } },
+      "then": {
+        "properties": {
+          "comparison_origin": { "const": "none" },
+          "lifecycle_status": { "const": "pending_admission" },
+          "verification_outcome": { "const": "not_run" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "evidence_state": { "enum": ["regression_supported", "causal_supported"] }
+        }
+      },
+      "then": {
+        "required": ["workload", "observed", "baseline", "impact", "materiality", "evidence", "confidence", "optimization"]
+      }
+    }
+  ],
+  "$defs": {
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "language"],
+      "properties": {
+        "kind": { "enum": ["service_unit", "task", "process", "ci_step", "script", "function"] },
+        "id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "language": { "type": "string", "pattern": "^[a-z][a-z0-9+-]{0,31}$" },
+        "runtime": { "type": "string", "maxLength": 80 },
+        "release_id": { "type": "string", "maxLength": 120 },
+        "git_sha": { "type": "string", "maxLength": 64 },
+        "source_locations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path"],
+            "properties": {
+              "path": { "type": "string", "maxLength": 512 },
+              "start_line": { "type": "integer", "minimum": 1 },
+              "end_line": { "type": "integer", "minimum": 1 },
+              "symbol": { "type": "string", "maxLength": 120 }
+            }
+          }
+        }
+      }
+    },
+    "workload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["functional_unit"],
+      "properties": {
+        "functional_unit": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "units": { "type": "number", "minimum": 0 },
+        "input_fingerprint": { "type": "string", "maxLength": 128 },
+        "quality_guards": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["metric", "operator", "threshold", "passed"],
+            "properties": {
+              "metric": { "type": "string" },
+              "operator": { "enum": [">=", "<=", "=="] },
+              "threshold": { "type": "number" },
+              "observed": { "type": ["number", "null"] },
+              "passed": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "metricPoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["metric", "value", "unit"],
+      "properties": {
+        "metric": { "type": "string", "minLength": 1 },
+        "value": { "type": "number" },
+        "unit": { "type": "string", "minLength": 1 },
+        "window_start": { "type": "string", "format": "date-time" },
+        "window_end": { "type": "string", "format": "date-time" }
+      }
+    },
+    "baseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value", "unit", "sample_count", "cohort_key", "statistic"],
+      "properties": {
+        "value": { "type": "number" },
+        "unit": { "type": "string" },
+        "sample_count": { "type": "integer", "minimum": 1 },
+        "cohort_key": { "type": "string", "minLength": 8 },
+        "statistic": { "enum": ["median", "mean", "p50", "robust_mean"] },
+        "uncertainty": { "$ref": "#/$defs/uncertainty" }
+      }
+    },
+    "uncertainty": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["method", "low", "high", "unit"],
+      "properties": {
+        "method": { "type": "string" },
+        "low": { "type": "number" },
+        "high": { "type": "number" },
+        "unit": { "type": "string" }
+      }
+    },
+    "impact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["impact_state"],
+      "properties": {
+        "normalized_delta": { "$ref": "#/$defs/metricPoint" },
+        "projected_excess": { "$ref": "#/$defs/metricPoint" },
+        "relative_delta_fraction": { "type": ["number", "null"] },
+        "recoverable_low": { "type": ["number", "null"] },
+        "recoverable_likely": { "type": ["number", "null"] },
+        "recoverable_high": { "type": ["number", "null"] },
+        "cost_usd": { "type": ["number", "null"] },
+        "energy_kwh": { "type": ["number", "null"] },
+        "impact_state": { "enum": ["unknown", "modeled", "measured"] }
+      }
+    },
+    "materiality": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["policy_id", "decision"],
+      "properties": {
+        "policy_id": { "type": "string" },
+        "absolute_floor_passed": { "type": "boolean" },
+        "relative_floor_passed": { "type": "boolean" },
+        "sample_floor_passed": { "type": "boolean" },
+        "decision": { "enum": ["pending", "material", "not_material", "abstain"] }
+      }
+    },
+    "evidenceItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["evidence_id", "kind", "captured_at", "value_state"],
+      "properties": {
+        "evidence_id": { "type": "string", "minLength": 8 },
+        "kind": {
+          "enum": [
+            "source",
+            "observation",
+            "profile",
+            "ci_comparison",
+            "runtime_baseline",
+            "provider_usage",
+            "billing",
+            "benchmark",
+            "user_disposition"
+          ]
+        },
+        "captured_at": { "type": "string", "format": "date-time" },
+        "scope": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "id"],
+          "properties": {
+            "kind": { "type": "string" },
+            "id": { "type": "string" }
+          }
+        },
+        "temporality": { "enum": ["delta", "cumulative", "instant"] },
+        "interval": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "start": { "type": "string", "format": "date-time" },
+            "end": { "type": "string", "format": "date-time" }
+          }
+        },
+        "observation_ids": { "type": "array", "items": { "type": "string" } },
+        "metric": { "type": "string" },
+        "value": { "type": "number" },
+        "unit": { "type": "string" },
+        "aggregation": { "type": "string" },
+        "functional_unit": { "type": "string" },
+        "method": { "type": "string" },
+        "method_version": { "type": "string" },
+        "evidence_grade": { "type": "string" },
+        "coverage_fraction": { "type": "number", "minimum": 0, "maximum": 1 },
+        "dropped_event_state": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["dropped", "count"],
+          "properties": {
+            "dropped": { "type": "boolean" },
+            "count": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "uncertainty": { "$ref": "#/$defs/uncertainty" },
+        "value_state": { "enum": ["observed", "estimated", "derived", "missing"] }
+      }
+    },
+    "confidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "detection_confidence",
+        "attribution_confidence",
+        "measurement_confidence",
+        "comparison_confidence",
+        "optimization_confidence",
+        "causal_confidence"
+      ],
+      "properties": {
+        "detection_confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "attribution_confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "measurement_confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "comparison_confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "optimization_confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "causal_confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "reason_codes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "optimization": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hypothesis_id", "summary", "risk"],
+      "properties": {
+        "hypothesis_id": { "type": "string", "minLength": 4 },
+        "summary": { "type": "string", "minLength": 8, "maxLength": 400 },
+        "verification_plan": { "type": "object" },
+        "risk": { "enum": ["low", "medium", "high"] }
+      }
+    },
+    "lineage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["detector_id", "detector_version", "policy_version"],
+      "properties": {
+        "detector_id": { "type": "string", "minLength": 1 },
+        "detector_version": { "type": "string", "minLength": 1 },
+        "policy_version": { "type": "string", "minLength": 1 },
+        "observation_ids": { "type": "array", "items": { "type": "string" } },
+        "benchmark_result_ids": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "compatibilityFingerprint": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "language": { "type": "string" },
+        "runtime": { "type": "string" },
+        "framework": { "type": "string" },
+        "dependency_lock_digest": { "type": "string" },
+        "hardware_model": { "type": "string" },
+        "cpu_quota": { "type": "string" },
+        "memory_limit": { "type": "string" },
+        "workload_id": { "type": "string" },
+        "functional_unit": { "type": "string" },
+        "environment": { "type": "string" },
+        "release_id": { "type": "string" },
+        "ci_workflow_sha": { "type": "string" }
+      }
+    }
+  }
+}

package/dist/analyze/serviceDiscovery.d.ts

@@ -0,0 +1,66 @@
+/**
+ * MP4 Analyze scaffold — JS/TS service discovery (experimental).
+ *
+ * Twin of Python ``netgreener.service_discovery`` for Node ecosystems.
+ * Heuristic / regex extraction only (no TypeScript AST yet). Additive: does
+ * **not** wire into CLI upload, VSCE, or the RunSession pipeline.
+ *
+ * Canonical ``service_unit`` keys match runtime:
+ *   - endpoints: ``"<METHOD> <path>"``
+ *   - tasks: ``"task:<name>"``
+ */
+export type ServiceEndpointUnit = {
+    service_unit: string;
+    unit_type: 'endpoint';
+    method: string;
+    path: string;
+    handler: string;
+    file: string;
+    line: number;
+    end_line: number;
+    is_async: boolean;
+    dynamic: boolean;
+    prefix_resolved: boolean;
+    /** Heuristic extractor confidence — not measured runtime evidence. */
+    evidence: 'heuristic_source';
+};
+export type ServiceTaskUnit = {
+    service_unit: string;
+    unit_type: 'task';
+    name: string;
+    handler: string;
+    file: string;
+    line: number;
+    end_line: number;
+    evidence: 'heuristic_source';
+};
+export type ServiceFileExtraction = {
+    frameworks: string[];
+    endpoints: ServiceEndpointUnit[];
+    tasks: ServiceTaskUnit[];
+};
+export type ServiceManifestV0 = {
+    schema: 'service_manifest_v0';
+    contract_status: 'mp4_scaffold';
+    framework: string | null;
+    frameworks_detected: string[];
+    entry_files: string[];
+    endpoints: ServiceEndpointUnit[];
+    tasks: ServiceTaskUnit[];
+    stats: {
+        endpoints: number;
+        tasks: number;
+        files_with_units: number;
+    };
+    notes: string[];
+};
+/** Frameworks whose imports / requires appear in ``source``. */
+export declare function detectFrameworks(source: string): string[];
+/**
+ * Extract service units from one JS/TS source string.
+ * Never throws on bad source — returns empty collections.
+ */
+export declare function extractServiceUnits(sourceCode: string, relPath?: string): ServiceFileExtraction;
+/** Project-level ``service_manifest_v0`` from ``{relPath: source}``. */
+export declare function buildServiceManifest(fileSources: Record<string, string>): ServiceManifestV0;
+export declare function isServiceProject(manifest: ServiceManifestV0): boolean;

package/dist/analyze/serviceDiscovery.js

@@ -0,0 +1,210 @@
+/**
+ * MP4 Analyze scaffold — JS/TS service discovery (experimental).
+ *
+ * Twin of Python ``netgreener.service_discovery`` for Node ecosystems.
+ * Heuristic / regex extraction only (no TypeScript AST yet). Additive: does
+ * **not** wire into CLI upload, VSCE, or the RunSession pipeline.
+ *
+ * Canonical ``service_unit`` keys match runtime:
+ *   - endpoints: ``"<METHOD> <path>"``
+ *   - tasks: ``"task:<name>"``
+ */
+const FRAMEWORK_IMPORT_HINTS = [
+    { id: 'express', pattern: /\bfrom\s+['"]express['"]|\brequire\(\s*['"]express['"]\s*\)/ },
+    { id: 'fastify', pattern: /\bfrom\s+['"]fastify['"]|\brequire\(\s*['"]fastify['"]\s*\)/ },
+    {
+        id: 'nest',
+        pattern: /\bfrom\s+['"]@nestjs\/(common|core|platform-express|platform-fastify)['"]/,
+    },
+    { id: 'bullmq', pattern: /\bfrom\s+['"]bullmq['"]|\brequire\(\s*['"]bullmq['"]\s*\)/ },
+    { id: 'next', pattern: /\bfrom\s+['"]next(\/|['"])|\brequire\(\s*['"]next['"]\s*\)/ },
+];
+const HTTP_ROUTE = /\b(?:app|router|server|fastify|instance)\.(get|post|put|delete|patch|head|options)\(\s*['"`]([^'"`]+)['"`]/gi;
+const NEST_MAPPING = /@(Get|Post|Put|Delete|Patch|Head|Options)\(\s*(?:['"`]([^'"`]*)['"`])?\s*\)/g;
+const BULLMQ_QUEUE_ADD = /\.add\(\s*['"`]([A-Za-z0-9_.:-]+)['"`]/g;
+function lineOf(source, index) {
+    if (index <= 0)
+        return 1;
+    let line = 1;
+    for (let i = 0; i < index && i < source.length; i += 1) {
+        if (source.charCodeAt(i) === 10)
+            line += 1;
+    }
+    return line;
+}
+function looksDynamic(path) {
+    return path.includes(':') || path.includes('*') || path.includes('{');
+}
+function normalizePath(path) {
+    if (!path)
+        return '/';
+    return path.startsWith('/') ? path : `/${path}`;
+}
+/** Frameworks whose imports / requires appear in ``source``. */
+export function detectFrameworks(source) {
+    const found = [];
+    for (const hint of FRAMEWORK_IMPORT_HINTS) {
+        if (hint.pattern.test(source) && !found.includes(hint.id)) {
+            found.push(hint.id);
+        }
+    }
+    return found;
+}
+function collectHttpRoutes(source, relPath) {
+    const endpoints = [];
+    const re = new RegExp(HTTP_ROUTE.source, HTTP_ROUTE.flags);
+    let match;
+    while ((match = re.exec(source)) !== null) {
+        const method = (match[1] || 'get').toUpperCase();
+        const path = normalizePath(match[2] || '/');
+        const start = lineOf(source, match.index);
+        endpoints.push({
+            service_unit: `${method} ${path}`,
+            unit_type: 'endpoint',
+            method,
+            path,
+            handler: '<heuristic>',
+            file: relPath,
+            line: start,
+            end_line: start,
+            is_async: false,
+            dynamic: looksDynamic(path),
+            prefix_resolved: false,
+            evidence: 'heuristic_source',
+        });
+    }
+    return endpoints;
+}
+function collectNestRoutes(source, relPath) {
+    const endpoints = [];
+    const re = new RegExp(NEST_MAPPING.source, NEST_MAPPING.flags);
+    let match;
+    while ((match = re.exec(source)) !== null) {
+        const method = (match[1] || 'Get').toUpperCase();
+        const pathRaw = match[2];
+        const path = pathRaw && pathRaw.length ? normalizePath(pathRaw) : '/';
+        const start = lineOf(source, match.index);
+        endpoints.push({
+            service_unit: `${method} ${path}`,
+            unit_type: 'endpoint',
+            method,
+            path,
+            handler: '<nest-heuristic>',
+            file: relPath,
+            line: start,
+            end_line: start,
+            is_async: false,
+            dynamic: looksDynamic(path),
+            prefix_resolved: false,
+            evidence: 'heuristic_source',
+        });
+    }
+    return endpoints;
+}
+function collectBullMqTasks(source, relPath) {
+    const tasks = [];
+    const seen = new Set();
+    const re = new RegExp(BULLMQ_QUEUE_ADD.source, BULLMQ_QUEUE_ADD.flags);
+    let match;
+    while ((match = re.exec(source)) !== null) {
+        const name = String(match[1] || '').trim();
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        const start = lineOf(source, match.index);
+        tasks.push({
+            service_unit: `task:${name}`,
+            unit_type: 'task',
+            name,
+            handler: '<bullmq-heuristic>',
+            file: relPath,
+            line: start,
+            end_line: start,
+            evidence: 'heuristic_source',
+        });
+    }
+    return tasks;
+}
+function dedupeUnits(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const key = `${item.service_unit}|${item.file}|${item.line}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(item);
+    }
+    return out;
+}
+/**
+ * Extract service units from one JS/TS source string.
+ * Never throws on bad source — returns empty collections.
+ */
+export function extractServiceUnits(sourceCode, relPath = '<unknown>') {
+    const source = String(sourceCode || '');
+    const frameworks = detectFrameworks(source);
+    const endpoints = [
+        ...collectHttpRoutes(source, relPath),
+        ...(frameworks.includes('nest') ? collectNestRoutes(source, relPath) : []),
+    ];
+    const tasks = frameworks.includes('bullmq') || /\bbullmq\b/.test(source)
+        ? collectBullMqTasks(source, relPath)
+        : [];
+    return {
+        frameworks,
+        endpoints: dedupeUnits(endpoints),
+        tasks: dedupeUnits(tasks),
+    };
+}
+/** Project-level ``service_manifest_v0`` from ``{relPath: source}``. */
+export function buildServiceManifest(fileSources) {
+    const frameworksDetected = [];
+    const endpoints = [];
+    const tasks = [];
+    const entryFiles = new Set();
+    for (const [relPath, source] of Object.entries(fileSources)) {
+        const extracted = extractServiceUnits(source, relPath);
+        for (const fw of extracted.frameworks) {
+            if (!frameworksDetected.includes(fw))
+                frameworksDetected.push(fw);
+        }
+        if (extracted.endpoints.length || extracted.tasks.length) {
+            entryFiles.add(relPath);
+        }
+        endpoints.push(...extracted.endpoints);
+        tasks.push(...extracted.tasks);
+    }
+    let framework = null;
+    if (endpoints.length && frameworksDetected.includes('express'))
+        framework = 'express';
+    else if (endpoints.length && frameworksDetected.includes('fastify'))
+        framework = 'fastify';
+    else if (endpoints.length && frameworksDetected.includes('nest'))
+        framework = 'nest';
+    else if (tasks.length && frameworksDetected.includes('bullmq'))
+        framework = 'bullmq';
+    else if (frameworksDetected.length)
+        framework = frameworksDetected[0];
+    return {
+        schema: 'service_manifest_v0',
+        contract_status: 'mp4_scaffold',
+        framework,
+        frameworks_detected: frameworksDetected,
+        entry_files: [...entryFiles].sort(),
+        endpoints,
+        tasks,
+        stats: {
+            endpoints: endpoints.length,
+            tasks: tasks.length,
+            files_with_units: entryFiles.size,
+        },
+        notes: [
+            'MP4 scaffold: heuristic JS/TS discovery only — not TypeScript AST, not CLI/VSCE wired, not resource findings',
+            'Does not modify RunSession upload or runtime metering pipelines',
+        ],
+    };
+}
+export function isServiceProject(manifest) {
+    return Boolean(manifest.stats.endpoints || manifest.stats.tasks);
+}

package/dist/analyze/unboundedParallelismDetector.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Heuristic JS/TS twin of Python ``unbounded_asyncio_gather_with_io``.
+ *
+ * RD0 disposition → mechanism ``unbounded_parallelism`` / ``network.io``.
+ * Flags ``Promise.all(…map…fetch)`` style fan-out without an obvious concurrency cap.
+ */
+import { type ResourceCandidateHit } from './resourceFindingCandidate.js';
+/**
+ * Detect unbounded Promise.all + API fan-out in one source file.
+ */
+export declare function detectUnboundedParallelismHits(source: string, relPath: string): ResourceCandidateHit[];