feat: SolaceNet gateway rails, IRU marketplace hardening, and docs

- Gateway adapter registry, rails routes, optional SOLACENET_GATEWAY_RAILS_ENFORCE; HTTP integration tests. - IRU marketplace: rate limits, public routes, notifications/SMTP env docs; marketplace UI constants and flows. - Quantum proxy legacy protocol types; debank/tezos/GSDS touch-ups; .env.example operator notes. - SolaceNet doc set (gaps, runbooks, telecom schema example). Tests: npm run test:iru-marketplace, npm run test:gateway (pass). Note: full-repo tsc still reports unrelated legacy errors outside this change set. Made-with: Cursor
2026-04-07 23:21:55 -07:00
parent 1190476b0a
commit 6ebf71dda8
75 changed files with 4104 additions and 338 deletions
--- a/docs/IRU_IMPLEMENTATION_STATUS.md
+++ b/docs/IRU_IMPLEMENTATION_STATUS.md
@@ -15,6 +15,7 @@ This document tracks the complete implementation of the IRU Production Readiness
 ### Phase 1: Marketplace & Portal Foundation ✅ COMPLETE

 #### 1.1 Sankofa Phoenix Marketplace ✅
+- **Catalog model:** Phoenix IRU marketplace rows are **partner-style** offerings (e.g. SolaceNet). **Native** platform services (VMs, IPs, app hosting, etc.) are documented and operated separately; see `docs/03-deployment/SANKOFA_MARKETPLACE_SURFACES.md` (native vs partner methodology).
 - ✅ Database schema (IruOffering, IruInquiry, IruSubscription, IruAgreement)
 - ✅ Backend services:
  - `marketplace.service.ts` - Marketplace business logic
--- a/docs/solacenet/AUDIT_GAPS_INCONSISTENCIES_MISSING.md
+++ b/docs/solacenet/AUDIT_GAPS_INCONSISTENCIES_MISSING.md
@@ -0,0 +1,68 @@
+# Audit — gaps, inconsistencies, and missing elements (SolaceNet + gateway + edges)
+
+**Purpose:** Delta review beyond [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md): naming drift, missing wiring, doc collisions, and security/ops gaps.  
+**Last updated:** 2026-04-07
+
+---
+
+## 1. Gaps (not yet covered elsewhere or under-specified)
+
+| Topic | Detail |
+|--------|--------|
+| **HTTP integration tests** | ~~Added~~ `gateway-rails-http.integration.test.ts` + `createGatewayHttpTestApp`; run via `npm run test:gateway`. |
+| **CI for gateway unit tests** | ~~Added~~ workflow `dbis-core-gateway-ci.yml` (Proxmox repo) on gateway path changes. |
+| **Go edge vs Node rails** | Documented as **intentional layering** in [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md) §6; optional future shared config if one edge must enumerate `dbis.adapter.*`. |
+| **Outbox / send pipeline** | No shared **idempotency store**, **DLQ**, or **transactional outbox** for rail `send` / instruction fan-out. |
+| **Audit export** | **Partial:** Winston + optional `SOLACENET_GATEWAY_AUDIT_LOG_PATH` NDJSON (`gateway-rails-audit.ts`). SIEM signing/long-term store still operator-owned. |
+| **Provider connector data** | **Partial:** `npm run seed:gateway-provider` upserts `dbis-gateway-rail-plane`. |
+| **Telecom northbound** | **Example schema** in `docs/solacenet/schemas/telecom-northbound-event.example.json`; AsyncAPI when boundary exists. |
+| **Rate limits** | **Partial:** extra per-IP limiter on `POST .../validate` and `.../receive` (`GATEWAY_RAIL_MUTATE_*`). Per-tenant budgets still open. |
+| **Adapter state & secrets** | `initialize(config, secretsRef)` not exercised by REST routes (always `{}`); **no** pattern for loading HSM/KMS refs per rail. |
+
+---
+
+## 2. Inconsistencies
+
+| Topic | Detail |
+|--------|--------|
+| **Naming: marketplace vs quantum vs adapter ID** | Marketplace says **“KTT Legacy”**; quantum uses **`KTT_EVIDENCE`**; adapter id is **`dbis.adapter.ktt-evidence`**. Same concept, three namespaces — integrators need a mapping table. |
+| **`EntitlementCheckContext.capabilityId`** | ~~Fixed~~ for payment-gateway, mobile-money, wallet-accounts, card-issuing, and tokenization routes; re-audit other `requireCapability` call sites if new services are added. |
+| **`GET /api/v1/gateway/rails` vs enforcement** | **Listing** adapters does **not** call `maybeRequireGatewayMicroservices` (by design: metadata). Still requires **same `/api` auth** as other routes. Document so it is not mistaken for “public” data. |
+| **Synthetic vs failed send** | SWIFT FIN / TT scaffolds return **`SENT`** without wire; KTT returns **`FAILED`** on send — **test harness semantics** differ; UIs/dashboards could mislead if not labeled scaffold. |
+| **“Remaining tasks” doc collision** | Proxmox **`docs/00-meta/REMAINING_TASKS.md`** is **unrelated** to **`dbis_core/docs/solacenet/REMAINING_TASKS_FULL_LIST.md`** — similar names, different scope (confusing in search). |
+| **MASTER_INDEX row** | SolaceNet row links into **`dbis_core/`** submodule path; if submodule not checked out, links 404 from browser — **operator** must open from full monorepo. |
+| **Section C checklist** (fixed) | Was stale vs `LegacyProtocol`; checklist now references **`legacy-protocol-types.ts`**. |
+
+---
+
+## 3. Missing elements
+
+| Element | Where it should live / action |
+|---------|-------------------------------|
+| **Rail name mapping table** | ~~Done~~ — [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md) §5. |
+| **Runbook: enable enforcement in prod** | ~~Done~~ — [SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md](SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md). |
+| **OpenAPI request body** for `POST /instructions` | ~~Expanded~~ in `gateway.routes.ts` Swagger block. |
+| **Go gateway** middleware hook (optional) | Still optional; see PLUGIN bridge §6. |
+| **E2E list** | **Internal verifier:** `scripts/verify/check-dbis-core-gateway-rails.sh` (needs `DBIS_CORE_API_BASE` + bearer token). |
+| **SEO / share** | **`/solacenet` document title** set in `SolaceNetPage` via `useEffect` (og tags still apex defaults unless SSR). |
+| **`AGENTS.md` pointer** | ~~Done~~ — SolaceNet row links hub, full list, audit, API path. |
+| **Cloudflare purge** | `purge-info-defi-oracle-cache.sh` purges static files only; **HTML** for new routes may still be served from stale **`index.html`** at edge in some setups — document **purge everything** or origin cache bust when needed. |
+| **Thirdweb adapter** | **`ethers`** added as dependency; `Provider` / `Signer` via `import type` from `ethers` — full-repo `tsc` may still have unrelated errors. |
+
+---
+
+## 4. Recommended follow-ups (short)
+
+1. ~~Add **rail mapping table** to [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md)~~ — done (section 5 + Go vs Node §6).  
+2. ~~Add **integration test** for `/api/v1/gateway/rails`~~ — done: `src/__tests__/integration/api/gateway-rails-http.integration.test.ts` + `npm run test:gateway` (HTTP suite uses `jest.gateway-http.config.js` with `ts-jest` `diagnostics: false` so it does not require full-repo Prisma strict compile); CI: `.github/workflows/dbis-core-gateway-ci.yml`.  
+3. ~~Align **`EntitlementCheckContext`**~~ — done for payment-gateway, mobile-money, wallet-accounts, card-issuing, tokenization routes.  
+4. ~~Link **AGENTS.md**~~ — done (SolaceNet row includes full list + audit).  
+5. **Remaining:** production **outbox/DLQ**, per-tenant rate budgets, full **`tsc`** green for entire `dbis_core`, wire **`requireGatewayMicroservicesForWorker`** into real MQ/file workers.  
+
+---
+
+## Related
+
+- [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md)  
+- [public/GAPS_AND_INCONSISTENCIES.md](public/GAPS_AND_INCONSISTENCIES.md)  
+- [REMAINING_TASKS_FULL_LIST.md](REMAINING_TASKS_FULL_LIST.md)
--- a/docs/solacenet/PLUGIN_AND_GATEWAY_BRIDGE.md
+++ b/docs/solacenet/PLUGIN_AND_GATEWAY_BRIDGE.md
@@ -0,0 +1,52 @@
+# SolaceNet — Plugin registry vs gateway rail adapters
+
+**Purpose:** Remove ambiguity between two integration surfaces in `dbis_core`.
+
+## 1. Plugin registry (`src/integration/plugins/plugin-registry.ts`)
+
+- **Intent:** Core-banking and ERP connectors (Temenos, Flexcube, SAP, Oracle Banking Platform).
+- **Pattern:** `IPluginAdapter` instances registered by short name (`temenos`, `swift`, `iso20022`, …).
+- **Use when:** Batch or API integration to a **core system** product, not necessarily a **marketplace rail** contract.
+
+## 2. Gateway rail adapters (`src/core/gateway/adapters/`)
+
+- **Intent:** Regulated **messaging rails** and evidence paths (SWIFT families, DTC/DTCC, TT, KTT evidence, Thirdweb contract invocation).
+- **Pattern:** `GatewayAdapter` + **`gateway-adapter-registry.ts`** canonical IDs (`dbis.adapter.*`).
+- **HTTP surface:** `/api/v1/gateway/rails`, `/api/v1/gateway/rails/:adapterId/health|validate|receive` (authenticated like other `/api/*` routes).
+- **SolaceNet:** Optional enforcement via `SOLACENET_GATEWAY_RAILS_ENFORCE=1` and tenant resolution (`x-tenant-id` or body `tenantId`).
+
+## 3. Bridge strategy (recommended)
+
+1. **Do not** duplicate the same bank connection as both an unnamed `swift` plugin and a `dbis.adapter.swift-fin` rail without documentation.
+2. Prefer **gateway adapters** for anything listed in `marketplace/gateway-microservices-offering.json` rails.
+3. Implement a **facade service** if one physical SWIFT connection must feed both: the facade calls the single connector and exposes plugin vs gateway shapes.
+4. Document the chosen path in the institutional onboarding pack.
+
+## 4. Quantum / QPS alignment
+
+`LegacyProtocol` in `src/infrastructure/quantum/proxy/legacy-protocol-types.ts` includes SolaceNet-extended rails so translation/compatibility APIs can reference the same protocol names where useful.
+
+## 5. Rail name mapping (marketplace ↔ quantum ↔ adapter ID)
+
+| Marketplace offering rail (`gateway-microservices-offering.json`) | `LegacyProtocol` (quantum) | Gateway adapter ID |
+|----------------------------------|-----------------------------|-------------------|
+| SWIFT FIN/MT | `SWIFT` | `dbis.adapter.swift-fin` |
+| SWIFT ISO 20022 | `ISO20022` | `dbis.adapter.swift-iso` |
+| SWIFT gpi | `SWIFT_GPI` | `dbis.adapter.swift-gpi` |
+| DTC Settlement | `DTC_SETTLEMENT` | `dbis.adapter.dtc-settlement` |
+| DTCC Family (NSCC) | `DTCC_NSCC` | `dbis.adapter.dtcc-nscc` |
+| DTCC Family (FICC) | `DTCC_FICC` | `dbis.adapter.dtcc-ficc` |
+| TT Route | `TT_ROUTE` | `dbis.adapter.tt-route` |
+| KTT Legacy | `KTT_EVIDENCE` | `dbis.adapter.ktt-evidence` |
+| Extensible Adapter SDK | N/A (integration pattern) | Add factory + ID in `gateway-adapter-registry.ts` |
+
+**HYBX sidecars:** map per deployment in `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md` — not duplicated here.
+
+## 6. Go edge gateway vs Node rails
+
+The **Go** service under `gateway/go/` performs **generic** capability pre-checks from path/headers (`X-Capability-ID`, `X-Tenant-ID`, …). It does **not** embed the TypeScript **`dbis.adapter.*`** catalog. **Node** (`/api/v1/gateway/rails`) owns rail adapter IDs and enforcement via `gateway-rails-enforcement.ts`. Treat this as **intentional layering**: Go = edge policy cache + proxy; Node = rail semantics — or add a shared config artifact if a single edge must enumerate rails.
+
+---
+
+**Version:** 1.1  
+**Last updated:** 2026-04-07
--- a/docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md
+++ b/docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md
@@ -0,0 +1,164 @@
+# SolaceNet — protocol gaps checklist (tracked)
+
+**Purpose:** Single **complete** inventory of **protocol, messaging, and integration** gaps across `dbis_core`, SolaceNet, and cross-repo RTGS / DBIS Rail dependencies. Use for backlog triage, ownership, and closing the loop with [RAIL_AND_PROTOCOL_GOVERNANCE.md](RAIL_AND_PROTOCOL_GOVERNANCE.md).
+
+**How to use status**
+
+| Status | Meaning |
+|--------|---------|
+| `open` | Not implemented or only stub/placeholder |
+| `partial` | Some path exists; production contract or wiring incomplete |
+| `n/a` | Explicitly out of scope for this repo (document boundary only) |
+| `done` | Production-capable per defined gate (update row when true) |
+
+**Last updated:** 2026-04-07
+
+---
+
+## A. Carrier and telecom signaling
+
+| ID | Protocol / stack | Location / note | Status | Close when |
+|----|------------------|-----------------|--------|------------|
+| PG-CAR-001 | **SS7** (MTP2/3, SCCP, ISUP, TCAP…) | Not in repo | `open` | N/A in app repo unless a **telecom boundary service** is chartered; SolaceNet owns northbound API only per governance doc |
+| PG-CAR-002 | **SIGTRAN** (M2PA, M3UA, SUA over SCTP) | Not in repo | `open` | Same as PG-CAR-001 |
+| PG-CAR-003 | **MAP / CAP / INAP** (circuit intelligence) | Not in repo | `open` | Same |
+| PG-CAR-004 | **Diameter** (LTE/5G adjacent) | Not in repo | `open` | Same |
+
+---
+
+## B. `dbis_core` gateway rail adapters (TypeScript)
+
+Path: `src/core/gateway/adapters/`. All are **scaffolds** unless status changed.
+
+| ID | Rail | Adapter path | Status | Gap summary |
+|----|------|--------------|--------|-------------|
+| PG-GW-001 | SWIFT FIN/MT | `swift-fin/swift-fin-adapter.ts` | `open` | No SWIFTNet, no real MT build/parse/sign, synthetic SENT/ACK |
+| PG-GW-002 | SWIFT ISO 20022 | `swift-iso/swift-iso-adapter.ts` | `open` | No transport, no XSD/JSON schema pipeline, no ACK semantics |
+| PG-GW-003 | SWIFT gpi | `swift-gpi/swift-gpi-adapter.ts` | `open` | No UETR tracker integration |
+| PG-GW-004 | DTC settlement | `dtc-settlement/dtc-settlement-adapter.ts` | `open` | No DTC message/API integration |
+| PG-GW-005 | DTCC NSCC | `dtcc/dtcc-nscc-adapter.ts` | `open` | No NSCC API/protocol integration |
+| PG-GW-006 | DTCC FICC | `dtcc/dtcc-ficc-adapter.ts` | `open` | No FICC API/protocol integration |
+| PG-GW-007 | TT route | `tt-route/tt-route-adapter.ts` | `open` | Synthetic routing only |
+| PG-GW-008 | KTT legacy evidence | `ktt-evidence/ktt-evidence-adapter.ts` | `open` | Trivial validate; **send unsupported**; no SoR match, no persistence contract |
+| PG-GW-009 | Thirdweb (chain RPC) | `thirdweb/thirdweb-adapter.ts` | `partial` | Encode/path comments still **placeholder** in places; not a banking rail but shares adapter plane |
+
+**B1. Wiring and registry**
+
+| ID | Gap | Status | Close when |
+|----|-----|--------|------------|
+| PG-GW-W01 | No **single** gateway adapter registry importing all rail adapters | `partial` | **Registry + REST + OpenAPI + unit tests:** `gateway-adapter-registry.ts`, `/api/v1/gateway/rails*`, Swagger tag **SolaceNet Gateway Rails**, `src/__tests__/unit/core/gateway/*.test.ts`. **Remaining:** DI singleton policy, production connectors, optional `send` orchestration |
+| PG-GW-W02 | **PluginRegistry** (`integration/plugins/`) vs **gateway adapters** — duplicate Swift/ISO concepts, no bridge doc in code | `partial` | **Doc:** [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md). **Remaining:** optional facade service in code |
+| PG-GW-W03 | SolaceNet **requireCapability** not consistently enforced on adapter ingress paths | `partial` | **On:** `SOLACENET_GATEWAY_RAILS_ENFORCE=1` for `/api/v1/gateway/rails/*`, `POST /instructions`, `GET /events/replay`. **Runbook:** [SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md](SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md). **Audit:** structured logs + optional `SOLACENET_GATEWAY_AUDIT_LOG_PATH` NDJSON; **`requireGatewayMicroservicesForWorker`** for MQ/file. **Remaining:** wire worker call sites + SIEM pipelines |
+
+---
+
+## C. Quantum / QPS legacy protocol coverage
+
+Services: `src/infrastructure/quantum/proxy/quantum-translation.service.ts`, `quantum-compatibility.service.ts`.
+
+**Type source:** `legacy-protocol-types.ts` — `LegacyProtocol` = core five plus **SolaceNet-extended** rails (`KTT_EVIDENCE`, `TT_ROUTE`, `DTC_SETTLEMENT`, `DTCC_NSCC`, `DTCC_FICC`, `SWIFT_GPI`, `MOJALOOP`, `RTGS`, `CARD_NETWORK`). **`GET /api/quantum-proxy/compatibility/protocols`** returns the full list.
+
+| ID | Missing vs marketplace / gateway rails | Status |
+|----|----------------------------------------|--------|
+| PG-QP-001 | **KTT**, **TT route**, **DTC**, **DTCC** (NSCC/FICC), **SWIFT gpi** as distinct handling | `partial` | **Types + defaults** in `legacy-protocol-types.ts` / quantum translation & compatibility |
+| PG-QP-002 | **RTGS** (generic), **Mojaloop**, **card networks**, **instant payment** schemes | `partial` | **RTGS**, **MOJALOOP**, **CARD_NETWORK** in `LegacyProtocol`; still scaffold scoring |
+| PG-QP-003 | **Telecom northbound** (carrier boundary event schema) | `partial` | **Example JSON Schema:** [schemas/telecom-northbound-event.example.json](schemas/telecom-northbound-event.example.json). **Remaining:** boundary service + AsyncAPI |
+
+---
+
+## D. Admin dashboards and metrics (protocol surfaces)
+
+| ID | Component | Path | Status | Gap |
+|----|-----------|------|--------|-----|
+| PG-AD-001 | GAS/QPS legacy rails | `gas-qps.service.ts` | `partial` | **SolaceNet adapter IDs** merged into `legacyRails`; volumes still 0 / heuristic until QPS integration |
+| PG-AD-002 | GAS/QPS mapping profiles | same | `open` | Placeholder profiles only |
+| PG-AD-003 | Global overview QPS / Ω / GPN / etc. | `global-overview.service.ts` | `open` | Marked placeholder |
+| PG-AD-004 | SCB payment rails | `scb-overview.service.ts` | `open` | Payment rails placeholder |
+
+---
+
+## E. DBIS Rail — on-chain and authorization protocol (parent repo docs)
+
+Source of truth for deployment truth: `docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md` (Proxmox repo).
+
+| ID | Protocol / contract layer | Status | Gap summary |
+|----|---------------------------|--------|-------------|
+| PG-RAIL-001 | **DBIS_RootRegistry** | `open` | Contract set not implemented in repo |
+| PG-RAIL-002 | **DBIS_ParticipantRegistry** | `open` | Same |
+| PG-RAIL-003 | **DBIS_SignerRegistry** | `open` | Same |
+| PG-RAIL-004 | **DBIS_SettlementRouter** | `open` | Same |
+| PG-RAIL-005 | **DBIS_GRU_MintController** (router-only mint) | `open` | Mint path still owner-mint on c* per master doc |
+| PG-RAIL-006 | **Production ISO Gateway** matching EIP-712 MintAuth pipeline | `partial` | Spec/rulebook complete; production service + on-chain registry not aligned |
+| PG-RAIL-007 | **MintAuth relayer** operational hardening | `partial` | Documented; full ops gate open |
+
+---
+
+## F. RTGS and external messaging protocols (Proxmox matrix)
+
+Canonical table: `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md`.  
+Below: rows that are **protocol, endpoint, or message-contract** heavy and **not Complete**. (Infrastructure rows like Besu/Explorer are omitted here; see matrix for full operational checklist.)
+
+| ID | Matrix component | Typical protocol / contract gap | Matrix state (as of doc) |
+|----|------------------|--------------------------------|--------------------------|
+| PG-RTGS-001 | FireFly primary `6200` | Event/orchestration API contract across workflows | Partial |
+| PG-RTGS-002 | FireFly secondary `6201` | HA / secondary node payload | Retired / standby |
+| PG-RTGS-003 | Fabric `6000-6002` | Fabric channel/chaincode deployment contract if in scope | Partial |
+| PG-RTGS-004 | Indy `6400-6402` | DID/ledger protocol production role | Partial |
+| PG-RTGS-005 | Aries / AnonCreds / Ursa | DIDComm / credential protocol lifecycle | Partial |
+| PG-RTGS-006 | Cacti | Cross-ledger connector protocol | Partial |
+| PG-RTGS-007 | OMNL / Fineract API rail | REST/auth/tenant settlement contract | Partial |
+| PG-RTGS-008 | Mifos X / Fineract UI | Operator/API procedures | Partial |
+| PG-RTGS-009 | HYBX participant / treasury | Business protocol for nostro/vostro + IDs | Planned |
+| PG-RTGS-010 | Depository / CSD | Securities settlement messaging model | Planned |
+| PG-RTGS-011 | Global custodian | Custody reporting / instruction protocols | Planned |
+| PG-RTGS-012 | FX pricing / dealing | Quote/booking protocol to OMNL | Planned |
+| PG-RTGS-013 | Liquidity pooling + **source adapters** | Per-source bank/pool protocol contracts | Planned |
+| PG-RTGS-014 | Custody / safekeeping lifecycle | End-to-end instruction + statement protocol | Planned |
+| PG-RTGS-015 | **Mojaloop** | Quote/transfer/callback/settlement API contract | Planned |
+| PG-RTGS-016 | HYBX sidecar layer + listed sidecars | Ingress/auth/retry/event protocols | Partial / Planned |
+| PG-RTGS-017 | **mt103-hardcopy-sidecar** | MT103 ingest ↔ settlement correlation | Partial |
+| PG-RTGS-018 | **card-networks-sidecar** | Card scheme settlement file/API protocol if in scope | Partial |
+| PG-RTGS-019 | **securities-sidecar** | Securities instruction protocol vs CSD | Partial |
+| PG-RTGS-020 | Chain 138 settlement path | Contract call graph as frozen protocol | Partial |
+| PG-RTGS-021 | MerchantSettlementRegistry / WithdrawalEscrow | Invocation protocol in RTGS flow | Partial |
+| PG-RTGS-022 | DBIS settlement tokens + reserve/oracle | Mint/burn and attestation protocols | Partial |
+| PG-RTGS-023 | FireFly / sidecar / chain **event model** | Correlation ID, retry, DLQ protocol | Planned |
+| PG-RTGS-024 | **ISO 20022 evidence and vault** | Archive/manifest/hash protocol | Partial |
+| PG-RTGS-025 | **Institutional 4.995 package** | Submission package protocol | Partial |
+| PG-RTGS-026 | **Indonesia / BNI** domestic | Live endpoint/auth/message contract | Planned |
+| PG-RTGS-027 | **Global correspondent / liquidity bank** | SWIFT/ISO/correspondent API contract | Planned |
+| PG-RTGS-028 | **ISO20022Router** on-chain + off-chain | G4 acceptance steps in matrix subsection | Partial until manual gate passes |
+| PG-RTGS-029 | RTGS production gate | All mandatory protocol lanes green | Planned |
+
+---
+
+## G. SolaceNet capability vs rail implementation
+
+| ID | Gap | Status | Close when |
+|----|-----|--------|------------|
+| PG-SN-001 | `gateway-microservices` capability describes rails; **adapters remain scaffolds** | `open` | Critical rails reach `done` in section B or scope reduced in offering JSON |
+| PG-SN-002 | `solacenet_provider_connector` rows for each live rail provider | `partial` | **Seed:** `npm run seed:gateway-provider` (`dbis-gateway-rail-plane`). **Remaining:** per-institution connectors + bindings |
+| PG-SN-003 | smom-dbis-138-publish / tokenization docs: **SolaceNet policy** integration called out as future in places | `partial` | Code paths call `requireCapability` or documented exception |
+
+---
+
+## H. Suggested close order (dependencies)
+
+1. **PG-GW-W01 / W02 / W03** — Single registry + SolaceNet enforcement (enables safe iteration).  
+2. **PG-RAIL-001–005 / 006** — On-chain authorization protocol (or explicit deferral).  
+3. **PG-RTGS-007, PG-RTGS-023** — OMNL + canonical event/correlation protocol.  
+4. **PG-GW-001–008** — Replace scaffolds rail-by-rail with sandbox → prod endpoints.  
+5. **PG-RTGS-015, 026, 027** — External switch/domestic/correspondent protocols.  
+6. **PG-CAR-*** — Only if product scope includes carrier signaling; boundary service first.
+
+---
+
+## Related documents
+
+- [REMAINING_TASKS_FULL_LIST.md](REMAINING_TASKS_FULL_LIST.md) — **prioritized full task list** (all remaining work in one place)  
+- [AUDIT_GAPS_INCONSISTENCIES_MISSING.md](AUDIT_GAPS_INCONSISTENCIES_MISSING.md) — **delta audit** (naming drift, missing CI/integration tests, edge gaps)  
+- [RAIL_AND_PROTOCOL_GOVERNANCE.md](RAIL_AND_PROTOCOL_GOVERNANCE.md)  
+- Proxmox: [DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](../../../docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md)  
+- Proxmox: [DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md](../../../docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md)  
+- `dbis_core/src/core/gateway/adapters/README.md`  
+- `dbis_core/marketplace/gateway-microservices-offering.json`
--- a/docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md
+++ b/docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md
@@ -0,0 +1,69 @@
+# SolaceNet — rail and external protocol governance
+
+**Purpose:** Define where **external messaging and carrier-style protocols** (payment rails, legacy evidence feeds, telecom-adjacent integrations) are **owned, versioned, and operated** inside the DBIS Core / SolaceNet stack.
+
+**Authority:** SolaceNet is the **control plane** for capabilities, entitlements, policy, audit, and the **Go edge gateway** (`gateway/go/`). Rails and protocol adapters are **maintained under SolaceNet** as defined below—not as ad-hoc modules without registry or policy hooks.
+
+---
+
+## 1. What this covers
+
+| Class | Examples | SolaceNet role |
+|--------|-----------|----------------|
+| **Financial messaging rails** | SWIFT FIN/MT, SWIFT ISO 20022, SWIFT gpi, DTC, DTCC family, TT route, KTT legacy evidence | Capability `gateway-microservices` / `gateway-adapters`; adapter implementations; schema and version registry; policy before execute |
+| **Institutional evidence** | KTT-style legacy files, batch ingest, untrusted evidence until SoR match | Same; explicit “evidence-only” adapters; no mint/settlement without downstream checks |
+| **Telecom signaling (SS7 family)** | MTP/SCCP/SIGTRAN, MAP/CAP at carrier edge | **Not implemented in application code here.** SolaceNet owns only the **northbound contract** (HTTPS/MQ/events) from a dedicated telecom boundary service; carrier stack stays outside this repo |
+
+---
+
+## 2. Maintenance responsibilities
+
+1. **Capability registry** — Each rail or protocol surface is registered (or sub-capability under `gateway-adapters`) with `defaultState`, dependencies, and version.
+2. **Policy** — Ingress and execution require `requireCapability` / gateway middleware alignment per tenant, region, and channel.
+3. **Audit** — Toggle changes, kill-switch use, and (where implemented) adapter decisions feed SolaceNet audit patterns.
+4. **Adapter code** — Canonical TypeScript adapters live under `src/core/gateway/adapters/`; the **edge** is `gateway/go/` (proxy, auth, capability pre-check).
+5. **Offerings and marketplace** — JSON offerings (e.g. `marketplace/gateway-microservices-offering.json`) declare rails; **governance** field identifies SolaceNet as maintainer.
+
+---
+
+## 3. Code and doc map
+
+| Artifact | Path |
+|----------|------|
+| Capability platform | `src/core/solacenet/` |
+| SolaceNet SDK | `src/shared/solacenet/sdk.ts` |
+| Go API gateway | `gateway/go/` |
+| Rail adapters (TS) | `src/core/gateway/adapters/` |
+| Docker stack | `docker-compose.solacenet.yml` |
+| Operator quick reference | `SOLACENET_QUICK_REFERENCE.md` (repo root of `dbis_core`) |
+| This governance doc | `docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md` |
+
+---
+
+## 4. Adding or changing a protocol
+
+1. Register or update **capability** (and entitlements) in the SolaceNet registry.
+2. Add adapter under `src/core/gateway/adapters/<rail>/` implementing `GatewayAdapter` (`sdk/adapter-interface.ts`).
+3. Wire adapter into the **single** gateway adapter registry when introduced (avoid parallel unregistered copies).
+4. Document trust model (trusted rail vs evidence-only vs telecom boundary).
+5. Update marketplace offering JSON and, if needed, seed scripts (`scripts/seed-gateway-capability.ts`).
+
+---
+
+## 5. Related platform notes
+
+- **Plugin registry** (`src/integration/plugins/plugin-registry.ts`) covers core-banking connectors; **rail protocol contracts** for regulated messaging should align with this governance doc or be explicitly bridged—do not treat plugins and gateway adapters as competing sources of truth without documentation. **Bridge guide:** [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md).
+- **DBIS Rail / Chain 138** settlement docs in the parent Proxmox repo describe on-chain authorization; SolaceNet rails feed **off-chain** evidence and controls that must satisfy those specs before submission.
+
+## 6. Tracked protocol gaps
+
+Maintained checklist (IDs, status, close criteria, RTGS cross-reference): [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md).
+
+## 7. Public documentation
+
+Markdown for **public** audiences (mirrored in spirit on **info.defi-oracle.io/solacenet**): [public/OVERVIEW.md](public/OVERVIEW.md), [public/GAPS_AND_INCONSISTENCIES.md](public/GAPS_AND_INCONSISTENCIES.md). Hub index: `docs/04-configuration/SOLACENET_PUBLIC_HUB.md` (parent Proxmox repo).
+
+---
+
+**Version:** 1.2  
+**Last updated:** 2026-04-07
--- a/docs/solacenet/REMAINING_TASKS_FULL_LIST.md
+++ b/docs/solacenet/REMAINING_TASKS_FULL_LIST.md
@@ -0,0 +1,171 @@
+# SolaceNet, gateway rails, and RTGS — full remaining task list
+
+**Purpose:** One actionable backlog derived from [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md), [public/GAPS_AND_INCONSISTENCIES.md](public/GAPS_AND_INCONSISTENCIES.md), and the Proxmox RTGS / DBIS Rail docs. Update row statuses in the checklist as tasks close.
+
+**Last reviewed:** 2026-04-07
+
+**Priority legend**
+
+| Tier | Meaning |
+|------|---------|
+| **P0** | Blocks honest production claims or regulatory narrative alignment |
+| **P1** | Core path to first production slice (settlement + evidence + one live rail) |
+| **P2** | Breadth, observability, UX, secondary rails |
+| **P3** | Optional, carrier, or explicit deferrals |
+
+---
+
+## P0 — Truth in advertising and critical alignment
+
+| # | Task | Gap ID(s) | Notes |
+|---|------|-----------|--------|
+| 1 | **Reconcile marketplace/offering copy** with live connector maturity — or scope down `gateway-microservices-offering.json` until rails are real | PG-SN-001, offering JSON | **Updated 2026-04-08:** description names scaffolds + KTT evidence semantics; keep row until production connectors ship. |
+| 2 | **Document KTT explicitly** as evidence-only in marketplace/UI copy; separate from symmetric send/receive rails | PG-GW-008, inconsistencies doc | Code already fails `send` by design |
+| 3 | **Decide DBIS Rail scope:** implement contracts + router-only mint **or** formally defer and update all docs that imply live Rail | PG-RAIL-001–005, master doc | See `docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md` |
+| 4 | **Fix or quarantine Thirdweb adapter** type issues (`ethers` namespace) for clean `tsc` / CI | PG-GW-009 | **Partial:** `ethers` dependency + `import type { Provider, Signer }`; full `dbis_core` `tsc` may still fail elsewhere. |
+
+---
+
+## P1 — Gateway core (SolaceNet + REST + enforcement)
+
+| # | Task | Gap ID(s) | Notes |
+|---|------|-----------|--------|
+| 5 | **DI / lifecycle policy** for rail adapters (singleton vs per-request) and document | PG-GW-W01 | Registry exists; avoid accidental state bleed |
+| 6 | **Orchestrated `send` path** (outbox, idempotency, DLQ) for rails that support outbound messages | PG-GW-W01, PG-GW-001–007 | KTT may stay receive-only |
+| 7 | **Extend `SOLACENET_GATEWAY_RAILS_ENFORCE`** to every rail ingress (file drop, MQ, future workers) + **audit log** export for denied/allowed | PG-GW-W03 | HTTP path partially done |
+| 8 | **Optional code facade** for PluginRegistry ↔ gateway adapters when one physical connector serves both | PG-GW-W02 | Doc exists; implement if needed |
+| 9 | **Register `solacenet_provider_connector`** rows per environment for each live provider | PG-SN-002 | Tie to capability bindings |
+|10 | **smom-dbis-138-publish / tokenization:** wire `requireCapability` or document explicit exception | PG-SN-003 | |
+
+---
+
+## P1 — Replace rail scaffolds (production connectors)
+
+| # | Task | Gap ID | Notes |
+|---|------|--------|--------|
+|11| SWIFT FIN/MT — SWIFTNet, crypto, parse, ACK/NAK, sandbox → prod | PG-GW-001 | |
+|12| SWIFT ISO 20022 — transport + schema validation + status | PG-GW-002 | |
+|13| SWIFT gpi — UETR tracker integration | PG-GW-003 | |
+|14| DTC settlement — real message/API | PG-GW-004 | |
+|15| DTCC NSCC — API/protocol | PG-GW-005 | |
+|16| DTCC FICC — API/protocol | PG-GW-006 | |
+|17| TT route — real routing contract | PG-GW-007 | |
+|18| KTT evidence — real validate, persistence, **SoR match**, correlation IDs; keep or drop `send` | PG-GW-008 | |
+|19| Thirdweb — remove encode placeholders or document as non-prod | PG-GW-009 | |
+
+---
+
+## P1 — DBIS Rail off-chain + relayer
+
+| # | Task | Gap ID | Notes |
+|---|------|--------|--------|
+|20| **Production ISO Gateway** aligned with EIP-712 MintAuth + `accountingRef` / `isoHash` | PG-RAIL-006 | Spec/rulebook exist |
+|21| **MintAuth relayer** — ops runbook, monitoring, key rotation, incident drill | PG-RAIL-007 | |
+
+---
+
+## P1 — RTGS spine (canonical docs matrix)
+
+*Full row-by-row status lives in* `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md`. *Tasks below are the protocol-heavy items still not Complete.*
+
+| # | Task | Gap ID | Matrix state |
+|---|------|--------|--------------|
+|22| Freeze **OMNL / Fineract** tenant, auth, settlement API contract | PG-RTGS-007 | Partial |
+|23| **Canonical event model** — correlation ID, retry, DLQ, FireFly/sidecar/chain | PG-RTGS-023 | Planned |
+|24| **Mojaloop** — live endpoint, auth, quote/transfer/callback | PG-RTGS-015 | Planned |
+|25| **Indonesia / BNI** — live domestic contract | PG-RTGS-026 | Planned |
+|26| **Global correspondent** — SWIFT/ISO, nostro/vostro, confirmations | PG-RTGS-027 | Planned |
+|27| **ISO 20022 evidence + vault** — manifests, hashes, legal path | PG-RTGS-024 | Partial |
+|28| **Institutional 4.995 package** — `--strict` readiness, real materials | PG-RTGS-025 | Partial |
+|29| **ISO20022Router** — complete G4 manual acceptance (deploy, payload, tx, correlation, evidence) | PG-RTGS-028 | Partial |
+|30| Freeze **Chain 138 settlement** contract graph for RTGS | PG-RTGS-020 | Partial |
+|31| Place **MerchantSettlementRegistry** / **WithdrawalEscrow** in canonical flows | PG-RTGS-021 | Partial |
+|32| **MT103 hardcopy sidecar** — ingest ↔ settlement correlation | PG-RTGS-017 | Partial |
+|33| **HYBX sidecars** — boundaries, auth, retries (all listed in matrix) | PG-RTGS-016 | Partial / Planned |
+|34| **RTGS production gate** — all mandatory rows green for chosen architecture | PG-RTGS-029 | Planned |
+
+---
+
+## P2 — Hyperledger / identity / interoperability (RTGS matrix)
+
+| # | Task | Gap ID | Notes |
+|---|------|--------|--------|
+|35| FireFly primary — orchestration role + real workflow | PG-RTGS-001 | Partial |
+|36| FireFly secondary — rebuild or formally exclude | PG-RTGS-002 | Retired / standby |
+|37| Fabric — production topology decision | PG-RTGS-003 | Partial |
+|38| Indy — production role decision | PG-RTGS-004 | Partial |
+|39| Aries / AnonCreds / Ursa — lifecycle validation | PG-RTGS-005 | Partial |
+|40| Cacti — cross-ledger contract | PG-RTGS-006 | Partial |
+|41| Mifos X / operator procedures | PG-RTGS-008 | Partial |
+|42| HYBX participant / treasury / nostro-vostro model | PG-RTGS-009 | Planned |
+|43| Depository / CSD layer | PG-RTGS-010 | Planned |
+|44| Global custodian | PG-RTGS-011 | Planned |
+|45| FX pricing / dealing engine | PG-RTGS-012 | Planned |
+|46| Liquidity pooling + source adapters | PG-RTGS-013 | Planned |
+|47| Custody / safekeeping lifecycle | PG-RTGS-014 | Planned |
+|48| Card-networks sidecar — scope + protocol | PG-RTGS-018 | Partial |
+|49| Securities sidecar — CSD alignment | PG-RTGS-019 | Partial |
+|50| Settlement tokens + reserve/oracle mapping | PG-RTGS-022 | Partial |
+
+---
+
+## P2 — Quantum / QPS and admin dashboards
+
+| # | Task | Gap ID | Notes |
+|---|------|--------|--------|
+|51| Replace **scaffold** FX/risk/scoring for `LegacyProtocol` extended rails with real rules | PG-QP-001, PG-QP-002 | Types exist |
+|52| **Telecom northbound event schema** (when boundary service exists) | PG-QP-003 | |
+|53| **GAS/QPS mapping profiles** — real profiles, not placeholders | PG-AD-002 | |
+|54| **Global overview** — QPS / Ω / GPN placeholders → real metrics or remove | PG-AD-003 | |
+|55| **SCB payment rails** — real data source | PG-AD-004 | |
+|56| **GAS/QPS** — wire true volumes per rail (not only adapter ID list + heuristics) | PG-AD-001 | |
+
+---
+
+## P3 — Carrier / telecom (out of app repo unless product requires)
+
+| # | Task | Gap ID | Notes |
+|---|------|--------|--------|
+|57| Charter **telecom boundary service** + northbound API into SolaceNet | PG-CAR-001–004 | SS7/SIGTRAN/MAP/CAP/Diameter |
+
+---
+
+## P3 — Consistency and hygiene (ongoing)
+
+| # | Task | Source | Notes |
+|---|------|--------|--------|
+|58| Align **outbox semantics** — synthetic `SENT` vs KTT `FAILED` on send; document test vs prod behavior | GAPS_AND_INCONSISTENCIES | |
+|59| **QPS “SWIFT” volume** — replace `iso_messages` string heuristic with real classification | GAPS_AND_INCONSISTENCIES | |
+|60| Keep **agent-hints / sitemap / verify script** in sync when adding public routes | Public gaps §3 | |
+|61| Run **`pnpm run verify:info-defi-oracle-public`** after each hub deploy | Ops | |
+|62| Optional **`pnpm run audit:info-defi-oracle-site`** (Playwright) in release cadence | Ops | |
+|63| Maintain **`PROTOCOL_GAPS_CHECKLIST.md`** statuses as backlog moves | Process | |
+
+---
+
+## Infrastructure rows (not duplicated here)
+
+Besu, Explorer, Caliper benchmarks, and other **non-protocol** RTGS matrix rows remain in `DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md` — track there for VM/LXC/ops completeness.
+
+---
+
+## Suggested execution waves (summary)
+
+1. **Wave A:** P0 items + PG-RAIL decision + first real rail sandbox (pick one: SWIFT ISO or domestic).  
+2. **Wave B:** OMNL freeze + event model + ISO evidence path + ISO20022Router G4.  
+3. **Wave C:** Remaining gateway adapters + provider connectors + QPS real metrics.  
+4. **Wave D:** Mojaloop / BNI / correspondent as jurisdiction requires.  
+5. **Wave E:** P2 institutional layers (CSD, custody, FX engine) per product scope.  
+6. **Wave F:** Carrier only if explicitly in scope.
+
+---
+
+## Related documents
+
+- [PROTOCOL_GAPS_CHECKLIST.md](PROTOCOL_GAPS_CHECKLIST.md) — ID-level tracking  
+- [public/GAPS_AND_INCONSISTENCIES.md](public/GAPS_AND_INCONSISTENCIES.md) — narrative gaps  
+- [RAIL_AND_PROTOCOL_GOVERNANCE.md](RAIL_AND_PROTOCOL_GOVERNANCE.md)  
+- [PLUGIN_AND_GATEWAY_BRIDGE.md](PLUGIN_AND_GATEWAY_BRIDGE.md)  
+- Proxmox: `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md`  
+- Proxmox: `docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md`  
+- Proxmox: `docs/04-configuration/SOLACENET_PUBLIC_HUB.md`
--- a/docs/solacenet/SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md
+++ b/docs/solacenet/SOLACENET_GATEWAY_RAILS_ENFORCE_RUNBOOK.md
@@ -0,0 +1,36 @@
+# Runbook — enable `SOLACENET_GATEWAY_RAILS_ENFORCE` (gateway rails)
+
+**Purpose:** Turn on SolaceNet capability checks for mutating gateway rail endpoints and related ingress (`/api/v1/gateway/rails/*` except `GET /rails` list, `POST /instructions`, `GET /events/replay`).
+
+**Prerequisites**
+
+- Policy engine / entitlements can resolve `gateway-microservices` for target tenants.
+- Tenants that must use rails have **active entitlements** (or policy allow) for capability id **`gateway-microservices`**.
+- Clients send **`x-tenant-id`** (or `tenantId` in JSON body where applicable). Optional default: set **`SOLACENET_DEFAULT_TENANT_ID`** in environment for lab only.
+
+**Audit**
+
+- Every allow/deny is logged as structured **`Gateway rails enforcement audit`** (Winston).
+- Optional **NDJSON file:** set `SOLACENET_GATEWAY_AUDIT_LOG_PATH` to an operator-writable path; append-only, rotate externally.
+
+**Steps**
+
+1. **Seed or verify entitlements** for each production tenant that should call rail adapters.
+2. Set environment on the API process:
+   - `SOLACENET_GATEWAY_RAILS_ENFORCE=1` (or `true`)
+   - Optionally `SOLACENET_DEFAULT_TENANT_ID=…` for single-tenant lab (not recommended for multi-tenant prod).
+3. **Smoke test without entitlement:** call `GET /api/v1/gateway/rails/dbis.adapter.ktt-evidence/health` with a tenant that lacks the capability — expect **403** with a forbidden message.
+4. **Smoke test with entitlement:** same call with an entitled tenant — expect **200** and health JSON.
+5. **Confirm list endpoint:** `GET /api/v1/gateway/rails` remains **200** (metadata only; still requires normal API auth).
+
+**Rollback**
+
+- Unset `SOLACENET_GATEWAY_RAILS_ENFORCE` or set to `0` / `false` and restart the API.
+
+**Related**
+
+- `src/core/gateway/rails/gateway-rails-enforcement.ts`
+- `dbis_core/.env.example` — SolaceNet gateway variables
+- `AUDIT_GAPS_INCONSISTENCIES_MISSING.md` — SIEM/export pipelines beyond file + logs remain optional
+
+**Version:** 1.0 · **Last updated:** 2026-04-07
--- a/docs/solacenet/public/GAPS_AND_INCONSISTENCIES.md
+++ b/docs/solacenet/public/GAPS_AND_INCONSISTENCIES.md
@@ -0,0 +1,59 @@
+# SolaceNet — gaps and inconsistencies (consolidated)
+
+**Purpose:** Single list of **protocol gaps**, **product/documentation mismatches**, and **structural inconsistencies** relevant to SolaceNet, gateway rails, and public messaging. For **actionable gap IDs** and close criteria, use [PROTOCOL_GAPS_CHECKLIST.md](../PROTOCOL_GAPS_CHECKLIST.md). For a **delta audit** (missing CI, naming drift, dual edge), see [AUDIT_GAPS_INCONSISTENCIES_MISSING.md](../AUDIT_GAPS_INCONSISTENCIES_MISSING.md).
+
+**Last updated:** 2026-04-07
+
+---
+
+## 1. Protocol and implementation gaps (summary)
+
+- **Carrier signaling (SS7/SIGTRAN/MAP/CAP/Diameter):** Not implemented in application repos; only a **northbound integration contract** is in scope for SolaceNet if a telecom boundary service is added.
+- **All TypeScript gateway rail adapters** under `src/core/gateway/adapters/` remain **scaffolds** (synthetic success or evidence-only stubs) until replaced with live connectors.
+- **KTT evidence adapter:** `send` is explicitly unsupported; **validate** is trivial; no system-of-record match.
+- **DBIS Rail on-chain contracts** (RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController): **not deployed** per Proxmox DBIS Rail master status; **owner mint** vs **router-only mint** remains a gap.
+- **Quantum / QPS** — **Partial:** `LegacyProtocol` now includes SolaceNet-aligned rails (KTT evidence, TT, DTC/DTCC, gpi, Mojaloop, RTGS, card); scoring remains **scaffold** until field contracts are frozen.
+- **Admin dashboards** (`gas-qps`, `global-overview`, `scb-overview`): **placeholder** rail metrics and profiles.
+- **RTGS / external bank protocols:** Many matrix rows **Planned** or **Partial** (Mojaloop, BNI, correspondent/SWIFT live contracts, ISO evidence packages, etc.)—see `docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md` in the Proxmox repo.
+
+---
+
+## 2. Inconsistencies (architecture and naming)
+
+| Topic | Issue |
+|--------|--------|
+| **Dual adapter systems** | **Mitigated (doc):** [PLUGIN_AND_GATEWAY_BRIDGE.md](../PLUGIN_AND_GATEWAY_BRIDGE.md). **Remaining:** optional facade in code if one physical connector serves both shapes. |
+| **KTT vs other rails** | Marketplace lists **KTT Legacy** next to full **send/receive** rails; code is **evidence-only** and **send** fails by design. |
+| **Synthetic success** | SWIFT FIN / TT scaffolds return **SENT** without network I/O; **KTT** returns **FAILED** on send—mixed semantics for “outbox” testing. |
+| **Thirdweb in gateway folder** | Shares adapter plane with **bank rails**; not a messaging rail—boundary should stay documented for integrators. |
+| **Offering copy vs reality** | `gateway-microservices-offering.json` describes a regulated fabric; **implementations are not production-grade** connectors yet. |
+| **QPS dashboard “SWIFT” volume** | Derived from `iso_messages` heuristics (`messageType.includes('SWIFT')`)—**not** true SWIFT FIN volume. |
+
+---
+
+## 3. Public web and documentation gaps
+
+| Topic | Issue |
+|--------|--------|
+| **info.defi-oracle.io** | **Mitigated:** `/solacenet` SPA page and nav link; `agent-hints.json`, `sitemap.xml`, `llms.txt`, and `verify:info-defi-oracle-public` updated. Deep technical docs remain in repo markdown only. |
+| **Cross-repo discovery** | **Mitigated:** `docs/04-configuration/SOLACENET_PUBLIC_HUB.md` indexes public web + `dbis_core/docs/solacenet/`. |
+| **Agent hints / sitemap** | Ongoing hygiene: any **new** public routes must update the same artifacts. |
+
+---
+
+## 4. Recommended next steps (ordered)
+
+1. Keep **PROTOCOL_GAPS_CHECKLIST.md** statuses current as code changes.  
+2. Enforce **SolaceNet capability checks** on any new rail ingress path.  
+3. Replace scaffolds **rail-by-rail** with sandbox then production connectors; update **public** pages to reflect “generally available” only when true.  
+4. Unify or document **PluginRegistry ↔ gateway adapters** with one facade.  
+5. Align **quantum** protocol enums with **marketplace** rails or explicitly exclude them.  
+
+---
+
+## Related documents
+
+- [PROTOCOL_GAPS_CHECKLIST.md](../PROTOCOL_GAPS_CHECKLIST.md)  
+- [RAIL_AND_PROTOCOL_GOVERNANCE.md](../RAIL_AND_PROTOCOL_GOVERNANCE.md)  
+- Proxmox: [DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](../../../../docs/03-deployment/DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md)  
+- Proxmox: [DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md](../../../../docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md)
--- a/docs/solacenet/public/OVERVIEW.md
+++ b/docs/solacenet/public/OVERVIEW.md
@@ -0,0 +1,39 @@
+# SolaceNet — public overview
+
+**Audience:** Institutions, integrators, and supervisors evaluating how **capabilities, policy, and rails** are governed in the DBIS Core stack. This page is **non-operational**: it does not expose credentials, internal endpoints, or live tenant data.
+
+---
+
+## What SolaceNet is
+
+**SolaceNet** is the **capability and control plane** in DBIS Core: it registers **what** product functions may run (payment gateway, tokenization, limits, fees, **gateway microservices / rail adapters**), for **whom** (tenant, program, region, channel), and under **which policy** (allow/deny, kill switch, audit). The **Go API gateway** (`dbis_core/gateway/go/`) can enforce capability checks at the edge before traffic reaches Node services.
+
+**Rail and messaging protocols** (for example SWIFT families, DTC/DTCC, telegraphic transfer routes, legacy evidence ingest such as KTT) are **maintained under SolaceNet**—see internal governance: `docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md`.
+
+---
+
+## What the public should expect
+
+| Topic | Public | Authenticated / contract |
+|--------|--------|---------------------------|
+| **Existence and scope** of SolaceNet | Yes — this document and the info hub page | — |
+| **Capability names and high-level behavior** | Summarized | Full API schemas and runbooks |
+| **Rail adapter wire protocols** | Described at category level only | Message formats, endpoints, keys, IPs |
+| **Production status** | “Integration in progress” where adapters are scaffolds | Environment-specific readiness |
+| **Chain 138 settlement** | Via [info.defi-oracle.io](https://info.defi-oracle.io) hub and explorer | DBIS Rail / RTGS runbooks (restricted) |
+
+---
+
+## Related reading (repository)
+
+- **Governance:** `dbis_core/docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md`
+- **Protocol gap tracking:** `dbis_core/docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md`
+- **Gaps and inconsistencies (product/doc):** `dbis_core/docs/solacenet/public/GAPS_AND_INCONSISTENCIES.md`
+- **Operator quick reference:** `dbis_core/SOLACENET_QUICK_REFERENCE.md`
+- **Proxmox public hub pointer:** `docs/04-configuration/SOLACENET_PUBLIC_HUB.md`
+- **Authenticated API (integrators):** `GET /api/v1/gateway/rails` and related routes on DBIS Core (see `gateway.routes.ts`); optional `SOLACENET_GATEWAY_RAILS_ENFORCE` — `dbis_core/.env.example`
+
+---
+
+**Version:** 1.0  
+**Last updated:** 2026-04-07
--- a/docs/solacenet/public/README.md
+++ b/docs/solacenet/public/README.md
@@ -0,0 +1,12 @@
+# SolaceNet — public documentation (markdown)
+
+Markdown in this folder is the **canonical source** for public-facing SolaceNet narrative. The live **web** summary is published on **https://info.defi-oracle.io/solacenet** (see `info-defi-oracle-138` in the Proxmox repo).
+
+| File | Purpose |
+|------|---------|
+| [OVERVIEW.md](OVERVIEW.md) | What SolaceNet is; public vs authenticated expectations; repo pointers |
+| [GAPS_AND_INCONSISTENCIES.md](GAPS_AND_INCONSISTENCIES.md) | Consolidated gaps and doc/product inconsistencies |
+
+**Internal** (not necessarily reproduced on the public site): [RAIL_AND_PROTOCOL_GOVERNANCE.md](../RAIL_AND_PROTOCOL_GOVERNANCE.md), [PROTOCOL_GAPS_CHECKLIST.md](../PROTOCOL_GAPS_CHECKLIST.md), [REMAINING_TASKS_FULL_LIST.md](../REMAINING_TASKS_FULL_LIST.md) (prioritized backlog), [AUDIT_GAPS_INCONSISTENCIES_MISSING.md](../AUDIT_GAPS_INCONSISTENCIES_MISSING.md) (delta audit), [PLUGIN_AND_GATEWAY_BRIDGE.md](../PLUGIN_AND_GATEWAY_BRIDGE.md).
+
+**Operator index:** `docs/04-configuration/SOLACENET_PUBLIC_HUB.md` (Proxmox repo root).
--- a/docs/solacenet/schemas/telecom-northbound-event.example.json
+++ b/docs/solacenet/schemas/telecom-northbound-event.example.json
@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dbis.example/schemas/solacenet/telecom-northbound-event.example.json",
+  "title": "Telecom boundary → Core northbound event (example)",
+  "description": "Placeholder contract for PG-QP-003 when a carrier boundary service exists. Not wire format for SS7; JSON over HTTPS/Kafka from the boundary only.",
+  "type": "object",
+  "required": ["eventId", "eventType", "occurredAt", "correlationId", "tenantId"],
+  "properties": {
+    "eventId": { "type": "string", "format": "uuid" },
+    "eventType": {
+      "type": "string",
+      "examples": ["carrier.signaling.observed", "carrier.route.health", "carrier.fraud.signal"]
+    },
+    "occurredAt": { "type": "string", "format": "date-time" },
+    "correlationId": { "type": "string" },
+    "tenantId": { "type": "string" },
+    "programId": { "type": "string" },
+    "region": { "type": "string" },
+    "channel": { "type": "string", "const": "TELECOM_NORTHBOUND" },
+    "payload": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Opaque carrier-normalized facts; no raw MAP/CAP on this bus."
+    }
+  },
+  "additionalProperties": false
+}