@netgreener/runtime 0.1.10 → 0.1.12

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 (39) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/dist/aggregator.d.ts +3 -0
  3. package/dist/aggregator.js +36 -13
  4. package/dist/analyze/buildResourceFindings.d.ts +1 -1
  5. package/dist/analyze/buildResourceFindings.js +4 -2
  6. package/dist/analyze/findingGuidance.d.ts +14 -0
  7. package/dist/analyze/findingGuidance.js +52 -0
  8. package/dist/analyze/index.d.ts +3 -2
  9. package/dist/analyze/index.js +3 -2
  10. package/dist/analyze/projectScan.d.ts +3 -1
  11. package/dist/analyze/projectScan.js +29 -6
  12. package/dist/analyze/resourceFindingCandidate.d.ts +6 -0
  13. package/dist/analyze/resourceFindingCandidate.js +11 -0
  14. package/dist/analyze/serviceDiscovery.d.ts +23 -1
  15. package/dist/analyze/serviceDiscovery.js +164 -4
  16. package/dist/cli/helpText.js +1 -0
  17. package/dist/cli/netgreener.js +8 -0
  18. package/dist/cli/runtimeCli.d.ts +2 -0
  19. package/dist/cli/runtimeCli.js +35 -0
  20. package/dist/config.js +3 -1
  21. package/dist/exporter.js +9 -0
  22. package/dist/externalApiMeter.js +12 -7
  23. package/dist/index.d.ts +1 -1
  24. package/dist/index.js +1 -1
  25. package/dist/managedCollectorLauncher.d.ts +2 -1
  26. package/dist/managedCollectorLauncher.js +2 -1
  27. package/dist/mcpToolMeter.js +6 -1
  28. package/dist/processResources.js +5 -2
  29. package/dist/runtime.d.ts +4 -5
  30. package/dist/runtime.js +86 -50
  31. package/dist/runtimeControls.d.ts +5 -0
  32. package/dist/runtimeControls.js +69 -0
  33. package/dist/runtimeHealth.d.ts +15 -0
  34. package/dist/runtimeHealth.js +47 -1
  35. package/dist/tenantContext.d.ts +4 -0
  36. package/dist/tenantContext.js +36 -10
  37. package/dist/uploader.js +45 -1
  38. package/fixtures/git/canonical_git_key_vectors.v1.json +66 -0
  39. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Changelog — @netgreener/runtime
2
2
 
3
+ ## [0.1.11] — 2026-10-21
4
+
5
+ ### Fixed
6
+ - Preserve exact retry payloads and isolate newly arriving observations.
7
+ - Allocate process CPU and memory consistently across routes and tenants.
8
+ - Bound tenant buckets and improve tenant inference and diagnostics.
9
+ - Improve service discovery and resource-finding guidance for Node projects.
10
+
3
11
  ## [0.1.10] — 2026-10-19
4
12
 
5
13
  ### Added
@@ -4,6 +4,7 @@ export declare class ServiceRuntimeAggregator {
4
4
  private byTenant;
5
5
  private windowStartedAt;
6
6
  resetWindow(): void;
7
+ excludePausedTime(milliseconds: number): void;
7
8
  windowStartedMs(): number;
8
9
  record(sample: {
9
10
  serviceUnit: string;
@@ -40,6 +41,8 @@ export declare class ServiceRuntimeAggregator {
40
41
  windowSeconds: number;
41
42
  /** Crude window RAM (GiB·h); split by occupancy share when present. */
42
43
  windowRamGbHours?: number | null;
44
+ /** One process-wide CPU delta; per-route values are allocated estimates. */
45
+ windowCpuSeconds?: number | null;
43
46
  occupancy?: {
44
47
  by_unit: Record<string, number>;
45
48
  in_flight_seconds: number;
@@ -1,4 +1,5 @@
1
1
  import { energyKwhToCarbonG } from './carbonLedger.js';
2
+ import { tenantBucketId } from './tenantContext.js';
2
3
  const MAX_UNITS = 500;
3
4
  const MAX_SERVICE_UNIT_LEN = 256;
4
5
  function normalizeServiceUnit(raw) {
@@ -22,6 +23,9 @@ export class ServiceRuntimeAggregator {
22
23
  this.byTenant.clear();
23
24
  this.windowStartedAt = Date.now();
24
25
  }
26
+ excludePausedTime(milliseconds) {
27
+ this.windowStartedAt += Math.max(0, milliseconds);
28
+ }
25
29
  windowStartedMs() {
26
30
  return this.windowStartedAt;
27
31
  }
@@ -29,10 +33,11 @@ export class ServiceRuntimeAggregator {
29
33
  const key = normalizeServiceUnit(sample.serviceUnit);
30
34
  this.recordIntoMap(this.units, key, sample);
31
35
  if (sample.tenantId) {
32
- let tenantUnits = this.byTenant.get(sample.tenantId);
36
+ const tenantId = tenantBucketId(sample.tenantId, this.byTenant);
37
+ let tenantUnits = this.byTenant.get(tenantId);
33
38
  if (!tenantUnits) {
34
39
  tenantUnits = new Map();
35
- this.byTenant.set(sample.tenantId, tenantUnits);
40
+ this.byTenant.set(tenantId, tenantUnits);
36
41
  }
37
42
  this.recordIntoMap(tenantUnits, key, sample);
38
43
  }
@@ -97,13 +102,16 @@ export class ServiceRuntimeAggregator {
97
102
  : null;
98
103
  const useOccupancy = Boolean(alloc?.useOccupancy);
99
104
  const sorted = list.sort((a, b) => b.durationMsTotal - a.durationMsTotal);
105
+ const totalCalls = list.reduce((sum, unit) => sum + unit.calls, 0);
100
106
  const units = sorted.map((u) => {
101
- const share = equalShare ? 1 / list.length : u.durationMsTotal / totalDuration;
107
+ const share = equalShare ? u.calls / totalCalls : u.durationMsTotal / totalDuration;
102
108
  const energy = energyBudget * share;
103
109
  const avg = u.calls ? u.durationMsTotal / u.calls : 0;
104
- const cpuSeconds = u.cpuMsMeasured
105
- ? u.cpuMsTotal / 1000
106
- : u.durationMsTotal / 1000;
110
+ const cpuSeconds = alloc?.windowCpuSeconds != null
111
+ ? nonNegativeFinite(alloc.windowCpuSeconds) * share
112
+ : u.cpuMsMeasured
113
+ ? u.cpuMsTotal / 1000
114
+ : u.durationMsTotal / 1000;
107
115
  const unit = {
108
116
  service_unit: u.serviceUnit,
109
117
  unit_type: u.unitType,
@@ -248,21 +256,33 @@ export class ServiceRuntimeAggregator {
248
256
  windowSeconds,
249
257
  windowRamGbHours,
250
258
  useOccupancy,
259
+ windowCpuSeconds: opts.windowCpuSeconds,
251
260
  };
252
261
  const units = this.buildUnitsList(this.units, windowEnergyKwh, equalShare, totalDuration, attributedOccMap, unitAlloc);
253
262
  const byTenant = {};
254
263
  const totalBusy = list.reduce((s, u) => s + u.durationMsTotal, 0);
264
+ const totalCalls = list.reduce((s, u) => s + u.calls, 0);
255
265
  for (const [tenantId, tenantMap] of this.byTenant.entries()) {
256
266
  const tenantList = [...tenantMap.values()].filter((u) => u.calls > 0);
257
267
  if (!tenantList.length)
258
268
  continue;
259
269
  const tenantBusy = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
270
+ const tenantShare = totalBusy > 0 ? tenantBusy / totalBusy
271
+ : tenantList.reduce((sum, unit) => sum + unit.calls, 0) / totalCalls;
260
272
  const tenantEnergy = totalBusy > 0
261
273
  ? windowEnergyKwh * (tenantBusy / totalBusy)
262
- : windowEnergyKwh / Math.max(1, this.byTenant.size);
274
+ : windowEnergyKwh * tenantShare;
263
275
  const tenantDuration = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
264
276
  const tenantEqual = tenantDuration <= 0;
265
- const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration, attributedOccMap, unitAlloc);
277
+ const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration, attributedOccMap, {
278
+ ...unitAlloc,
279
+ // Route occupancy cannot identify tenants sharing that route.
280
+ useOccupancy: false,
281
+ windowRamGbHours: windowRamGbHours == null ? null
282
+ : windowRamGbHours * tenantShare,
283
+ windowCpuSeconds: opts.windowCpuSeconds == null ? null
284
+ : opts.windowCpuSeconds * tenantShare,
285
+ });
266
286
  if (!tenantUnits.length)
267
287
  continue;
268
288
  byTenant[tenantId] = {
@@ -286,9 +306,11 @@ export class ServiceRuntimeAggregator {
286
306
  else
287
307
  attribution = 'duration_share';
288
308
  const attribution_detail = {
289
- cpu: measuredCpu
290
- ? { method: 'request_process_cpu_time', kind: 'measured' }
291
- : { method: 'request_duration_proxy', kind: 'proxy' },
309
+ cpu: opts.windowCpuSeconds != null
310
+ ? { method: 'process_window_duration_share', kind: 'allocated_estimate' }
311
+ : measuredCpu
312
+ ? { method: 'request_process_cpu_time', kind: 'proxy' }
313
+ : { method: 'request_duration_proxy', kind: 'proxy' },
292
314
  ram: {
293
315
  method: useOccupancy
294
316
  ? 'concurrency_normalized_active_occupancy'
@@ -303,7 +325,7 @@ export class ServiceRuntimeAggregator {
303
325
  },
304
326
  gpu: { method: 'none', kind: 'unavailable' },
305
327
  energy: {
306
- cpu_dynamic: measuredCpu ? 'cpu_time_share_preferred' : 'duration_share',
328
+ cpu_dynamic: 'duration_share',
307
329
  memory: useOccupancy ? 'ram_occupancy_share' : 'unallocated',
308
330
  gpu: 'none',
309
331
  },
@@ -361,7 +383,8 @@ export class ServiceRuntimeAggregator {
361
383
  this.windowStartedAt = Math.min(this.windowStartedAt, snapshot.windowStartedAt);
362
384
  }
363
385
  this.mergeMap(this.units, snapshot.units);
364
- for (const [tenantId, sourceMap] of snapshot.byTenant.entries()) {
386
+ for (const [sourceTenantId, sourceMap] of snapshot.byTenant.entries()) {
387
+ const tenantId = tenantBucketId(sourceTenantId, this.byTenant);
365
388
  let targetMap = this.byTenant.get(tenantId);
366
389
  if (!targetMap) {
367
390
  targetMap = new Map();
@@ -6,7 +6,7 @@
6
6
  import { type DeclaredExternalApiEntry } from './declaredExternalApis.js';
7
7
  import { type ListCandidateSourceFilesOptions } from './projectScan.js';
8
8
  import { type ResourceFindingCandidateV1 } from './resourceFindingCandidate.js';
9
- import type { ServiceManifestV0 } from './serviceDiscovery.js';
9
+ import { type ServiceManifestV0 } from './serviceDiscovery.js';
10
10
  export type BuildResourceFindingsOptions = ListCandidateSourceFilesOptions & {
11
11
  projectId?: string;
12
12
  /** Max candidate findings to return (default 50). */
@@ -9,6 +9,7 @@ import { collectDeclaredExternalApis, dependencyMapFromPackageJson, } from './de
9
9
  import { collectPreferAstHits } from './preferAstDetectors.js';
10
10
  import { buildServiceManifestFromPaths, listCandidateSourceFiles, } from './projectScan.js';
11
11
  import { toResourceFindingCandidate, } from './resourceFindingCandidate.js';
12
+ import { attachServiceUnitsToFindings } from './serviceDiscovery.js';
12
13
  import { filterValidResourceFindings } from './validateResourceFinding.js';
13
14
  import { isTypescriptAnalyzeAvailable } from './loadTypescript.js';
14
15
  function readProjectDependencyMap(projectDir) {
@@ -66,7 +67,8 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
66
67
  continue;
67
68
  }
68
69
  }
69
- const findings = buildResourceFindingsFromSources(sources, opts);
70
+ const manifest = buildServiceManifestFromPaths(projectDir, Object.keys(sources), opts);
71
+ const findings = attachServiceUnitsToFindings(buildResourceFindingsFromSources(sources, opts), manifest);
70
72
  const by_mechanism = {};
71
73
  for (const f of findings) {
72
74
  by_mechanism[f.mechanism_id] = (by_mechanism[f.mechanism_id] || 0) + 1;
@@ -75,7 +77,6 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
75
77
  sources,
76
78
  packageDependencies: readProjectDependencyMap(projectDir),
77
79
  });
78
- const manifest = buildServiceManifestFromPaths(projectDir, Object.keys(sources), opts);
79
80
  return {
80
81
  schema: 'resource_analyze_result_v0',
81
82
  contract_status: 'mp4_scaffold',
@@ -97,6 +98,7 @@ export function buildResourceAnalyzeResultFromPaths(projectDir, relPaths, opts =
97
98
  '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)',
98
99
  `typescript AST available=${isTypescriptAnalyzeAvailable()}`,
99
100
  'Candidates are fail-closed filtered through vendored resource_finding_v1 JSON Schema (Ajv)',
101
+ 'Guidance is optimization.summary (schema-legal); Next App Router / Pages API fill service_manifest endpoints',
100
102
  'Skipped RD0 context-only: http_call_without_timeout; skipped low-energy print_in_loop; skipped ML-only excess_training_work / accelerator_underutilization',
101
103
  ],
102
104
  };
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Candidate-safe guidance for Node Analyze findings.
3
+ *
4
+ * resource_finding_v1 forbids extra top-level fields. Guidance belongs on
5
+ * optional ``optimization.{hypothesis_id,summary,risk}`` — never a new property.
6
+ * Does not upload, verify, or claim measured savings.
7
+ */
8
+ export type MechanismGuidance = {
9
+ hypothesis_id: string;
10
+ summary: string;
11
+ risk: 'low' | 'medium' | 'high';
12
+ };
13
+ export declare const MECHANISM_GUIDANCE: Record<string, MechanismGuidance>;
14
+ export declare function optimizationForMechanism(mechanismId: string): MechanismGuidance | null;
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Candidate-safe guidance for Node Analyze findings.
3
+ *
4
+ * resource_finding_v1 forbids extra top-level fields. Guidance belongs on
5
+ * optional ``optimization.{hypothesis_id,summary,risk}`` — never a new property.
6
+ * Does not upload, verify, or claim measured savings.
7
+ */
8
+ export const MECHANISM_GUIDANCE = {
9
+ retry_amplification: {
10
+ hypothesis_id: 'cap_retries_jitter',
11
+ summary: 'Cap retry attempts and add exponential backoff with jitter so failed calls do not multiply paid traffic.',
12
+ risk: 'medium',
13
+ },
14
+ external_api_overconsumption: {
15
+ hypothesis_id: 'batch_or_cache_api',
16
+ summary: 'Batch requests, cache stable responses, or move the call outside the hot path so cost does not scale with every item.',
17
+ risk: 'medium',
18
+ },
19
+ unbounded_parallelism: {
20
+ hypothesis_id: 'limit_concurrency',
21
+ summary: 'Bound concurrency with a pool or semaphore so fan-out cannot exhaust sockets, workers, or provider rate limits.',
22
+ risk: 'high',
23
+ },
24
+ polling_or_idle_work: {
25
+ hypothesis_id: 'replace_poll_sleep',
26
+ summary: 'Replace tight poll/sleep loops with a webhook, queue, or backoff so idle wait does not burn CPU and outbound calls.',
27
+ risk: 'medium',
28
+ },
29
+ repeated_work: {
30
+ hypothesis_id: 'reuse_computed_result',
31
+ summary: 'Hoist or cache repeated reads and identical work so the same payload is not fetched or recomputed every iteration.',
32
+ risk: 'low',
33
+ },
34
+ process_or_runtime_churn: {
35
+ hypothesis_id: 'reuse_runtime_process',
36
+ summary: 'Reuse a long-lived process or loaded model instead of spawning or reloading on every request or loop iteration.',
37
+ risk: 'high',
38
+ },
39
+ memory_retention_or_materialization: {
40
+ hypothesis_id: 'stream_or_chunk',
41
+ summary: 'Stream or chunk the dataset instead of materializing the full collection in memory on the hot path.',
42
+ risk: 'medium',
43
+ },
44
+ per_item_instead_of_batch: {
45
+ hypothesis_id: 'batch_per_item_work',
46
+ summary: 'Replace per-item lookups or inference with a batched API or join so work grows with batches, not each row.',
47
+ risk: 'medium',
48
+ },
49
+ };
50
+ export function optimizationForMechanism(mechanismId) {
51
+ return MECHANISM_GUIDANCE[mechanismId] ?? null;
52
+ }
@@ -1,5 +1,6 @@
1
- export { buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, type ServiceEndpointUnit, type ServiceFileExtraction, type ServiceManifestV0, type ServiceTaskUnit, } from './serviceDiscovery.js';
2
- export { buildServiceManifestFromPaths, listCandidateSourceFiles, type ListCandidateSourceFilesOptions, } from './projectScan.js';
1
+ export { attachServiceUnitsToFindings, buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, nextFileRoutePath, type ServiceEndpointUnit, type ServiceFileExtraction, type ServiceManifestV0, type ServiceTaskUnit, } from './serviceDiscovery.js';
2
+ export { DEFAULT_MAX_SOURCE_FILES, buildServiceManifestFromPaths, listCandidateSourceFiles, type ListCandidateSourceFilesOptions, } from './projectScan.js';
3
+ export { MECHANISM_GUIDANCE, optimizationForMechanism, type MechanismGuidance, } from './findingGuidance.js';
3
4
  export { NON_RESOURCE_CATEGORIES, RESOURCE_DOMAINS, admitAnalyzeCandidate, isNonResourceCategory, type AdmissionDecision, type NonResourceCategory, type ResourceDomain, } from './resourceAdmission.js';
4
5
  export { languageForPath, toResourceFindingCandidate, type ResourceCandidateHit, type ResourceFindingCandidateV1, type ResourcePrimaryDomain, } from './resourceFindingCandidate.js';
5
6
  export { detectRetryAmplificationHits } from './retryAmplificationDetector.js';
@@ -1,5 +1,6 @@
1
- export { buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, } from './serviceDiscovery.js';
2
- export { buildServiceManifestFromPaths, listCandidateSourceFiles, } from './projectScan.js';
1
+ export { attachServiceUnitsToFindings, buildServiceManifest, detectFrameworks, extractServiceUnits, isServiceProject, nextFileRoutePath, } from './serviceDiscovery.js';
2
+ export { DEFAULT_MAX_SOURCE_FILES, buildServiceManifestFromPaths, listCandidateSourceFiles, } from './projectScan.js';
3
+ export { MECHANISM_GUIDANCE, optimizationForMechanism, } from './findingGuidance.js';
3
4
  export { NON_RESOURCE_CATEGORIES, RESOURCE_DOMAINS, admitAnalyzeCandidate, isNonResourceCategory, } from './resourceAdmission.js';
4
5
  export { languageForPath, toResourceFindingCandidate, } from './resourceFindingCandidate.js';
5
6
  export { detectRetryAmplificationHits } from './retryAmplificationDetector.js';
@@ -1,6 +1,8 @@
1
1
  import { type ServiceManifestV0 } from './serviceDiscovery.js';
2
+ /** Default Analyze walk cap — large enough for Next App Router trees. */
3
+ export declare const DEFAULT_MAX_SOURCE_FILES = 5000;
2
4
  export type ListCandidateSourceFilesOptions = {
3
- /** Max files to return (default 200). */
5
+ /** Max files to return (default 5000). */
4
6
  maxFiles?: number;
5
7
  /** Max bytes to read per file when building a manifest (default 512 KiB). */
6
8
  maxFileBytes?: number;
@@ -4,7 +4,10 @@
4
4
  */
5
5
  import { readdirSync, readFileSync, statSync } from 'node:fs';
6
6
  import { join, relative, sep } from 'node:path';
7
- import { buildServiceManifest } from './serviceDiscovery.js';
7
+ import { buildServiceManifest, nextFileRoutePath, } from './serviceDiscovery.js';
8
+ /** Default Analyze walk cap — large enough for Next App Router trees. */
9
+ export const DEFAULT_MAX_SOURCE_FILES = 5000;
10
+ const WALK_SAFETY_CAP = 20_000;
8
11
  const DEFAULT_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
9
12
  const DEFAULT_SKIP_DIR_NAMES = new Set([
10
13
  'node_modules',
@@ -20,17 +23,31 @@ const DEFAULT_SKIP_DIR_NAMES = new Set([
20
23
  function normalizeRel(path) {
21
24
  return path.split(sep).join('/');
22
25
  }
26
+ function scanRank(rel) {
27
+ const n = rel.replace(/\\/g, '/');
28
+ if (nextFileRoutePath(n))
29
+ return 0;
30
+ if (n.startsWith('app/') ||
31
+ n.startsWith('src/app/') ||
32
+ n.startsWith('pages/') ||
33
+ n.startsWith('src/pages/')) {
34
+ return 1;
35
+ }
36
+ if (n.startsWith('src/'))
37
+ return 2;
38
+ return 3;
39
+ }
23
40
  /**
24
41
  * List repo-relative JS/TS source paths under ``projectDir`` (bounded).
25
42
  * Never throws — returns [] on errors.
26
43
  */
27
44
  export function listCandidateSourceFiles(projectDir, opts = {}) {
28
- const maxFiles = Math.max(1, opts.maxFiles ?? 200);
45
+ const maxFiles = Math.max(1, opts.maxFiles ?? DEFAULT_MAX_SOURCE_FILES);
29
46
  const extensions = new Set([...(opts.extensions ?? DEFAULT_EXTENSIONS)].map((e) => e.toLowerCase()));
30
47
  const skip = new Set([...(opts.skipDirNames ?? DEFAULT_SKIP_DIR_NAMES)].map((n) => n.toLowerCase()));
31
48
  const out = [];
32
49
  const walk = (absDir) => {
33
- if (out.length >= maxFiles)
50
+ if (out.length >= WALK_SAFETY_CAP)
34
51
  return;
35
52
  let entries;
36
53
  try {
@@ -40,7 +57,7 @@ export function listCandidateSourceFiles(projectDir, opts = {}) {
40
57
  return;
41
58
  }
42
59
  for (const entry of entries) {
43
- if (out.length >= maxFiles)
60
+ if (out.length >= WALK_SAFETY_CAP)
44
61
  return;
45
62
  const name = entry.name;
46
63
  if (name.startsWith('.') && name !== '.env.example') {
@@ -76,7 +93,8 @@ export function listCandidateSourceFiles(projectDir, opts = {}) {
76
93
  return [];
77
94
  }
78
95
  walk(projectDir);
79
- return out.sort();
96
+ out.sort((a, b) => scanRank(a) - scanRank(b) || a.localeCompare(b));
97
+ return out.slice(0, maxFiles);
80
98
  }
81
99
  /**
82
100
  * Read supplied repo-relative paths (or auto-walk) and build ``service_manifest_v0``.
@@ -102,10 +120,15 @@ export function buildServiceManifestFromPaths(projectDir, relPaths, opts = {}) {
102
120
  }
103
121
  }
104
122
  const manifest = buildServiceManifest(sources);
123
+ const scanned = Object.keys(sources).length;
124
+ const maxFiles = Math.max(1, opts.maxFiles ?? DEFAULT_MAX_SOURCE_FILES);
105
125
  manifest.notes = [
106
126
  ...manifest.notes,
107
- `scanned_files=${Object.keys(sources).length}`,
127
+ `scanned_files=${scanned}`,
108
128
  relPaths ? 'paths=explicit' : 'paths=auto_walk',
129
+ ...(!relPaths && scanned >= maxFiles
130
+ ? [`scan_truncated=true max_files=${maxFiles}`]
131
+ : []),
109
132
  ];
110
133
  return manifest;
111
134
  }
@@ -36,6 +36,12 @@ export type ResourceFindingCandidateV1 = {
36
36
  observation_ids: string[];
37
37
  benchmark_result_ids: string[];
38
38
  };
39
+ /** Optional candidate guidance — schema-legal subset of resource_finding_v1.optimization. */
40
+ optimization?: {
41
+ hypothesis_id: string;
42
+ summary: string;
43
+ risk: 'low' | 'medium' | 'high';
44
+ };
39
45
  };
40
46
  export type ResourceCandidateHit = {
41
47
  mechanism_id: string;
@@ -5,6 +5,7 @@
5
5
  * change RunSession, and does not claim Optimize / verified savings.
6
6
  */
7
7
  import { createHash } from 'node:crypto';
8
+ import { optimizationForMechanism } from './findingGuidance.js';
8
9
  import { admitAnalyzeCandidate } from './resourceAdmission.js';
9
10
  const POLICY_VERSION = '0.1.0';
10
11
  function languageFromPath(relPath) {
@@ -36,6 +37,7 @@ export function toResourceFindingCandidate(hit, projectId = 'local') {
36
37
  return null;
37
38
  const language = hit.language || languageFromPath(hit.rel_path);
38
39
  const scopeId = (hit.symbol || hit.rel_path).slice(0, 200);
40
+ const guidance = optimizationForMechanism(hit.mechanism_id);
39
41
  return {
40
42
  schema_version: 'resource_finding_v1',
41
43
  finding_id: stableFindingId(hit, projectId).slice(0, 128),
@@ -68,6 +70,15 @@ export function toResourceFindingCandidate(hit, projectId = 'local') {
68
70
  observation_ids: [],
69
71
  benchmark_result_ids: [],
70
72
  },
73
+ ...(guidance
74
+ ? {
75
+ optimization: {
76
+ hypothesis_id: guidance.hypothesis_id.slice(0, 64),
77
+ summary: guidance.summary.slice(0, 400),
78
+ risk: guidance.risk,
79
+ },
80
+ }
81
+ : {}),
71
82
  };
72
83
  }
73
84
  export function languageForPath(relPath) {
@@ -54,8 +54,13 @@ export type ServiceManifestV0 = {
54
54
  };
55
55
  notes: string[];
56
56
  };
57
+ /**
58
+ * HTTP path implied by a Next.js App Router ``route`` file or Pages ``pages/api`` file.
59
+ * Route groups ``(marketing)`` and parallel slots ``@modal`` are dropped.
60
+ */
61
+ export declare function nextFileRoutePath(relPath: string): string | null;
57
62
  /** Frameworks whose imports / requires appear in ``source``. */
58
- export declare function detectFrameworks(source: string): string[];
63
+ export declare function detectFrameworks(source: string, relPath?: string): string[];
59
64
  /**
60
65
  * Extract service units from one JS/TS source string.
61
66
  * Never throws on bad source — returns empty collections.
@@ -64,3 +69,20 @@ export declare function extractServiceUnits(sourceCode: string, relPath?: string
64
69
  /** Project-level ``service_manifest_v0`` from ``{relPath: source}``. */
65
70
  export declare function buildServiceManifest(fileSources: Record<string, string>): ServiceManifestV0;
66
71
  export declare function isServiceProject(manifest: ServiceManifestV0): boolean;
72
+ type FindingScope = {
73
+ kind: 'function' | 'service_unit' | 'task' | 'script';
74
+ id: string;
75
+ source_locations: Array<{
76
+ path: string;
77
+ start_line: number;
78
+ end_line: number;
79
+ }>;
80
+ };
81
+ /**
82
+ * Attribute a finding to the owning endpoint/task when the file+line is unambiguous.
83
+ * Same rule as Python ``attach_service_units``: innermost span, else sole unit on the file.
84
+ */
85
+ export declare function attachServiceUnitsToFindings<T extends {
86
+ scope: FindingScope;
87
+ }>(findings: T[], manifest: ServiceManifestV0): T[];
88
+ export {};