# Vulnerability Explorer API Guild Charter (Epic 6)

## Mission
Expose policy-aware vulnerability listing, detail, simulation, workflow, and export APIs backed by the Findings Ledger and evidence services. Provide deterministic, RBAC-enforced endpoints that power Console, CLI, and automation workflows.

## Scope
- Service under `src/VulnExplorer/StellaOps.VulnExplorer.Api` (query engine, workflow endpoints, simulation bridge, export orchestrator).
- Integration with Findings Ledger, Policy Engine, Conseiller, Excitor, SBOM Service, Scheduler, and Authority.
- Evidence bundle assembly and signing hand-off.

## Principles
1. **Policy-driven** – All responses reference the requested policy version and include rationale metadata.
2. **Immutable facts** – APIs read advisory/VEX/inventory evidence; they never mutate or overwrite source documents.
3. **Audit-ready** – Every workflow action records ledger events and exposes provenance (IDs, timestamps, actors).
4. **Deterministic & efficient** – Query results stable under fixed inputs; pagination and grouping honor budgets.
5. **Secure** – RBAC/ABAC enforced server-side; exports signed; attachments served via scoped URLs.

## Collaboration
- Coordinate schemas with Findings Ledger, Console, CLI, and Docs; publish OpenAPI + JSON schemas.
- Work with DevOps/Observability for performance dashboards and SLOs.

## Tooling
- .NET 10 preview minimal API with async streaming for exports.
- PostgreSQL projections from Findings Ledger; Redis for query caching as needed.
- Integration with Policy Engine batch eval and simulation endpoints.

## Definition of Done
- Endpoints documented (OpenAPI), tested (unit/integration/perf), and budget-enforced.
- Telemetry/alerts configured; CI covers determinism.
- Evidence bundle signing verified; docs updated with compliance checklist.

## Required Reading
- `docs/modules/platform/architecture-overview.md`

## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both correspoding sprint file `/docs/implplan/SPRINT_*.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.