ADR-039 — Database-per-service ownership and the consolidated Vulnerabilities service

Status: Accepted (revision 12, 2026-07-23 — owner rulings on the round-20 architecture review: D13 amended — KEV returns to Tier 0 (owner: “don’t accept loss; we seek to be the best one” — exploit evidence becomes a first-class hub signal family served via hub API/events/artifact; program SPRINT_20260723_003); DC-06/07 amended (stream_epoch in the event envelope — producer restore/rebuild no longer silently freezes consumers); DC-36 replayability = derive- on-demand over the hub’s own raw documents + revision history (owner: replay reproduces via the API; no archival of replayed artifacts); DC-37 estate restore doctrine (restore classes + epoch-driven convergence + restore drills); DC-38 one consensus-evaluator library fed by the sectioned corpus artifact + local overlays; DC-39 contract-version discipline at the artifact and plugin seams; P17 Platform charter (domain-agnostic, no domain nouns); P18 service-birth criteria (the consolidation criteria apply in reverse to any new deployable). Rev-11 record — DC-33: BinaryIndex’s knowledge plane dissolves into the hub (owner-initiated; no stellaops_binaryindex; Symbols = hub-adjacent CAS); DC-34: SbomService = the SBOM system of record (absorbs vuln.sbom_registry + Scanner’s SBOM registry; blobs → object store). Rev-10 record — owner reconfirmed the migration hard rule (P4 sharpened: every microservice carries and applies its own migrations; no central mechanism of any kind); adds DC-29 one-outbox-lineage (evolve StellaOps.Eventing, which already ships an outbox — currently homed in the shared DB’s timeline schema, register X17) . Rev-9 record — adds P16 non-PostgreSQL state ownership (Valkey keyspaces/streams + object-store buckets follow the same owner/budget rules — DC-27/DC-28) and extends DC-26 to the central migrator’s runtime faces (Platform’s migration admin API + /api/v1/admin/seed-demo, the CLI’s manual migration applier). Rev-8 record — owner approved the OfflineKit unification (EVL-3 → program 025: ExportCenter + Mirror.Creator + AirGap Importer/Bundle/Sync → StellaOps.OfflineKit / stellaops_offlinekit; sealed-mode posture + time anchor → Platform; airgap-controller/airgap-time deployables retire; replay stays separate). Rev-7 record — adds P15 decision-time independence and binds the design-challenges register (DC-01…DC-20) as binding design input for all programs. Rev-6 record — owner correction: the platform database keeps its name stellaops_platform; the bare stellaops name applies at the container/instance level (executed in SPRINT_20260722_021 PLT-2). Owner approved the evaluation outcomes: Evidence merge (011 widened to Attestor+TSA+tileproxy+EvidenceLocker → stellaops_evidence; Signer stays out), Graph+ReachGraph merge (023 → stellaops_graph; signals separate), registry→Integrations (024, availability-isolated role), doctor-web retirement (009 DOC-5), remediation archive (dormant, evidence-backed), export→hub rejected. AirGap: investigation confirmed a posture/exchange mixture — split proposal (posture→Platform; Importer+Mirror.Creator+ExportCenter → StellaOps.OfflineKit) pending owner confirmation in 022 EVL-3; see service-consolidation-review.md §2.3. Rev-4 record: owner review round 3 approved D1–D14 with instructions: D1 hub database stellaops_vuln; D2 rebuild-from-scratch default with agent-judged mechanical shortcuts; D3 owner/refactor-source named explicitly; D6 “do it the right way”; D8 100 GB available + old plane deleted before re-ingest; D11 registry-based doctor architecture; D14 one program per merge. The hard rule is codified in CODE_OF_CONDUCT.md §8.2 and AGENTS.md §2.7. Runtime/destructive actions still require their named execution windows per sprint.) Deciders: Owner (V. Moushkov, reviews of 2026-07-22) + Architecture Evidence: vulnerability-data-plane-separation-investigation.md, database-ownership-matrix.md, vulnerability-data-plane-v2-design.md

Context

For the third time in three months a vulnerability corpus has expanded inside the physical stellaops_platform database (May: 306 GB, June: 420 GB, July: 91 GB and growing). Live measurements on 2026-07-22:

• stellaops_platform is 91 GB; the platform schema itself is 2,024 kB (0.002%).
• The vulnerability plane (vuln 71 GB + vex 9.6 GB + vexhub 5.9 GB + concelier 2.3 GB) is ~89 GB — 97.8% of the database. Raw source documents are only ~6 GB of that; the rest is multiplied derived copies and their indexes.
• ~46 service schemas from ~35 deployables share one database via a single STELLAOPS_POSTGRES_CONNECTION. Only Authority has its own database — proving the per-service pattern already works here.
• The three “vulnerability” deployables (Concelier, Excititor web+worker, VexHub) write into each other’s schemas (Excititor deletes Concelier’s vuln.issue_*; Excititor writes VexHub’s vexhub.statements) — they were never really independent services.

Owner review (2026-07-22) resolved the direction: these are one domain and should be one service with one database, focused on being the raw + normalized vulnerability knowledge hub; per-tenant decision projections belong to the control plane; existing corpus data is disposable because connectors and mirror bundles can restore it from sources.

Decision (policy)

P1 — One physical database and role per independently deployable microservice

Every independently deployable microservice owns its own physical PostgreSQL database and a dedicated role. Web/worker replicas (and init jobs) of the same microservice share that owner database. Independent microservices never share domain tables. Schema-per-service inside a shared database is explicitly not compliant. Where two “services” cannot avoid sharing domain tables, that is the signal they are one service and must be consolidated (as applied to Vulnerabilities in D2).

This is a HARD RULE, codified in docs/code-of-conduct/CODE_OF_CONDUCT.md §8.2 and AGENTS.md §2.7 (2026-07-22). Root cause of the original miss: those documents themselves said a service “owns a PostgreSQL schema” — the contract legitimized schema-level ownership, so every agent complied with the letter while ~46 schemas shared one database. The boundary is the database; the wording is fixed at the source.

P2 — Naming and connection contract

• Database: stellaops_<service>; role: stellaops_<service> (owner of its database only). Owner-directed exceptions: the Platform control-plane database keeps its current name stellaops_platform(owner correction 2026-07-22 — no DB rename); the vulnerability hub is stellaops_vuln. The bare stellaops name applies at the container/instance level and is aligned at endgame (SPRINT_20260722_021 PLT-2).
• Connection env var: STELLAOPS_POSTGRES_<SERVICE>_CONNECTION (hub: STELLAOPS_POSTGRES_VULN_CONNECTION; precedent: STELLAOPS_POSTGRES_AUTHORITY_CONNECTION).
• Persistence naming standard: every data-access/migration project is StellaOps.<Service>.Persistence (one per service, embedded Migrations/**/*.sql). Existing deviations (Concelier.Storage, Scanner.Storage, …Database, split DAL projects) are renamed as their service’s wave lands.

P3 — No shared-connection fallback (fail closed)

A service whose owner connection is missing MUST fail to start with an explicit error. Falling back to STELLAOPS_POSTGRES_CONNECTION is forbidden. After all waves complete the generic variable is retired and Platform uses STELLAOPS_POSTGRES_PLATFORM_CONNECTION.

P4 — Migration ownership (HARD RULE — owner reconfirmed 2026-07-23)

Every microservice carries its own migrations — embedded in its own (or its hosted libraries’) assemblies, applied by its own startup, against its own database, and nowhere else. No central mechanism of any kind is compliant: not a plugin file (X15), not an admin API, not a CLI applier — all three exist today and all three retire (SPRINT_20260722_026 + DC-26). Platform never migrates another service’s schema. Shared persistence libraries (Cryptography.CredentialStore → crypto, Verdict, Plugin.Registry, Eventing, Artifact.Infrastructure, scheduler client) ship their migrations inside the library, and the hosting service embeds and applies them into its own database — that is what “carries its own migrations” means for shared code.

P5 — Cross-service data access

Allowed mechanisms, in order of preference: (1) the owning service’s API; (2) transactional outbox → ordered events → idempotent inbox + durable checkpoint, applied by a single leased writer with a fencing token per stream; (3) a time-boxed entry on the approved read-contract register (matrix §3). Anything else — and any cross-service write or delete — is a defect. Cross-service SQL JOINs die by construction once databases separate.

P6 — Outbox/inbox/checkpoint/lease standard

One shared implementation (extending StellaOps.Infrastructure.Postgres) provides: outbox appended in the same source transaction as the fact write; inbox/checkpoint advanced in the same destination transaction as the applied change; renewable lease with fencing token; content-guarded (logically and physically idempotent) upserts; source generation + completion markers so absence is only tombstoned after a completed generation. Age-only retention of currently applicable facts is forbidden.

P7 — Capacity budgets and metrics on every write path

Every data plane declares per-database budgets (bytes, rows, WAL/batch) enforced by a shared capacity contract governing all of its write paths — not a guard on one writer. Alarms and writer-pause trip before the safety floor with an operator-visible reason.

P8 — Cluster topology

The harm vector in all three incidents was volume exhaustion; a dedicated cluster+volume is the only boundary in a Docker estate that caps blast radius. Tablespaces inside one containerized instance are rejected.

P9 — Backup/restore boundaries

Backups are per-database. The vulnerability hub’s primary recovery story is re-ingestion from sources and mirror bundles (D7); control-plane databases keep conventional backup/restore. Rollback remains forward-only per ADR-004.

P10 — Enforcement

Architecture conformance tests (src/__Tests/architecture/…): (a) every WebService resolves only its own connection key; (b) no non-Platform source references STELLAOPS_POSTGRES_CONNECTION beyond the pinned register; © compose lint maps each service to its own database; (d) persistence projects follow the P2 naming standard. Role grants make cross-owner writes fail in integration tests.

P11 — Doctor is a plugin model with a platform capability registry

Health/diagnostic checks execute inside the service they check, via a doctor plugin hosted by that service (using the existing plugin SDK), surfaced over the service’s own API. Owner-directed architecture (D11, three phases): (1) doctor base library + plugin contract first; (2) a registration surface on Platform where every microservice with one or more doctor functions registers them (capability catalog: service, check id, category, endpoint), so discovery is dynamic, not config; (3) current consumers of the central Doctor (Console pages, ops runbooks, doctor CLI) are rerouted to the per-service endpoints via that registry. The Doctor service aggregates via registry + APIs only — no cross-database connections, no knowledge of foreign schemas; the Doctor.Plugins.Database probe-everything pattern is retired (matrix X10). Program: SPRINT_20260722_009.

P13 — Anti-bloat data-modeling rules (all new schemas, estate-wide)

Every table declares a retention class (source-of-truth / derived-rebuildable / append-audit partitioned with a window / cache-bounded); no second full representation of a semantic fact; verbose payloads separated from hot rows; every index justified by a named reader (index bytes > heap bytes needs a recorded reason); per-database budgets with a doctor-plugin size check; physically idempotent writers (content-guarded upserts, never unconditional DO UPDATE). Details and enforcement: service-consolidation-review.md §4.

P14 — Domain-homing rule

Data lives with its domain, not with its consumer. A service may hold another domain’s data only as a declared, rebuildable projection. (Live violation this rule retires: ~2.05 GB of EPSS — per-CVE vulnerability data — homed in the scanner schema because Scanner consumes it; it relocates to the Vulnerabilities hub.)

P16 — Non-PostgreSQL state follows the same ownership rules

Databases are not the only shared state. Valkey keyspaces/streams and object-store buckets/ prefixes have named owners, a prefix convention, and P7 budgets — the original harm vector was disk exhaustion, and object stores/queues can reproduce it unpoliced. Every service’s keys/streams live under its own prefix ({service}: keys; the existing stream:{name} convention); every object-store bucket/prefix appears in the ownership matrix with its owner and budget; the doctor standard checks include cache/bucket size against budget. Cross-service consumption of another owner’s stream is a contract (DC-06/07 envelope), never ad-hoc key reads. Details: DC-27, DC-28.

P15 — Decision-time independence (release gates never wait on the data plane)

Release decisions read only control-plane state. Policy’s gate evaluation consumes its own projections (fed asynchronously by hub events); no gate-time code path performs a synchronous call or query into the vulndata cluster. A vulndata outage therefore degrades freshness (verdicts carry a staleness/corpus_state annotation per DC-09), never availability of release decisions. Enforced by conformance (Policy holds no vulndata-cluster connection) and a chaos test (stop the vulndata cluster → gates keep deciding). Full rationale: DC-11.

P12 — The vulnerability hub is tenant-free

stellaops_vulnerabilities holds global knowledge only: raw and normalized vulnerability/VEX/ distro data, provenance, and global consensus. Anything tenant-scoped (effective per-tenant decisions, overlays, acceptances, local VEX) lives in control-plane services. This keeps the hub rebuildable-from-sources by definition and removes tenancy/RLS complexity from the largest data plane.

P17 — Platform charter (rev-12)

Platform is the estate’s domain-agnostic control plane: estate settings, sealed-mode posture state, capability/actor catalogs, console bootstrap. It owns no domain nouns (vulnerabilities, findings, evidence, scans, releases, jobs, notifications, SBOMs…). Anything carrying a domain noun or a domain write-path belongs to a domain service or a shared library. Adding a Platform responsibility requires an ADR-039 amendment arguing why it is estate posture rather than domain logic. Enforcement: review gate + a conformance lint for domain nouns in Platform schemas/APIs. Rationale: posture (025), the capability registry (009), and the actor-identity catalog (027) are each individually justified — this charter keeps the sum bounded so Platform never regrows into the god-service whose database this program just emptied.

P18 — Service-birth criteria (rev-12)

The consolidation criteria (review §1) apply in reverse: a new independently deployable service (and database) requires the §1 walkthrough in writing (domain language, shared tables, scaling profile; the keep-separate tests: security boundary, blast radius, optional shipping) plus an ADR-039 amendment adding it to the topology and the ownership matrix. No deployable enters compose without its matrix row, owner database, and P4 migrations. Rationale: the estate consolidated once from ~44 deployables; without a birth gate the count silently creeps back over the decade.

Decisions (VDPS-D1 … VDPS-D14)

Program structure (many sprints, deliberately)

Consequences

• One strong service boundary replaces three blurry ones; the hub’s contract (connector plugins in, mirror bundles in/out, lookup APIs out, events out) is explicit and tenant-free.
• The vulnerability corpus can at worst exhaust its own volume; Platform is untouchable by it.
• Rebuild-from-sources becomes the tested recovery path (the same machinery air-gapped estates use), which is a stronger guarantee than backups of derived state.
• Cost: the D2 rename is a large mechanical change with known plugin/embedded-resource traps, and re-ingest duration (days) makes connector health a hard dependency.

References

• Investigation & live evidence: docs/architecture/vulnerability-data-plane-separation-investigation.md
• Ownership matrix & register: docs/architecture/database-ownership-matrix.md
• Hub design, ERD, budget, test plan: docs/architecture/vulnerability-data-plane-v2-design.md
• ADR-004 forward-only migrations; ADR-010 shared tenant resolver (superseded by D10 when accepted); §2.7/§2.11 of AGENTS.md