Skip to main content

Quality tables

CodeCrucible stores everything in the core Postgres database, in six tables created by two hand-run migrations:

MigrationTables
packages/db/drizzle/0006_quality.sqlquality_runs, quality_functions, quality_mutants, quality_baselines, quality_chunk_cache
packages/db/drizzle/0007_quality_submissions.sqlquality_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.

ConstraintRule
PKid uuid, default gen_random_uuid() (the API supplies its own)
quality_runs_workflow_id_uniqueworkflow_id unique; written as `'quality-'
quality_runs_parent_id_quality_runs_id_fkparent_id references quality_runs(id)
quality_runs_status_validstatus in running, completed, partial, inconclusive, error, cancelled
quality_runs_intent_validintent in remediation, feature
quality_runs_verdict_validcompleted needs a verdict in passed:remediation, passed:feature, failed, and a pass must equal `'passed:'
quality_runs_error_code_validerror 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_validnull or ^sha256:[0-9a-f]{64}$
quality_runs_repo_len, quality_runs_package_len1..140, 1..214
quality_runs_protected_branch_lennull or 1..255
quality_runs_findings_sizeoctet_length(findings::text) <= 65536
quality_runs_counters_nonnegsandbox_ms, chunks_total, chunks_timeout, cache_hits at least 0
quality_runs_closed_iff_terminalclosed_at IS NULL exactly when status = 'running'
Indexesquality_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).

ConstraintRule
quality_functions_run_id_file_qualified_name_uniqueunique (run_id, file, qualified_name); upserts are idempotent
FKrun_id references quality_runs(id)
quality_functions_source_sha256_hex^[0-9a-f]{64}$
quality_functions_file_len, quality_functions_qualified_name_len1..512 each
quality_functions_coverage_rangecoverage BETWEEN 0 AND 1
quality_functions_counts_validall 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.

ConstraintRule
quality_mutants_run_id_stable_id_uniqueunique (run_id, stable_id)
FKrun_id references quality_runs(id)
quality_mutants_stable_id_hex^[0-9a-f]{64}$
quality_mutants_status_validkilled, survived, no_coverage, timeout, compile_error, runtime_error, ignored, pending
quality_mutants_rekill_validnull, confirmed or not_reproduced
quality_mutants_snippet_lenoriginal and replacement at most 80 characters (the store cuts by code points first)
quality_mutants_file_len, quality_mutants_function_len, quality_mutants_mutator_len1..512, 1..512, 1..64
quality_mutants_killed_by_validkilled_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.

ConstraintRule
quality_baselines_function_uniqueunique (repo, package, branch, file, qualified_name)
FKrun_id references quality_runs(id)
quality_baselines_base_sha_hex, quality_baselines_source_sha256_hex40 and 64 hex
quality_baselines_crap_nonnegcrap >= 0
quality_baselines_mutation_score_rangemutation_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​

ConstraintRule
PKcache_key char(64)
quality_chunk_cache_key_hex^[0-9a-f]{64}$
quality_chunk_cache_report_sizeoctet_length(report) <= 131072
Indexquality_chunk_cache_last_hit_at_idx (last_hit_at)
RuleValueWhere
Keysha256 of package tree hash, transitive workspace: dependency tree hashes, chunk spec, image digest, policy config hashchunkCacheKey
First write winsan existing entry is only touched (last_hit_at), never replacedputChunk
Row cap2,000 rows (about 250 MiB); least recently hit evicted beyond it, under the advisory lock agentforge:quality:chunk_cacheputChunk, QUALITY_LIMITS.maxChunkCacheRows
TTLrows not hit for 30 days deleted by the close activitysweepChunkCache, QUALITY_LIMITS.chunkCacheTtlDays
TouchgetChunk updates last_hit_at on every readgetChunk

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.

ConstraintRule
PKid uuid (the future run id)
quality_submissions_intent_validremediation, feature
quality_submissions_head_sha_hex40 hex
quality_submissions_repo_len, quality_submissions_package_len1..140, 1..214
Indexquality_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)ScopeTaken by
agentforge:quality:admissionglobalcreateRun for top-level runs and for children (one lock for both counts)
agentforge:quality:run:<id>one run idcreateRun with a supplied id (idempotent admission)
agentforge:quality:submit:<client>one clientsubmit (pending cap)
agentforge:quality:chunk_cacheglobalputChunk (insert and eviction)

All are transaction-scoped (pg_advisory_xact_lock).

Limits used by the data layer (QUALITY_LIMITS)​

KeyValue
maxSnippetChars80
maxChunkReportBytes131,072 (128 KiB)
maxChunkCacheRows2,000
chunkCacheTtlDays30
maxFindingsBytes65,536 (64 KiB)
defaultConcurrency1

Sources​

  • packages/db/drizzle/0006_quality.sql, packages/db/drizzle/0007_quality_submissions.sql
  • packages/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.ts
  • packages/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