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. 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).

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.
• 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 (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):

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

Batch response (example shape):

{
  "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 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	Full JIS blueprint (subsystems, storage, visualization, global coverage).
hybx_compliance_routing_sidecar_technical_plan.md	Sidecar engines, API sketch, evaluation flow.
hybx_routing_graph_data_model.md	Routing vertices/edges, costVector, jurisdiction overlays.
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