Healthcare Claims — Implementation Guide
Audience: Healthcare providers, payers, TPAs, implementation teams. Vertical: Healthcare — hospitals, clinics, pharmacies, insurance payers, third-party administrators. Status: Configuration-only design; HIPAA/FHIR boundaries enforced; no bespoke tables. Substrate: Reuses Jijibora building/reflex/community infrastructure; medical claims use the seeded Kenya medical claim pack.
1. Claim Types — Healthcare
| Claim Type | CNS URI | Bound To | Typical Evidence Required |
|---|
| Medical Claim | cns://claim/type/healthcare/medical_claim | resource:patient | Service codes (CPT/ICD-10), clinical report, provider NPI, diagnosis |
| Pharmacy Claim | cns://claim/type/healthcare/pharmacy_claim | resource:patient | Drug NDC, prescriber DEA, pharmacy NABP, diagnosis, quantity |
| Prior Authorization | cns://claim/type/healthcare/prior_auth | resource:patient | Clinical justification, service request, payer approval |
| Service Dispute | cns://claim/type/healthcare/service_dispute | claim:medical_claim | Itemized bill, EOB, patient complaint, provider response |
| Pharmacy Benefit Dispute | cns://claim/type/healthcare/pharmacy_dispute | claim:pharmacy_claim | Prescription fill record, formulary, copay receipt |
2. PHI Protection Boundaries
Healthcare claims never declare raw sensitive health fields in the claim record. Sensitive clinical data (diagnoses, treatment notes, lab results) is stored in MinIO with encrypted access and referenced by hash in the claim metadata field.
| Field | Stored In Claim? | Storage Location | Access Control |
|---|
| Patient name, ID | Yes (truth_node) | truth_node:person | APF role-based, BBS+ selective disclosure |
| Diagnosis codes | No | MinIO (encrypted) | Hash reference in claim metadata |
| Treatment notes | No | MinIO (encrypted) | Hash reference in claim metadata |
| Service codes (CPT/ICD-10) | Yes | Claim metadata | APF: adjuster, reinsurer roles only |
| Provider NPI | Yes | Claim metadata | APF: provider panel roles |
| Pharmacy NDC | Yes | Claim metadata | APF: pharmacy benefit manager |
Match facets are scrubbed: surprising raw metadata inside a facet is refused rather than matched. Private detail never travels in a public notice.
3. Guard Policies — Healthcare
3.1 Separation of Duties
| Claim Type | Creator May Approve? | Barred Pairs | Notes |
|---|
| Medical Claim | No | Adjuster ↔ Provider | Adjuster assesses; provider renders care — different persons |
| Pharmacy Claim | No | Pharmacist ↔ Prescriber | Pharmacist dispenses; prescriber prescribes — different persons |
| Prior Auth | No | Requester ↔ Approver | Requesting provider cannot approve their own prior auth |
| Service Dispute | No | Biller ↔ Complaint Reviewer | Different parties |
3.2 Quorum Bands
| Amount Range | Risk | Quorum | Approver Roles |
|---|
| < $500 | Low | One-person standard | Adjuster |
| $500 – $5,000 | Mid | Two-person | Adjuster + reinsurer |
| > $5,000 | High | Three-person | Adjuster + reinsurer + medical director |
| Prior Auth | Any | Two-person | Adjuster + medical director |
| Litigation | Any | Cross-agency | Legal + external auditor + reinsurer |
3.3 Evidence Requirements
| Claim Type | Required Evidence | Source |
|---|
| Medical Claim | Service codes (CPT/ICD-10), clinical report, provider NPI | EHR integration + claim record |
| Pharmacy Claim | Drug NDC, prescriber DEA, pharmacy NABP, quantity | Pharmacy management system |
| Prior Auth | Clinical justification, service request | Provider portal + medical records |
| Service Dispute | Itemized bill, EOB, patient complaint | Billing system + payer EOB |
4. Panel Roles — Healthcare
| Role | Capabilities Required | Attestation | Lease TTL | Claim Types |
|---|
| Adjuster | loss_assessment, medical_adjudication, claims_review | Yes | 1 hour | All |
| Reinsurer | reinsurance, evidence_review, catastrophe_assessment | Yes | 8 hours | High-value, litigation |
| Medical Director | clinical_review, prior_auth_approve, utilization_review | Yes | 8 hours | Prior auth, high-value medical |
| Provider (clinic/pharmacy) | service_rendered, dispensing, clinical_documentation | Yes | 1 hour | Medical claim, pharmacy claim |
All roles require: approved affiliation + active status + attestation. Fail-closed: missing values refuse with a service error.
5. SLA Windows — Healthcare
| Claim Type | Severity | Default Window | Escalation To |
|---|
| Medical Claim | Urgent | 72 hours | Adjuster |
| Medical Claim | Standard | 30 days | Reinsurer |
| Pharmacy Claim | Standard | 14 days | Pharmacy benefit manager |
| Prior Authorization | Urgent | 48 hours | Medical director |
| Prior Authorization | Standard | 15 days | Medical director |
| Service Dispute | Standard | 45 days | Adjuster + reinsurer |
6. Intake Maps — Healthcare
| Map ID | Target | Fields Mapped | Source Channels |
|---|
intake:healthcare:medical | claim creation | patient_id, service_codes, provider_npi, diagnosis_codes, place_of_service, claim_amount | EHR, clearinghouse, provider portal, API |
intake:healthcare:pharmacy | claim creation | patient_id, drug_ndc, prescriber_dea, pharmacy_nabp, quantity, days_supply | Pharmacy system, e-prescribing, API |
intake:healthcare:prior-auth | claim creation | patient_id, service_request, clinical_justification, requesting_provider | Provider portal, fax, API |
Intake maps target claim creation only. No raw PHI in intake maps — PHI references only.
7. PoCE Integration Points
| Transition | PoCE Trigger | Evidence Recorded |
|---|
| Notice of loss | fn::lifecycle::start_poce_session | patient, provider, service date, claim type |
| Clinical review | fn::lifecycle::record_poce_step | reviewer, clinical decision, service codes approved |
| Prior auth decision | fn::lifecycle::record_poce_step | approver, decision, conditions, validity period |
| Claim settled | fn::lifecycle::finalize_poce_session | payer, amount, payment reference, EOB |
| Dispute resolved | fn::lifecycle::record_poce_step | resolver, resolution, adjustment amount |
8. Worked Example — Medical Claim (HIPAA/FHIR)
- Provider submits claim via clearinghouse (EDI 837) through Camel gateway (SOAP/XML translation).
- Claim created:
cns://claim/type/healthcare/medical_claim, bound to resource:patient, PHI scrubbed from claim metadata, clinical report stored in MinIO with hash reference. - Adjuster assigned via panel eligibility (two-person quorum for amounts > $500).
- Clinical review performed — service codes validated against diagnosis, medical necessity checked.
- Claim approved — adjuster + reinsurer sign off (quorum reached).
- Claim settled — payment authorized against EOB, PoCE receipt sealed.
- EOB transmitted back to provider via EDI 835 through Camel gateway.
Guard check: Adjuster ≠ Provider (SOD enforced). PHI never in match facets. No settlement without PoCE proof receipt.
9. What We Do Not Build
- No EHR replacement. The EHR remains the clinical system of record; Sovereign OS mirrors billing-relevant data.
- No HIPAA non-compliant data handling. PHI is encrypted at rest, accessed via BBS+ selective disclosure, never in match facets.
- No synthetic "optimal" treatment or cost estimate. Solver down → 502/503 fail closed.
- No fake metrics (e.g., "99% claims auto-adjudicated"). Live data or honest empty states.
10. Deployment
- Deploy strata:
s252_health_claim_display, s264_health_foreign_claim_notify, s282_processing_claim - Seed CNS types:
cns://claim/type/healthcare/* - Seed lookups: guard policies, quorum bands, SLA windows, panel roles, intake maps in NATS KV
- Seed scenario packs: medical claim, pharmacy claim, prior auth packs
- Test:
GET /v1/claims/processing/readiness — all probes must pass before LIVE