# DBAOps Sovereign™ — Engineering Handoff Manual vs Codebase (Status)

**Manual version referenced:** 1.0 (May 2026, RHOYLLE INNOVATION EMPIRE LLC)  
**This status doc version:** 1.1 — *reconciles the directive with the repository as implemented; update on every major merge.*

**Legend:** ✅ done (or largely present) · ⚠️ partial / prototype · ❌ not started / materially incomplete

---

## DEPLOY-RUNBOOK (operational pre-flight)

**This section is an operational pre-flight list.** Passing automation exercises these steps on a given revision; it does not replace change control, security review, or tenant-specific validation.

| Step | Command / probe |
|------|-------------------|
| Local verification (default) | From repo root: `npm run verify:deploy` — syntax check + API Jest suite |
| Optional SQL reachability (needs `SOVEREIGN_DB_CONNECTION`) | `VERIFY_DEPLOY_MIGRATE_CHECK=true npm run verify:deploy` — runs `migrate --check-only` (SELECT 1 + `ctl.Servers` probe, no DDL) |
| Optional live smoke | Start API, then `VERIFY_DEPLOY_LIVE_API=http://127.0.0.1:3041 npm run verify:deploy` |
| Command Center all zeros | If `/api/overview` returns `instances: 0` and `warnings: []`, the fleet table (`ctl.Servers`) is empty — expected after a fresh migrate until you register instances; `SOVEREIGN_USE_MOCK_DATA=true` serves a seeded demo fleet instead. |
| Optional static UI build | `VERIFY_DEPLOY_WEB_BUILD=true npm run verify:deploy` |
| Production runtime | `NODE_ENV=production`, `JWT_SECRET`, `SOVEREIGN_REQUIRE_AUTH` **omit or `true`** (`false` exits — fail-closed vs open API), `SOVEREIGN_DB_CONNECTION`, `GET /api/health/ready` with `SOVEREIGN_REQUIRE_DATABASE=true` for orchestrators |

**References:** full customer-facing environment table in **`docs/CUSTOMER-DEPLOYMENT.md`**; Docker templates **`docker-compose.yml`**, **`docker-compose.all-in-one.yml`**, **`docker/Dockerfile.api`**. Pilot compose defaults to `NODE_ENV=development` so evaluation works without secrets; production parity requires explicit env (see compose comments).

---

## Executive answer: are the manual items “fully done”?

**No.** The product is a strong **working platform** (API surface, licensing engine, multi-industry packs, Simulator v1, Board Room embeds, operations UI). The manual describes a **full enterprise compliance platform** (signed license manifest on every request, zero unauthenticated reads, full policy catalog & resolver, HA leader election, Merkle audit proofs, Power BI AppSource packs, ONNX predictive v1 with backtesting, 20 Simulator scenarios + synthetic telemetry, CI enforcement of gates). **Most of §3–§12 remains roadmap work.**

Use this file as the **living gap register**. When you finish a subsection, flip ✅ and link the PR.

---

## §2 Commitments vs code today

| Commitment | Status | Notes |
|------------|--------|--------|
| Absolute data sovereignty | ⚠️ | No default telemetry phone-home module in app path; validate air-gap with a formal **automated outbound test** (manual §12.3 #76). |
| Truthfulness of every metric | ⚠️ | Operations summary exposes `meta.sourceRows`, `hints`, and **`collectionState`** (added v1.1); many other KPIs still show `0` without state — extend pattern fleet-wide. |
| Court-admissible audit chain | ⚠️ | Schema and routes exist; **third-party verifier** + Merkle schedule per manual not complete. |
| Air-gapped operation | ⚠️ | Config flags / data-sovereignty UX; **24h no-outbound automated test** not in repo as specified. |

---

## §3 Foundational shifts

### 3.1 License manifest (Ed25519, every request, Feature Registry)

| Item | Status |
|------|--------|
| Signed `.license` file + embedded public key | ❌ Current: SQL `ctl.LicenseEntitlements` / legacy `ctl.License` + `FeaturesJson` merge (see `src/api/lib/licenseEngine.js`). |
| Verify on **every** request with cache invalidate on file change | ❌ |
| Feature Gate Registry + CI enforcing codes | ⚠️ **Scaffold:** `src/api/lib/featureGateRegistry.js` lists codes; CI grep not wired. |
| `featureGate` reads manifest only | ❌ Still reads merged snapshot from DB/feature flags. |
| Settings → License page showing manifest | ❌ |

### 3.2 Configuration Catalog + Policy Resolver

| Item | Status |
|------|--------|
| `config.PolicyThresholdCatalog` + CustomerPolicy + NavigationCatalog driven UI | ❌ Thresholds remain in code (e.g. volume low-free in `getCoverageKpis`). |
| Policy Resolver-only reads | ❌ |
| CI: no numeric literals in routes | ❌ |

### 3.3 Single instance / leader lease / HA license

| Item | Status |
|------|--------|
| Fingerprint + leader row + standby deny | ❌ Community cap is **≤1 instance** in default profile; not full HA manifest model. |

**Doc fix vs product:** Manual §5.1 says Community “up to **3** monitored instances.” The **current codebase default** Community profile uses **1** instance (`licenseEngine`). Align contract copy with `ctl.LicenseEntitlements` or change code — pick one owner.

---

## §4 Policy & Threshold Framework

| Item | Status |
|------|--------|
| 80–120 policies seeded with citations | ❌ Appendix A illustrative only. |
| Policy Library / Editor UI | ❌ |

---

## §5 License tiers (eight editions)

| Item | Status |
|------|--------|
| Same binary, edition via entitlements | ✅ Directionally yes (`licenseEngine` + industry packs). |
| All eight edition behaviors fully tested | ❌ Not all SKU combinations enumerated in automated tests. |
| No `if edition == Government` branches | ✅ **Intent kept** — use packs + FeaturesJson; grep in review. |

---

## §6 Ship-blockers (manual)

| # | Gate | Status | Notes |
|---|------|--------|--------|
| 21–24 | Auth + role + feature on **every** route | ❌ Many `GET`s are still public (e.g. fleet, overview). |
| 25–28 | Truthfulness / 503 on degraded summary | ⚠️ **Partially addressed:** error path now **503**; KPI **—** when `collectionState.coverageKpis === 'never_collected'`. |
| 29–32 | `meta.product`, `meta.tenant`, `meta.environment`, `meta.requestId` on all responses | ❌ |
| 33–35 | Mock data out of production path | ❌ `db.js` mock still co-located; tighten `.npmignore` / build. |
| 36–37 | Tenant filter on all queries | ❌ `getFleetServerCount` etc. |
| 38–40 | Global rate limits | ❌ Login only. |
| 41–44 | Operations summary auth, policy sample size, structured disk/reachability, cache | ⚠️ Sample size via **`SOVEREIGN_OPERATIONS_SAMPLE_LIMIT`**; auth not applied; cache not added. |

---

## §7 Data collection pipeline

| Item | Status |
|------|--------|
| Agents + hardened ingest + per-domain CollectionState table | ⚠️ Ingest routes exist; **CollectionState** not modeled as specified. |

---

## §8 Power BI / executive

| Item | Status |
|------|--------|
| OData / CSV / Board Room embeds | ⚠️ Board Room + OData routes exist; **AppSource template + certified connector** ❌. |
| Seven dashboard parity in React | ❌ |

---

## §9 Predictive engine

| Item | Status |
|------|--------|
| ONNX, feature store, backtesting, confidence in UI | ❌ Scaffolding / mock paths in `aiInsights`. |

---

## §10 Competitive features

| Item | Status |
|------|--------|
| Parity list (Query Store, workload replay, etc.) | ⚠️ **Partial** coverage across product; not tracked as a single program. |

---

## §11 Simulator

| Item | Status |
|------|--------|
| Data-driven JSON catalog + API + UI | ✅ (`src/api/data/dbaopsSimulator.catalog.json`, routes, `/simulator`). |
| 20 scenarios, synthetic telemetry loop, signed scenarios, certificates / audit | ❌ **3** scenarios; choice-based only; no synthetic time-series engine. |
| Free tier “5 scenarios” vs code | ⚠️ Align licensing SKUs with scenario counts. |

### Why `GET /api/simulator/catalog` sometimes returns `NOT_FOUND`

That response is the app’s **generic 404** (`code: NOT_FOUND`). Typical causes:

1. **Process on port 3041 is an old build** — restart the API after `git pull` / deploy. Uptime in `/api/health` that is **days** while you just merged Simulator is a clue.  
2. **License**: route is behind `featureGate('learning.simulator')`. A **403 FEATURE_LOCKED** would appear if the gate ran; **404** means the route is not registered on that process.  
3. **Wrong service** — another app bound to 3041.

**Verify:** `rg "simulator/catalog" src/api/app.js` on the deployed tree, then restart Node.

---

## §12 Sequencing & success criteria (#69–77)

| # | Criterion | Met? |
|---|-----------|------|
| 69 | Every route auth + role + feature + tenant + CI | ❌ |
| 70 | No thresholds in route files + CI | ❌ |
| 71 | Eight signed manifests in test | ❌ |
| 72 | Three engines + real pilot data in Operations | ⚠️ Engines supported in places; **pilot data** is deployment-specific. |
| 73 | AppSource + 3 dashboards | ❌ |
| 74 | Predictive v1 + 75% backtest | ❌ |
| 75 | 5 / 20 Simulator scenarios + public verifier | ⚠️ **3** scenarios; verifier ❌ |
| 76 | 24h air-gap automated test | ❌ |
| 77 | Third-party evidence verify without Sovereign | ⚠️ Partial infrastructure only |

---

## Manual quality improvements (v1.0 → apply to your master doc)

1. **Renumbering:** Section 3.1 jumps from bullet 4–10 (Word auto-numbering); re-sequence 1…n.  
2. **Naming:** Use **RHOYLLE INNOVATION EMPIRE LLC** consistently (legal).  
3. **Community instances:** Reconcile **3** (manual) vs **1** (current default in code) with product/legal.  
4. **Cross-reference:** Point “Feature Gate Registry” to `src/api/lib/featureGateRegistry.js` once CI enforces it.  
5. **Tracing:** Add requirement for **OpenTelemetry** or **requestId** middleware when implementing §6.3.  
6. **Simulator §11.3:** Current shipping path is **JSON catalog** (not YAML); allow either in spec or standardize on JSON for v1.

---

## Industry SKU operational prerequisites (regulated / enterprise posture)

Deployments that present **financial, healthcare, or public-sector** SKUs must wire the control plane—not only SPA auth:

- **JWT signing secret** (`JWT_SECRET`) in production — never rely on the dev placeholder; align with `SOVEREIGN_REQUIRE_AUTH` (defaults **on** in production).
- **Ingest/API key** for collectors (`SOVEREIGN_INGEST_KEY`) whenever agents post to `/api/ingest/*`; treat keys as tier-1 secrets.
- **`CORS_ORIGIN`** explicit allowlist — do not rely on localhost defaults beyond bootstrap; CSP is deployment-owned (typically reverse proxy / IIS), especially if Power BI embeds constrain `frame-src`.
- **Burst rate limits** (`SOVEREIGN_API_BURST_*`, `SOVEREIGN_API_BURST_LIMIT_DISABLED`) and login throttles for edge protection.
- **SIEM / correlation headers** — API emits/stabilizes `X-Request-Id`; forward to logs and APM.
- **Industry entitlements** — regulated compliance pack routes (`/api/compliance-packs/:packCode`) and containment certificates require both **tier floor** and **industry pack** features in `FeaturesJson` / `_dbaopsIndustryPack`; optional **strict response headers** via `SOVEREIGN_ENTERPRISE_STRICT_HEADERS` (HSTS only with `SOVEREIGN_STRICT_HSTS=true`).

---

## Closing

The manual is the **target operating model**. This file is the **scoreboard**. Shipping “the manual” is a **multi-quarter** program; the codebase is **on the path** but **not there**. Prioritize **§6 control + truthfulness + tenant** before deeper differentiators.

— Generated as engineering truth; update with each release.
