Quality tables
CodeCrucible stores everything in the core Postgres database, in six tables created by two hand-run migrations:
| Migration | Tables |
|---|---|
packages/db/drizzle/0006_quality.sql | quality_runs, quality_functions, quality_mutants, quality_baselines, quality_chunk_cache |
packages/db/drizzle/0007_quality_submissions.sql | quality_submissions |
Migrations are run by hand on every deployment; neither has run anywhere yet. The Drizzle schema is in
packages/db/src/schema.ts; the CHECK constraints for enums are generated from the zod enums in
packages/agent-types/src/quality.ts, so the database and the code cannot drift. All SQL is in PgQualityStore
(packages/db/src/quality.ts). Rows hold source fragments (at most 80 characters), never whole files.
ER diagram
quality_runs
One row per admitted (or refused) run: assessments, verifies and verify children.
| Constraint | Rule |
|---|---|
| PK | id uuid, default gen_random_uuid() (the API supplies its own) |
quality_runs_workflow_id_unique | workflow_id unique; written as `'quality-' |
quality_runs_parent_id_quality_runs_id_fk | parent_id references quality_runs(id) |
quality_runs_status_valid | status in running, completed, partial, inconclusive, error, cancelled |
quality_runs_intent_valid | intent in remediation, feature |
quality_runs_verdict_valid | completed needs a verdict in passed:remediation, passed:feature, failed, and a pass must equal `'passed:' |
quality_runs_error_code_valid | error needs error_code matching ^[a-z][a-z0-9_]{0,63}$; any other status has a null code |
quality_runs_base_sha_hex, quality_runs_head_sha_hex | ^[0-9a-f]{40}$ |
quality_runs_config_sha256_hex | ^[0-9a-f]{64}$ |
quality_runs_image_digest_valid | null or ^sha256:[0-9a-f]{64}$ |
quality_runs_repo_len, quality_runs_package_len | 1..140, 1..214 |
quality_runs_protected_branch_len | null or 1..255 |
quality_runs_findings_size | octet_length(findings::text) <= 65536 |
quality_runs_counters_nonneg | sandbox_ms, chunks_total, chunks_timeout, cache_hits at least 0 |
quality_runs_closed_iff_terminal | closed_at IS NULL exactly when status = 'running' |
| Indexes | quality_runs_repo_package_created_at_idx (repo, package, created_at), quality_runs_client_created_at_idx (client, created_at) |
The verdict constraint is the database form of "a feature pass is never recorded as a remediation pass".
Run row lifecycle
Every write to child rows is conditional on the run being open (closed_at IS NULL ... FOR UPDATE), so a late activity
retry after close changes nothing and reports false. closeRun updates only an open row, so the close is idempotent;
sandbox_ms is written as an absolute total, so a retried close cannot count it twice. (PgQualityStore.addSandboxMs
exists but no caller uses it: sandbox time reaches the row only at close.)
findings is capped in the core close activity (capFindings): the first findings whose compact JSON fits half of
64 KiB, because jsonb text adds a space after every : and ,, which at most doubles the compact JSON.
quality_functions
One row per measured function of a run (from the merged chunk reports).
| Constraint | Rule |
|---|---|
quality_functions_run_id_file_qualified_name_unique | unique (run_id, file, qualified_name); upserts are idempotent |
| FK | run_id references quality_runs(id) |
quality_functions_source_sha256_hex | ^[0-9a-f]{64}$ |
quality_functions_file_len, quality_functions_qualified_name_len | 1..512 each |
quality_functions_coverage_range | coverage BETWEEN 0 AND 1 |
quality_functions_counts_valid | all counts and crap non-negative, and killed + survived + no_coverage + timeout <= mutants_total |
crap is computed by the core activity as crap(cyclomatic, coverage) with the (capped) coverage. mutants_total
includes compile_error, runtime_error, ignored and pending, which is why the sum constraint is <=.
quality_mutants
One row per trusted mutant of a run. A verify run also holds copies of its head child's re-killed candidates with
rekill set.
| Constraint | Rule |
|---|---|
quality_mutants_run_id_stable_id_unique | unique (run_id, stable_id) |
| FK | run_id references quality_runs(id) |
quality_mutants_stable_id_hex | ^[0-9a-f]{64}$ |
quality_mutants_status_valid | killed, survived, no_coverage, timeout, compile_error, runtime_error, ignored, pending |
quality_mutants_rekill_valid | null, confirmed or not_reproduced |
quality_mutants_snippet_len | original and replacement at most 80 characters (the store cuts by code points first) |
quality_mutants_file_len, quality_mutants_function_len, quality_mutants_mutator_len | 1..512, 1..512, 1..64 |
quality_mutants_killed_by_valid | killed_by a JSON array of at most 4,096 bytes |
The survivors REST page reads status = 'survived' in stable_id order with a keyset cursor (stable_id > cursor).
quality_baselines
The protected branch's current measurement per function: the "no new debt" reference of every assessment's gate.
| Constraint | Rule |
|---|---|
quality_baselines_function_unique | unique (repo, package, branch, file, qualified_name) |
| FK | run_id references quality_runs(id) |
quality_baselines_base_sha_hex, quality_baselines_source_sha256_hex | 40 and 64 hex |
quality_baselines_crap_nonneg | crap >= 0 |
quality_baselines_mutation_score_range | mutation_score BETWEEN 0 AND 100 |
writeBaseline writes only for an open run with protected_branch IS NOT NULL, and setRunRefs sets
protected_branch only when the computed base equals the head, i.e. the head is the protected tip (AC15). It
upserts by function, so a function that disappeared keeps its old baseline row. mutation_score is
100 * (killed + timeout) / (killed + timeout + survived + no_coverage), or 100 for a function without mutants.
The gate reads the baseline joined to the writing run's quality_functions rows (readBaselineFunctions).
quality_chunk_cache
| Constraint | Rule |
|---|---|
| PK | cache_key char(64) |
quality_chunk_cache_key_hex | ^[0-9a-f]{64}$ |
quality_chunk_cache_report_size | octet_length(report) <= 131072 |
| Index | quality_chunk_cache_last_hit_at_idx (last_hit_at) |
| Rule | Value | Where |
|---|---|---|
| Key | sha256 of package tree hash, transitive workspace: dependency tree hashes, chunk spec, image digest, policy config hash | chunkCacheKey |
| First write wins | an existing entry is only touched (last_hit_at), never replaced | putChunk |
| Row cap | 2,000 rows (about 250 MiB); least recently hit evicted beyond it, under the advisory lock agentforge:quality:chunk_cache | putChunk, QUALITY_LIMITS.maxChunkCacheRows |
| TTL | rows not hit for 30 days deleted by the close activity | sweepChunkCache, QUALITY_LIMITS.chunkCacheTtlDays |
| Touch | getChunk updates last_hit_at on every read | getChunk |
Only reports that parsed with the strict QualityChunkReport schema are cached, so a hit never serves an invalid one.
quality_submissions
A submitted run that is not yet admitted (ADR 0009, bead .111). The API writes no run row; it records a submission so
it can cap pending runs per client and answer queued reads.
| Constraint | Rule |
|---|---|
| PK | id uuid (the future run id) |
quality_submissions_intent_valid | remediation, feature |
quality_submissions_head_sha_hex | 40 hex |
quality_submissions_repo_len, quality_submissions_package_len | 1..140, 1..214 |
| Index | quality_submissions_client_created_at_idx (client, created_at) |
There is no foreign key to quality_runs. A submission stops counting when a run row with the same id exists or when it
is older than QUALITY_PENDING_TTL_SEC; both are swept lazily on the next submit of any client.
Advisory locks
Lock key (hashtext) | Scope | Taken by |
|---|---|---|
agentforge:quality:admission | global | createRun for top-level runs and for children (one lock for both counts) |
agentforge:quality:run:<id> | one run id | createRun with a supplied id (idempotent admission) |
agentforge:quality:submit:<client> | one client | submit (pending cap) |
agentforge:quality:chunk_cache | global | putChunk (insert and eviction) |
All are transaction-scoped (pg_advisory_xact_lock).
Limits used by the data layer (QUALITY_LIMITS)
| Key | Value |
|---|---|
maxSnippetChars | 80 |
maxChunkReportBytes | 131,072 (128 KiB) |
maxChunkCacheRows | 2,000 |
chunkCacheTtlDays | 30 |
maxFindingsBytes | 65,536 (64 KiB) |
defaultConcurrency | 1 |
Sources
packages/db/drizzle/0006_quality.sql,packages/db/drizzle/0007_quality_submissions.sqlpackages/db/src/quality.ts(PgQualityStore:createRun,submit,releaseSubmission,getSubmission,getRun,listSurvivors,addSandboxMs,sandboxSecondsToday,closeRun,setRunRefs,readBaselineFunctions,putFunctions,putMutants,writeBaseline,getChunk,putChunk,sweepChunkCache,PENDING_BASE_SHA,MAX_OPEN_CHILDREN)packages/db/src/schema.tspackages/agent-types/src/quality.ts(QUALITY_LIMITS, enums)apps/worker/src/quality/core-activities.ts(capFindings,merge,mutationScore)packages/quality-core/src/analysis.ts(chunkCacheKey).omc/plans/codecrucible-mutant-hunter.md(section 3 "Storage", "Cache")docs/sessions/2026-11-16-codecrucible-build/adr/0009-quality-admission-and-pending-submissions.md