fi-fhir docs

fi-fhir Component Status Matrix

Single source of truth for component maturity, test coverage, and freshness. Refresh with make docs-status after significant merges.

Summary

Maturity	Count	Description
Production	22	Stable, tested, deployed
Beta	9	Feature-complete, needs coverage or hardening
Alpha	5	Functional but limited testing or scope
Planned	2	Designed but not yet implemented (tracked via #7, #8)

Parsers (`internal/parser/*`)

Component	Path	Maturity	Coverage	Notes	Last Updated
HL7v2 Parser	`internal/parser/hl7v2/`	Production	84.3%	Legacy adapters plus strict published A01 path	2026-07-13
CSV Parser	`internal/parser/csv/`	Production	82.0%	Schema inference for patient/lab records	2026-01-14
EDI X12 Parser	`internal/parser/edi/`	Production	73.9%	837P, 835, 270/271, 276/277; loop parsing	2026-01-14
EDI Companion Guides	`internal/parser/edi/companion/`	Production	89.1%	Medicare, BlueCross, United built-in guides	2026-01-14
CDA/CCDA Parser	`internal/parser/cda/`	Production	85.8%	Namespace-aware XML, section handlers	2026-02-07
FHIR Parser	`internal/parser/fhir/`	Production	95.2%	FHIR R4 resource ingestion	2026-01-14

Core Libraries (`pkg/*`)

Component	Path	Maturity	Coverage	Notes	Last Updated
Events (canonical model)	`pkg/events/`	Production	80.5%	Immutable semantic event types	2026-03-09
Event Sourcing	`pkg/eventsourcing/`	Production	72.7%	Store, projections, snapshots, sagas, outbox	2026-02-27
ES Projections	`pkg/eventsourcing/projections/`	Production	88.9%	Patient timeline, stats, active encounters	2026-01-14
Config	`pkg/config/`	Production	89.3%	Layered loading (defaults → file → env), secrets	2026-02-27
Integration Contracts	`pkg/integration/`	Alpha	89.8%	Exact provenance plus deployment policy and strict runtime invariants	2026-07-14
Source Profiles	`pkg/profile/`	Beta	71.9%	Inference, linting, vendor templates	2026-02-27
Validators	`pkg/validate/`	Production	98.2%	NPI, MBI, SSN, DEA; Luhn/checksum	2026-01-09
FHIR Mapper	`pkg/fhir/`	Production	75.2%	24+ US Core resources, validation	2026-01-19
ETL Pipeline	`pkg/etl/`	Beta	84.8%	Source/sink framework, CLI commands	2026-02-27
Storage	`pkg/storage/`	Beta	56.5%	Abstraction layer for file/S3/MinIO	2026-02-27
Terminology (core)	`pkg/terminology/`	Production	84.2%	LOINC, ICD-10, fuzzy matching, UMLS	2026-03-07
Terminology DB	`pkg/terminology/db/`	Beta	22.5%	PostgreSQL loaders; needs testcontainers	2026-03-07
Terminology Upload	`pkg/terminology/upload/`	Beta	85.7%	Mapping file upload pipeline	2026-02-03
Terminology Suggest	`pkg/terminology/suggest/`	Beta	83.4%	Suggestion engine; httptest-based coverage	2026-02-28
Terminology Semantic	`pkg/terminology/semantic/`	Production	95.0%	Embedding-based semantic search	2026-02-28
Terminology Index	`pkg/terminology/index/`	Production	92.2%	Vector indexing; httptest + mock coverage	2026-03-03
Patient Matching	`pkg/matching/`	Production	85.3%	Deterministic + probabilistic, MPI, batch	2026-02-27
LLM Client	`pkg/llm/`	Production	86.3%	Multi-provider client, retry, embeddings	2026-03-06
LLM Copilot	`pkg/llm/copilot/`	Production	98.0%†	CEL-based copilot + workflow generation	2026-02-08

Internal Services (`internal/*`)

Component	Path	Maturity	Coverage	Notes	Last Updated
Workflow Engine	`internal/workflow/`	Production	78.6%	Actions plus strict DSL v1 and pure planner	2026-07-13
Integration Processor	`internal/integration/processor/`	Alpha	84.5%	Shared A01 preview/production kernel plus PostgreSQL atomic admission	2026-07-14
Integration Lifecycle	`internal/integration/lifecycle/`	Alpha	—	PostgreSQL versioned state, immutable releases, deployed-only MLLP admission	2026-07-15
HL7v2 MLLP Ingress	`internal/integration/mllp/`	Alpha	—	Lifecycle-gated durable ACK, TLS/client/capacity bounds; GitOps pending	2026-07-15
HL7v2 HTTP Ingress	`internal/integration/ingress/`	Alpha	—	Bearer/HMAC, bounded body, durable response; GitOps activation pending	2026-07-14
Delivery Reliability	`internal/integration/delivery/`	Alpha	—	PostgreSQL leases/retry/circuit/DLQ/recovery plus real Kafka publisher	2026-07-15
Batch Ingestion	`internal/integration/batch/`	Alpha	—	S3/SFTP streaming, PostgreSQL checkpoint/resume, verified archive	2026-07-16
Integration Sessions	`internal/integration/session/`	Alpha	—	Restart-safe workspace, simulation, signed tested-revision publication, exact lifecycle promotion	2026-07-18
Retention Purge	`internal/integration/retention/`	Alpha	—	Per-tenant audited retention policy plus multi-replica purge by tombstone; PostgreSQL-proved	2026-08-09
GraphQL API	`internal/api/graphql/`	Beta	9.5%*	Bounded POST plus session-only SSE; WebSocket disabled	2026-07-16
FHIR Subscriptions	`internal/fhir/subscription/`	Production	83.7%	Bidirectional; client + webhook receiver	2026-02-27
Terminology Autoroute	`internal/terminology/autoroute/`	Beta	92.1%	Routing engine + serve-time pending-expiry sweep + review webhook notifier	2026-08-08
Terminology Workflow	`internal/terminology/workflow/`	Production	95.7%	Temporal workflow + activity + worker unit tests	2026-03-03
LLM Explain	`internal/llm/explain/`	Production	99.7%	Warning + workflow explanation generation	2026-02-28
LLM Extract	`internal/llm/extract/`	Production	84.3%	Structured data extraction from documents	2026-03-09
LLM Quality	`internal/llm/quality/`	Production	93.8%	Data quality analysis	2026-01-23

* GraphQL coverage is low because gqlgen generates ~2000 resolver stubs; actual hand-written resolver logic is well-tested (80.8% in resolvers/ sub-package).

† Copilot coverage is per-package (leaf package not exercised cross-package).

Slice 1.1c shipped in MR !96; main pipeline 18621 passed every blocking gate and published matching API/UI images. GitOps MRs !368 and !369 rolled out their verified digests, passed public auth/origin/containment/provenance/PHI probes, and resumed healthy automation. Exact evidence is recorded in .loom/iteration-plan-phase-1-slice-1-1c-authenticated-preview-adapters.md.

Slice 1.3 adds exact POST /v1/hl7v2 as the first production adapter. MR !99 pipeline 18898 passed 32/32 jobs; required job 182088 ran all 20 PostgreSQL 16 restart, duplicate-collapse, profile-divergence, IDE-parity, preview-side- effect, and leakage assertions. Merge commit 48d156d2 repeated the proof in main job 182694; pipeline 18951 passed 35/35 and published digest-addressed API/UI images. Production GitOps activation and external outbox delivery remain intentionally pending.

Slice 2.1 adds the backend deployment lifecycle contract and PostgreSQL catalog. It keeps legacy integration revision digests stable, records failed and successful connection checks, enforces optimistic lifecycle transitions, prevents revision/ release/history mutation with database triggers, and resolves an exact release only while deployed. MR !101 pipeline 19014 passed 32/32, including lifecycle job 183463; merge commit a95bb44f repeated the lifecycle proof in main job 183702. That main run exposed a pre-existing concurrent receipt primary-key conflict. MR !102 changed receipt insertion to arbitrate either deterministic unique key before the authoritative tenant/idempotency lookup; pipeline 19045 passed 24/24. Final main pipeline 19052 passed 26/26, including durable- submission job 183938 and lifecycle job 183940.

Slice 2.2 adds the optional production MLLP consumer of that catalog. A strict content-addressed UTF-8 listener applies framing/timeouts, TLS 1.3 mutual auth, CIDR, connection, deployed capacity, and ACK policy. Positive ACKs follow the atomic submission commit, and transaction-scoped admission serializes with pause/retire. Unit/race tests and required CI test discovery pass locally; the PostgreSQL 16/TCP proof passed in MR !104 job 184996; pipeline 19175 passed 33/33 and merged as 6205fa39. Main pipeline 19193 passed 36/36 and independently repeated the proof in job 185093. GraphQL and Mapping Studio lifecycle controls and production GitOps activation remain open.

Slice 2.3 adds a PostgreSQL-leased delivery worker, bounded retry and circuit state, durable DLQ, authenticated/idempotent replay and resubmit, and a real Kafka producer with stable attempt keys. Local unit/race/full-suite gates pass; MR !106 pipeline 19226 passed 34/34 with required job 185433 and merged as ca968fbf. Main pipeline 19235 passed 37/37 and independently repeated the PostgreSQL 16/Kafka proof in job 185505.

Slice 2.4 adds an optional lifecycle-gated S3/SFTP batch worker with bounded concatenated-HL7v2 streaming, release-pinned PostgreSQL leases/checkpoints, deterministic admission identity, mandatory S3 versioning/SFTP host-key trust, and verified digest-addressed archive-before-delete. MR !108 pipeline 19331 passed 35/35 with required provider recovery job 186259 and merged as ed32915f. Main pipeline 19344 passed 38/38 and independently repeated the PostgreSQL 16/MinIO/SSH-SFTP proof in job 186476. Production GitOps activation remains intentionally pending.

Slice 3.1 adds an opt-in PostgreSQL Integration Session workspace with durable sessions, redacted-by-default samples, AES-256-GCM explicit retention, append-only artifact revisions, immutable terminal runs, accepted decisions, reopenable exports, and exact profile revision/digest execution. MR !111 pipeline 19409 passed 37/37 with required restart/raw-PHI job 187425 and merged as 15746ccd. Main pipeline 19424 passed 40/40 and independently repeated the proof in job 187618. Production GitOps activation remains intentionally pending.

Slice 3.3 adds exact-revision workflow draft simulation over server-owned immutable session runs. The production pure planner emits PHI-minimal event/route/transform/action traces without executing transforms or actions; PostgreSQL persists those traces and deterministic comparison deltas across restart. Workflow Builder sends revision and run identities rather than browser event payloads. MR !122 pipeline 19872 passed 37/37 with required session job 191685 and benchmark job 191688, and merged as d42f7233; main pipeline 19878 passed 40/40 with independent session job 191786 and benchmark job 191789. Slice 3.4 adds append-only signed publications that prove session profile/workflow content against exact production references before lifecycle approval and deployment. Source Profile reviews now retain a real baseline diff and required actor-attributed change summary. Production GitOps activation remains intentionally pending.

Infrastructure

Coverage Legend

Range	Indicator
≥ 80%	✅ Good
60–79%	⚠️ Acceptable
< 60%	❌ Needs work

Refreshing This Document

make docs-status        # Re-run tests + generate fresh data
make docs-status-quick  # Use existing coverage.out (faster)
make docs-status-check  # Check for coverage drift (CI gate)

Contributor Workflow

After changing Go source code, coverage percentages may shift.
CI runs test:docs-status to detect drift > 5% between this file and computed values.
If the job fails, regenerate: make docs-status then commit the updated docs/STATUS.md.
The drift threshold is configurable via DRIFT_THRESHOLD env var (default: 5.0%).

The scripts/docs-status.sh --check-drift script compares computed coverage from coverage.out against the values in this file and exits non-zero when drift exceeds the threshold.