save progress

src/AirGap/__Libraries/StellaOps.AirGap.Bundle/AGENTS.md

@@ -0,0 +1,73 @@
+# AirGap Bundle Agent Charter
+
+## Mission
+- Provide bundle format, parsing, building, and signing for air-gapped deployments.
+- Enable creation and consumption of offline knowledge snapshot bundles.
+
+## Responsibilities
+- Maintain bundle format schemas and models (`BundleManifest`, `KnowledgeSnapshotManifest`).
+- Implement bundle building (`BundleBuilder`), loading (`BundleLoader`), and reading/writing (`SnapshotBundleReader/Writer`).
+- Provide manifest signing (`SnapshotManifestSigner`) with DSSE/TUF verification support.
+- Implement import targets for Concelier advisories, Excititor VEX, and policy registry.
+- Ensure bundle operations are deterministic and verifiable.
+
+## Required Reading
+- docs/README.md
+- docs/07_HIGH_LEVEL_ARCHITECTURE.md
+- docs/modules/platform/architecture-overview.md
+- docs/modules/airgap/architecture.md
+- src/AirGap/AGENTS.md (parent module charter)
+- docs/24_OFFLINE_KIT.md
+
+## Working Directory & Scope
+- Primary: src/AirGap/__Libraries/StellaOps.AirGap.Bundle/
+- Dependencies: StellaOps.AirGap.Persistence, StellaOps.Cryptography
+- Coordinates with: AirGap.Importer (consumes bundles), AirGap.Controller (seal state)
+
+## Key Components
+### Models/
+- `BundleManifest.cs` — Top-level bundle metadata and entry list
+- `KnowledgeSnapshotManifest.cs` — Snapshot-specific manifest with digest references
+
+### Services/
+- `BundleBuilder.cs` — Creates bundles from source data with manifest generation
+- `BundleLoader.cs` — Loads and validates existing bundles
+- `SnapshotBundleReader.cs` — Streaming reader for bundle contents
+- `SnapshotBundleWriter.cs` — Streaming writer for bundle creation
+- `SnapshotManifestSigner.cs` — DSSE signing of manifests
+- `TimeAnchorService.cs` — Time anchor integration for staleness tracking
+- `KnowledgeSnapshotImporter.cs` — Orchestrates snapshot import
+
+### Import Targets/
+- `ConcelierAdvisoryImportTarget.cs` — Advisory data import
+- `ExcititorVexImportTarget.cs` — VEX statement import
+- `PolicyRegistryImportTarget.cs` — Policy bundle import
+
+### Extractors/
+- Archive extraction utilities for bundle contents
+
+### Schemas/
+- JSON schema definitions for bundle formats
+
+### Validation/
+- Bundle format and content validators
+
+### Serialization/
+- Bundle serialization/deserialization helpers
+
+## Testing Expectations
+- Unit tests in `__Libraries/__Tests/StellaOps.AirGap.Bundle.Tests/`
+- Test bundle round-trips (build -> serialize -> load -> verify)
+- Verify manifest signing and verification with test keys
+- Test import targets with fixture data
+- Ensure deterministic ordering in manifests and archives
+- Test extraction with malformed/tampered data for security
+
+## Working Agreement
+- Determinism: stable manifest ordering, content-addressed digests, reproducible archives.
+- Offline-friendly: no network calls; all data comes from local bundle files.
+- Security: mandatory signature verification; reject tampered bundles.
+- Schema stability: bundle format changes require versioning and migration support.
+- Observability: structured logs for bundle operations, import metrics.
+- Update sprint status in docs/implplan/SPRINT_*.md when starting/completing work.
+- Mirror decisions in sprint Decisions & Risks section.