Concepts and glossary
Canonical definitions for TheSpider campaigns, slices, leases, findings, and identity
Audit structure
| Term | Definition |
|---|---|
| Project | Tenant-scoped container for repository identity, mode, methodology versions, campaigns, and finding identity. |
| Methodology | Immutable configuration version containing buckets, categories, passes, scopes, and prompt sections. |
| Campaign | Audit of a target branch and commit using one methodology version. Campaign types are full, incremental, and retest. |
| Audit run | One campaign cell for a pass and bucket. |
| Slice | Smallest execution unit: one audit run assigned to one model. A slice moves through pending, running, completed, or failed state. |
| Lease | Time-bounded claim granting one worker the right to execute a slice. Expiry requeues the slice; first accepted result wins. |
| Report | One model-emitted observation parsed from a slice's raw stdout. Reports retain model, pass, bucket, file, category, CWE, and evidence provenance. |
Finding identity
| Term | Definition |
|---|---|
| Finding | Project-level deduplicated issue that teams triage. Security-mode projects call it a finding or vulnerability; bug-mode projects call it a bug. |
| Finding fingerprint | Deterministic identity derived from normalized, scrubbed report content. A project maps each known fingerprint to one canonical finding. |
| Fingerprint alias | Additional fingerprint mapped to an existing canonical finding after adjudication or merge. Aliases preserve identity when wording or evidence changes. |
| Sighting | Evidence that a finding appeared in a campaign, branch, and commit. Comparison uses sightings rather than the campaign where the finding was first created. |
| Keeper | Canonical finding that remains active after a merge. |
| Soft merge | Merge that points a losing finding to its keeper instead of deleting it. Reports, aliases, sightings, and provenance resolve through the keeper while the loser remains an auditable tombstone. |
Finding identity is project-global, not branch-local. A finding can have sightings on several branches and campaigns while retaining one triage state.
Campaign comparison
| Term | Definition |
|---|---|
| Baseline | Campaign selected as the prior side of a comparison. An explicit baseline wins; otherwise the preceding campaign is used where supported. |
| New finding | Live keeper sighted in the selected campaign but not the baseline. |
| Resolved finding | Live keeper sighted in the baseline but absent from the selected campaign. Absence should not be treated as proof while campaign slices remain incomplete. |
| Carried-forward finding | Open keeper sighted in both selected and baseline campaigns. |
| Gate | Cheap authenticated campaign read returning pass, fail, or pending from slice completion and new findings. CI polls the gate; it does not run models. |
Remediation and retest
| Term | Definition |
|---|---|
| Fix record | Remediation record with description, pull request, ticket, and one or more commits. |
| False-positive record | Decision record with reason, decider, notes, and optional commit through which the decision applies. |
| Retest campaign | Finding-scoped campaign that runs the finding's bucket and passes matching its files. |
| Fix verification | Retest conclusion attached to a fix. confirmed means the covered retest did not reproduce the finding; regressed means the same or deduplicated finding reappeared. |
Execution boundary
| Term | Definition |
|---|---|
| Brain | Server-side logic for prompts, parsing, scrubbing, fingerprints, deduplication, triage, usage, and persistence. |
| Agent | Thin local process that detects Git metadata, claims leases, runs model commands in a checkout, and uploads raw stdout plus a short stderr tail. |
| Runner | Command bound to a model code on an agent host. It consumes a prompt file and emits marker-delimited findings on stdout. |
| Artifact | Content-addressed prompt, output, normalized output, or stderr object stored for provenance. |
Continue with campaign workflows, the runner contract, or the API reference.