Open_Ultra_SAST/.kiro/specs/detection-core/requirements.md

Requirements Document

Project Description (Input)

Who has the problem: the maintainer of OpenUltraSAST. Every detection arm built so far (prover, hunter, push hook, proof arm) is corrected link by link, and corrections do not compose — v1→v2 retunes transferred 0/17 on untouched cases, and the 2026-10-30 admission run on the untouched pilot population returned NO-GO (0/12 pairs, in-family 0/3, 9/12 repositories with zero framework recognition).

Current situation: detection is specified as per-family, per-arm runners around an implicit core. The ordered trace exists for one family (access-control-prover), learned components fit pool shortcuts (deletion count separates reversed fixes at 0.90), and misses concentrate in unmeasured links: entry recognition, call resolution (11.9% complete), guard dominance, and the 120s pre-push budget.

What should change: one specified core object — the security trace — with a contract every arm, fact pack, and consumer reuses: given a push (base, head) within a fixed budget, output proven defect claims (each with its witness) plus explicit coverage of what was not decided, on repositories never seen. Models are bounded to residuals; admission on an untouched population gates the trace itself; no fitted component ever sees pool labels.

Requirements

Requirement 1: Canonical trace object

The detection core shall define one canonical trace object per analyzed change as the shared security object for all detection arms.

1. When a change is analyzed, the detection core shall produce a canonical trace carrying entry identity, ordered hops with call-target completeness, operation kind with resource and authority, witnesses with provenance and match relations, guard effects, completeness reasons, a final judgment, and the input digests of the analysis.
2. The detection core shall serialize every trace deterministically, so that identical inputs produce byte-identical traces.

Requirement 2: Three-way judgment vocabulary

The detection core shall judge every analyzed operation as exactly one of unguarded, discharged, or indeterminate.

1. The detection core shall never convert an indeterminate judgment into a clean (discharged or unguarded-free) result.
2. When evidence for a judgment is incomplete, the detection core shall return indeterminate with the named incompleteness reasons.

Requirement 3: Coverage accounting

The detection core shall account for every input it did or did not use, so a zero result is never indistinguishable from an unread input.

1. When a change is analyzed, the detection core shall report entry-recognition coverage, per-call resolution outcomes with exactly one outcome bucket per call, and named reasons for every unchecked operation.
2. If any input file is read as zero bytes, the detection core shall fail the run as an instrument failure rather than reporting a clean result.

Requirement 4: Measured budget and change scoping

The detection core shall derive its time budget from measurement, not from a fixed constant.

1. When a change is analyzed, the detection core shall measure and record reply time and change complexity (changed regions, call count, changed size) for every change.
2. The detection core shall derive the per-change budget from the measured distribution (sample count, percentile, reference workload and hardware disclosed) and shall publish that derivation under the fixed measurement schema; the budget shall be configurable per workload class, never a single static constant.
3. When a change exceeds the measured budget, the detection core shall fail the budget gate naming the change, the elapsed time, and the budget derivation exceeded.
4. While a push is analyzed, the detection core shall limit analysis to regions affected by the change and shall record the scope it used.

Requirement 5: Verdict contract

The detection core shall distinguish proven defect claims from bounded silence.

1. When the detection core reports a defect, the claim shall carry its witness evidence and an exact location tied to the change.
2. When the detection core cannot decide a site, it shall report that site as undecided with its coverage reason, and shall never present an undecided site as a clean result.

Requirement 6: Provenance and digests

The detection core shall stamp every trace and verdict with the identities of its inputs.

1. The detection core shall record, for every analysis, the analyzer revision, fact-set digest, acquisition-record digest, configuration digest, population digest, and per-change input digest.
2. If any recorded digest cannot be re-derived from the named inputs, the detection core shall refuse the result rather than accept it.

Requirement 7: Admission gate contract

The detection core shall gate any generalization claim on an untouched population.

1. When an arm is proposed for pre-push use, the detection core shall require a reviewed manifest naming the frozen analyzer, facts, acquisition, configuration, and an untouched admission population before any admission label is opened.
2. The detection core shall consume admission manifests without producing, mutating, or re-labeling them, and shall refuse manifests that are unreviewed, label-exposing, acquisition-changed, or spent.
3. When admission evidence is scored, the detection core shall report paired vulnerable/fixed behavior, ordinary false alarms, and every gate (budget, instrument, pre-registered criteria) as an evidence-backed GO or NO-GO.

Requirement 8: No fitting on evaluation labels

The detection core shall not allow any fitted component to train on evaluation labels.

1. The detection core shall prohibit tuned prompts, thresholds, or fitted models whose training data includes pool or admission labels.
2. When a fitted component is proposed, the detection core shall require it to pass reversed-pair probes (a fix and its reversed fix shall not be separable by the component's decision features), per-repository holdout, and admission on an untouched population before any claim is made.

Requirement 9: Bounded role for models

The detection core shall bound every model to residual questions over the trace.

1. Where a model judges a trace, the detection core shall present the deterministic trace and require the judgment to be zero-shot over that trace.
2. The detection core shall not allow a model to propose-and-adjudicate the same claim, and shall reserve blocking verdicts for demonstrated proofs with a differential witness.

Requirement 10: Family fact packs as the extension point

The detection core shall admit new vulnerability families only as fact packs over the core trace contract.

1. When a new family is added, the detection core shall require the family's entry, operation, and guard knowledge as reviewed fact packs stamped into the trace's provenance, without changing the trace schema or judgment vocabulary.
2. The detection core shall report, per arm, the vulnerability families the arm claims, so admission and rollout numbers are never read across families the arm does not cover.

Requirement 11: Consumer and re-parenting contract

The detection core shall be the single contract that existing detection specs reuse.

1. The detection core shall define the interface through which the pre-push transaction consumes traces and verdicts within its deadline.
2. The detection core shall define the interface through which proof-based blocking evidence attaches to a trace verdict.
3. When an existing arm's behavior is described, the detection core shall require that description to be expressed over the core contract rather than as a separate runner contract.

Requirement 12: Fixed measurement schema

The detection core shall require one fixed measurement schema for every detection number.

1. When any detection result is reported, the detection core shall require population and freeze digests, judgment vocabulary, every rate with its sample count and uncertainty interval, coverage, instrument failures, and runtime.
2. When a measurement changes population or judgment vocabulary, the detection core shall treat the result as a new baseline and shall not present it as a trend against the previous baseline.

Out of Scope

• The pre-push hook transaction, rollout policy, and capability registry (pre-push-safety-net).
• New vulnerability families and their fact content (fact-pack specs).
• Fitted models of any kind in the core path.
• Engine and graph internals (contributor-scan).