up

src/__Libraries/StellaOps.Infrastructure.Postgres/AGENTS.md

@@ -0,0 +1,32 @@
+# StellaOps.Infrastructure.Postgres — AGENTS
+
+## Roles
+- Backend engineer: maintain the shared PostgreSQL infrastructure primitives (DataSourceBase, RepositoryBase, MigrationRunner, options/DI helpers).
+- QA automation: own Postgres Testcontainers coverage, tenant-context/RLS checks, and migration idempotency tests.
+- DevOps liaison: keep provisioning values in `ops/devops/postgres` aligned with library defaults (timeouts, schema names, TLS, pooling).
+
+## Required Reading
+- docs/db/README.md, SPECIFICATION.md, RULES.md, VERIFICATION.md, CONVERSION_PLAN.md
+- docs/modules/platform/architecture-overview.md
+- docs/airgap/airgap-mode.md
+- ops/devops/AGENTS.md (DevOps working agreement)
+
+## Working Directory & Scope
+- Primary: `src/__Libraries/StellaOps.Infrastructure.Postgres`
+- Allowed shared libs/tests: `src/__Libraries/StellaOps.Infrastructure.Postgres.Testing`, `src/__Libraries/__Tests/StellaOps.Infrastructure.Postgres.Tests`
+- Cross-module storage projects may reference this library but edits to them must be recorded in the owning sprint before touching.
+
+## Determinism & Guardrails
+- Target runtime: .NET 10, Npgsql 9.x; keep options defaults deterministic (UTC timezone, statement timeout, stable pagination ordering).
+- Tenant context must be set via `set_config('app.current_tenant', ...)` on every connection before use; never bypass DataSourceBase.
+- Migrations ship as embedded resources; MigrationRunner uses SHA256 checksums and `RunFromAssemblyAsync`—do not execute ad-hoc SQL outside tracked migrations.
+- Respect air-gap posture: no external downloads at runtime; pin Postgres/Testcontainers images (`postgres:16-alpine` or later) in tests.
+
+## Testing Expectations
+- Integration tests run with Testcontainers; Docker is required locally. Command: `dotnet test src/__Libraries/__Tests/StellaOps.Infrastructure.Postgres.Tests -c Release`.
+- Tests must isolate state per class (unique schema names) and clean up via transactions or schema drops.
+- Treat analyzer warnings as errors; ensure nullable enabled and `LangVersion` follows repo default.
+
+## Handoff Notes
+- Align configuration defaults with the provisioning values under `ops/devops/postgres` (ports, pool sizes, SSL/TLS).
+- Update this AGENTS file whenever connection/session rules or provisioning defaults change; record updates in the sprint Execution Log.