# PrismClaim — implementation map

**Status:** Active (2026-08-19)  
**Core package:** `prismclaim/prismclaim-core` v0.1.0 (6 tests passing)  
**Architecture:** [master-architecture-v3.1.md](master-architecture-v3.1.md) · **Contracts:** [contracts-addendum-v3.2.md](contracts-addendum-v3.2.md) · **Stack split:** [composition-map.md](composition-map.md)

This document traces what exists today and what to build next. It is the PrismClaim counterpart to `docs/prismsql-implementation.md`.

---

## What this system is

A **hosted verification middleware** for **837P professional claims**. Customers POST a proposed claim (or note-only in Autonomous Agent Mode) with clinical documentation. PrismClaim returns `ACCEPT`, `REVIEW`, or `REFUSE` with evidence coverage, violations, versioned hashes, and optional human clearance (`claim_hash_v2`).

**Form factor:** Managed REST API in the existing InsightITS API container (`meeting-scheduler` Flask app), JWT + membership/licensing (same pattern as PrismSQL), MCP tools for agent loops, plus docs and product landing when the API is live.

**Not in v1:** Institutional (837I), dental, clearinghouse submission, ChorusGraph as a hard dependency.

---

## Local stack inventory (available now)

| Package | Location | Pin | PrismClaim use |
|---------|----------|-----|----------------|
| **vectorprism** | `C:\code\VectorPrism` (editable git) | 0.1.x | Taxonomy retrieval, epistemic pre-checks — after medical corpus ingest |
| **prismmanifest** | pip / Shield vendor tree | 0.3.4 | `ProvenanceSpan`, `FieldClaim`, Ed25519 sealing |
| **prism-shield** | `C:\code\Prism_shield` (editable git) | 0.2.x | Tri-state gate, escalation, replay guard, KMS |
| **chorusgraph** | `C:\code\ChorusGraph` (editable git) | 1.3.0 | **Optional** — `route_ledger_ref` when agent graph runs |
| **PrismSQL precedent** | `meeting-scheduler/prismsql/` | — | Blueprint, tiers, store, billing, JWT auth template |

PrismManifest catalog: *“Works with any orchestrator — ChorusGraph optional.”* Proposed Mode uses a **linear pipeline** (`chorusgraph: false` pattern, same as hosted PrismSQL).

---

## Code that exists today

### `prismclaim-core` (landed)

```
prismclaim-core/src/prismclaim_core/
  enums.py              DecisionState, TrustTier, ResolutionAction, GroundingStatus, …
  hashing.py            canonical_json, compute_claim_hash_v1/v2
  models/
    claim.py            CanonicalClaim837P, UntrustedCandidateFacts
    evidence.py         EvidenceSpan, FieldEvidenceBinding
    audit.py            AuditManifestV1, HumanClearanceRecord
    requests.py         VerifyClaimRequest, ResolveEscalationRequest
    responses.py        ClaimVerificationResponse, Violation
  adapters/             NotImplementedError until wired to libs
    vectorprism.py      taxonomy pre-checks
    prismmanifest.py    seal evidence manifest
    prismshield.py      release gate
    chorusgraph.py      route ledger ref (optional)
  stubs/                Explicit gap markers
    policy.py           YAML rule engine
    extraction.py       Autonomous Agent Mode extractors
    ontology.py         CPT/ICD VectorPrism corpus
    phi_custody.py      S3 / note bytes resolver
    jobs.py             async 202 polling
    batch_ingest.py     S3 batch drops
    audit_bundle.py     payer audit export
```

**Small additions beyond the initial Pydantic snippet:**

| Addition | Module | Purpose |
|----------|--------|---------|
| Typed enums | `enums.py` | `GroundingStatus`, `CheckResult` — not raw strings on bindings/checks |
| API request models | `models/requests.py` | `VerifyClaimRequest`, `ResolveEscalationRequest` for Flask wiring |
| Hash helpers | `hashing.py` | `canonical_json()`, `compute_claim_hash_v1/v2` — audit byte flow |
| Honest stubs | `stubs/*`, `adapters/*` | `NotImplementedError` + gap context — no fake ACCEPT/REFUSE |

**Suggested next step:** Flask blueprint in `meeting-scheduler/prismclaim/` mirroring `prismsql/blueprint.py`, **or** policy bundle loader first (`policy/loader.py` + contracts §5 YAML) if engine-before-HTTP is preferred. Order: blueprint shell → engine (fixture notes) → policy loader → Shield adapter.

### `meeting-scheduler/prismclaim/` (landed — Phase 1–2)

```
meeting-scheduler/prismclaim/
  blueprint.py          /api/prismclaim/v1/* (verify, jobs, replay, resolve, audit-bundle, me, checkout)
  engine.py             verify pipeline, replay, resolve, audit-bundle
  store.py              Postgres subscribers, claims, escalations, jobs, usage
  tiers.py              sandbox / developer / pro / enterprise
  billing.py            Stripe checkout
  policy/loader.py      policy_v2.4.1.yaml evaluator
  evidence.py           evidence graph + coverage
  extraction.py         deterministic candidate extraction v1
  manifest.py           evidence_manifest_hash (+ optional Manifest seal)
  conflict.py           proposed vs untrusted divergence → REVIEW
nginx/conf.d/snippets/prismclaim-api.inc
meeting-scheduler/mcp_tools/prismclaim_*.json
docs/prismclaim-api.md · docs/prismclaim-implementation.md
products/prismclaim.html
catalog/prismclaim.json · catalog/prismclaim.md
```

### Still stubbed / Phase 3+

```
prismclaim_core adapters   VectorPrism ontology, full Manifest Ed25519, Shield when PRISMCLAIM_SHIELD_ENABLED
S3 clinical_note_uri       phi_custody — use clinical_note_text until wired
Batch S3 ingress           batch_ingest stub
Dashboard tab              dashboard.html#prismclaim (portal + verify form)
React landing              src/pages/products/prismclaim-landing/ + guides/claim-verification.html
```

---

## Target layers (build order)

```
HTTP Flask
  prismclaim/blueprint.py       POST /api/prismclaim/v1/claims/verify, …
Auth
  utils.auth.require_auth       JWT email = tenant principal (same as PrismSQL)
Account / entitlement
  prismclaim/store.py           prismclaim_subscribers, claims, escalations, usage
  prismclaim/tiers.py           claim/month limits, HITL seats, async jobs
  prismclaim/billing.py         Stripe checkout
Ingress
  prismclaim/guard.py           PrismGuard (fail closed)
  prismclaim/conflict.py        proposed vs untrusted → REVIEW (no auto-correct)
Orchestration (PrismClaim-owned)
  prismclaim/engine.py          linear verify pipeline
  prismclaim/evidence.py        coverage ratio, bindings
Delegates
  adapters/vectorprism.py       → local vectorprism after ontology ingest
  adapters/prismmanifest.py     → ProvenanceSpan map + seal
  adapters/prismshield.py       → PrismShieldGateway
  adapters/chorusgraph.py       → optional route ledger
Policy (PrismClaim-owned)
  prismclaim/policy/loader.py   versioned YAML bundles
  stubs/policy.py               replace with real evaluator
Hash / audit (PrismClaim-owned)
  hashing.py                    already in prismclaim-core
  store                         persist v1/v2, replay pins
Out
  prismclaim/errors.py          fail-closed refuse codes
  audit + audit-bundle export
```

---

## Data flow — verify (target)

```mermaid
flowchart TD
  A[JWT + VerifyClaimRequest] --> B[ensure_subscriber + tier check]
  B --> C[resolve clinical note — phi_custody]
  C --> D[extract or accept proposed_claim]
  D --> E{proposed vs untrusted diverge?}
  E -->|yes| F[force REVIEW + divergence violation]
  E -->|no| G[VectorPrism taxonomy pre-check]
  G --> H[policy bundle evaluate]
  H --> I[evidence graph + coverage]
  I --> J[PrismManifest seal]
  J --> K[Prism-Shield gate]
  K --> L[claim_hash_v1 + ClaimVerificationResponse]
  F --> L
```

Human path: `POST …/escalations/{id}/resolve` → `ResolutionAction` → `claim_hash_v2` → updated clearance record.

---

## API mount (target)

| Method | Path | Model |
|--------|------|--------|
| POST | `/api/prismclaim/v1/claims/verify` | `VerifyClaimRequest` → `ClaimVerificationResponse` or 202 |
| GET | `/api/prismclaim/v1/jobs/{ticket_id}` | stub → job schema TBD |
| POST | `/api/prismclaim/v1/claims/{id}/replay` | historical / diagnostic pins |
| POST | `/api/prismclaim/v1/escalations/{id}/resolve` | `ResolveEscalationRequest` |
| GET | `/api/prismclaim/v1/claims/{id}/audit-bundle` | stub → export format TBD |

Register in `meeting-scheduler/app.py` alongside `prismsql_bp`.

---

## PrismSQL files to copy as template

| PrismSQL | PrismClaim equivalent |
|----------|----------------------|
| `prismsql/blueprint.py` | `prismclaim/blueprint.py` |
| `prismsql/store.py` | `prismclaim/store.py` |
| `prismsql/tiers.py` | `prismclaim/tiers.py` |
| `prismsql/billing.py` | `prismclaim/billing.py` |
| `prismsql/engine.py` | `prismclaim/engine.py` |
| `prismsql/errors.py` | `prismclaim/errors.py` |
| `docs/prismsql-api.md` | `docs/prismclaim-api.md` |
| `catalog/prismsql.json` | `catalog/prismclaim.json` |

---

## Related docs

- [Implementation readiness](implementation-readiness.md) — go / no-go and remaining gaps
- [Ship checklist](ship-checklist.md) — landing, MCP, catalog, deploy