test(satellites): per-satellite merged coverage gate + breaker/isolation hardening

Address four production-readiness concerns from a reviewer (satellite RC
honesty, admin auth, circuit breaker vs Redis, concurrency isolation). Three
were already sound; the work is tests, CI teeth, and doc reconciliation.

Concern 1 - per-satellite MERGED coverage gate. Admin's controllers are
integration-tested by design, so a unit-floor bar would be coverage theatre.
Instead:
- new scripts/check-satellite-coverage.mjs buckets the merged unit+integration
  lcov by packages/<sat>/src and gates each RC satellite against a declared
  floor (lasagnaSatellite.minMergedCoverage)
- ci.yml uploads each satellite's unit V8 into the aggregate merge and runs the
  gate (report-only first run; ratchet floors just under the measured numbers,
  then drop SATELLITE_COV_REPORT_ONLY to enforce)
- check-satellite-graduation.mjs now requires the floor declared at the bar
- stability.md + upgrade-to-1.0.md stop telling adopters to treat satellite
  packages as experimental (they are RC; in-core opt-in features stay experimental)

Concern 3 - circuit breaker survives a Redis outage. New integration spec forces
the wired Redis to reject and proves persist/restore/destroy never throw; unit
reinforcement for the no-Redis path; new resilience.md section.

Concern 4 - cross-tenant isolation under load. New ~1000-write bounded-concurrency
fuzz spec with direct-DB read-back; data-isolation/index.md concurrency section
(schema-pg scoped).

Concern 2 - admin auth docs point at the demo middleware and the empty-array
boot guard.

Local gates green (794 unit, build:all, typecheck, lint, knip, docs:build).
Integration specs are CI-only.

Author: Arcoders

.changeset/satellite-merged-coverage-gate.md

@@ -0,0 +1,17 @@
+---
+"@adonisjs-lasagna/admin": patch
+"@adonisjs-lasagna/sso": patch
+"@adonisjs-lasagna/billing": patch
+"@adonisjs-lasagna/backup": patch
+"@adonisjs-lasagna/websockets": patch
+---
+
+Add a declared per-satellite merged-coverage floor to each satellite manifest
+(`lasagnaSatellite.minMergedCoverage`) plus a CI gate
+(`scripts/check-satellite-coverage.mjs`) that enforces each satellite's MERGED
+(unit + integration) source coverage against it. This makes the `release
+candidate` label backed by a real per-package number, not just the repo-wide
+aggregate, and it respects that controller-heavy satellites (admin) are exercised
+by the integration tier rather than by unit tests. The graduation gate now also
+requires the floor to be declared at the bar. No public API or runtime behavior
+change; the manifest field is internal tooling metadata.

.github/workflows/ci.yml

@@ -109,6 +109,51 @@ jobs:
           path: coverage/.v8/unit
           if-no-files-found: warn
 
+      # Each satellite's UNIT V8 (written by its test:coverage to
+      # coverage/.v8/<sat>-unit above). The coverage-report job merges these with
+      # each satellite's integration V8 so check-satellite-coverage.mjs can gate a
+      # real per-satellite MERGED number. One flat artifact per satellite (like the
+      # integration uploads) so they extract flat into the shared temp dir.
+      - name: Upload raw satellite unit coverage (V8) — sso
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: c8-raw-sso-unit
+          path: coverage/.v8/sso-unit
+          if-no-files-found: warn
+
+      - name: Upload raw satellite unit coverage (V8) — backup
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: c8-raw-backup-unit
+          path: coverage/.v8/backup-unit
+          if-no-files-found: warn
+
+      - name: Upload raw satellite unit coverage (V8) — admin
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: c8-raw-admin-unit
+          path: coverage/.v8/admin-unit
+          if-no-files-found: warn
+
+      - name: Upload raw satellite unit coverage (V8) — billing
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: c8-raw-billing-unit
+          path: coverage/.v8/billing-unit
+          if-no-files-found: warn
+
+      - name: Upload raw satellite unit coverage (V8) — websockets
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: c8-raw-websockets-unit
+          path: coverage/.v8/websockets-unit
+          if-no-files-found: warn
+
       # Full report (unused exports / orphaned files / deps) stays informational.
       - name: Knip (unused-code report)
         run: npm run knip
@@ -791,6 +836,40 @@ jobs:
           name: c8-raw-billing-integration
           path: coverage/.v8/all
 
+      # Satellite UNIT V8, merged into the same temp dir so each satellite's
+      # MERGED (unit+integration) src coverage is what check-satellite-coverage.mjs
+      # gates below. websockets has no integration tier here (it runs in the WS e2e
+      # job without coverage), so its merged number is unit-only (see the gate).
+      - name: Download raw satellite unit coverage (V8) — sso
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: c8-raw-sso-unit
+          path: coverage/.v8/all
+
+      - name: Download raw satellite unit coverage (V8) — backup
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: c8-raw-backup-unit
+          path: coverage/.v8/all
+
+      - name: Download raw satellite unit coverage (V8) — admin
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: c8-raw-admin-unit
+          path: coverage/.v8/all
+
+      - name: Download raw satellite unit coverage (V8) — billing
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: c8-raw-billing-unit
+          path: coverage/.v8/all
+
+      - name: Download raw satellite unit coverage (V8) — websockets
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: c8-raw-websockets-unit
+          path: coverage/.v8/all
+
       - name: Aggregate coverage report (unit + integration, remapped to src)
         run: npm run coverage:report
 
@@ -808,12 +887,33 @@ jobs:
         # pure-helper extraction added functions the integration tier only
         # partially exercises, so its floor stays at 78. Keep a small margin
         # under the measured numbers and re-check a real run before ratcheting.
+        # NOTE: these numbers predate the per-satellite gate work, which also
+        # merges each satellite's UNIT V8 into this lcov (including websockets
+        # src, new to the aggregate). The shift is expected to be small and
+        # net-positive, but re-measure on the next full run before ratcheting.
         env:
           COV_MIN_LINES: '81' # measured ~82.7%
           COV_MIN_FUNCTIONS: '78' # measured ~78.9%
           COV_MIN_BRANCHES: '78' # measured ~78.5%
         run: node scripts/coverage-gate.mjs coverage/lcov.info
 
+      # Per-satellite MERGED coverage gate: buckets coverage/lcov.info by
+      # packages/<sat>/src and checks each RC satellite against the floor it
+      # declares in package.json (lasagnaSatellite.minMergedCoverage). This is
+      # the honest "is this satellite RC-worthy" number, because it counts the
+      # integration tier, which is where controller-heavy satellites (admin) are
+      # actually exercised.
+      #
+      # FIRST RUN IS REPORT-ONLY (SATELLITE_COV_REPORT_ONLY=1): the floors above
+      # are conservative placeholders. Read the printed per-satellite numbers from
+      # this step, ratchet each satellite's minMergedCoverage just under its
+      # measured actual (lines stays >= 60, the graduation bar), then DELETE the
+      # env line below to flip this into an enforcing gate.
+      - name: Per-satellite merged coverage gate
+        env:
+          SATELLITE_COV_REPORT_ONLY: '1'
+        run: node scripts/check-satellite-coverage.mjs coverage/lcov.info
+
       - name: Upload combined coverage
         if: always()
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4

docs/docs/data-isolation/index.md

@@ -68,6 +68,35 @@ flowchart TB
   end
 ```
 
+## Why isolation holds under concurrency
+
+A fair worry with multitenancy is whether two tenants hammering the server at
+once can ever cross over. For the default `schema-pg` driver, three properties
+make that structurally impossible, not merely unlikely:
+
+- **One pool per tenant, `searchPath` baked into the connection config.** Each
+  tenant's `tenant_<uuid>` connection is created with its schema already set as
+  the `searchPath`. The package never runs a shared `SET search_path` on a pooled
+  connection, so there is no per-query mutation for a concurrent request to race.
+- **Pools are keyed by `tenant_<uuid>`.** A query for tenant A can only draw a
+  connection from tenant A's pool, so a warm pool for B can never serve A's query.
+- **`AsyncLocalStorage` keeps `tenancy.currentId()` accurate across `await`.**
+  Interleaved `await` points and `Promise.all` fan-out do not bleed one request's
+  tenant context into another.
+
+This is backed by tests, not just argument: a 16-way parallel `tenancy.run()`
+scope test proves the context never bleeds, the cross-tenant e2e fires 100
+interleaved HTTP writes across 5 tenants with a direct-DB read-back, and a fuzz
+spec scales that to roughly 1000 interleaved writes across 10 tenants. Every one
+asserts that a tenant's schema holds only its own rows.
+
+This argument is specific to `schema-pg` (and `database-pg`, which goes further
+with a whole database per tenant). The `rowscope-pg` driver is different by
+design: it shares one connection and scopes every query by a `tenant_id` filter
+(with an optional RLS backstop), so its isolation rests on the query-scoping
+mixin rather than on per-tenant pools. See
+[rowscope-pg](/docs/data-isolation/rowscope-pg).
+
 ## Choosing a driver
 
 - **Strict isolation, easy backups, easy per-tenant restore** →

docs/docs/resilience.md

@@ -77,6 +77,42 @@ right default for availability, but it is invisible unless you subscribe to
 `DependencyDegraded`. Choose `fail-closed` where correctness beats uptime.
 :::
 
+## The tenant circuit breaker
+
+The per-tenant circuit breaker is a separate mechanism from the dependency
+policies above, and it answers a common production worry directly: **a Redis
+outage cannot take it down.**
+
+The decision is in-memory and per-tenant. Each tenant gets its own in-process
+opossum breaker that trips on real `SELECT 1` probes against *that tenant's*
+database connection. When a tenant's DB starts failing, its breaker opens and the
+tenant fails fast (no more 5-second-timeout probes) while every healthy tenant is
+untouched. Redis is **not** in this decision path.
+
+Redis is used for one thing only: a best-effort cache of the OPEN state across
+process restarts, so a tenant whose DB was down stays OPEN through a deploy
+instead of re-learning it from scratch. Every read and write of that cache is
+wrapped in a try/catch that logs a warning and carries on. So when Redis is
+unavailable:
+
+- The breaker keeps working entirely from memory. It does not fail open, and it
+  does not fail closed.
+- Persisting a state change (open, close, half-open) logs a warning and moves on.
+- Restoring on startup logs a warning and the breaker simply starts CLOSED, then
+  re-learns the tenant's health from its next probe.
+
+The only degraded case is narrow: if the process restarts *during* a Redis
+outage, the persisted OPEN state is lost, so the first request to that tenant
+pays one bounded `circuitBreaker.resetTimeout` before the breaker re-trips. That
+is the same bounded delay described in
+[circuit breaker reopens after a restart](/docs/gotchas#circuit-breaker-reopens-after-a-restart),
+and it is deliberate.
+
+The path is covered end to end: a unit test asserts the full open/reset/destroy
+cycle never throws with no Redis bound, and an integration test forces the wired
+Redis to reject every command and proves the breaker still opens, resets, and
+restores without throwing.
+
 ## The exception
 
 A `fail-closed` dependency throws `DependencyUnavailableException` instead of a

docs/docs/satellites/admin-rest-api.md

@@ -28,6 +28,18 @@ curl -H "Authorization: Bearer $TOKEN" \
   https://app.example.com/admin/multitenancy/tenants
 ```
 
+For a concrete starting point, the demo app ships a minimal example at
+`examples/api/app/middleware/demo_admin_auth_middleware.ts` (a header check
+against an env token). Treat it as an illustration of *where* the guard goes, not
+a production auth primitive: swap it for your real session, bearer, or mTLS check.
+
+One footgun the boot guard closes for you: a pattern like
+`middleware: authEnabled ? [adminAuth] : []` would, when the flag is off, mount
+the destructive routes public while *looking* guarded. The startup check rejects
+an empty middleware array the same way it rejects an omitted one, so "looks
+guarded but is public" cannot happen. Going public is only possible by writing
+`middleware: false` on purpose.
+
 ### CSRF
 
 The admin API does **not** apply CSRF protection itself. If you mount it behind a

docs/docs/stability.md

@@ -88,7 +88,7 @@ The isolation substrate. Everything here is **release candidate** unless noted.
 | Tenant resolution (subdomain / path / header) | Release candidate | Always via `resolveTenantId()`. |
 | `TenantAdapter` + base-model routing | Release candidate | |
 | Connection LRU, budget, optional hard cap | Release candidate | `enforceConnectionCap` defaults `false`; see [scaling limits](/docs/scaling-limits). |
-| Circuit breaker | Release candidate | OPEN state restored from Redis across restarts. |
+| Circuit breaker | Release candidate | In-memory and per-tenant; survives a Redis outage. See [resilience](/docs/resilience#the-tenant-circuit-breaker). |
 | Dependency resilience (`ResilienceService`, 503 fail-closed) | Release candidate | A resolved tenant whose DB is down returns a typed 503, never central. |
 | Contextual logging (`AsyncLocalStorage`) | Release candidate | |
 | Tenant lifecycle (provision / migrate), hooks, lifecycle events | Release candidate | |
@@ -119,25 +119,40 @@ satellite is published as `>=1.0.0`, so the version string a consumer reads off
 npm matches the semver promise this page makes. CI enforces the agreement
 mechanically: `scripts/check-stability-versions.mjs` parses this page, and
 `scripts/check-satellite-graduation.mjs` verifies each satellite meets the
-graduation gate (coverage gate, manifest, configure hook, CHANGELOG, doc page,
-version) before it can carry the `release candidate` label.
+graduation gate (coverage gate, merged-coverage floor, manifest, configure hook,
+CHANGELOG, doc page, version) before it can carry the `release candidate` label.
 
 Each satellite cleared the same graduation bar: an own coverage gate
-(`.c8rc.json`) with unit tests over its security-critical core, an
+(`.c8rc.json`) with unit tests over its security-critical core, a declared
+per-satellite **merged** (unit + integration) coverage floor enforced in CI
+(`scripts/check-satellite-coverage.mjs`), so a controller-heavy satellite whose
+handlers are exercised by the integration tier is still held to a real number; an
 auto-describable `lasagnaSatellite` manifest at the frozen Satellite ABI
 (`satelliteApi: 1`), green `publint` + `arethetypeswrong`, a doc page, and a
 CHANGELOG. As with the core, `release candidate` (not `stable`) reflects the two
 still-open items: an independent security review and production mileage.
 
+**What graduates an in-core opt-in feature to `release candidate`?** The same
+bar, scoped to a feature rather than a package: its own coverage at the
+graduation floor, a doc page, a stable public surface, and a CHANGELOG entry. The
+opt-in features listed above (quotas, webhooks, metrics, audit logs, branding,
+feature flags, impersonation) stay `experimental` until they clear it.
+
 ## How to read this if you are adopting
 
 - Want true tenant isolation and nothing else? You are on `release-candidate`
   ground: the core. Pin the version, follow the [deployment](/docs/deployment)
   and [security](/security) guides, and you are leaning only on what is tested
   and gated in CI.
-- Reaching for a satellite (billing, SSO, admin, backup, quotas, webhooks, and
-  the rest)? Treat it as `experimental`: it works and is covered by tests, but
-  pin the version and read the changelog before each upgrade.
+- Reaching for a satellite *package* (billing, SSO, admin, backup, websockets)?
+  You are on `release-candidate` ground too: each cleared the graduation gate
+  above (frozen Satellite ABI, its own merged coverage floor, doc page, and
+  CHANGELOG). Pin the version and read the changelog before each upgrade, the
+  same as the core.
+- Using an in-core opt-in feature (quotas, webhooks, metrics, audit logs,
+  branding, feature flags, impersonation)? Those are still `experimental`: they
+  work and are covered by tests, but they are not under the 1.x semver promise,
+  so pin the version and read the changelog before each upgrade.
 - Watch this page. As the security review and production mileage close, the core
   moves to `stable` and the matrix is updated in the same change.
 

docs/docs/upgrade-to-1.0.md

@@ -26,13 +26,16 @@ the only thing to check is the resolver default at the end.
 
 1.0 narrows its promise on purpose. The isolation **core** is a release
 candidate: feature complete and green in CI, with the `stable` label withheld
-until an independent security review and production mileage close. The satellites
-(billing, SSO, the admin REST API, backup, and the opt-in in-core features like
-quotas, webhooks, and metrics) are **experimental** and are not covered by the
-1.x semver promise, so they may change in a minor release. The full breakdown and
-the per-tier rules are in the [stability matrix](/docs/stability). Pin your
-versions accordingly and check the changelog before upgrading an experimental
-surface.
+until an independent security review and production mileage close. The satellite
+**packages** (billing, SSO, the admin REST API, backup, websockets) are release
+candidates too: each cleared the same graduation gate as the core (frozen
+Satellite ABI, its own merged coverage floor, doc page, CHANGELOG), so they sit
+under the 1.x semver promise. The opt-in **in-core features** (quotas, webhooks,
+metrics, audit logs, branding, feature flags, impersonation) are still
+**experimental** and are not covered by that promise, so they may change in a
+minor release. The full breakdown and the per-tier rules are in the
+[stability matrix](/docs/stability). Pin your versions accordingly and check the
+changelog before upgrading an experimental surface.
 
 ## 1. Install the satellites you use
 

packages/admin/package.json

@@ -41,6 +41,7 @@
   "lasagnaSatellite": {
     "name": "admin",
     "satelliteApi": 1,
+    "minMergedCoverage": { "lines": 60, "functions": 50, "branches": 50 },
     "aliases": ["admin"],
     "install": [
       "npm install @adonisjs-lasagna/admin"

packages/backup/package.json

@@ -53,6 +53,7 @@
   "lasagnaSatellite": {
     "name": "backup",
     "satelliteApi": 1,
+    "minMergedCoverage": { "lines": 60, "functions": 50, "branches": 50 },
     "aliases": ["backup"],
     "provider": "@adonisjs-lasagna/backup/provider",
     "commands": "@adonisjs-lasagna/backup/commands",

packages/billing/package.json

@@ -56,6 +56,7 @@
   "lasagnaSatellite": {
     "name": "billing",
     "satelliteApi": 1,
+    "minMergedCoverage": { "lines": 60, "functions": 50, "branches": 50 },
     "aliases": ["billing"],
     "migrations": "stubs/migrations",
     "requires": ["quotas"],