feat: implment bulk radius api (CM-1328)

[ulemons]

Summary

Adds bulk (batch) endpoints for the akrites-external blast-radius API, mirroring the
existing batch pattern already used by packages/advisories/contacts detail lookups:
POST /blast-radius/jobs:batch to submit multiple blast-radius analysis jobs in one
request, and POST /blast-radius/jobs:batch/poll to poll multiple analyses by id in
one paginated request. The OpenAPI spec is updated to document both.

Changes

• New POST /blast-radius/jobs:batch — submits up to MAX_BLAST_RADIUS_JOBS_PER_BATCH
  (20, hard limit agreed after a cost test; 10 is the recommended/documented default,
  not schema-enforced) jobs per request, each starting its own Temporal workflow.
• New POST /blast-radius/jobs:batch/poll — polls up to 100 analysisIds per request,
  paginated (page/pageSize), reusing the found/not-found echo pattern from the
  other batch endpoints (unknown id → { found: false, analysis: null }).
• Submit and poll batch have different failure semantics on purpose:
  • Validation (e.g. an unsupported ecosystem) is atomic across the whole jobs
    array — one invalid entry rejects the entire batch with a 400, none of the jobs
    are submitted.
  • Runtime failures (e.g. Temporal unreachable) are isolated per job — that job's
    entry comes back status: 'failed', the rest of the batch still submits, and the
    response is still 202.
• Bulk submit sits behind the same strict blastRadiusRateLimiter as the single-job
  route (not the regular rate limiter), since each request can multiply Temporal
  workflow starts up to 20x. Bulk poll is read-only and uses the regular rate limiter.
• New schema/pagination helper file blastRadiusBatch.ts — reuses the existing
  single-job Zod schema (blastRadiusJobRequestSchema) and mapper (toBlastRadiusJobEntry,
  toBlastRadiusAnalysis) rather than duplicating validation/response-shaping logic.
• Ran through a structured code review (/code-review --fix): fixed a bug where
  createAnalysis sat outside the per-job try/catch (one job's DB error could reject
  the whole batch's Promise.all), parallelized two independent DB reads in the poll
  handler, and deduplicated a repeated object literal. Flagged-but-not-fixed items
  (documented in review discussion, not applied here): the rate limiter counts
  requests rather than workflow starts (20x throughput vs. single-job route), and
  submitOneJob/paginateAnalysisIds duplicate logic from pre-existing
  submitBlastRadiusJob.ts/purl.ts — left alone since fixing those would require
  touching working code outside this diff's scope.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Performance improvement
• Chore / dependency update
• Documentation

JIRA ticket

CM-1328

[cursor]

PR Summary

Medium Risk
Bulk submit can start many costly Temporal/LLM workflows per request (capped at 20) and the default submit rate limit is much higher; worker concurrency and heartbeat changes affect blast-radius pipeline reliability under load.

Overview
Adds bulk blast-radius support on the akrites-external API: POST .../blast-radius/jobs:batch (up to 20 jobs, each starting its own Temporal workflow) and POST .../blast-radius/jobs:batch/poll (up to 100 analysisIds, paginated, found/not-found per id). OpenAPI documents the new schemas and routes.

Submit uses the strict blastRadiusRateLimiter like single-job submit; poll uses the normal read limiter. Invalid job payloads fail the whole batch with 400; Temporal/DB failures on one job return failed for that entry only (202). Shared validation lives in blastRadiusBatch.ts; poll uses new DAL batch reads (getAnalysisDetailsByIds, getVerdictResultsBatch, getDependentsExcludedByRangeCountBatch).

Also raises the default blast-radius submit rate limit from 5/hour to 50/hour, gives the blast-radius worker its own ServiceWorker with maxConcurrentActivityTaskExecutions: 8, and adds Temporal heartbeats during long dependents download/ranking work, reachability retry backoff, and a heartbeat on the report activity.

^{Reviewed by Cursor Bugbot for commit d6a945d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

failAnalysis rejects entire batch

Medium Severity

In bulk submit, when one job hits the catch path, an awaited failAnalysis that throws rejects that submitOneJob promise. Because the handler uses Promise.all over all jobs, one cleanup failure turns the whole request into a 500 even when other jobs already started workflows, contradicting the per-job isolation described for bulk submit.

 

^{Reviewed by Cursor Bugbot for commit bc1a7fc. Configure here.}

[Copilot]

Pull request overview

Adds bulk submission and polling endpoints for blast-radius analyses.

Changes:

• Adds batch submit and paginated batch poll handlers.
• Adds validation, pagination helpers, and unit tests.
• Registers routes and updates the OpenAPI contract.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
submitBlastRadiusJobBatch.ts	Submits multiple Temporal workflows.
getBlastRadiusJobBatch.ts	Polls multiple analyses.
blastRadiusBatch.ts	Defines batch schemas and pagination.
blastRadiusBatch.test.ts	Tests schemas and pagination.
openapi.yaml	Documents batch endpoints.
akrites-external/index.ts	Registers batch routes and limiters.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:35

• getPackagesTemporalClient() establishes the Temporal connection and can reject when Temporal is unreachable (backend/src/db/packagesTemporal.ts:18-42). Because that happens before the per-job try blocks, the entire request fails instead of returning a 202 with failed entries. Move client acquisition into submitOneJob's failure boundary (the getter already caches the connection promise) so this runtime failure follows the documented per-job semantics.

  const packagesTemporal = await getPackagesTemporalClient()

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:92

• If failAnalysis rejects, submitOneJob still rejects and Promise.all fails the whole batch. This directly defeats the stated isolation for createAnalysis failures (a database error may also make this follow-up write fail). Guard the failure-recording write separately, log that persistence failure, and still return this job's failed entry if the endpoint contract must always isolate per-job runtime failures.

    await blastRadiusDal.failAnalysis(qx, analysisInput, errorMessage)

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (3)

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:35

• getPackagesTemporalClient() establishes the connection and can reject when Temporal is unreachable. Because it runs before jobs.map(...), a cold-start outage fails the entire HTTP request instead of returning one failed entry per job with 202 as the endpoint contract promises. Move client acquisition into the per-job try path (the cached _init promise still prevents 20 independent successful connections).

  const packagesTemporal = await getPackagesTemporalClient()

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:92

• This awaited cleanup can itself reject, which escapes submitOneJob and makes Promise.all reject the whole batch. In particular, the newly handled createAnalysis DB failure is likely to make this second DB write fail too, so the advertised per-job isolation is not guaranteed. Handle/log failure persistence separately so submitOneJob still resolves to its failed entry.

    await blastRadiusDal.failAnalysis(qx, analysisInput, errorMessage)

backend/src/api/public/v1/packages/getBlastRadiusJobBatch.ts:51

• Valid UUID input is case-insensitive, while PostgreSQL serializes UUID columns in lowercase. An uppercase analysisId therefore passes z.uuid() but misses these case-sensitive maps, returning found: false (or empty verdict/count data) for an existing analysis. Normalize lookup keys while preserving requestedAnalysisId for the response echo.

  const results: BlastRadiusAnalysisBulkEntry[] = pagedAnalysisIds.map((requestedAnalysisId) => {
    const analysis = analysisById.get(requestedAnalysisId)

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:35

• Temporal client initialization happens before the per-job boundary. getPackagesTemporalClient() performs Connection.connect() and can reject when Temporal is unreachable, so this path returns a batch-wide 5xx before creating any analysis rows instead of the documented 202 with failed entries. Acquire/await the client inside submitOneJob's try (the cached initializer will still share one connection attempt) so this failure is mapped per job.

  const packagesTemporal = await getPackagesTemporalClient()

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:92

• This awaited recovery write can itself reject, causing submitOneJob to reject and Promise.all to fail the entire request. That breaks the endpoint's stated per-job isolation, especially for the createAnalysis database-error path this catch is intended to handle. Handle failure persistence separately (with appropriate logging/response semantics) so the helper cannot unexpectedly reject.

    await blastRadiusDal.failAnalysis(qx, analysisInput, errorMessage)

backend/src/api/public/v1/akrites-external/index.ts:31

• This also raises the existing single-job endpoint's default limit from 5 to 50 requests/hour. Combined with 20 jobs per batch, the default now permits up to 1,000 workflow/LLM starts per hour, while the PR describes retaining the strict limiter and does not document this separate 10× relaxation. Keep the previous default unless this capacity and cost increase was explicitly approved.

      : 50,

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b677219. Configure here.}

[cursor]

Report activity heartbeat timeout

Medium Severity

Adding a one-minute heartbeatTimeout on blastRadiusReport requires heartbeats during the activity, but runReportStage runs with no progress callbacks and heartbeat() only runs after it finishes. If report aggregation exceeds one minute, Temporal can fail the stage even though startToCloseTimeout allows two minutes.

 

^{Reviewed by Cursor Bugbot for commit b677219. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (4)

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:38

• Temporal connection setup happens before the per-job failure boundary. getPackagesTemporalClient() calls Connection.connect, so if Temporal is unreachable on a cold connection this rejects the entire request with a 500 and no per-job results, contrary to the documented isolation semantics. Acquire the client inside each job's guarded path (the shared initializer will still deduplicate the connection), or map an initialization failure to failed entries for every job.

  const packagesTemporal = await getPackagesTemporalClient()

  const results: BlastRadiusJobEntry[] = await Promise.all(
    jobs.map((body) => submitOneJob(qx, packagesTemporal, body)),

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:92

• A rejection from failAnalysis still escapes submitOneJob and rejects the outer Promise.all, so the promised per-job isolation is not guaranteed. This is especially likely after createAnalysis failed because the same database problem can make this recovery write fail. Handle and log the secondary persistence failure while still returning the failed entry, or use an all-settled aggregation that explicitly maps every rejection.

    await blastRadiusDal.failAnalysis(qx, analysisInput, errorMessage)

backend/src/api/public/v1/akrites-external/index.ts:31

• Raising this request-based limit from 5 to 50 lets one client enqueue up to 1,000 workflows per hour through 20-item batches, versus five workflows per hour before this PR. That materially increases Temporal/LLM load and cost while the PR description explicitly notes that workflow-weighted limiting was not implemented. Keep the existing default unless the limiter is changed to account for batch size.

      : 50,

backend/src/api/public/v1/akrites-external/openapi.yaml:462

• The response can contain status: failed precisely because a job was not successfully submitted (for example, workflow.start failed), so saying every job is submitted is inaccurate for API consumers. Document that every requested job receives an entry and that failed entries may represent submission failures.

      description: >
        Plain array in request order, one entry per submitted job — unlike the
        read batches there is no found/not-found case, every job is submitted.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (5)

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:35

• getPackagesTemporalClient() establishes the Temporal connection before entering any per-job try/catch. On a cold request while Temporal is unreachable, this rejects the whole handler with a 500, rather than returning a 202 with one failed result per job as the batch contract promises. Move client acquisition into the per-job failure boundary (while preserving the shared cached connection) or explicitly convert acquisition failure into per-job failed entries.

  const packagesTemporal = await getPackagesTemporalClient()

backend/src/api/public/v1/packages/submitBlastRadiusJobBatch.ts:92

• This recovery write can itself reject. If the database remains unavailable after createAnalysis fails, or if marking a failed workflow start fails, submitOneJob rejects and the surrounding Promise.all aborts the entire response, contradicting the documented per-job isolation. Handle and log a failAnalysis failure without allowing it to reject the batch, or use an all-settled aggregation that still produces a result for every input.

    const errorMessage = err instanceof Error ? err.message : String(err)
    await blastRadiusDal.failAnalysis(qx, analysisInput, errorMessage)

backend/src/api/public/v1/packages/getBlastRadiusJobBatch.ts:51

• UUID text is case-insensitive, but PostgreSQL returns UUID columns in canonical lowercase while z.uuid() accepts uppercase hex. An uppercase analysisId therefore queries successfully but misses these case-sensitive Maps, returning found: false (and would also miss verdict/count buckets). Normalize only the lookup key while preserving requestedAnalysisId in the echoed response.

  const results: BlastRadiusAnalysisBulkEntry[] = pagedAnalysisIds.map((requestedAnalysisId) => {
    const analysis = analysisById.get(requestedAnalysisId)

services/apps/packages_worker/src/blast-radius/workflows.ts:41

• The report activity only calls heartbeat() after runReportStage has completed. Adding a one-minute heartbeat timeout therefore makes any otherwise-valid report taking 1–2 minutes time out before its first heartbeat, reducing the effective limit below the existing two-minute start-to-close timeout. Remove this heartbeat timeout, or pass a heartbeat callback into the report stage and invoke it during the work.

  heartbeatTimeout: '1 minute',

backend/src/api/public/v1/akrites-external/index.ts:31

• The bulk route consumes one limiter token while starting up to 20 workflows, and this same change also raises the shared limiter default from 5 to 50. At the hard batch size that permits 1,000 costly workflows/hour (and increases the existing single-job allowance 10×), so the limiter no longer bounds workflow-start cost as described. Keep the prior default unless the increase is explicitly required, and make bulk submissions consume tokens proportional to jobs.length or use a separate weighted limiter.

  max:
    Number.isSafeInteger(blastRadiusRateLimitMax) && blastRadiusRateLimitMax > 0
      ? blastRadiusRateLimitMax
      : 50,