Skip to main content

REST routes, admission and limits

CodeCrucible is exposed only over REST in apps/api (bead CC-2.6, AC16; the MCP read facade is later). The API writes no run row: it validates, checks the daily limits, records a pending submission and starts the workflow. The workflow's core admission activity creates the quality_runs row with the run id the API returned (ADR 0009).

Code: apps/api/src/quality.ts (registerQualityRoutes, createQualityStarter), config in apps/api/src/config.ts, schemas and the route table in packages/agent-types/src/http.ts. General API behaviour (API keys, request ids, rate limiting, error envelope) is on REST API.

Enabling​

SettingEffect
QUALITY_ENABLED unset (or not 1/true)Routes are not registered: every /v1/quality/* path answers 404
QUALITY_ENABLED=1 without a startercreateApp throws at startup: "QUALITY_ENABLED is set but no quality workflow starter is wired"
QUALITY_ENABLED=1 and FACTORY_REPOS emptyConfig refuses: "QUALITY_ENABLED needs FACTORY_REPOS"
a QUALITY_CLIENTS entry not in API_KEYSConfig refuses: "QUALITY_CLIENTS client X is not in API_KEYS"

server.ts wires createQualityStarter(cfg) only when QUALITY_ENABLED is set.

Routes​

MethodPathBodySuccess
POST/v1/quality/runsQualityRunRequest202 { runId } (200 on an idempotent replay)
POST/v1/quality/verifyQualityVerifyRequest202 { runId } (200 on an idempotent replay)
GET/v1/quality/runs/:idnone200 QualityRunView
GET/v1/quality/runs/:id/survivors?cursor=none200 QualitySurvivorsPage

The survivors route takes a query string, which the route table cannot express, so it is registered outside routes (like the factory artifact route). Every /v1/quality/* request first passes a middleware that answers 403 forbidden unless the authenticated client is in QUALITY_CLIENTS (API_KEYS has no scopes).

Request bodies​

QualityRunRequest (strict)
repo FactoryRepo (owner/name)
package ^(?![/.])(?!.*\.\.)[A-Za-z0-9._/@-]{1,200}$ e.g. packages/agent-core
headSha ^[0-9a-f]{40}$

QualityVerifyRequest = QualityRunRequest +
intent "remediation" | "feature", default "remediation"

There is no base SHA in either request: the exec worker computes it as the merge base with the protected tip (see anti-gaming). An unknown key is a 400.

Headers​

Idempotency-Key (header name idempotency-key) is required on both POSTs, 1 to 128 characters (FACTORY_LIMITS.maxIdempotencyKeyChars).

Submit flow​

Run ids and idempotency​

digest = sha256(JSON.stringify([client, idempotencyKey, kind, parsedBody]))
runId = digest laid out as a version-8 UUID

The same client, key, kind and body always name the same run and the same workflow id quality-<runId>. The starter uses WorkflowIdReusePolicy.REJECT_DUPLICATE; WorkflowExecutionAlreadyStartedError becomes already_started and the response is 200 with the same runId. A different body under the same key is a different run.

The starter​

createQualityStarter(cfg) opens a lazy connection to TEMPORAL_ADDRESS (TLS when configured) and a client on the quality namespace with the quality payload key, then starts qualityAssessmentWorkflow or qualityVerifyWorkflow by type name on agentforge-quality. Without TEMPORAL_ADDRESS or payload keys every start fails at once (temporal_unconfigured, 503).

VariableDefaultRule
QUALITY_TEMPORAL_NAMESPACETEMPORAL_NAMESPACE
QUALITY_TEMPORAL_PAYLOAD_KEYS, QUALITY_TEMPORAL_PAYLOAD_KEY_IDthe session payload keysset both or neither; a namespace different from TEMPORAL_NAMESPACE must bring its own keys, and its key map must not hold the main namespace's current key id
Namespace mismatch (observed in code)

The core worker registers the quality workflows and core activities on its own TEMPORAL_NAMESPACE with the session payload keys (apps/worker/src/worker.ts); it has no separate quality namespace setting. The exec worker defaults to agentforge-quality. A deployment that sets QUALITY_TEMPORAL_NAMESPACE on the API to a separate namespace would start workflows that no core worker polls. The namespace layout is part of the open precondition PRE-0; it is unverified against a real cluster.

Admission​

Admission is the core activity admit (first step of every workflow), not the API. It runs under the Postgres advisory lock agentforge:quality:admission:

LimitVariableDefaultEnforced where
Active top-level runsQUALITY_CONCURRENCY (core worker)1, and the worker config caps it at 1admission, under the lock; a verify with its children counts as one
Open children per verifyMAX_OPEN_CHILDREN (code)2admission of a child; a child needs an open, top-level parent of the same client
Pending submissions per clientQUALITY_MAX_PENDING_PER_CLIENT (API)4 (1..100)submit, under the per-client lock
Pending TTLQUALITY_PENDING_TTL_SEC (API)86,400 (at least 60)submit sweep and the queued read
Daily sandbox seconds per clientQUALITY_DAILY_SANDBOX_SECONDS_PER_CLIENT14,400API at submit (429), admission under the lock, cacheLookup before the chunks
Daily sandbox seconds, globalQUALITY_DAILY_SANDBOX_SECONDS_GLOBAL28,800same
Sandbox seconds per assessmentQUALITY_RUN_LIMITS.assessmentSandboxMs3,600 sworkflow, before each chunk: partial
Sandbox seconds per verify (children included)QUALITY_RUN_LIMITS.verifySandboxMs7,200 sworkflow: partial

Notes from the code:

  • The API also parses QUALITY_CONCURRENCY (default 1) but does not use it; only the core worker's value, capped at 1 ("at most the number of exec hosts, 1 in v1"), is enforced.
  • "Today" is the UTC day of created_at; a run spanning midnight counts wholly on its start day (marked shortcut).
  • Sandbox time reaches quality_runs.sandbox_ms only when a run closes. The API's check at submit therefore counts open runs at 0; the admission check counts each open run at GREATEST(sandbox_ms, 3,600 s).
  • Limits and the kill switch are checked at admission and once before the chunks, not per chunk (ADR 0009: per-chunk checks would exceed the 150-event history budget).

Known leak (ADR 0009)​

A submission that waits longer than its TTL, or a workflow that ends without admission, stops counting and can let a client exceed the pending cap. There is no workflow execution timeout yet.

Reads​

GET /v1/quality/runs/:id​

The id is lower-cased. The owning client gets the row; anyone else gets 404 not_found (scoping like the factory jobs). A submitted but not yet admitted run reads as queued for its own client.

QualityRunView (strict):

FieldSourceQueued value
id, parentIdid, parent_idid, null
repo, package, headSha, intentrun rowfrom the submission
baseShabase_sha0000000000000000000000000000000000000000 (PENDING_BASE_SHA)
statusrunning, completed, partial, inconclusive, error, cancelledqueued
verdictpassed:remediation, passed:feature, failed or nullnull
errorCodeerror_codenull
findingsfindings (array)[]
sandboxSecondssandbox_ms / 10000
chunksTotal, chunksTimeout, cacheHitscounters0
createdAt, closedAtISO 8601submission time, null

An admitted run still shows the provisional baseSha of 40 zeros until cacheLookup records the computed base.

GET /v1/quality/runs/:id/survivors?cursor=​

Returns survived mutants in stable_id order, QUALITY_SURVIVORS_PAGE = 200 per page:

{
"survivors": [
{ "stableId": "…64 hex…", "file": "src/budget.ts", "function": "reserve",
"mutator": "ConditionalExpression", "original": "a > b", "replacement": "true" }
],
"nextCursor": "…64 hex… or null"
}

(Example values are illustrative.) Pass nextCursor as ?cursor= for the next page; null is the last page. A cursor must be 1 to 128 characters (400 otherwise). The run must belong to the client (404 otherwise). Survivors of a verify's measurement are on its head child run; the verify run's own mutant rows hold only re-killed candidates. The child run ids are not returned by any route (only parentId on a child).

Error codes​

All errors use the API envelope { error: { code, message }, requestId } (ApiError).

HTTPCodeWhen
400invalid_requestmissing or over-long Idempotency-Key, body not JSON, body fails the strict schema, bad cursor
401unauthorizedno or unknown API key (shared API middleware)
403forbiddenclient not in QUALITY_CLIENTS; repo not in FACTORY_REPOS ("repo is not in FACTORY_REPOS")
404not_foundunknown run, another client's run, expired submission; every route when QUALITY_ENABLED is unset
413payload_too_largebody over the API's body limit (limitBody middleware)
429budget_exhausteddaily sandbox seconds used up (client: "daily sandbox seconds for this client are used up"; global: "daily sandbox seconds are used up")
429too_many_pendingthe client has QUALITY_MAX_PENDING_PER_CLIENT submissions waiting for admission
503unavailablethe workflow start failed or Temporal is unconfigured; Retry-After: 30 (cause temporal_unreachable)

Run-level outcomes (error_code values such as base_stale, exec_lost, budget_exhausted refused at admission) are not HTTP errors: they appear in QualityRunView.errorCode. See assessment workflow.

AC16 test coverage​

apps/api/test/quality.test.ts: 404 with QUALITY_ENABLED unset; startup refusal without a starter; namespace and key defaults; strict config bounds; 403 for client and repo; 400 for body and key; 202 under 1 s with refs only and 200 on replay; verify intent default; 503 with no row when Temporal is down; 429 too_many_pending at the cap, a failed start not holding a slot, exactly the cap accepted under concurrent submits; survivors page at 200 with a cursor and 404 for another client; 429 once the client or global daily seconds are used up.

Sources​

  • apps/api/src/quality.ts (registerQualityRoutes, submit, uuidFrom, createQualityStarter)
  • apps/api/src/config.ts (QUALITY_*, int, superRefine rules, qualityNamespace, qualityPayloadKeys)
  • apps/api/src/app.ts, apps/api/src/server.ts, apps/api/src/errors.ts (sendOutcome, invalidRequest)
  • packages/agent-types/src/http.ts (QualityRunRequest, QualityVerifyRequest, QualityRunAccepted, QualityRunView, QualitySurvivorsPage, QUALITY_SURVIVORS_PAGE, IDEMPOTENCY_HEADER, routes, HTTP_STATUS, toResponse, ApiError)
  • packages/agent-types/src/factory.ts (FACTORY_LIMITS.maxIdempotencyKeyChars)
  • packages/db/src/quality.ts (createRun, submit, getSubmission, getRun, listSurvivors, sandboxSecondsToday, PENDING_BASE_SHA)
  • apps/worker/src/config.ts (QUALITY_CONCURRENCY: int(1, 1, 1)), apps/worker/src/worker.ts
  • apps/worker/src/quality/core-activities.ts (admit, cacheLookup)
  • apps/api/test/quality.test.ts
  • docs/sessions/2026-11-16-codecrucible-build/adr/0009-quality-admission-and-pending-submissions.md
  • docs/deploy-quality.md (Environment)