# AGENTS
## Role
Job orchestration and lifecycle. Registers job definitions, schedules execution, triggers runs, reports status for connectors and exporters.
## Scope
- Contracts: IJob (execute with CancellationToken), JobRunStatus, JobTriggerOutcome/Result.
- Registration: JobSchedulerBuilder.AddJob<T>(kind, cronExpression?, timeout?, leaseDuration?); options recorded in JobSchedulerOptions.
- Plugin host integration discovers IJob providers via registered IDependencyInjectionRoutine implementations.
- Coordination: start/stop, single-flight via storage locks/leases, run bookkeeping (status, timings, errors).
- Triggering: manual/cron/API; parameterized runs; idempotent rejection if already running.
- Surfacing: enumerate definitions, last run, recent runs, active runs to WebService endpoints.
## Participants
- WebService exposes REST endpoints for definitions, runs, active, and trigger.
- Storage.Mongo persists job definitions metadata, run documents, and leases (locks collection).
- Source connectors and Exporters implement IJob and are registered into the scheduler via DI and Plugin routines.
- Models/Merge/Export are invoked indirectly through jobs.
- Plugin host runtime loads dependency injection routines that register job definitions.
## Interfaces & contracts
- Kind naming: family:source:verb (e.g., nvd:fetch, redhat:map, export:trivy-db).
- Timeout and lease duration enforce cancellation and duplicate-prevention.
- TimeProvider used for deterministic timing in tests.
## In/Out of scope
In: job lifecycle, registration, trigger semantics, run metadata.
Out: business logic of connectors/exporters, HTTP handlers (owned by WebService).
## Observability & security expectations
- Metrics: job.run.started/succeeded/failed, job.durationMs, job.concurrent.rejected, job.alreadyRunning.
- Logs: kind, trigger, params hash, lease holder, outcome; redact params containing secrets.
- Honor CancellationToken early and often.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Core.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.