stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
17d45a6d303350efb35db194b706c526070417be
git.stella-ops.org/src/ExportCenter/AGENTS.md
StellaOps Bot 17d45a6d30
Some checks failed
Airgap Sealed CI Smoke / sealed-smoke (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
feat: Implement Filesystem and MongoDB provenance writers for PackRun execution context 
- Added `FilesystemPackRunProvenanceWriter` to write provenance manifests to the filesystem.
- Introduced `MongoPackRunArtifactReader` to read artifacts from MongoDB.
- Created `MongoPackRunProvenanceWriter` to store provenance manifests in MongoDB.
- Developed unit tests for filesystem and MongoDB provenance writers.
- Established `ITimelineEventStore` and `ITimelineIngestionService` interfaces for timeline event handling.
- Implemented `TimelineIngestionService` to validate and persist timeline events with hashing.
- Created PostgreSQL schema and migration scripts for timeline indexing.
- Added dependency injection support for timeline indexer services.
- Developed tests for timeline ingestion and schema validation.
2025-11-30 15:38:14 +02:00

4.7 KiB
Raw Blame History

Export Center · AGENTS Charter (Sprint 0164-0001-0001)

Module Scope & Working Directory

  • Working directory: src/ExportCenter/** (API/WebService, Worker, Core/Infrastructure libs, Trivy/Mirror/DevPortal adapters, RiskBundles pipeline, tests, seed/config). Cross-module edits require an explicit note in the sprint Decisions & Risks.
  • Mission: produce deterministic evidence exports (JSON, Trivy DB, mirror/delta, devportal offline) with provenance, signing, and distribution (HTTP, OCI, object) that remain offline-friendly and tenant-safe.

Roles

  • Backend engineer (.NET 10 / ASP.NET Core): API surface, planner/run lifecycle, RBAC/tenant guards, SSE events, download endpoints.
  • Adapter engineer: Trivy DB/Java DB, mirror delta, OCI distribution, encryption/KMS wrapping, pack-run integration.
  • Worker/Concurrency engineer: job leasing, retries/idempotency, retention pruning, scheduler hooks.
  • Crypto/Provenance steward: signing, DSSE/in-toto, age/AES-GCM envelope handling, provenance schemas.
  • QA automation: WebApplicationFactory + Mongo/Mongo2Go fixtures, adapter regression harnesses, determinism checks, offline-kit verification scripts.
  • Docs steward: keep docs/modules/export-center/*.md, sprint Decisions & Risks, and CLI docs aligned with behavior.

Required Reading (treat as read before setting DOING)

  • docs/README.md
  • docs/07_HIGH_LEVEL_ARCHITECTURE.md
  • docs/modules/platform/architecture-overview.md
  • docs/modules/export-center/architecture.md
  • docs/modules/export-center/profiles.md
  • docs/modules/export-center/trivy-adapter.md (for 36-001/36-002)
  • docs/modules/export-center/mirror-bundles.md (for 37-001/37-002)
  • docs/modules/export-center/provenance-and-signing.md
  • docs/modules/export-center/operations/kms-envelope-pattern.md (for 37-002 encryption/KMS)
  • Sprint file docs/implplan/SPRINT_0164_0001_0001_exportcenter_iii.md

Working Agreements

  • Enforce tenant scoping and RBAC on every API, worker fetch, and distribution path; no cross-tenant exports unless explicitly whitelisted and logged.
  • Maintain determinism: sorted outputs, canonical JSON, UTC RFC3339 timestamps, stable hashing; identical selectors yield identical manifests.
  • Offline-first: avoid new external calls; OCI distribution must be feature-flagged/disable-able for air-gap; tests must not reach the network.
  • Aggregation-Only Contract for evidence: no derived modifications; policy outputs stay separate and clearly labeled.
  • Concurrency: default per-tenant run caps (4 active) and idempotent retries; cooperative cancellation must clean partial artefacts and audit outcome.
  • Cross-module changes (Authority/Orchestrator/CLI) only when sprint explicitly covers them; log in Decisions & Risks.

Coding & Observability Standards

  • Target .NET 10 with curated local-nugets/; MongoDB driver ≥ 3.x; ORAS/OCI client where applicable.
  • Metrics under StellaOps.ExportCenter.*; tag tenant, profile, adapter, result; document new counters/histograms.
  • Logs structured, no PII; include runId, tenant, profile, adapter, correlationId; map phases (plan, resolve, adapter, manifest, sign, distribute).
  • SSE/telemetry events must be deterministic and replay-safe; backpressure aware.
  • Signing/encryption: default cosign-style KMS signing; age/AES-GCM envelopes with key wrapping; store references in provenance only (no raw keys).

Testing Rules

  • API/worker tests: StellaOps.ExportCenter.Tests with WebApplicationFactory + in-memory/Mongo2Go fixtures; assert tenant guards, RBAC, quotas, SSE timelines.
  • Adapter regression: deterministic fixtures for Trivy DB/Java DB, mirror delta/base comparison, OCI manifest generation; no network.
  • Risk bundle pipeline: tests in StellaOps.ExportCenter.RiskBundles.Tests (or add) covering bundle layout, DSSE signatures, checksum publication.
  • Determinism checks: stable ordering/hashes in manifests, provenance, and distribution descriptors; retry paths must not duplicate outputs.
  • Keep tests air-gap friendly; seeded data under seed-data/ or inline fixtures.

Delivery Discipline

  • Update sprint tracker statuses (TODO → DOING → DONE/BLOCKED) in docs/implplan/SPRINT_0164_0001_0001_exportcenter_iii.md when starting/finishing/blocking work; mirror design decisions in Decisions & Risks and Execution Log.
  • If a decision is needed (API contract, KMS envelope pattern), mark the task BLOCKED, describe the decision in sprint Decisions & Risks, and continue with other unblocked tasks.
  • When contracts or schemas change (API, manifest, provenance, adapter outputs), update module docs and link them from the sprint.
  • Retain deterministic retention/pruning behavior; document feature flags and defaults in docs/modules/export-center/operations/*.md when modified.