@bbradar/mcp 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release notes
 
+## 0.3.1 — hunt deadlines and target accuracy (2026-10-13)
+
+- Reduced unnecessary upstream target rows for small direct reads while preserving offset/limit semantics and full-page scans for local filters. Added a live STDIO check with fresh prefix comparison and cache diagnostics. Catalog concurrency remains four: smaller-pool trials did not establish a reliable improvement under changing API latency.
+- Fixed target inventory pagination in latest-addition and named-program workflows, added language-filter continuations, and exposed remaining offsets. Named target actions now honor target-type and language filters.
+- Marked bounded scope counts and capped legacy exports as incomplete instead of full inventory totals. Export fallbacks reject upstream filters they cannot preserve. Malformed collection pages now fail explicitly rather than becoming empty successes.
+- Rejected unknown arguments across all tools, respected negotiated aggregate page limits, and corrected SDK version diagnostics with a packaged-server regression check. Added live workflow smoke checks that report aggregate measurements and stop on failure without retries.
+- Reserved catalog, recent-change and target-sampling time within the hunt's existing tool deadline. Slow optional reads no longer consume the entire call; completed catalog pages survive later-page timeouts with explicit incomplete coverage, errors and phase timings.
+- Applied existing hunt VDP exclusion upstream when negotiated, preserving unknown classifications and the local filters. Added a read-only live hunt benchmark with aggregate timings and quota reporting, plus deadline, cancellation, coverage and legacy-API regression fixtures. Retained the four-request catalog limit after live concurrency comparisons showed no reliable gain from six.
+- Rejected Activity version IDs on catalog/feed snapshot inputs and validated required signal periods and payout metric/period combinations before sending requests. Tool descriptions and guides distinguish the two snapshot contracts and preserve user filters after empty or partial results.
+
 ## 0.3.0 — Activity and payout views (2026-10-12)
 
 - Added five Activity tools to the default 30-tool `core` profile: `get_activity_capabilities`, `get_activity_snapshot`, `get_activity_rankings`, `get_program_payouts`, and `get_activity_change_detail`. Rankings cover payouts, Value, scope, rewards, updates, reports, response, status and all changes. The `full` profile also exposes nine per-view aliases.

package/README.md

@@ -135,6 +135,8 @@ Repository results preserve the API's comparison completeness/method/ancestry ev
 
 `search_programs`, `search_targets`, `get_recent_changes`, and `get_repository_changes` accept the API's optional stable `snapshot` token. Send `snapshot: "start"` on page 1 and reuse the returned `meta.snapshot` with identical filters until `meta.snapshot_expires_at`. Snapshot responses bypass the local TTL cache, and an expired snapshot 410 is not mistaken for an expired change-feed cursor. Snapshot creation receives a 60-second minimum request timeout because it performs consistency work and can be materially slower; the fast `find_hunt_targets` workflow intentionally keeps live indexed paging and the ordinary configured timeout.
 
+Catalog and feed snapshot tokens have at most 32 characters. `find_programs` uses that same contract. The 64-character version ID from `get_activity_snapshot` binds only Activity capabilities, rankings, event details and program payouts; do not pass it to catalog discovery.
+
 ### Activity and payouts
 
 Use `get_activity_capabilities` before choosing a ranking. Its versioned views give
@@ -344,6 +346,22 @@ Already-retired historical events cannot be reconstructed. `get_program_targets`
 follows upstream API pages until it can satisfy the requested offset/limit or the
 inventory ends. Missing public scope is treated as out of scope.
 
+Target lists expose `meta.has_more` and `meta.next_offset`; repeat the same filters
+with that offset to continue. `language_tags` applies while scanning pages, so
+sparse matches do not skip eligible targets. Named target actions honor their
+target-type and language filters. `get_latest_added_targets` also pages its optional
+inventory and returns `full_targets_next_offset` for `get_program_targets`.
+Scope summaries and breakdowns label sampled counts with `count_scope` and
+`possibly_incomplete`; unknown full filtered totals are omitted. Legacy export
+fallbacks disclose their cap and reject filters whose upstream semantics they
+cannot preserve. All tools reject unknown arguments, and malformed collection
+responses return errors instead of claiming the inventory is empty.
+
+Small direct target reads request only the prefix needed for their offset and limit,
+up to the negotiated page size, instead of always loading a 500-row page. Local
+scope and language post-filters retain full pages to find sparse matches. This
+reduces excess transfer and processing while preserving fresh reads and row offsets.
+
 Cursors are memory-only by default. Set `BBRADAR_MCP_CURSOR_STATE_PATH` to opt into restart-safe cursor persistence. The state file contains only endpoint-prefixed SHA-256 filter hashes and non-negative numeric IDs—never raw filters, API responses, program or target records, credentials, or authorization headers.
 
 For cacheable responses, large target and change collections return at most 50 inline records by default; the remainder is held in a bounded, ten-minute continuation resource. Private or `no-store` pages stay in the current structured result and are never put in a reusable continuation. Compact tool text keeps model context small.
@@ -379,6 +397,24 @@ Call `get_mcp_status` to inspect cache and stale-hit rates, circuit states, curs
 
 Run `npm run benchmark` for deterministic local benchmarks. They report request and byte counts, model-context bytes, latency percentiles, and memory under representative History and analytics concurrency. Fixture timings are separate from live API latency.
 
+With `BBRADAR_API_KEY` already configured, run `npm run build` then `node benchmark/live-hunt.mjs` for one authenticated all-platform Web2 hunt (domain/API, $5,000 maximum bounty, at least three eligible and five total targets, 15 results). It reports aggregate phase timings, request counts, quota and sampled coverage without printing the key or program/target records. This consumes live API quota and makes no automatic retries. Live catalog updates can change rows between pages; signatures help distinguish result changes from timing changes.
+
+`node benchmark/live-api-check.mjs` checks negotiated capabilities, discovery,
+all nine Activity tabs, program and target reads, payouts, History, daily analytics,
+feeds, combined filters and the same hunt. It emits aggregate measurements and
+stops at the first failure. An optional section (`activity`, `programs`, `analytics`,
+`feeds`, or `hunt`) runs only that workflow and its prerequisites, so independent
+checks can continue without repeating successful sections. These are live reads
+and consume quota; a smoke pass is not an uptime or complete-catalog guarantee.
+
+`node benchmark/live-stdio.mjs` performs the original hunt through the actual
+STDIO server entry point using the configured key, then compares a fresh small
+target page with the prefix of a fresh wider page. Use `targets` to run the target
+check independently. It reports cache activity, timings and counts, never target
+identifiers. Partial hunts fail the benchmark instead of counting as speed gains.
+`live-hunt.mjs --catalog-concurrency=2` can test a lower catalog request cap;
+inspect both timings and coverage before adopting a concurrency change.
+
 Maintainers can compare the working tree against a committed revision with `npm run build` followed by `node --expose-gc benchmark/compare-revisions.mjs HEAD`. This uses the same fixtures and alternating samples for both revisions, reports discovery and result sizes, and measures repeated private reads separately from cacheable reads. It requires the repository and development dependencies.
 
 Run `npm run test:package` to pack the release, install its production dependencies in a temporary directory, audit them, and exercise the packaged STDIO server. CI runs the checks on Node 20, 22, and 24.
@@ -393,6 +429,12 @@ Use `find_hunt_targets` as the default one-call path when a request combines goo
 
 `find_hunt_targets` supports arbitrary platform inclusion/exclusion, scope/target/language filters, reward and breadth thresholds, Web2/Web3 modes, target-intelligence filters, freshness windows, `free_submission_only`, and balanced/reward/scope/freshness/competition ranking. Activity inputs such as `payout_period: "30d"` with `payout_positive: true`, or `scope_period: "30d"` with `scope_added_min: 1`, first narrow its candidates on the server in global order; the remaining filters and `ranking_mode` then apply locally, and `scan` reports how much of the server result was examined. Unknown inputs are rejected rather than ignored. It suppresses bulk `bbradar://` resource links while preserving each program's public BBRadar and platform URLs, preventing large shortlists from flooding model context.
 
+The hunt reserves time within the configured tool deadline: catalog discovery uses at most 60%, optional recent-change queries 30% in parallel, and target sampling finishes by 90%, leaving time to return the result. With the default 30 seconds, those bounds are 18, 9 and 27 seconds. A stalled later catalog page preserves completed pages; Activity scans retain only their completed ordered prefix. A failed first catalog page remains an error. Partial reads include `errors`, warnings, `meta.partial_success`, `result_guidance.coverage_incomplete` and `meta.phase_timing`. Missing enrichment is unavailable evidence. Keep the user's platform scope and thresholds; a sampled change feed cannot identify the complete supported platform set.
+
+Legacy catalog hunts apply their existing VDP exclusion upstream when the API advertises that mode, then retain the local filters. Programs with unknown classifications and positive rewards remain eligible. Older APIs keep local exclusion. Catalog paging retains its four-request limit within the configured global pool; Activity scans keep their separate two-request limit.
+
+Combined Activity filters need independent periods. `change_category` requires `updates_period`; filtering additions with `scope_period` and `scope_added_min` alone needs no category. `payout_total` requires `payout_period: "all_time"`; use `payout_increase` for tracked 24h/7d/30d/90d changes, or an enabled `payout_native_90d` comparison with 90d for provider-reported values. Invalid combinations fail locally with guidance. An empty valid result does not authorize changing requested thresholds.
+
 ```json
 {
   "platforms": ["Immunefi", "HackenProof", "BugCrowd", "YesWeHack"],

package/benchmark/live-api-check.mjs

@@ -0,0 +1,126 @@
+// Read-only production smoke check. Requires BBRADAR_API_KEY; emits aggregate
+// measurements only and stops at the first failed call without retrying.
+// Usage: node benchmark/live-api-check.mjs [all|activity|programs|analytics|feeds|hunt]
+import assert from "node:assert/strict";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { BBRadarClient } from "../dist/bbradarClient.js";
+import { loadConfig } from "../dist/config.js";
+import { createBbradarServer } from "../dist/server.js";
+
+const config = loadConfig();
+config.toolProfile = "core";
+const section = process.argv[2] ?? "all";
+assert.ok(["all", "activity", "programs", "analytics", "feeds", "hunt"].includes(section), "Use all, activity, programs, analytics, feeds, or hunt.");
+const enabled = name => section === "all" || section === name;
+const upstream = new BBRadarClient(config);
+const observations = [];
+const report = { measured_at: new Date().toISOString(), fixture: false, section, observations };
+let server, client;
+async function call(name, args = {}) {
+  const before = upstream.diagnostics().upstream_requests.actual_requests;
+  const result = await client.callTool({ name, arguments: args });
+  const data = result.structuredContent;
+  observations.push({ tool: name, tab: args.tab, success: !result.isError,
+    status: data?.error?.status,
+    error: data?.error?.message?.replaceAll(config.apiKey, "[redacted]"),
+    duration_ms: data?.mcp_timing?.duration_ms,
+    requests: upstream.diagnostics().upstream_requests.actual_requests - before,
+    rows: (data?.rows ?? data?.programs ?? data?.targets ?? data?.changes ?? data?.series ?? data?.matches)?.length,
+    no_store: data?.cache?.no_store, partial_success: data?.meta?.partial_success,
+    coverage_incomplete: data?.result_guidance?.coverage_incomplete,
+    phase_timing: data?.meta?.phase_timing });
+  if (result.isError) throw new Error(`${name} failed with status ${data?.error?.status ?? "unknown"}`);
+  return data;
+}
+
+try {
+  await upstream.negotiateCapabilities();
+  const contract = upstream.capabilitySnapshot();
+  assert.equal(contract.status, "negotiated");
+  report.contract_version = contract.contract.contract_version;
+  report.api_endpoints = Object.keys(contract.contract.endpoints).sort();
+  server = createBbradarServer(upstream, config);
+  client = new Client({ name: "bbradar-live-check", version: "1" });
+  const [a, b] = InMemoryTransport.createLinkedPair();
+  await Promise.all([client.connect(a), server.connect(b)]);
+  const discovery = await client.listTools();
+  report.core_tool_count = discovery.tools.length;
+  report.discovery_bytes = Buffer.byteLength(JSON.stringify(discovery));
+  const status = await call("get_mcp_status");
+  report.server_version = status.status.server_version;
+  report.sdk_version = status.status.sdk_version;
+  await call("get_bbradar_guide");
+  let snapshot;
+  if (enabled("activity") || enabled("programs")) {
+    const version = await call("get_activity_snapshot");
+    snapshot = version.snapshot_id;
+  }
+  if (enabled("activity")) {
+    const capabilities = await call("get_activity_capabilities", { snapshot });
+    for (const tab of capabilities.tabs) {
+      // Let the server select its advertised default; an unqualified default
+      // legitimately returns no rows plus available_views, never an invented view.
+      const page = await call("get_activity_rankings", { tab: tab.id, snapshot, limit: 1 });
+      assert.equal(page.tab, tab.id);
+      assert.equal(page.meta.snapshot_id, snapshot);
+      assert.equal(page.cache.no_store, true);
+      assert.ok(Array.isArray(page.rows));
+      if (page.sort === null) assert.ok(Array.isArray(page.available_views));
+    }
+  }
+  let program;
+  if (enabled("programs") || enabled("analytics")) {
+    const catalog = await call("search_programs", { page_size: 5 });
+    program = catalog.programs.find(row => row.platform !== "Self-Hosted");
+    assert.ok(program?.id, "The bounded live catalog had no program for the detail checks.");
+  }
+  if (enabled("programs")) {
+    await call("get_program", { program_id: program.id });
+    await call("get_program_targets", { program_id: program.id, limit: 2 });
+    await call("get_program_payouts", { program_id: program.id, snapshot });
+    await call("get_program_activity", { program_id: program.id });
+    await call("get_program_history", { program_id: program.id, limit: 1 });
+    await call("get_history_changes", { limit: 1 });
+  }
+  if (enabled("analytics")) {
+    await call("get_analytics_platform_series", { platform: program.platform, limit: 1 });
+    await call("get_analytics_program_detail", { program_id: program.id, limit: 1 });
+    await call("get_analytics_program_activity", { limit: 1 });
+  }
+  if (enabled("feeds")) {
+    await call("get_recent_changes", { page_size: 1 });
+    await call("get_repository_changes", { page_size: 1, include_targets: false });
+    await call("get_opportunities", { level: "elite", page_size: 1 });
+    const combined = await call("find_programs", {
+      payout_period: "30d", payout_positive: true, require_bounty: true, max_pages: 1, max_results: 1
+    });
+    assert.ok(combined.scan);
+  }
+  if (enabled("hunt")) {
+    const hunt = await call("find_hunt_targets", {
+      surface_mode: "web2", target_types: ["domain", "api"], require_bounty: true,
+      min_bounty_max: 5000, min_eligible_targets: 3, min_total_targets: 5,
+      include_recent_changes: true, include_unknown_report_count: true,
+      recent_target_days: 90, max_results: 15, targets_per_result: 3,
+      ranking_mode: "balanced", upstream_request_budget: 50
+    });
+    assert.ok(hunt.matches.length > 0);
+    assert.equal(hunt.filters.min_bounty_max, 5000);
+    assert.equal(hunt.filters.surface_mode, "web2");
+    assert.ok(hunt.upstream_budget.used <= 50);
+    report.hunt = { returned: hunt.matches.length, target_samples: hunt.matches.reduce((sum, row) => sum + row.target_samples.length, 0),
+      ranking_scope: hunt.ranking_scope, upstream_budget: hunt.upstream_budget, partial_success: hunt.meta.partial_success };
+    if (hunt.meta.partial_success) process.exitCode = 1;
+  }
+} catch (error) {
+  report.failure = String(error.message).replaceAll(config.apiKey, "[redacted]");
+  process.exitCode = 1;
+} finally {
+  await client?.close();
+  await server?.close();
+  report.requests = upstream.diagnostics().upstream_requests.actual_requests;
+  report.concurrency = upstream.diagnostics().request_concurrency;
+  report.request_window = upstream.diagnostics().upstream_request_window;
+  console.log(JSON.stringify(report, null, 2));
+}

package/benchmark/live-hunt.mjs

@@ -0,0 +1,105 @@
+// One authenticated read-only hunt. Only aggregate measurements reach stdout;
+// credentials and program/target records are never written to disk.
+// With BBRADAR_API_KEY configured: node benchmark/live-hunt.mjs
+// Optional experiment: node benchmark/live-hunt.mjs --catalog-concurrency=2
+// This only lowers catalog concurrency; it never changes filters or page counts.
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { BBRadarClient } from "../dist/bbradarClient.js";
+import { loadConfig } from "../dist/config.js";
+import { createBbradarServer } from "../dist/server.js";
+
+const args = {
+  surface_mode: "web2", target_types: ["domain", "api"], require_bounty: true,
+  min_bounty_max: 5000, min_eligible_targets: 3, min_total_targets: 5,
+  include_recent_changes: true, include_unknown_report_count: true,
+  recent_target_days: 90, max_results: 15, targets_per_result: 3,
+  ranking_mode: "balanced", upstream_request_budget: 50
+};
+const config = loadConfig();
+const catalogOption = process.argv.slice(2);
+assert.ok(catalogOption.length <= 1 && (!catalogOption.length || /^--catalog-concurrency=[1-4]$/.test(catalogOption[0])),
+  "Use --catalog-concurrency=1, 2, 3 or 4, or omit it for the server default.");
+const catalogConcurrency = catalogOption.length ? Number(catalogOption[0].split("=")[1]) : Number.POSITIVE_INFINITY;
+let activeCatalog = 0;
+let peakCatalog = 0;
+const catalogWaiters = [];
+async function acquireCatalog() {
+  if (activeCatalog < catalogConcurrency) {
+    activeCatalog += 1;
+    peakCatalog = Math.max(peakCatalog, activeCatalog);
+    return;
+  }
+  await new Promise(resolve => catalogWaiters.push(resolve));
+}
+function releaseCatalog() {
+  const next = catalogWaiters.shift();
+  if (next) next(); else activeCatalog -= 1;
+}
+const upstream = new BBRadarClient(config);
+const request = upstream.request.bind(upstream);
+const redact = value => String(value).replaceAll(config.apiKey, "[redacted]");
+let timings = [];
+let catalogIds = new Set();
+upstream.request = async options => {
+  const start = performance.now();
+  const endpoint = options.path.replace(/\/programs\/.+\/targets$/, "/programs/:program_id/targets");
+  const isCatalog = options.path === "/pro/programs";
+  if (isCatalog) await acquireCatalog();
+  try {
+    const result = await request(options);
+    for (const program of result.data?.programs ?? []) catalogIds.add(program.id);
+    timings.push({ endpoint, page: options.query?.page, elapsed_ms: Math.round(performance.now() - start),
+      status: result.status, cached: result.cached, coalesced: result.coalesced,
+      rows: result.data?.programs?.length ?? result.data?.results?.length ?? result.data?.targets?.length });
+    return result;
+  } catch (error) {
+    timings.push({ endpoint, page: options.query?.page, elapsed_ms: Math.round(performance.now() - start),
+      status: error.status ?? null, error: redact(error.message) });
+    throw error;
+  } finally {
+    if (isCatalog) releaseCatalog();
+  }
+};
+const hash = values => createHash("sha256").update(JSON.stringify([...values].sort())).digest("hex");
+
+try {
+  await upstream.negotiateCapabilities();
+  const server = createBbradarServer(upstream, config);
+  const client = new Client({ name: "bbradar-live-benchmark", version: "1" });
+  const [a, b] = InMemoryTransport.createLinkedPair();
+  await Promise.all([client.connect(a), server.connect(b)]);
+  try {
+    timings = [];
+    catalogIds = new Set();
+    const before = upstream.diagnostics().upstream_requests.actual_requests;
+    const result = await client.callTool({ name: "find_hunt_targets", arguments: args });
+    const data = result.structuredContent;
+    const matches = data?.matches ?? [];
+    const observation = {
+      concurrency: config.maxConcurrentRequests,
+      catalog_concurrency_cap: Number.isFinite(catalogConcurrency) ? catalogConcurrency : "server_default",
+      catalog_request_peak: peakCatalog, is_error: result.isError ?? false,
+      error: data?.error ? { status: data.error.status, message: redact(data.error.message) } : undefined,
+      timing: data?.mcp_timing, phase_timing: data?.meta?.phase_timing,
+      returned: matches.length, target_samples: matches.reduce((count, match) => count + match.target_samples.length, 0),
+      programs_without_target_samples: matches.filter(match => !match.target_samples.length).length,
+      partial_success: data?.meta?.partial_success, coverage_incomplete: data?.result_guidance?.coverage_incomplete,
+      ranking_scope: data?.ranking_scope,
+      upstream_budget: data?.upstream_budget, actual_requests: upstream.diagnostics().upstream_requests.actual_requests - before,
+      catalog_rows: catalogIds.size, catalog_signature: hash(catalogIds),
+      shortlist_signature: hash(matches.map(match => match.program.id)),
+      errors: data?.errors?.map(error => ({ status: error.status, message: redact(error.message) })),
+      timings
+    };
+    if (result.isError || data?.meta?.partial_success) process.exitCode = 1;
+    console.log(JSON.stringify({ fixture: false, measured_at: new Date().toISOString(), arguments: args, observations: [observation],
+      quota: upstream.diagnostics().upstream_rate_limit,
+      request_window: upstream.diagnostics().upstream_request_window }, null, 2));
+  } finally { await client.close(); await server.close(); }
+} catch (error) {
+  console.error(JSON.stringify({ status: error.status ?? null, message: redact(error.message) }));
+  process.exitCode = 1;
+}

package/benchmark/live-stdio.mjs

@@ -0,0 +1,80 @@
+// Authenticated production smoke check through the actual STDIO entry point.
+// Emits aggregates only; never writes credentials or program/target records.
+// node benchmark/live-stdio.mjs [hunt|targets]
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { loadConfig } from "../dist/config.js";
+
+const config = loadConfig();
+const mode = process.argv[2] ?? "hunt";
+assert.ok(["hunt", "targets"].includes(mode), "Use hunt or targets.");
+const client = new Client({ name: "bbradar-live-stdio", version: "1" });
+const transport = new StdioClientTransport({ command: process.execPath,
+  args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))], stderr: "pipe",
+  env: { BBRADAR_API_KEY: config.apiKey, BBRADAR_API_BASE_URL: config.apiBaseUrl,
+    BBRADAR_MCP_TOOL_PROFILE: "core", BBRADAR_MCP_VALIDATE_ON_STARTUP: "true" } });
+const report = { measured_at: new Date().toISOString(), fixture: false, transport: "stdio", mode };
+async function call(name, args = {}) {
+  const result = await client.callTool({ name, arguments: args });
+  if (result.isError) throw new Error(`${name}: ${result.structuredContent?.error?.message ?? "MCP call failed"}`);
+  return result.structuredContent;
+}
+try {
+  await client.connect(transport);
+  const tools = await client.listTools();
+  report.core_tools = tools.tools.length;
+  const before = (await call("get_mcp_status")).status.client;
+  assert.equal(before.capability_negotiation.status, "negotiated");
+  let programs;
+  if (mode === "hunt") {
+    const hunt = await call("find_hunt_targets", {
+      surface_mode: "web2", target_types: ["domain", "api"], require_bounty: true,
+      min_bounty_max: 5000, min_eligible_targets: 3, min_total_targets: 5,
+      include_recent_changes: true, include_unknown_report_count: true,
+      recent_target_days: 90, max_results: 15, targets_per_result: 3,
+      ranking_mode: "balanced", upstream_request_budget: 50
+    });
+    report.hunt = { duration_ms: hunt.mcp_timing.duration_ms, phase_timing: hunt.meta.phase_timing,
+      programs: hunt.matches.length, target_samples: hunt.matches.reduce((n, row) => n + row.target_samples.length, 0),
+      upstream_requests: hunt.upstream_budget.used, partial_success: hunt.meta.partial_success,
+      ranking_scope: hunt.ranking_scope, catalog_pages_read: hunt.source_requests.filter(row => row.source === "programs").length,
+      errors: hunt.errors?.map(error => ({ status: error.status, message: error.message?.replaceAll(config.apiKey, "[redacted]") })),
+      shortlist_signature: createHash("sha256").update(JSON.stringify(hunt.matches.map(row => row.program.id).sort())).digest("hex") };
+    assert.equal(hunt.meta.partial_success, false, "The hunt returned incomplete work; do not count it as a successful performance run.");
+    assert.ok(hunt.matches.length > 0);
+    programs = hunt.matches.map(row => row.program);
+  } else {
+    programs = (await call("search_programs", { page_size: 10 })).programs;
+  }
+  // Compare the requested prefix with a fresh wider read. A live source change
+  // remains a failed comparison, never an excuse to substitute old data.
+  const selected = [...programs].sort((a, b) => (b.scope_summary?.target_counts?.eligible_for_bounty ?? 0)
+    - (a.scope_summary?.target_counts?.eligible_for_bounty ?? 0))[0];
+  assert.ok(selected?.id, "The bounded catalog returned no target candidate.");
+  const args = { program_id: selected.id, output_mode: "identifiers" };
+  const wide = await call("get_program_targets", { ...args, limit: 500 });
+  const small = await call("get_program_targets", { ...args, limit: 3 });
+  assert.ok(wide.targets.length > 0);
+  assert.ok(JSON.stringify(wide.targets.slice(0, 3)) === JSON.stringify(small.targets), "Fresh target prefixes differ; inspect source drift before claiming equivalence.");
+  assert.equal(wide.cache.no_store, true);
+  assert.equal(small.cache.no_store, true);
+  report.target_prefix = { equal: true, wide_read_rows: wide.targets.length, small_read_rows: small.targets.length,
+    wide_read_ms: wide.mcp_timing.duration_ms, small_read_ms: small.mcp_timing.duration_ms,
+    small_read_has_more: small.meta.has_more, small_read_next_offset: small.meta.next_offset, both_no_store: true };
+  const after = (await call("get_mcp_status")).status.client;
+  report.upstream_requests = after.upstream_requests.actual_requests - before.upstream_requests.actual_requests;
+  report.response_cache = after.response_cache;
+  report.request_window = after.upstream_request_window;
+  assert.equal(after.request_concurrency.active, 0);
+  assert.equal(after.request_concurrency.queued, 0);
+} catch (error) {
+  report.failure = String(error.message).replaceAll(config.apiKey, "[redacted]");
+  process.exitCode = 1;
+} finally {
+  await client.close();
+  await transport.close();
+  console.log(JSON.stringify(report, null, 2));
+}

package/dist/activityContract.d.ts

@@ -1,2 +1,4 @@
 /** Catalog metadata stays available when Activity computation is disabled. */
 export declare function requiresActivityQuery(input?: Record<string, unknown>): boolean;
+/** Validate dependencies without supplying or changing the user's periods. */
+export declare function validateActivityCatalogInput(input: Record<string, unknown>): void;

package/dist/activityContract.js

@@ -12,4 +12,36 @@ export function requiresActivityQuery(input = {}) {
     return Object.entries(input).some(([key, value]) => value !== undefined && value !== null
         && (key === "sort_by" ? value !== "updated" : ACTIVITY_FILTERS.has(key)));
 }
+/** Validate dependencies without supplying or changing the user's periods. */
+export function validateActivityCatalogInput(input) {
+    const requirements = {
+        scope: ["scope_added_min", "scope_removed_min", "scope_net_min", "scope_net_max"],
+        reward: ["reward_change", "reward_change_min_pct"],
+        updates: ["active_days_min", "changes_min", "change_category"],
+        reports: ["reports_min", "reports_max", "reports_change", "reports_change_min_pct"],
+        resolved: ["resolved_min"], status: ["status_change"],
+        payout: ["payout_min", "payout_max", "payout_metric", "payout_activity", "payout_positive", "payout_precision"]
+    };
+    const sortPeriods = {
+        payout_amount: "payout", payout_lower_bound: "payout", payout_upper_bound: "payout",
+        scope_added: "scope", scope_net: "scope", reward_change: "reward", active_days: "updates",
+        last_change: "updates", reports: "reports", reports_change: "reports", resolved: "resolved"
+    };
+    for (const [prefix, keys] of Object.entries(requirements)) {
+        const signal = keys.find((key) => input[key] !== undefined);
+        if ((signal || sortPeriods[String(input.sort_by)] === prefix) && input[`${prefix}_period`] === undefined) {
+            throw new Error(`Specify ${prefix}_period for ${signal ?? `sort_by=${String(input.sort_by)}`}. Periods are never inferred from another signal.`);
+        }
+    }
+    const period = input.payout_period;
+    const metric = input.payout_metric ?? (period === "all_time" ? "payout_total" : "payout_increase");
+    if (period !== undefined && ((metric === "payout_total") !== (period === "all_time")
+        || (metric === "payout_native_90d" && period !== "90d"))) {
+        throw new Error("Payout metric and period are incompatible: payout_total requires all_time; payout_increase uses 24h, 7d, 30d or 90d; payout_native_90d requires 90d. Keep the requested period and choose its supported metric.");
+    }
+    if (input.payout_activity !== undefined && (metric !== "payout_increase"
+        || (input.payout_activity !== "increase" && period !== "30d"))) {
+        throw new Error("payout_activity requires payout_increase; no_increase and lower require payout_period=30d.");
+    }
+}
 //# sourceMappingURL=activityContract.js.map

package/dist/activityContract.js.map

@@ -1 +1 @@
-{"version":3,"file":"activityContract.js","sourceRoot":"","sources":["../src/activityContract.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY;IACnG,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,iBAAiB,EAAE,mBAAmB;IAC5F,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB;IAC3F,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,EAAE,gBAAgB;IACvF,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,iBAAiB;IAC3F,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,0BAA0B;IACrF,0BAA0B,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB;CAClG,CAAC,CAAC;AAEH,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,QAAiC,EAAE;IACvE,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;WACpF,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"activityContract.js","sourceRoot":"","sources":["../src/activityContract.ts"],"names":[],"mappings":"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"}

package/dist/bbradarClient.d.ts

@@ -10,6 +10,7 @@ export type ApiRequestOptions = {
     staleWhileRevalidateMs?: number;
     timeoutMs?: number;
     signal?: AbortSignal;
+    expectedArray?: "programs" | "targets" | "results";
 };
 export type ApiReadControls = Pick<ApiRequestOptions, "cache" | "coalesce" | "timeoutMs" | "signal">;
 export type ApiResult<T> = {
@@ -73,7 +74,10 @@ export declare class BBRadarClient {
     private capabilityNegotiation;
     private capabilityState;
     constructor(config: ServerConfig);
-    withRequestContext<T>(signal: AbortSignal, callback: () => T | Promise<T>, snapshotStart?: boolean): Promise<T>;
+    withRequestContext<T>(signal: AbortSignal, callback: () => T | Promise<T>, snapshotStart?: boolean, timeoutMs?: number): Promise<T>;
+    /** Give one aggregate stage a shorter budget without extending its parent. */
+    withRequestTimeout<T>(timeoutMs: number, callback: () => T | Promise<T>): Promise<T>;
+    throwIfRequestAborted(): void;
     diagnostics(): {
         response_cache: {
             entries: number;

package/dist/bbradarClient.js

@@ -131,12 +131,12 @@ export class BBRadarClient {
         this.cache = new TtlCache(config.cacheMaxEntries, config.cacheTtlMs, config.programStaleWhileRevalidateMs ?? DEFAULT_PROGRAM_SWR_MS);
         this.negativeCache = new TtlCache(config.cacheMaxEntries, config.negativeCacheTtlMs);
     }
-    async withRequestContext(signal, callback, snapshotStart = false) {
+    async withRequestContext(signal, callback, snapshotStart = false, timeoutMs) {
         const controller = new AbortController();
         const onAbort = () => controller.abort(signal.reason);
-        const timeout = setTimeout(() => controller.abort(new DOMException("Tool deadline exceeded.", "TimeoutError")), snapshotStart
+        const timeout = setTimeout(() => controller.abort(new DOMException("Tool deadline exceeded.", "TimeoutError")), timeoutMs ?? (snapshotStart
             ? Math.max(this.config.requestTimeoutMs, SNAPSHOT_START_MIN_TIMEOUT_MS)
-            : this.config.requestTimeoutMs);
+            : this.config.requestTimeoutMs));
         signal.addEventListener("abort", onAbort, { once: true });
         if (signal.aborted)
             onAbort();
@@ -149,6 +149,15 @@ export class BBRadarClient {
             controller.abort();
         }
     }
+    /** Give one aggregate stage a shorter budget without extending its parent. */
+    withRequestTimeout(timeoutMs, callback) {
+        return this.withRequestContext(this.requestContext.getStore() ?? new AbortController().signal, callback, false, Math.max(1, timeoutMs));
+    }
+    throwIfRequestAborted() {
+        if (this.requestContext.getStore()?.aborted) {
+            throw new BBRadarApiError({ message: "BBRadar API request was cancelled or exceeded its tool deadline.", requestId: randomUUID(), status: 408 });
+        }
+    }
     diagnostics() {
         const endpointEntries = [...this.endpointMetrics.entries()];
         const totalRequests = endpointEntries.reduce((total, [, metric]) => total + metric.requests, 0);
@@ -307,6 +316,7 @@ export class BBRadarClient {
     listPrograms(query, controls = {}) {
         return this.request({
             path: "/pro/programs",
+            expectedArray: "programs",
             query,
             ...snapshotAwareReadControls(query, controls, true, this.config.requestTimeoutMs)
         });
@@ -326,6 +336,7 @@ export class BBRadarClient {
     getProgramTargets(programId, query = {}) {
         return this.request({
             path: `/pro/programs/${encodeProgramIdPath(programId)}/targets`,
+            expectedArray: "targets",
             query: {
                 page: 1,
                 page_size: this.endpointNumber("program_targets", "max_page_size", 500),
@@ -336,6 +347,7 @@ export class BBRadarClient {
     getRecentChanges(query, controls = {}) {
         return this.request({
             path: "/pro/targets/changes",
+            expectedArray: "results",
             query,
             ...snapshotAwareReadControls(query, controls, query.after_id === undefined, this.config.requestTimeoutMs)
         });
@@ -343,6 +355,7 @@ export class BBRadarClient {
     getRepositoryChanges(query, controls = {}) {
         return this.request({
             path: "/pro/repositories/changes",
+            expectedArray: "results",
             query,
             ...snapshotAwareReadControls(query, controls, query.after_id === undefined, this.config.requestTimeoutMs)
         });
@@ -350,6 +363,7 @@ export class BBRadarClient {
     searchTargets(query, controls = {}) {
         return this.request({
             path: "/pro/targets/search",
+            expectedArray: "results",
             query,
             ...snapshotAwareReadControls(query, controls, true, this.config.requestTimeoutMs)
         });
@@ -357,6 +371,7 @@ export class BBRadarClient {
     getOpportunities(level, query) {
         return this.request({
             path: `/pro/opportunities/${encodeURIComponent(level)}`,
+            expectedArray: "programs",
             query,
             ...snapshotAwareReadControls(query, {}, true, this.config.requestTimeoutMs)
         });
@@ -591,6 +606,12 @@ export class BBRadarClient {
                     }
                     throw new BBRadarApiError(params);
                 }
+                if (options.expectedArray && !Array.isArray(asRecord(data)?.[options.expectedArray])) {
+                    throw new BBRadarApiError({
+                        message: `BBRadar API returned a malformed page: expected ${options.expectedArray}.`,
+                        requestId, upstreamRequestId, status: 502, cacheAllowed: false
+                    });
+                }
                 const result = {
                     data: data,
                     status: response.status,