Bug-Candidate Interface

[azchin]

Enrich the bug candidate interface by providing more libCRS arguments, and concretize the format of bug-candidates (e.g. SARIF). In doing so, we also want the following libCRS functionality for bug-candidates:

• quick lookup on what bug-candidates currently exist (instead of ls + reading all candidate files on disk)
• attaching and editing metadata to bug-candidates, like "currently exploring" or "fixed" or "false positive" or "confirmed but not fixed"
• a CRS or CRS sub-agent may claim the bug-candidate, so that duplicate effort is not administered across parallel agents

Implementation wise, this should be done as a libCRS interface with SQLite under the hood. That way we can keep our "all artifacts are files" methodology and oss-crs-workdir is portable.

This is related to, but not identical to #255. This interface is specific for bug-candidates, not general purpose knowledge store.

[azchin]

We also need to account for bug-candidate locations moving over time across versions. A simple file:location is not sufficient to encapsulate all versions of the program, so we need to tie multiple locations + version ranges to the same candidate.

[azchin]

If parallel agents are running on the same bug-candidate, we should also provide a way to publish / subscribe to updates on that bug-candidate.

[azchin]

Bug-Candidate Interface — implementation summary

The bug-candidate interface is implemented in libCRS. This comment summarizes the interface, the SARIF fields it builds on, and how the two artifact forms (SARIF files + a SQLite index) relate.

Two artifact forms: SARIF is the record, the DB is the index

A bug-candidate exists as two coupled representations:

1. A SARIF 2.1.0 file — the durable, portable artifact. When a CRS records a candidate, libCRS publishes its SARIF as a plain file, so it uses the normal artifacts/exchange machinery: it shows up in oss-crs artifacts/archive and forwards to other CRSs exactly like a PoV. This keeps the "all artifacts are files" model intact.
2. A row in a global SQLite database — the queryable index/materialized view. One DB for the whole workdir (OSS_CRS_BUG_CANDIDATE_DIR/index.sqlite, i.e. .oss-crs-workdir/BUG_CANDIDATE_DIR/), mounted read-write into every CRS module container of every run. SQLite's own WAL locking handles concurrent access, so state is immediately consistent across CRSs and claim is a genuine atomic check-and-set.

The DB is a rebuildable cache, not the source of truth — the SARIF files are. This is what the DB↔file provenance below guarantees.

The libCRS interface

Each command is exposed both as a libCRS bug-candidate <verb> CLI command and as a 1:1 CRSUtils.bug_candidate_* Python method. By intention:

• add — record a new bug-candidate: its discovery method / rule, one or more code locations, a severity, an associated harness, and arbitrary key/value properties. It can build the candidate from those fields or import an existing SARIF report. The same command also enriches an existing candidate — e.g. adding another location (the same bug in a new revision) or more properties.
• mark-explored — record that this CRS investigated the candidate, whatever the outcome.
• mark-pov — record that a PoV was produced from the candidate, linking the reproducing input.
• claim / release — take, and give up, temporary exclusive ownership of a candidate so parallel agents don't chase the same one; ownership lapses on its own if the holder goes away.
• merge — declare two candidates the same bug (explicit deduplication).
• note — attach free-form commentary to a candidate, e.g. why a lead was ruled out.
• list / get — find and read candidates, filtered by whether they have a PoV, who has explored them, their version, or their properties. Reads can be widened beyond the current harness to borrow leads from a project's other harnesses, or from every project in the database; borrowed candidates are marked as foreign. (Recording is always scoped to the CRS's own target+harness — only reads widen.)
• sync / watch — ingest externally-provided candidates (e.g. bootup/directed inputs), and subscribe to a live stream of updates as other CRSs and agents make them.

add flags → SARIF fields

add either imports a SARIF file (--raw <file>) or builds the SARIF from flags. When building, each flag populates a specific SARIF field:

Flag	SARIF field
--rule <str>	result.ruleId — bug class / discovery method
--message <str>	result.message.text
--severity error|warning|note	result.level
--id <guid>	result.correlationGuid — target an existing candidate; a new one is minted when omitted
--file <path>	result.locations[].physicalLocation.artifactLocation.uri
--uri-base-id <str>	…artifactLocation.uriBaseId
--line / --column / --end-line / --end-column	…physicalLocation.region.{startLine,startColumn,endLine,endColumn}
--function <name>	…location.logicalLocations[kind=function].name
--version <rev>	run.versionControlProvenance[].revisionId
--repo <uri>	…versionControlProvenance[].repositoryUri
--branch <name>	…versionControlProvenance[].branch
--property KEY=VALUE (repeatable)	result.properties — indexed and queryable via list --property

--version / --repo default to the campaign's OSS_CRS_TARGET_REVISION / OSS_CRS_TARGET_REPOSITORY when omitted, so a location resolves to the source it was found against without the agent supplying it. The remaining flags — --harness (associated harness), --pov-ref (link a reproducing input), --agent (actor recorded on the event) — are operational, not SARIF result fields.

DB ↔ SARIF provenance

The link between a DB row and its SARIF file is deterministic, not stored:

• A candidate's SARIF filename is always <correlation_id>.sarif.json. Because it is a pure function of the candidate id, the DB stores no path column — a consumer reconstructs the filename from the id, and the row's created_run column locates the producing run's bug-candidates directory.
• Every mutation appends a row to an updates table (type, actor CRS/agent, run id, timestamp, payload) — the pub/sub log that watch streams and that lets the index be re-derived.
• Directed-input / bootup raw SARIF (delivered read-only via FETCH_DIR/bug-candidates) is folded into the DB idempotently by sync.

SARIF fields we build on

Identity and versioning are SARIF-native — we did not invent parallel fields:

Concept	SARIF field
Candidate identity (equivalence class — "same bug across versions/runs")	result.correlationGuid — the candidate_id is this value; minted and embedded when a submitted result lacks one
Per-instance detection provenance	result.guid — recorded as a detection, never as identity, so repeated detections collapse into one candidate
Merge/dedup hint	result.partialFingerprints
Program version a location is valid for	run.versionControlProvenance[].revisionId (+ repositoryUri, branch) — so one bug whose file:line moves across versions stays a single candidate with several versioned locations
Location	physicalLocation.artifactLocation.uri (+ uriBaseId), region.{startLine,startColumn,endLine,endColumn}, logicalLocations[kind=function].name
Severity / class	result.level / result.ruleId
Arbitrary indexed metadata	result.properties bag — queryable (e.g. subagent=pov-gen)

The build↔parse of the SARIF result shape lives in one place (sarif.build_result / sarif._parse_result) so the two stay in lockstep. location.version / repository_uri default automatically to the campaign's resolved source revision / main_repo (injected as OSS_CRS_TARGET_REVISION / OSS_CRS_TARGET_REPOSITORY), so candidates auto-resolve to the source they were found against without the agent supplying it.

Candidate metadata tracked in the DB

Beyond identity and locations, each candidate carries:

• pov_ref (with pov_crs, pov_agent, pov_at) — columns on the candidates row, set by mark-pov: the hash of the PoV produced from the candidate, plus who/when. Empty until a PoV exists.
• explored_by — derived from a separate explorations table, one row per (candidate, crs), written by mark-explored. It is the list of CRSs that have tried the candidate; the CRS name is taken from the environment, not passed by the caller. One row per CRS, so concurrent CRSs marking the same candidate don't collide.
• status — not stored; computed on read as pov_generated when pov_ref is set, else new.
• claim (owner + lease expiry) and properties (the queryable key/value bag).

There is intentionally no confirmed/false_positive state — a CRS that rules a candidate out records the reasoning in a note rather than mutating shared state that other CRSs also read.

The DB is versioned and migrates in place on open, since it is global and outlives any single schema.