Audit lifecycle
Queue admission, deterministic scanning, context assembly, agent reasoning, reports, SSE progress, retries, and partial results.
- 01Ingest
Capture an exact source snapshot or validate an uploaded artifact.
- 02Observe
Extract deterministic code, dependency, IaC, and CI/CD facts.
- 03Reconcile
Build tenant-scoped entities, edges, evidence, and contradictions.
- 04Reason
Route bounded context to specialist agents and verify every claim.
- 05Deliver
Publish architecture, findings, costs, and controlled remediation.
Admission and queueing
Audit creation requires workspace access, an authorized source, and an idempotency key. A workspace may have at most one active-or-queued audit. A duplicate request returns a typed conflict that identifies the existing audit rather than creating competing work.
The scheduler uses global scanner capacity and runner health to expose queue position. Queue state is persisted; it is not inferred from a browser connection.
Stage contract
| Stage | Durable output | Can be partial? |
|---|---|---|
| Ingestion | exact commit or validated upload snapshot | no—invalid source stops admission |
| Scanning | normalized observations, SBOM, scanner coverage | yes—each failed scanner creates a coverage gap |
| Reconciliation | entities, relationships, evidence, contradictions | yes—missing source lowers confidence |
| Agent analysis | typed artifacts with evidence IDs | yes—budget or agent failure is explicit |
| Reporting | canonical Pydantic JSON | yes—coverage and omitted stages are prominent |
| Export | Markdown, DOCX, PDF, JSON, Mermaid/SVG/PNG | format-specific failure is retryable |
Live events
Authenticated SSE emits monotonic events for queue position, stage transitions, scanner logs, agent artifacts, cost, cache decisions, warnings, retries, and terminal state. Clients reconnect with the last received event identifier and deduplicate by event ID.
queue.updated
audit.stage.started
scanner.log
agent.artifact.completed
usage.updated
audit.coverage_gap.created
audit.completedCancellation and retry
Cancellation stops new activities, requests cooperative termination of active work, and preserves evidence already committed. Retry creates or resumes only an allowed failed boundary; it does not silently overwrite the prior attempt or duplicate costs.
A partial report is a valid terminal outcome
Scanner failure, unavailable model budget, or an exhausted cost cap produces a report that names the missing coverage. It never produces a clean verdict by omission.