# Excititor WebService Charter

## Mission
Expose Excititor APIs (console VEX views, graph/Vuln Explorer feeds, observation intake/health) while honoring the Aggregation-Only Contract (no consensus/severity logic in this service).

## Scope
- Working directory: `src/Excititor/StellaOps.Excititor.WebService`
- HTTP APIs, DTOs, controllers, authz filters, composition root, telemetry hooks.
- Wiring to Core/Storage libraries; no direct policy or consensus logic.

## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/excititor/README.md#latest-updates`
- `docs/modules/excititor/vex_observations.md`
- `docs/ingestion/aggregation-only-contract.md`
- `docs/modules/excititor/implementation_plan.md`

## Roles
- Backend developer (.NET 10 / C# preview).
- QA automation (integration + API contract tests).

## Working Agreements
1. Update sprint `Delivery Tracker` when tasks move TODO→DOING→DONE/BLOCKED; mirror notes in Execution Log.
2. Keep APIs aggregation-only: persist raw observations, provenance, and precedence pointers; never merge/weight/consensus here.
3. Enforce tenant scoping and RBAC on all endpoints; default-deny for cross-tenant data.
4. Offline-first: no external network calls; rely on cached/mirrored feeds only.
5. Observability: structured logs, counters, optional OTEL traces behind configuration flags.

## Testing
- Prefer deterministic API/integration tests under `__Tests` with seeded Mongo fixtures.
- Verify RBAC/tenant isolation, idempotent ingestion, and stable ordering of VEX aggregates.
- Use ISO-8601 UTC timestamps and stable sorting in responses; assert on content hashes where applicable.

## Determinism & Data
- MongoDB is the canonical store; never apply consensus transformations before persistence.
- Ensure paged/list endpoints use explicit sort keys (e.g., vendor, upstreamId, version, createdUtc).
- Avoid nondeterministic clocks/randomness; inject clocks and GUID providers for tests.

## Boundaries
- Do not modify Policy Engine or Cartographer schemas from here; consume published contracts only.
- Configuration via appsettings/environment; no hard-coded secrets.

## Ready-to-Start Checklist
- Required docs reviewed.
- Test database/fixtures prepared (no external dependencies).
- Feature flags defined for new endpoints before exposing them.