docs consolidation and others

docs/modules/airgap/guides/bundle-repositories.md

@@ -0,0 +1,38 @@
+# Bundle Catalog & Items Repositories (prep for AIRGAP-IMP-57-001)
+
+## Scope
+- Deterministic storage for offline bundle metadata with tenant isolation (RLS) and stable ordering.
+- Ready for PostgreSQL-backed implementation while providing in-memory deterministic reference behavior.
+
+## Schema (logical)
+- `bundle_catalog`:
+  - `tenant_id` (string, PK part, RLS partition)
+  - `bundle_id` (string, PK part)
+  - `digest` (hex string)
+  - `imported_at_utc` (datetime)
+  - `content_paths` (array of strings, sorted ordinal)
+- `bundle_items`:
+  - `tenant_id` (string, PK part, RLS partition)
+  - `bundle_id` (string, PK part)
+  - `path` (string, PK part)
+  - `digest` (hex string)
+  - `size_bytes` (long)
+
+## Implementation delivered (2025-11-20)
+- In-memory repositories enforcing tenant isolation and deterministic ordering:
+  - `InMemoryBundleCatalogRepository` (upsert + list ordered by `bundle_id`).
+  - `InMemoryBundleItemRepository` (bulk upsert + list ordered by `path`).
+- Models: `BundleCatalogEntry`, `BundleItem`.
+- Tests cover upsert overwrite semantics, tenant isolation, and deterministic ordering (`tests/AirGap/StellaOps.AirGap.Importer.Tests/InMemoryBundleRepositoriesTests.cs`).
+
+## Migration notes (for PostgreSQL backends)
+- Create compound unique indexes on (`tenant_id`, `bundle_id`) for catalog; (`tenant_id`, `bundle_id`, `path`) for items.
+- Enforce RLS by always scoping queries to `tenant_id` and validating it at repository boundary (as done in in-memory reference impl).
+- Keep paths lowercased or use ordinal comparisons to avoid locale drift; sort before persistence to preserve determinism.
+
+## Next steps
+- Implement PostgreSQL-backed repositories mirroring the deterministic behavior and indexes above.
+- Wire repositories into importer service/CLI once storage provider is selected.
+
+## Owners
+- AirGap Importer Guild.