@netgreener/runtime 0.1.9 → 0.1.11

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 (44) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/dist/aggregator.d.ts +2 -0
  3. package/dist/aggregator.js +33 -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/externalApiMeter.d.ts +8 -1
  17. package/dist/externalApiMeter.js +118 -25
  18. package/dist/index.d.ts +3 -1
  19. package/dist/index.js +3 -1
  20. package/dist/managedCollectorLauncher.d.ts +2 -1
  21. package/dist/managedCollectorLauncher.js +2 -1
  22. package/dist/mcpToolMeter.d.ts +101 -0
  23. package/dist/mcpToolMeter.js +496 -0
  24. package/dist/next.d.ts +28 -0
  25. package/dist/next.js +143 -10
  26. package/dist/nextConfig.d.ts +34 -0
  27. package/dist/nextConfig.js +73 -0
  28. package/dist/nextEntryTransform.d.ts +9 -0
  29. package/dist/nextEntryTransform.js +181 -0
  30. package/dist/runtime.d.ts +12 -6
  31. package/dist/runtime.js +113 -52
  32. package/dist/runtimeHealth.js +1 -1
  33. package/dist/tenantContext.d.ts +3 -0
  34. package/dist/tenantContext.js +35 -9
  35. package/dist/types.d.ts +8 -0
  36. package/examples/azure-functions-gate/.funcignore +6 -0
  37. package/examples/azure-functions-gate/README.md +25 -0
  38. package/examples/azure-functions-gate/host.json +15 -0
  39. package/examples/azure-functions-gate/package-lock.json +161 -0
  40. package/examples/azure-functions-gate/package.json +14 -0
  41. package/examples/azure-functions-gate/src/functions/health.js +27 -0
  42. package/fixtures/git/canonical_git_key_vectors.v1.json +66 -0
  43. package/loaders/next-entry-loader.cjs +14 -0
  44. package/package.json +3 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,25 @@
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
+
11
+ ## [0.1.10] — 2026-10-19
12
+
13
+ ### Added
14
+ - Next.js config wrapper and `loaders/next-entry-loader.cjs` for App Router route, page, and server-action observation
15
+ - Ephemeral invoke flush after the response closes
16
+ - `calls_unknown` on external API rows when a call has no token usage
17
+
18
+ ## [0.1.9] — 2026-10-12
19
+
20
+ ### Added
21
+ - Public export `@netgreener/runtime/next`
22
+
3
23
  ## [0.1.8] — 2026-09-27
4
24
 
5
25
  ### Fixed
@@ -40,6 +40,8 @@ export declare class ServiceRuntimeAggregator {
40
40
  windowSeconds: number;
41
41
  /** Crude window RAM (GiB·h); split by occupancy share when present. */
42
42
  windowRamGbHours?: number | null;
43
+ /** One process-wide CPU delta; per-route values are allocated estimates. */
44
+ windowCpuSeconds?: number | null;
43
45
  occupancy?: {
44
46
  by_unit: Record<string, number>;
45
47
  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) {
@@ -29,10 +30,11 @@ export class ServiceRuntimeAggregator {
29
30
  const key = normalizeServiceUnit(sample.serviceUnit);
30
31
  this.recordIntoMap(this.units, key, sample);
31
32
  if (sample.tenantId) {
32
- let tenantUnits = this.byTenant.get(sample.tenantId);
33
+ const tenantId = tenantBucketId(sample.tenantId, this.byTenant);
34
+ let tenantUnits = this.byTenant.get(tenantId);
33
35
  if (!tenantUnits) {
34
36
  tenantUnits = new Map();
35
- this.byTenant.set(sample.tenantId, tenantUnits);
37
+ this.byTenant.set(tenantId, tenantUnits);
36
38
  }
37
39
  this.recordIntoMap(tenantUnits, key, sample);
38
40
  }
@@ -97,13 +99,16 @@ export class ServiceRuntimeAggregator {
97
99
  : null;
98
100
  const useOccupancy = Boolean(alloc?.useOccupancy);
99
101
  const sorted = list.sort((a, b) => b.durationMsTotal - a.durationMsTotal);
102
+ const totalCalls = list.reduce((sum, unit) => sum + unit.calls, 0);
100
103
  const units = sorted.map((u) => {
101
- const share = equalShare ? 1 / list.length : u.durationMsTotal / totalDuration;
104
+ const share = equalShare ? u.calls / totalCalls : u.durationMsTotal / totalDuration;
102
105
  const energy = energyBudget * share;
103
106
  const avg = u.calls ? u.durationMsTotal / u.calls : 0;
104
- const cpuSeconds = u.cpuMsMeasured
105
- ? u.cpuMsTotal / 1000
106
- : u.durationMsTotal / 1000;
107
+ const cpuSeconds = alloc?.windowCpuSeconds != null
108
+ ? nonNegativeFinite(alloc.windowCpuSeconds) * share
109
+ : u.cpuMsMeasured
110
+ ? u.cpuMsTotal / 1000
111
+ : u.durationMsTotal / 1000;
107
112
  const unit = {
108
113
  service_unit: u.serviceUnit,
109
114
  unit_type: u.unitType,
@@ -248,21 +253,33 @@ export class ServiceRuntimeAggregator {
248
253
  windowSeconds,
249
254
  windowRamGbHours,
250
255
  useOccupancy,
256
+ windowCpuSeconds: opts.windowCpuSeconds,
251
257
  };
252
258
  const units = this.buildUnitsList(this.units, windowEnergyKwh, equalShare, totalDuration, attributedOccMap, unitAlloc);
253
259
  const byTenant = {};
254
260
  const totalBusy = list.reduce((s, u) => s + u.durationMsTotal, 0);
261
+ const totalCalls = list.reduce((s, u) => s + u.calls, 0);
255
262
  for (const [tenantId, tenantMap] of this.byTenant.entries()) {
256
263
  const tenantList = [...tenantMap.values()].filter((u) => u.calls > 0);
257
264
  if (!tenantList.length)
258
265
  continue;
259
266
  const tenantBusy = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
267
+ const tenantShare = totalBusy > 0 ? tenantBusy / totalBusy
268
+ : tenantList.reduce((sum, unit) => sum + unit.calls, 0) / totalCalls;
260
269
  const tenantEnergy = totalBusy > 0
261
270
  ? windowEnergyKwh * (tenantBusy / totalBusy)
262
- : windowEnergyKwh / Math.max(1, this.byTenant.size);
271
+ : windowEnergyKwh * tenantShare;
263
272
  const tenantDuration = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
264
273
  const tenantEqual = tenantDuration <= 0;
265
- const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration, attributedOccMap, unitAlloc);
274
+ const tenantUnits = this.buildUnitsList(tenantMap, tenantEnergy, tenantEqual, tenantDuration, attributedOccMap, {
275
+ ...unitAlloc,
276
+ // Route occupancy cannot identify tenants sharing that route.
277
+ useOccupancy: false,
278
+ windowRamGbHours: windowRamGbHours == null ? null
279
+ : windowRamGbHours * tenantShare,
280
+ windowCpuSeconds: opts.windowCpuSeconds == null ? null
281
+ : opts.windowCpuSeconds * tenantShare,
282
+ });
266
283
  if (!tenantUnits.length)
267
284
  continue;
268
285
  byTenant[tenantId] = {
@@ -286,9 +303,11 @@ export class ServiceRuntimeAggregator {
286
303
  else
287
304
  attribution = 'duration_share';
288
305
  const attribution_detail = {
289
- cpu: measuredCpu
290
- ? { method: 'request_process_cpu_time', kind: 'measured' }
291
- : { method: 'request_duration_proxy', kind: 'proxy' },
306
+ cpu: opts.windowCpuSeconds != null
307
+ ? { method: 'process_window_duration_share', kind: 'allocated_estimate' }
308
+ : measuredCpu
309
+ ? { method: 'request_process_cpu_time', kind: 'proxy' }
310
+ : { method: 'request_duration_proxy', kind: 'proxy' },
292
311
  ram: {
293
312
  method: useOccupancy
294
313
  ? 'concurrency_normalized_active_occupancy'
@@ -303,7 +322,7 @@ export class ServiceRuntimeAggregator {
303
322
  },
304
323
  gpu: { method: 'none', kind: 'unavailable' },
305
324
  energy: {
306
- cpu_dynamic: measuredCpu ? 'cpu_time_share_preferred' : 'duration_share',
325
+ cpu_dynamic: 'duration_share',
307
326
  memory: useOccupancy ? 'ram_occupancy_share' : 'unallocated',
308
327
  gpu: 'none',
309
328
  },
@@ -361,7 +380,8 @@ export class ServiceRuntimeAggregator {
361
380
  this.windowStartedAt = Math.min(this.windowStartedAt, snapshot.windowStartedAt);
362
381
  }
363
382
  this.mergeMap(this.units, snapshot.units);
364
- for (const [tenantId, sourceMap] of snapshot.byTenant.entries()) {
383
+ for (const [sourceTenantId, sourceMap] of snapshot.byTenant.entries()) {
384
+ const tenantId = tenantBucketId(sourceTenantId, this.byTenant);
365
385
  let targetMap = this.byTenant.get(tenantId);
366
386
  if (!targetMap) {
367
387
  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 {};