proxmox/hybx_jurisdictional_cheat_sheets_implementation_roadmap.md

# HYBX Jurisdictional Cheat Sheets — Implementation Roadmap

This document **operationalizes** the blueprint in [hybx_jurisdictional_cheat_sheets_technical_plan.md](hybx_jurisdictional_cheat_sheets_technical_plan.md). It defines build order, a **canonical schema v1**, API/service boundaries, integration contracts with the Compliance & Routing Sidecar and the routing graph model, and explicit non-goals. It does not replace the technical plan.

---

## 1. Scope statement

- **Inherits** the JIS vision: deterministic jurisdiction knowledge for banking, payments, liquidity, settlement, and regulatory execution (see technical plan Purpose and Core Objective).
- **This roadmap** only specifies: what to implement first, schema norms, MVP geography, read APIs, and how consumers (especially the sidecar) call JIS.
- **Out of roadmap detail**: full legal research, production data feeds, and UI design specs (covered at a high level only).

---

## 2. Architecture placement

JIS is a **read-mostly fact service**. It is **not** the Policy DSL: policies interpret facts; JIS supplies structured **facts** (permissions, rails, risk tiers, citations).

```mermaid
flowchart LR
  Composer[Transaction_Composer]
  Orch[Orchestrator]
  Sidecar[Compliance_Routing_Sidecar]
  JIS[JIS_Service]
  Policy[Policy_DSL_future]
  Composer --> Orch
  Orch --> Sidecar
  Sidecar --> JIS
  Sidecar --> Policy
  JIS -.->|facts_only| Sidecar
```

**Flow (conceptual):** Transaction graph / compiled transaction enters the sidecar; sidecar performs jurisdiction lookup against JIS (by ids, currencies, corridor pairs); sidecar combines JIS outputs with internal rules and optional future Policy DSL to produce PASS/WARN/FAIL, routing constraints, and explainable decisions.

---

## 3. Canonical schema v1 (normative for code)

Aligns with the technical plan “Data Model Design / Core Structure” example. All profiles are JSON-serializable documents stored as versioned rows.

### 3.1 Root envelope (every stored profile)

| Field | MVP required | Full profile | Description |
|--------|--------------|--------------|-------------|
| `schemaVersion` | yes | yes | e.g. `"1.0.0"` for this spec. |
| `jurisdictionId` | yes | yes | Stable id (see section 4). |
| `profileVersion` | yes | yes | Semver or monotonic string for this jurisdiction’s content. |
| `effectiveFrom` | yes | yes | ISO-8601 date/time. |
| `effectiveTo` | no | optional | Null if current. |
| `dataQuality` | yes | yes | `complete` \| `partial` \| `stub` — MVP seeds often `partial` or `stub`. |
| `sourceRefs` | recommended | yes | Array of `{ "title", "url"?, "publisher"?, "retrievedAt"? }` per subsection or aggregated. |
| `core` | yes | yes | Registry fields (see 3.2). |
| `currencyRules` | yes | yes | Array or map by currency code; see 3.3. |
| `fxRules` | yes | yes | FX convertibility, controls, limits (may be stub). |
| `settlementSystems` | yes | yes | List of settlement rail summaries. |
| `licensingRules` | partial | yes | License types applicable in jurisdiction; MVP may be empty array with `dataQuality`. |
| `crossBorderRules` | partial | yes | Inbound/outbound, restricted jurisdictions. |
| `riskProfile` | yes | yes | Political/financial/sanctions tiers as scalars or enums. |
| `sanctions` | no | optional | Module from technical plan § Sanctions Intelligence. |
| `documentation` | no | optional | Required doc types for payments. |
| `feeGovernance` | no | optional | Max fees, disclosures (technical plan § Fee Governance). |

### 3.2 `core` (jurisdiction registry)

Minimum MVP fields:

- `countryName`, `isoCountryCode` (ISO 3166-1 alpha-2)
- `primaryFinancialRegulator` (string)
- `legalSystemType` (enum or string)
- `centralBankName` (string)
- `primaryCurrency` (ISO 4217)
- `timeZones` (string[])
- `politicalRiskTier`, `financialRiskTier` (string or number; align with technical plan Risk Intelligence)

Full profile adds: region, capital, secondary regulators, languages, extended sanctions status fields as in technical plan.

### 3.3 `currencyRules` (per currency or default)

Each entry should support at least:

- `currency` (ISO 4217)
- `convertibilityLevel` (enum: e.g. `fully_convertible`, `managed`, `restricted`)
- `settlementType` (string or enum)
- `liquidityAvailability` (enum or coarse string)
- `centralBankRestrictions` (string, optional)

### 3.4 Versioning rules

- **schemaVersion**: bump **minor** for backward-compatible new optional fields; **major** for breaking renames.
- **profileVersion**: independent per `jurisdictionId`; any material regulatory update increments profile version and sets `effectiveFrom`.

---

## 4. Jurisdiction ID scheme

- **Default:** ISO 3166-1 alpha-2 uppercase (`ID`, `US`, `SG`, `GB`).
- **Sub-national or zones:** use hyphenated suffixes, e.g. `US-NY` only if the product truly needs sub-national rules; otherwise keep national id and encode specificity in `core` or overlays.
- **EU:** prefer national ids (`DE`, `FR`) for MVP; introduce `EU` or `EU-DE` only when cross-EU harmonized profiles are maintained as first-class rows.
- **Special financial centers:** e.g. `HK`, `MO` as ISO codes; avoid custom ids unless they are registered in an internal enum table.

Document every non-ISO id in a single **registry table** in the implementation repo.

---

## 5. Phased delivery

| Phase | Goal | Outcome |
|-------|------|--------|
| **0** | Schema + validation | JSON Schema (or TypeScript types) + validator; one sample fixture (e.g. `ID`) that validates. |
| **1** | JIS MVP service | `GET /jurisdiction/{id}` returns active profile by id; `POST /jurisdiction/query` with `{ "ids": string[] }` returns map id → profile; store in **Postgres** (prod) or **SQLite** (local dev); **no Elasticsearch**. |
| **2** | Pilot dataset | Seed **5–10** jurisdictions; **minimum** `ID`, `US`, `SG`, `GB`. Use `dataQuality: partial` or `stub` and `sourceRefs` where legal detail is incomplete. |
| **3** | Sidecar integration contract | Written contract (this section expanded in runbooks): request/response fields, caching, error handling; optional `constraintHints` for routing graph (see section 6). |
| **4** | Search (optional) | Add Elasticsearch or Postgres FTS **only** when query patterns exceed id/batch lookup. |
| **5** | Dashboard / visualization | Defer until API and seeds are stable (technical plan Visualization). |

---

## 6. Integration with existing HYBX artifacts

### 6.1 Compliance & Routing Sidecar

- Reference: [hybx_compliance_routing_sidecar_technical_plan.md](hybx_compliance_routing_sidecar_technical_plan.md).
- Sidecar `POST /evaluate-transaction` (or equivalent) should resolve **all jurisdiction ids** present on the transaction graph, participant registry, or routing plan, then call JIS (batch) before or during compliance/routing engines.
- JIS returns **facts only**; the sidecar applies rules (AML/KYC/sanctions workflows may still use other services; JIS supplies jurisdiction-grounded permissions and tiers).

### 6.2 Routing graph data model

- Reference: [hybx_routing_graph_data_model.md](hybx_routing_graph_data_model.md) (jurisdiction overlays, `regulatoryPenalty`, transaction-level filters).
- **Mapping:** JIS `riskProfile`, `fxRules`, `crossBorderRules`, and `currencyRules` inform:
  - vertex `jurisdiction` and `capabilities` validation;
  - edge `jurisdictions[]` tags and suggested `costVector.regulatoryPenalty` (sidecar computes penalty from JIS facts + policy weights).
- JIS does **not** store the routing graph; it **constrains** how the graph may be traversed.

### 6.3 Transaction Composer

- Optional future: jurisdiction pickers on nodes, auto-tagging `jurisdictionId` on `TransactionNodeData`. **Out of scope** for phases 0–1 unless product prioritizes it.
- Composer continues to emit design-time graphs; orchestrator/sidecar enrich with registry ids.

---

## 7. Sidecar integration contract (phase 3 deliverable detail)

**Batch request (example):**

```json
{
  "jurisdictionIds": ["ID", "US"],
  "context": {
    "currencies": ["USD", "IDR"],
    "corridor": { "fromJurisdiction": "US", "toJurisdiction": "ID" },
    "effectiveAt": "2026-03-29T12:00:00Z"
  }
}
```

**Batch response (example shape):**

```json
{
  "profiles": {
    "ID": { "schemaVersion": "1.0.0", "jurisdictionId": "ID", "profileVersion": "0.1.0", "dataQuality": "partial", "core": {}, "currencyRules": [], "fxRules": {}, "settlementSystems": [], "crossBorderRules": {}, "riskProfile": {} }
  },
  "notFound": []
}
```

**Errors:** HTTP 404 for unknown id on single GET; batch omits missing ids in `profiles` and lists them in `notFound` (or returns explicit errors—choose one behavior and document in OpenAPI).

**Caching:** Sidecar or API gateway may cache by `(jurisdictionId, profileVersion)` with TTL aligned to technical plan (configurable; target lookup < 100 ms p95 at steady state with cache).

---

## 8. Data acquisition and legal posture

- **MVP:** Manually curated YAML/JSON seeds in-repo or loaded from migration; every non-trivial field should have `sourceRefs` where possible.
- **Production expansion:** Licensed legal/regulatory data providers and official publications (technical plan Data Acquisition Model). **No** commitment to automated scraping in MVP code paths.
- **Disclaimer:** Profiles are engineering aids; final legal interpretation remains with compliance officers and counsel.

---

## 9. Non-goals (explicit)

- Full **global coverage** on day one (technical plan Phase 1/2 expansion applies).
- **Real-time** regulatory crawling as a blocking dependency for MVP.
- **Multilingual** content in MVP (technical plan Localization deferred).
- **Graph database** for JIS core (optional in technical plan; not required for MVP).
- Replacing **sanctions screening vendors** or **KYC** systems—JIS complements them with jurisdiction facts.

---

## 10. Acceptance criteria (“MVP ready”)

1. At least **four** jurisdiction profiles (`ID`, `US`, `SG`, `GB`) validate against **schema v1**.
2. `GET /jurisdiction/{id}` and `POST /jurisdiction/query` implemented and documented (OpenAPI or equivalent).
3. With a **warm cache**, p95 read latency meets **< 100 ms** internal target under nominal load (align with technical plan Performance Targets).
4. **One worked example** documented end-to-end: transaction touching **USD→IDR** with participants in **US** and **ID**, showing which JIS fields the sidecar would read for FX and cross-border checks, and how results feed [hybx_routing_graph_data_model.md](hybx_routing_graph_data_model.md) overlays.

### Worked example (narrative)

- Transaction: remitter in **US**, beneficiary bank in **ID**, USD notionally converted to IDR.
- Sidecar resolves `US` and `ID` profiles; checks `fxRules` and `crossBorderRules` for both; reads `currencyRules` for USD/IDR; compares against transaction amounts and rails in the routing plan.
- If a rule indicates heightened friction, sidecar may set routing graph `regulatoryPenalty` on affected edges or return WARN with explanation references to `sourceRefs`.

---

## 11. References

| Document | Role |
|----------|------|
| [hybx_jurisdictional_cheat_sheets_technical_plan.md](hybx_jurisdictional_cheat_sheets_technical_plan.md) | Full JIS blueprint (subsystems, storage, visualization, global coverage). |
| [hybx_compliance_routing_sidecar_technical_plan.md](hybx_compliance_routing_sidecar_technical_plan.md) | Sidecar engines, API sketch, evaluation flow. |
| [hybx_routing_graph_data_model.md](hybx_routing_graph_data_model.md) | Routing vertices/edges, `costVector`, jurisdiction overlays. |
| [transaction-composer/](transaction-composer/) | Design-time transaction graph and compiler (optional future jurisdiction fields). |

---

## Document control

| Item | Value |
|------|--------|
| Roadmap version | 1.0 |
| Aligns with technical plan | As of repo snapshot; amend when blueprint changes |
| Next reviews | After phase 1 API freeze; after first pilot dataset sign-off |