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
| Setting | Effect |
|---|---|
QUALITY_ENABLED unset (or not 1/true) | Routes are not registered: every /v1/quality/* path answers 404 |
QUALITY_ENABLED=1 without a starter | createApp throws at startup: "QUALITY_ENABLED is set but no quality workflow starter is wired" |
QUALITY_ENABLED=1 and FACTORY_REPOS empty | Config refuses: "QUALITY_ENABLED needs FACTORY_REPOS" |
a QUALITY_CLIENTS entry not in API_KEYS | Config refuses: "QUALITY_CLIENTS client X is not in API_KEYS" |
server.ts wires createQualityStarter(cfg) only when QUALITY_ENABLED is set.
Routes
| Method | Path | Body | Success |
|---|---|---|---|
POST | /v1/quality/runs | QualityRunRequest | 202 { runId } (200 on an idempotent replay) |
POST | /v1/quality/verify | QualityVerifyRequest | 202 { runId } (200 on an idempotent replay) |
GET | /v1/quality/runs/:id | none | 200 QualityRunView |
GET | /v1/quality/runs/:id/survivors?cursor= | none | 200 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).
| Variable | Default | Rule |
|---|---|---|
QUALITY_TEMPORAL_NAMESPACE | TEMPORAL_NAMESPACE | |
QUALITY_TEMPORAL_PAYLOAD_KEYS, QUALITY_TEMPORAL_PAYLOAD_KEY_ID | the session payload keys | set 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 |
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:
| Limit | Variable | Default | Enforced where |
|---|---|---|---|
| Active top-level runs | QUALITY_CONCURRENCY (core worker) | 1, and the worker config caps it at 1 | admission, under the lock; a verify with its children counts as one |
| Open children per verify | MAX_OPEN_CHILDREN (code) | 2 | admission of a child; a child needs an open, top-level parent of the same client |
| Pending submissions per client | QUALITY_MAX_PENDING_PER_CLIENT (API) | 4 (1..100) | submit, under the per-client lock |
| Pending TTL | QUALITY_PENDING_TTL_SEC (API) | 86,400 (at least 60) | submit sweep and the queued read |
| Daily sandbox seconds per client | QUALITY_DAILY_SANDBOX_SECONDS_PER_CLIENT | 14,400 | API at submit (429), admission under the lock, cacheLookup before the chunks |
| Daily sandbox seconds, global | QUALITY_DAILY_SANDBOX_SECONDS_GLOBAL | 28,800 | same |
| Sandbox seconds per assessment | QUALITY_RUN_LIMITS.assessmentSandboxMs | 3,600 s | workflow, before each chunk: partial |
| Sandbox seconds per verify (children included) | QUALITY_RUN_LIMITS.verifySandboxMs | 7,200 s | workflow: 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 (markedshortcut). - Sandbox time reaches
quality_runs.sandbox_msonly when a run closes. The API's check at submit therefore counts open runs at 0; the admission check counts each open run atGREATEST(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):
| Field | Source | Queued value |
|---|---|---|
id, parentId | id, parent_id | id, null |
repo, package, headSha, intent | run row | from the submission |
baseSha | base_sha | 0000000000000000000000000000000000000000 (PENDING_BASE_SHA) |
status | running, completed, partial, inconclusive, error, cancelled | queued |
verdict | passed:remediation, passed:feature, failed or null | null |
errorCode | error_code | null |
findings | findings (array) | [] |
sandboxSeconds | sandbox_ms / 1000 | 0 |
chunksTotal, chunksTimeout, cacheHits | counters | 0 |
createdAt, closedAt | ISO 8601 | submission 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).
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | missing or over-long Idempotency-Key, body not JSON, body fails the strict schema, bad cursor |
| 401 | unauthorized | no or unknown API key (shared API middleware) |
| 403 | forbidden | client not in QUALITY_CLIENTS; repo not in FACTORY_REPOS ("repo is not in FACTORY_REPOS") |
| 404 | not_found | unknown run, another client's run, expired submission; every route when QUALITY_ENABLED is unset |
| 413 | payload_too_large | body over the API's body limit (limitBody middleware) |
| 429 | budget_exhausted | daily sandbox seconds used up (client: "daily sandbox seconds for this client are used up"; global: "daily sandbox seconds are used up") |
| 429 | too_many_pending | the client has QUALITY_MAX_PENDING_PER_CLIENT submissions waiting for admission |
| 503 | unavailable | the 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.tsapps/worker/src/quality/core-activities.ts(admit,cacheLookup)apps/api/test/quality.test.tsdocs/sessions/2026-11-16-codecrucible-build/adr/0009-quality-admission-and-pending-submissions.mddocs/deploy-quality.md(Environment)