@netgreener/runtime 0.1.8 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/TUTORIAL.md +120 -29
  2. package/dist/aggregator.d.ts +12 -2
  3. package/dist/aggregator.js +135 -8
  4. package/dist/analyze/buildResourceFindings.d.ts +4 -0
  5. package/dist/analyze/buildResourceFindings.js +17 -0
  6. package/dist/analyze/cli.d.ts +1 -0
  7. package/dist/analyze/cli.js +22 -1
  8. package/dist/analyze/declaredExternalApis.d.ts +31 -0
  9. package/dist/analyze/declaredExternalApis.js +174 -0
  10. package/dist/analyze/index.d.ts +1 -0
  11. package/dist/analyze/index.js +1 -0
  12. package/dist/auto.d.ts +7 -0
  13. package/dist/auto.js +8 -0
  14. package/dist/bullmq.d.ts +2 -2
  15. package/dist/bullmq.js +28 -58
  16. package/dist/carbonLedger.d.ts +28 -0
  17. package/dist/carbonLedger.js +52 -0
  18. package/dist/cgroupV2.d.ts +44 -0
  19. package/dist/cgroupV2.js +174 -0
  20. package/dist/cli/helpText.d.ts +3 -3
  21. package/dist/cli/helpText.js +42 -35
  22. package/dist/cli/netgreener.d.ts +7 -7
  23. package/dist/cli/netgreener.js +23 -16
  24. package/dist/cli/runCli.d.ts +20 -0
  25. package/dist/cli/runCli.js +249 -0
  26. package/dist/cli/runPreload.d.ts +5 -0
  27. package/dist/cli/runPreload.js +43 -0
  28. package/dist/collectorMetadata.d.ts +1 -1
  29. package/dist/collectorMetadata.js +2 -0
  30. package/dist/config.d.ts +2 -0
  31. package/dist/config.js +6 -2
  32. package/dist/exporter.d.ts +7 -2
  33. package/dist/exporter.js +12 -6
  34. package/dist/express.js +17 -6
  35. package/dist/externalApiMeter.d.ts +43 -1
  36. package/dist/externalApiMeter.js +267 -5
  37. package/dist/fastify.js +17 -6
  38. package/dist/index.d.ts +10 -2
  39. package/dist/index.js +9 -1
  40. package/dist/init.d.ts +30 -0
  41. package/dist/init.js +31 -0
  42. package/dist/lifecycle.d.ts +45 -0
  43. package/dist/lifecycle.js +112 -0
  44. package/dist/managedCollectorLauncher.d.ts +37 -0
  45. package/dist/managedCollectorLauncher.js +162 -0
  46. package/dist/n4/deploymentMatrix.d.ts +9 -5
  47. package/dist/n4/deploymentMatrix.js +13 -9
  48. package/dist/n4/missingnessInventory.js +3 -3
  49. package/dist/next.d.ts +61 -0
  50. package/dist/next.js +195 -0
  51. package/dist/occupancyTracker.d.ts +27 -0
  52. package/dist/occupancyTracker.js +87 -0
  53. package/dist/optimize/apply.d.ts +38 -0
  54. package/dist/optimize/apply.js +173 -0
  55. package/dist/optimize/cli.d.ts +26 -0
  56. package/dist/optimize/cli.js +323 -0
  57. package/dist/optimize/index.d.ts +6 -0
  58. package/dist/optimize/index.js +5 -0
  59. package/dist/optimize/llmApply.d.ts +22 -0
  60. package/dist/optimize/llmApply.js +80 -0
  61. package/dist/optimize/llmSession.d.ts +88 -0
  62. package/dist/optimize/llmSession.js +135 -0
  63. package/dist/optimize/provider.d.ts +17 -0
  64. package/dist/optimize/provider.js +119 -0
  65. package/dist/optimize/safePatches.d.ts +18 -0
  66. package/dist/optimize/safePatches.js +247 -0
  67. package/dist/optimize/types.d.ts +79 -0
  68. package/dist/optimize/types.js +6 -0
  69. package/dist/optimize/verification.d.ts +16 -0
  70. package/dist/optimize/verification.js +165 -0
  71. package/dist/processResources.d.ts +5 -0
  72. package/dist/processResources.js +28 -4
  73. package/dist/processRuntime.js +7 -28
  74. package/dist/processTree.d.ts +47 -0
  75. package/dist/processTree.js +148 -0
  76. package/dist/runContextEnrichment.d.ts +11 -0
  77. package/dist/runContextEnrichment.js +92 -0
  78. package/dist/runtime.d.ts +29 -1
  79. package/dist/runtime.js +94 -16
  80. package/dist/sdk/client.d.ts +152 -0
  81. package/dist/sdk/client.js +396 -0
  82. package/dist/sdk/gitUrl.d.ts +6 -0
  83. package/dist/sdk/gitUrl.js +87 -0
  84. package/dist/sdk/index.d.ts +5 -0
  85. package/dist/sdk/index.js +5 -0
  86. package/dist/serverlessHints.d.ts +9 -6
  87. package/dist/serverlessHints.js +10 -7
  88. package/dist/taskMeter.d.ts +14 -0
  89. package/dist/taskMeter.js +53 -0
  90. package/dist/types.d.ts +35 -0
  91. package/examples/aca-container-gate/Dockerfile +20 -0
  92. package/examples/aca-container-gate/azure-container-app.yaml +27 -0
  93. package/examples/aca-container-gate/gate.env +7 -0
  94. package/examples/aca-container-gate/server.mjs +117 -0
  95. package/examples/express-local-live-smoke.mjs +127 -0
  96. package/examples/extractRunId.mjs +11 -0
  97. package/examples/next-pilot-dry-run.mjs +32 -0
  98. package/examples/serverless-thin-gate.mjs +89 -0
  99. package/fixtures/run-smoke/hello.mjs +4 -0
  100. package/package.json +23 -2
package/TUTORIAL.md CHANGED
@@ -2,10 +2,10 @@
2
2
 
3
3
  **Twin of:** [`SERVICE_RUNTIME_TUTORIAL.md`](../docs/SERVICE_RUNTIME_TUTORIAL.md)
4
4
  **§4–§6** (FastAPI / Celery / process wrap).
5
- **Package:** `@netgreener/runtime` (private, experimental).
6
- **Not claimed:** MP3 production support, npm publish, default collector cutover,
7
- managed Node sidecar collector parity with Python Celery, or live acceptance
8
- without your retained evidence.
5
+ **Package:** `@netgreener/runtime` (public npm; see [`PRODUCTION_DOCS.md`](PRODUCTION_DOCS.md)).
6
+ **Governed label:** **Node.js Runtime production** (N10 issued 2026-10-02).
7
+ **Still not claimed:** default collector cutover; container/K8s; cgroup as production claim.
8
+ **Opt-in (DevOps):** `NETGREENER_COLLECTOR_MODE=managed` — same idea as Python Celery (§7).
9
9
 
10
10
  | Need deeper reference | Doc |
11
11
  |-----------------------|-----|
@@ -14,7 +14,9 @@ without your retained evidence.
14
14
  | Package status / CI | [`README.md`](README.md), [`ROADMAP.md`](ROADMAP.md) |
15
15
  | Tenant dogfood | [`NODE_TENANT_DOGFOOD.md`](../docs/NODE_TENANT_DOGFOOD.md) |
16
16
  | Service tokens | [`CI_SERVICE_TOKEN_ONBOARDING.md`](../docs/CI_SERVICE_TOKEN_ONBOARDING.md) |
17
- | Python twin | [`SERVICE_RUNTIME_TUTORIAL.md`](../docs/SERVICE_RUNTIME_TUTORIAL.md) |
17
+ | Python twin (Celery managed) | [`SERVICE_RUNTIME_TUTORIAL.md`](../docs/SERVICE_RUNTIME_TUTORIAL.md) · [`SERVICE_RUNTIME_INTEGRATION.md`](../docs/SERVICE_RUNTIME_INTEGRATION.md) |
18
+ | Optimize / LLM apply gates | [`OPTIMIZE_STUB.md`](OPTIMIZE_STUB.md) |
19
+ | Owner publish commands (CLI / npm / VSIX) | [`OWNER_PUBLISH_COMMANDS.md`](../docs/OWNER_PUBLISH_COMMANDS.md) |
18
20
 
19
21
  ---
20
22
 
@@ -26,18 +28,26 @@ without your retained evidence.
26
28
  | **Fastify** HTTP API | Per-**route** KPIs | `netgreenerFastifyPlugin` | **Yes — one `register`** (§4) |
27
29
  | **Nest** | Express or Fastify under the hood | `applyNetGreenerNestHooks(app)` | **Yes — one hook** (§4) |
28
30
  | **BullMQ** worker | Per-**task** KPIs | `netgreenerBullMqProcessor` | **Yes — wrap the processor** (§5) |
29
- | **Script / cron / batch** `node …` | Process window + outbound `fetch` | `startProcessRuntime` / `runWithProcessTenant` | **Yes — start helper** (§6) |
31
+ | **Script / cron / batch** `node …` | Process window + outbound `fetch` | `startProcessRuntime` / `runWithProcessTenant` / `netgreener run` | **Yes — start helper or CLI** (§6–§7) |
32
+
33
+ ### Who should touch which env vars?
34
+
35
+ | Audience | Use | Ignore unless DevOps asks |
36
+ |----------|-----|---------------------------|
37
+ | **App developer** (Express/Fastify/Nest) | Token, project id, `SERVICE_RUNTIME=1` | `COLLECTOR_MODE`, `EXPORT_MODE=collector` |
38
+ | **DevOps / platform** | Workers needing durable spool | `NETGREENER_COLLECTOR_MODE=managed` (Python Celery twin; Node `netgreener run`) |
30
39
 
31
40
  Default upload mode remains **`NETGREENER_EXPORT_MODE=direct`**. Sibling collector
32
- IPC is opt-in only; do not cut over the default without explicit authorization.
41
+ IPC and managed mode are **opt-in only**; we do not cut over the default.
33
42
 
34
43
  ```text
35
- HTTP: middleware/plugin → window → POST /api/v1/runsessions/ (default direct; or dry-run)
36
- BullMQ: wrapped processor → window → same upload path (v0; no Python-style managed sidecar yet)
37
- Process: startProcessRuntime → window → same upload path
44
+ HTTP: middleware/plugin → window → POST /api/v1/runsessions/ (default direct)
45
+ BullMQ: wrapped processor → window → same direct path (default)
46
+ Process: startProcessRuntime / netgreener run → window → direct (default)
38
47
 
39
- Opt-in: NETGREENER_EXPORT_MODE=collector → length-prefixed IPC → sibling collector spool
40
- (default remains direct; see §4.5)
48
+ Opt-in: NETGREENER_EXPORT_MODE=collector → IPC → sibling collector (you start collector)
49
+ Opt-in: NETGREENER_COLLECTOR_MODE=managed → NetGreener starts+drains collector for you
50
+ (Python: Celery launcher; Node: netgreener run)
41
51
  ```
42
52
 
43
53
  ---
@@ -74,15 +84,12 @@ Find **ORG_ID** / **PROJECT_ID** in the NetGreener dashboard (project URL looks
74
84
 
75
85
  ## 3. Install `@netgreener/runtime` in that project
76
86
 
77
- The package is **private** today (Azure DevOps / internal registry). Install from your
78
- approved feed or path — there is **no** public npm publish yet.
79
-
80
87
  ```bash
81
- # Example once the private feed is configured for your project:
82
88
  npm install @netgreener/runtime
83
89
  ```
84
90
 
85
- Engines: Node **22** or **24** (see `package.json` `engines`).
91
+ Requires Node.js **22** or **24** (see `package.json` `engines`). For install /
92
+ upgrade / claimed limits, see [`PRODUCTION_DOCS.md`](PRODUCTION_DOCS.md).
86
93
 
87
94
  Verify the import resolves:
88
95
 
@@ -261,9 +268,9 @@ Worker/process twins: §5.5 / §6.1. Local proofs:
261
268
  ## 5. BullMQ — any worker project (Part 5 twin)
262
269
 
263
270
  Unlike Python Celery (entrypoint wrap, often **no** task code changes), Node BullMQ
264
- v0 meters by **wrapping the processor** you already pass to `Worker`. There is **no**
265
- `netgreener runtime entrypoint` CLI for Node yet, and **no** `NETGREENER_COLLECTOR_MODE=managed`
266
- sidecar requirement for this path — default remains direct flush from the worker process.
271
+ v0 meters by **wrapping the processor** you already pass to `Worker`. Default remains
272
+ **direct** flush from the worker process. For a **managed** sibling collector (Python
273
+ Celery twin), see §7 — opt-in DevOps only; not required for BullMQ KPIs.
267
274
 
268
275
  ### 5.1 Wrap the processor (required for task KPIs)
269
276
 
@@ -373,13 +380,96 @@ yet; call `startProcessRuntime` from your entry file (or a thin launcher you own
373
380
  ### 6.1 Opt-in sibling collector (process → MP2 IPC)
374
381
 
375
382
  Same env as §4.5 / §5.5. Flush via `flushProcessRuntime('manual')` or shutdown.
376
- IPC payload uses `collector: node_process`. Still **not** a managed process-tree
377
- sampler or CLI launcher — those remain MP3. Proof lives in
378
- `src/tests/workers.collector.integration.test.ts`.
383
+ IPC payload uses `collector: node_process`. For **NetGreener-started** collector
384
+ lifecycle (Python Celery twin), use §7 instead of manually starting the sibling.
385
+
386
+ ---
387
+
388
+ ## 7. Managed collector — `NETGREENER_COLLECTOR_MODE=managed` (opt-in)
389
+
390
+ **Same idea as Python Celery** (`docs/SERVICE_RUNTIME_INTEGRATION.md`): NetGreener
391
+ starts and drains a sibling `python -m netgreener.collector_server`, and the Node
392
+ child exports with `NETGREENER_EXPORT_MODE=collector`.
393
+
394
+ ### Who needs this?
395
+
396
+ | You are… | Recommendation |
397
+ |----------|----------------|
398
+ | Wiring Express / Fastify / Nest | **Skip** — leave unset; use default **direct** |
399
+ | Running BullMQ with default path | **Skip** unless platform asks for durable spool |
400
+ | DevOps wrapping `netgreener run` / workers | **Optional** — set `managed` when you want supervised collector |
401
+
402
+ ### Example (`netgreener run`)
403
+
404
+ ```powershell
405
+ $env:NETGREENER_SERVICE_RUNTIME = "1"
406
+ $env:NETGREENER_TOKEN = "ngs_…" # kept on collector; stripped from child by default
407
+ $env:NETGREENER_PROJECT_ID = "97"
408
+ $env:NETGREENER_COLLECTOR_MODE = "managed"
409
+ # optional: $env:NETGREENER_COLLECTOR_ENDPOINT = "tcp://127.0.0.1:17999"
410
+ netgreener run .\jobs\report.mjs .
411
+ ```
412
+
413
+ Requires Python with `netgreener.collector_server` importable. Windows: **`tcp://` only**.
414
+
415
+ When the Node child flushes with `EXPORT_MODE=collector`, IPC includes `emitter_pid`.
416
+ The collector attaches an honest **`collector_resource_sample_v0`** (process-tree via
417
+ psutil; cgroup v2 on Linux only) onto `session_metadata` — it does **not** erase
418
+ Node `node_process_*` provenance. Disable with
419
+ `NETGREENER_COLLECTOR_ENRICH_RESOURCES=0`.
420
+
421
+ Default package / unset mode remains **direct**. Managed does **not** change N10
422
+ production claim wording by itself.
423
+
424
+ ### CI / dogfood (no upload)
425
+
426
+ ```powershell
427
+ # Module honesty (Linux tree/cgroup; Windows unavailable = PASS)
428
+ npm run example:n5b-linux-gate
429
+
430
+ # Live flush → collector enrich (needs sibling ../netgreener_cli or NETGREENER_CLI_ROOT)
431
+ # Linux CI sets NETGREENER_N5B_REQUIRE_FLUSH=1
432
+ npm run example:n5b-flush-dogfood
433
+ ```
434
+
435
+ Artifact: `artifacts/n5b-flush/latest.json`. Azure job: `n5b_flush_dogfood`.
436
+
437
+ ---
438
+
439
+ ## 7b. Optimize, LLM apply-verified, Investigate (parity)
440
+
441
+ Default optimize stays **local** (no LLM, no upload). Same `api_server` brain when you opt in.
442
+
443
+ ### CLI
444
+
445
+ ```powershell
446
+ # Local proposals (+ optional deterministic safe apply)
447
+ netgreener optimize .\my-app
448
+ netgreener optimize .\my-app --apply --skip-test
449
+
450
+ # Shared LLM session (review JSON)
451
+ $env:NETGREENER_TOKEN = "ngs_…"
452
+ netgreener optimize .\my-app --llm --project-id 97
453
+
454
+ # LLM splice writes — VerificationProvider before/after (NOT the same as --apply)
455
+ netgreener optimize .\my-app --llm --apply-verified --project-id 97 --skip-test
456
+ ```
457
+
458
+ `--llm` + `--apply` is rejected on purpose. Use `--apply-verified` for LLM writes.
459
+
460
+ ### VS Code (Node workspace)
461
+
462
+ | Command | Path |
463
+ |---------|------|
464
+ | **Plan Optimizations** | QuickPick: LLM plan · **LLM apply-verified (CLI)** · Local Node Optimize |
465
+ | **Investigate Anomaly Brief** | Claim brief → `.netgreener/anomaly-investigation.json` → scoped Analyze |
466
+ | URI | `vscode://netgreener.netgreener-vscode-extension/anomalyBrief?briefId=…` |
467
+
468
+ Does **not** flip `EXPORT_MODE`. Does **not** invent measured savings.
379
469
 
380
470
  ---
381
471
 
382
- ## 7. Common failures
472
+ ## 8. Common failures
383
473
 
384
474
  | Symptom | Check |
385
475
  |---------|--------|
@@ -390,12 +480,13 @@ sampler or CLI launcher — those remain MP3. Proof lives in
390
480
  | Tenant missing after auth (Fastify) | Use `bindFastifyTenant(request, …)` |
391
481
  | BullMQ jobs invisible | Processor must be wrapped with `netgreenerBullMqProcessor` |
392
482
  | BullMQ tenant missing | `NETGREENER_TENANT_SOURCE=task_kwarg` + kwarg in `job.data` |
393
- | Package not found on npm | Expected — package is private until MP3 publish |
394
- | Serverless / Lambda freezes mid-window | Use thin-flush (§9); flush at invoke end; durability is best-effort |
483
+ | Package not found on npm | Check `@netgreener/runtime` install / registry access |
484
+ | Managed collector fails to start | Python `netgreener.collector_server` on PATH; Windows needs `tcp://` |
485
+ | Serverless / Lambda freezes mid-window | Use thin-flush (§10); flush at invoke end; durability is best-effort |
395
486
 
396
487
  ---
397
488
 
398
- ## 8. Minimal copy-paste canaries
489
+ ## 9. Minimal copy-paste canaries
399
490
 
400
491
  **Express dry-run:** middleware + `/health` + `NETGREENER_RUNTIME_DRY_RUN=1` +
401
492
  `getExpressRuntime().flush('manual')`.
@@ -410,7 +501,7 @@ sampler or CLI launcher — those remain MP3. Proof lives in
410
501
 
411
502
  ---
412
503
 
413
- ## 9. Thin-flush / serverless mode
504
+ ## 10. Thin-flush / serverless mode
414
505
 
415
506
  Long-running VM / container / K8s Node should keep default **`direct`** or opt-in
416
507
  **`collector`** (§4.5). Serverless hosts often cannot run a durable sibling collector.
@@ -475,7 +566,7 @@ flipping the default off `direct` for long-running Node.
475
566
 
476
567
  ---
477
568
 
478
- ## 10. Stop here (honesty)
569
+ ## 11. Stop here (honesty)
479
570
 
480
571
  This tutorial does **not** by itself:
481
572
  - publish `@netgreener/runtime` to npm
@@ -17,6 +17,8 @@ export declare class ServiceRuntimeAggregator {
17
17
  peakRssKb?: number;
18
18
  }): void;
19
19
  private recordIntoMap;
20
+ /** Peak RSS (KiB) across units with calls — for crude window RAM estimate. */
21
+ maxPeakRssKb(): number;
20
22
  private buildUnitsList;
21
23
  hasData(): boolean;
22
24
  totalDurationMs(): number;
@@ -27,14 +29,22 @@ export declare class ServiceRuntimeAggregator {
27
29
  /** True when any unit recorded peak RSS. */
28
30
  hasMeasuredRss(): boolean;
29
31
  /**
30
- * Build service_runtime_v0. N1 uses duration-share energy attribution (trend).
31
- * CPU-accurate share can land later without changing the schema.
32
+ * Build service_runtime_v0.
33
+ * When occupancy snapshot is present → ``cpu_and_occupancy_v1`` (anomaly evidence).
34
+ * Occupancy is window-scaled (Python twin) so coverage reconciles to ``window_seconds``.
32
35
  */
33
36
  buildV0(opts: {
34
37
  collector: string;
35
38
  framework: string;
36
39
  windowEnergyKwh: number;
37
40
  windowSeconds: number;
41
+ /** Crude window RAM (GiB·h); split by occupancy share when present. */
42
+ windowRamGbHours?: number | null;
43
+ occupancy?: {
44
+ by_unit: Record<string, number>;
45
+ in_flight_seconds: number;
46
+ idle_seconds: number;
47
+ } | null;
38
48
  }): ServiceRuntimeV0 | null;
39
49
  /** Take a snapshot and reset live window (Python take_snapshot analogue). */
40
50
  takeSnapshot(): ServiceRuntimeAggregator;
@@ -1,3 +1,4 @@
1
+ import { energyKwhToCarbonG } from './carbonLedger.js';
1
2
  const MAX_UNITS = 500;
2
3
  const MAX_SERVICE_UNIT_LEN = 256;
3
4
  function normalizeServiceUnit(raw) {
@@ -76,11 +77,25 @@ export class ServiceRuntimeAggregator {
76
77
  unit.peakRssKbMax = Math.max(unit.peakRssKbMax, rss);
77
78
  }
78
79
  }
79
- buildUnitsList(source, windowEnergyKwh, equalShare, totalDuration) {
80
+ /** Peak RSS (KiB) across units with calls — for crude window RAM estimate. */
81
+ maxPeakRssKb() {
82
+ let max = 0;
83
+ for (const u of this.units.values()) {
84
+ if (u.calls > 0 && u.peakRssKbMax > max)
85
+ max = u.peakRssKbMax;
86
+ }
87
+ return max;
88
+ }
89
+ buildUnitsList(source, windowEnergyKwh, equalShare, totalDuration, occByUnit, alloc) {
80
90
  const list = [...source.values()].filter((u) => u.calls > 0);
81
91
  if (!list.length)
82
92
  return [];
83
93
  const energyBudget = nonNegativeFinite(windowEnergyKwh);
94
+ const windowSeconds = nonNegativeFinite(alloc?.windowSeconds ?? 0);
95
+ const windowRam = alloc?.windowRamGbHours != null
96
+ ? nonNegativeFinite(alloc.windowRamGbHours)
97
+ : null;
98
+ const useOccupancy = Boolean(alloc?.useOccupancy);
84
99
  const sorted = list.sort((a, b) => b.durationMsTotal - a.durationMsTotal);
85
100
  const units = sorted.map((u) => {
86
101
  const share = equalShare ? 1 / list.length : u.durationMsTotal / totalDuration;
@@ -96,7 +111,7 @@ export class ServiceRuntimeAggregator {
96
111
  errors: u.errors,
97
112
  cpu_seconds_total: Math.round(cpuSeconds * 10000) / 10000,
98
113
  energy_kwh: energy,
99
- carbon_g: energy * 0.4 * 1000,
114
+ carbon_g: energyKwhToCarbonG(energy).carbonG,
100
115
  duration_ms: {
101
116
  avg: Math.round(avg * 100) / 100,
102
117
  max: Math.round(u.durationMsMax * 100) / 100,
@@ -105,13 +120,22 @@ export class ServiceRuntimeAggregator {
105
120
  if (u.peakRssKbMax > 0) {
106
121
  unit.peak_rss_kb_max = Math.round(u.peakRssKbMax);
107
122
  }
123
+ const occ = occByUnit?.[u.serviceUnit];
124
+ const occS = occ != null && occ > 0 ? occ : 0;
125
+ if (occS > 0) {
126
+ unit.occupancy_seconds = Math.round(occS * 1e6) / 1e6;
127
+ }
128
+ if (windowRam != null) {
129
+ const occShare = useOccupancy && windowSeconds > 0 ? occS / windowSeconds : share;
130
+ unit.ram_gb_hours = Math.round(windowRam * occShare * 1e6) / 1e6;
131
+ }
108
132
  return unit;
109
133
  });
110
134
  const allocatedRaw = units.reduce((s, u) => s + u.energy_kwh, 0);
111
135
  const drift = energyBudget - allocatedRaw;
112
136
  if (units.length && Math.abs(drift) > 0) {
113
137
  units[0].energy_kwh += drift;
114
- units[0].carbon_g = units[0].energy_kwh * 0.4 * 1000;
138
+ units[0].carbon_g = energyKwhToCarbonG(units[0].energy_kwh).carbonG;
115
139
  }
116
140
  for (const u of units) {
117
141
  u.energy_kwh = Math.round(u.energy_kwh * 1e12) / 1e12;
@@ -160,8 +184,9 @@ export class ServiceRuntimeAggregator {
160
184
  return false;
161
185
  }
162
186
  /**
163
- * Build service_runtime_v0. N1 uses duration-share energy attribution (trend).
164
- * CPU-accurate share can land later without changing the schema.
187
+ * Build service_runtime_v0.
188
+ * When occupancy snapshot is present → ``cpu_and_occupancy_v1`` (anomaly evidence).
189
+ * Occupancy is window-scaled (Python twin) so coverage reconciles to ``window_seconds``.
165
190
  */
166
191
  buildV0(opts) {
167
192
  const list = [...this.units.values()].filter((u) => u.calls > 0);
@@ -169,9 +194,62 @@ export class ServiceRuntimeAggregator {
169
194
  return null;
170
195
  const windowEnergyKwh = nonNegativeFinite(opts.windowEnergyKwh);
171
196
  const windowSeconds = nonNegativeFinite(opts.windowSeconds);
197
+ const windowRamGbHours = opts.windowRamGbHours != null ? nonNegativeFinite(opts.windowRamGbHours) : null;
172
198
  const totalDuration = list.reduce((s, u) => s + u.durationMsTotal, 0);
173
199
  const equalShare = totalDuration <= 0;
174
- const units = this.buildUnitsList(this.units, windowEnergyKwh, equalShare, totalDuration);
200
+ const occ = opts.occupancy;
201
+ const unitKeys = new Set(list.map((u) => u.serviceUnit));
202
+ const rawOccByUnit = occ?.by_unit || {};
203
+ let attributedOccMap = {};
204
+ let orphanOcc = 0;
205
+ for (const [k, v] of Object.entries(rawOccByUnit)) {
206
+ const n = Math.max(0, Number(v) || 0);
207
+ if (n <= 0)
208
+ continue;
209
+ if (unitKeys.has(k))
210
+ attributedOccMap[k] = n;
211
+ else
212
+ orphanOcc += n;
213
+ }
214
+ let totalOcc = Object.values(attributedOccMap).reduce((s, v) => s + v, 0);
215
+ const idleSecondsRaw = Math.max(0, occ?.idle_seconds || 0);
216
+ const inFlightSecondsRaw = Math.max(0, occ?.in_flight_seconds || 0);
217
+ let unattributedOcc = idleSecondsRaw + inFlightSecondsRaw + orphanOcc;
218
+ const hasOccupancySignal = Boolean(occ) && (totalOcc > 0 || unattributedOcc > 0);
219
+ // Align occupancy coverage to the meter window (Python service_runtime_v0 twin).
220
+ if (hasOccupancySignal && windowSeconds > 0) {
221
+ const coverage = totalOcc + unattributedOcc;
222
+ if (coverage <= 0) {
223
+ unattributedOcc = windowSeconds;
224
+ }
225
+ else if (Math.abs(coverage - windowSeconds) > 1e-9) {
226
+ const scale = windowSeconds / coverage;
227
+ attributedOccMap = Object.fromEntries(Object.entries(attributedOccMap).map(([k, v]) => [k, v * scale]));
228
+ totalOcc = Object.values(attributedOccMap).reduce((s, v) => s + v, 0);
229
+ unattributedOcc = windowSeconds - totalOcc;
230
+ }
231
+ }
232
+ const useOccupancy = hasOccupancySignal && (totalOcc > 0 || unattributedOcc > 0);
233
+ // Keep idle / in-flight proportions after window-scale (orphan folds into unattributed).
234
+ let idleOut = idleSecondsRaw;
235
+ let inFlightOut = inFlightSecondsRaw;
236
+ if (useOccupancy && windowSeconds > 0) {
237
+ const rawUna = idleSecondsRaw + inFlightSecondsRaw + orphanOcc;
238
+ if (rawUna > 0) {
239
+ idleOut = unattributedOcc * (idleSecondsRaw / rawUna);
240
+ inFlightOut = unattributedOcc * (inFlightSecondsRaw / rawUna);
241
+ }
242
+ else {
243
+ idleOut = unattributedOcc;
244
+ inFlightOut = 0;
245
+ }
246
+ }
247
+ const unitAlloc = {
248
+ windowSeconds,
249
+ windowRamGbHours,
250
+ useOccupancy,
251
+ };
252
+ const units = this.buildUnitsList(this.units, windowEnergyKwh, equalShare, totalDuration, attributedOccMap, unitAlloc);
175
253
  const byTenant = {};
176
254
  const totalBusy = list.reduce((s, u) => s + u.durationMsTotal, 0);
177
255
  for (const [tenantId, tenantMap] of this.byTenant.entries()) {
@@ -184,7 +262,7 @@ export class ServiceRuntimeAggregator {
184
262
  : windowEnergyKwh / Math.max(1, this.byTenant.size);
185
263
  const tenantDuration = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
186
264
  const tenantEqual = tenantDuration <= 0;
187
- const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration);
265
+ const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration, attributedOccMap, unitAlloc);
188
266
  if (!tenantUnits.length)
189
267
  continue;
190
268
  byTenant[tenantId] = {
@@ -197,14 +275,63 @@ export class ServiceRuntimeAggregator {
197
275
  const allocated = units.reduce((s, u) => s + u.energy_kwh, 0);
198
276
  const residual = windowEnergyKwh - allocated;
199
277
  const tolerance = Math.max(1e-12, Math.abs(windowEnergyKwh) * 1e-6);
278
+ const measuredCpu = this.hasMeasuredCpu();
279
+ let attribution;
280
+ if (useOccupancy)
281
+ attribution = 'cpu_and_occupancy_v1';
282
+ else if (measuredCpu)
283
+ attribution = 'cpu_share';
284
+ else if (equalShare)
285
+ attribution = 'equal_share_no_cpu_signal';
286
+ else
287
+ attribution = 'duration_share';
288
+ const attribution_detail = {
289
+ cpu: measuredCpu
290
+ ? { method: 'request_process_cpu_time', kind: 'measured' }
291
+ : { method: 'request_duration_proxy', kind: 'proxy' },
292
+ ram: {
293
+ method: useOccupancy
294
+ ? 'concurrency_normalized_active_occupancy'
295
+ : this.hasMeasuredRss()
296
+ ? 'process_rss_peak_observed'
297
+ : 'unallocated',
298
+ kind: useOccupancy
299
+ ? 'allocated_estimate'
300
+ : this.hasMeasuredRss()
301
+ ? 'measured'
302
+ : 'unavailable',
303
+ },
304
+ gpu: { method: 'none', kind: 'unavailable' },
305
+ energy: {
306
+ cpu_dynamic: measuredCpu ? 'cpu_time_share_preferred' : 'duration_share',
307
+ memory: useOccupancy ? 'ram_occupancy_share' : 'unallocated',
308
+ gpu: 'none',
309
+ },
310
+ };
311
+ const unattributedRam = useOccupancy && windowSeconds > 0 && windowRamGbHours != null
312
+ ? windowRamGbHours * (unattributedOcc / windowSeconds)
313
+ : null;
200
314
  return {
201
315
  framework: opts.framework,
202
316
  collector: opts.collector,
203
317
  window_seconds: Math.round(windowSeconds * 100) / 100,
204
- attribution: equalShare ? 'equal_share_no_cpu_signal' : 'duration_share',
318
+ attribution,
319
+ attribution_detail,
205
320
  accuracy: 'trend',
206
321
  units,
207
322
  ...(Object.keys(byTenant).length ? { by_tenant: byTenant } : {}),
323
+ ...(useOccupancy
324
+ ? {
325
+ unattributed: {
326
+ occupancy_seconds: Math.round(unattributedOcc * 1e6) / 1e6,
327
+ idle_seconds: Math.round(idleOut * 1e6) / 1e6,
328
+ in_flight_seconds: Math.round(inFlightOut * 1e6) / 1e6,
329
+ ...(unattributedRam != null
330
+ ? { ram_gb_hours: Math.round(unattributedRam * 1e6) / 1e6 }
331
+ : {}),
332
+ },
333
+ }
334
+ : {}),
208
335
  allocation_reconciliation_v0: {
209
336
  schema_version: 1,
210
337
  window_energy_kwh: windowEnergyKwh,
@@ -3,6 +3,7 @@
3
3
  * Prefer TypeScript AST when available; heuristics otherwise.
4
4
  * Additive Analyze path — never touches RunSession upload.
5
5
  */
6
+ import { type DeclaredExternalApiEntry } from './declaredExternalApis.js';
6
7
  import { type ListCandidateSourceFilesOptions } from './projectScan.js';
7
8
  import { type ResourceFindingCandidateV1 } from './resourceFindingCandidate.js';
8
9
  import type { ServiceManifestV0 } from './serviceDiscovery.js';
@@ -17,10 +18,13 @@ export type ResourceAnalyzeResultV0 = {
17
18
  project_id: string;
18
19
  manifest: ServiceManifestV0;
19
20
  findings: ResourceFindingCandidateV1[];
21
+ /** Python analyze twin — catalog seed when uploaded via findings/batch. */
22
+ declared_external_apis: DeclaredExternalApiEntry[];
20
23
  stats: {
21
24
  files_scanned: number;
22
25
  findings: number;
23
26
  by_mechanism: Record<string, number>;
27
+ declared_external_apis: number;
24
28
  };
25
29
  notes: string[];
26
30
  };
@@ -5,11 +5,21 @@
5
5
  */
6
6
  import { readFileSync, statSync } from 'node:fs';
7
7
  import { join } from 'node:path';
8
+ import { collectDeclaredExternalApis, dependencyMapFromPackageJson, } from './declaredExternalApis.js';
8
9
  import { collectPreferAstHits } from './preferAstDetectors.js';
9
10
  import { buildServiceManifestFromPaths, listCandidateSourceFiles, } from './projectScan.js';
10
11
  import { toResourceFindingCandidate, } from './resourceFindingCandidate.js';
11
12
  import { filterValidResourceFindings } from './validateResourceFinding.js';
12
13
  import { isTypescriptAnalyzeAvailable } from './loadTypescript.js';
14
+ function readProjectDependencyMap(projectDir) {
15
+ try {
16
+ const raw = readFileSync(join(projectDir, 'package.json'), { encoding: 'utf8' });
17
+ return dependencyMapFromPackageJson(JSON.parse(raw));
18
+ }
19
+ catch {
20
+ return null;
21
+ }
22
+ }
13
23
  function collectHitsFromSources(sources) {
14
24
  const hits = [];
15
25
  for (const [rel, source] of Object.entries(sources)) {
@@ -61,6 +71,10 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
61
71
  for (const f of findings) {
62
72
  by_mechanism[f.mechanism_id] = (by_mechanism[f.mechanism_id] || 0) + 1;
63
73
  }
74
+ const declared_external_apis = collectDeclaredExternalApis({
75
+ sources,
76
+ packageDependencies: readProjectDependencyMap(projectDir),
77
+ });
64
78
  const manifest = buildServiceManifestFromPaths(projectDir, Object.keys(sources), opts);
65
79
  return {
66
80
  schema: 'resource_analyze_result_v0',
@@ -68,15 +82,18 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
68
82
  project_id: projectId,
69
83
  manifest,
70
84
  findings,
85
+ declared_external_apis,
71
86
  stats: {
72
87
  files_scanned: Object.keys(sources).length,
73
88
  findings: findings.length,
74
89
  by_mechanism,
90
+ declared_external_apis: declared_external_apis.length,
75
91
  },
76
92
  notes: [
77
93
  'MP4 scaffold: TypeScript AST preferred for all current RD0 twins; heuristics fallback when typescript absent',
78
94
  'Stable mechanism_id/evidence_state aligned to resource_finding_v1 + RD0 disposition',
79
95
  'Does not modify RunSession upload, CLI, or VSCE wiring',
96
+ 'declared_external_apis: package.json + static import/require (Python twin); Analyze CLI upload=never — post via SDK findings/batch to seed catalog',
80
97
  'Detectors: retry_amplification, external_api_overconsumption, unbounded_parallelism, polling_or_idle_work, repeated_work, process_or_runtime_churn (subprocess + model_load), memory_retention_or_materialization, per_item_instead_of_batch (nested lookup + inference_inside_loop)',
81
98
  `typescript AST available=${isTypescriptAnalyzeAvailable()}`,
82
99
  'Candidates are fail-closed filtered through vendored resource_finding_v1 JSON Schema (Ajv)',
@@ -14,6 +14,7 @@
14
14
  * --json-summary print machine-readable gate summary only (CI)
15
15
  * --fail-on any|<mechanism>[,…] CI gate (exit 1 when exceeded)
16
16
  * --max-at-or-above <n> with --fail-on: allow up to N matches (default 0)
17
+ * --depth quick|standard|thorough Python-parity LLM file budget (accepted; static analyze ignores)
17
18
  * --quiet suppress non-JSON status lines on stderr
18
19
  */
19
20
  /** Run analyze subcommand; ``argv`` is args after ``analyze`` / bin name. */
@@ -14,6 +14,7 @@
14
14
  * --json-summary print machine-readable gate summary only (CI)
15
15
  * --fail-on any|<mechanism>[,…] CI gate (exit 1 when exceeded)
16
16
  * --max-at-or-above <n> with --fail-on: allow up to N matches (default 0)
17
+ * --depth quick|standard|thorough Python-parity LLM file budget (accepted; static analyze ignores)
17
18
  * --quiet suppress non-JSON status lines on stderr
18
19
  */
19
20
  import { accessSync, constants, statSync } from 'node:fs';
@@ -22,6 +23,7 @@ import { pathToFileURL } from 'node:url';
22
23
  import { buildAnalyzeGateSummary, findingsExceedFailThreshold, formatAnalyzeGateFailureMessage, resolveAnalyzeGateLimit, } from './analyzeGate.js';
23
24
  import { buildResourceAnalyzeResultFromPaths } from './buildResourceFindings.js';
24
25
  import { formatAnalyzeHelp } from '../cli/helpText.js';
26
+ const LLM_DEPTHS = new Set(['quick', 'standard', 'thorough']);
25
27
  function printHelp() {
26
28
  process.stdout.write(formatAnalyzeHelp());
27
29
  }
@@ -34,6 +36,7 @@ function parseArgs(argv) {
34
36
  jsonSummary: false,
35
37
  failOn: null,
36
38
  maxAtOrAbove: null,
39
+ depth: 'standard',
37
40
  quiet: false,
38
41
  help: false,
39
42
  positional: [],
@@ -56,6 +59,24 @@ function parseArgs(argv) {
56
59
  flags.jsonSummary = true;
57
60
  continue;
58
61
  }
62
+ if (arg === '--depth') {
63
+ const value = String(argv[++i] || '')
64
+ .trim()
65
+ .toLowerCase();
66
+ if (!LLM_DEPTHS.has(value)) {
67
+ throw new Error(`Invalid --depth ${value || '(empty)'}. Use quick, standard, or thorough.`);
68
+ }
69
+ flags.depth = value;
70
+ continue;
71
+ }
72
+ if (arg.startsWith('--depth=')) {
73
+ const value = arg.slice('--depth='.length).trim().toLowerCase();
74
+ if (!LLM_DEPTHS.has(value)) {
75
+ throw new Error(`Invalid --depth ${value || '(empty)'}. Use quick, standard, or thorough.`);
76
+ }
77
+ flags.depth = value;
78
+ continue;
79
+ }
59
80
  if (arg === '--quiet') {
60
81
  flags.quiet = true;
61
82
  continue;
@@ -166,7 +187,7 @@ export function runAnalyzeCli(argv) {
166
187
  : result;
167
188
  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
168
189
  if (!flags.quiet && !flags.jsonSummary) {
169
- process.stderr.write(`netgreener analyze: files=${result.stats.files_scanned} findings=${result.stats.findings} upload=never\n`);
190
+ process.stderr.write(`netgreener analyze: files=${result.stats.files_scanned} findings=${result.stats.findings} declared_apis=${result.stats.declared_external_apis} upload=never\n`);
170
191
  }
171
192
  const limit = resolveAnalyzeGateLimit(flags.failOn, flags.maxAtOrAbove);
172
193
  if (flags.failOn && limit != null) {
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Collect structured external-API declarations for Analyze output.
3
+ *
4
+ * Twin of Python ``declared_external_apis.py``: seeds the server catalog via
5
+ * ``POST /findings/batch`` when a caller uploads. Node Analyze CLI remains
6
+ * ``upload=never``; this only builds the payload (package.json + static imports).
7
+ *
8
+ * See ``docs/EXTERNAL_API_PR_TO_RELEASE.md``.
9
+ */
10
+ export type DeclaredExternalApiEntry = {
11
+ provider_key: string;
12
+ detection_method: string;
13
+ module_roots: string[];
14
+ file_paths: string[];
15
+ };
16
+ /** Extract package specs from JS/TS import / require / dynamic import. */
17
+ export declare function extractImportPackageRoots(source: string): string[];
18
+ export type CollectDeclaredExternalApisInput = {
19
+ /** path → source (repo-relative keys). */
20
+ sources?: Record<string, string>;
21
+ /** Parsed package.json dependencies (merged deps + optional peer/optional). */
22
+ packageDependencies?: Record<string, string> | null;
23
+ /** Label for package.json file_paths (default ``package.json``). */
24
+ packageJsonPath?: string;
25
+ };
26
+ /**
27
+ * Build ``declared_external_apis`` rows for analyze / findings-batch.
28
+ */
29
+ export declare function collectDeclaredExternalApis(input?: CollectDeclaredExternalApisInput): DeclaredExternalApiEntry[];
30
+ /** Read dependency map from a package.json object. */
31
+ export declare function dependencyMapFromPackageJson(pkg: unknown): Record<string, string> | null;