@nexalink/coding-contracts 0.2.0 → 0.4.0

package/README.md

@@ -108,14 +108,54 @@ approved evidence set.
 
 ## Main exports
 
-| Category         | Exports                                                                                                                                          |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Types            | `RcmCodingInput`, `RcmCodingOutput`, `RcmSupportingReference`, `RcmModelPrompt`, `RcmRetrievalMetadata`, `RcmRuntimeEvent`, `RcmWorkflowCatalog` |
-| Zod schemas      | `rcmCodingInputSchema`, `rcmCodingOutputSchema`, and one schema for each additional contract type                                                |
-| Validation       | `rcm*ValidationError` functions and `validRcm*` boolean helpers                                                                                  |
-| Workflow policy  | `RCM_WORKFLOW_ID`, `RCM_MODEL_POLICY_ID`, `RCM_HUMAN_REVIEW_POLICY_ID`, `RCM_HUMAN_REVIEW_INSTRUCTION`, `RCM_OUTPUT_SCHEMA_NAME`                 |
-| Schema versions  | `RCM_INPUT_SCHEMA_VERSION`, `RCM_OUTPUT_SCHEMA_VERSION`, `RCM_REFERENCE_SCHEMA_VERSION`, and the other contract wire-version constants           |
-| Schema documents | `Rcm*SchemaJson` values, JSON Schema package subpaths, `versions.json`, and `workflow-constants.json`                                            |
+| Category         | Exports                                                                                                                                                                                                |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Types            | `RcmCodingInput`, `RcmCodingOutput`, `RcmSupportingReference`, `RcmModelPrompt`, `RcmRetrievalMetadata`, `RcmRuntimeEvent`, `RcmReviewerEvent`, `RcmWorkflowCatalog`                                   |
+| Case models      | `CodingCase`, `CodingCaseContext`, `CodingCasePayer`, `CodingCaseClinical`, `CodingServiceLine`, `CodingExtension`, `CodingBatch`                                                                      |
+| Decision models  | `CodingDecision`, `CodingDecisionLine`, `CodingEvidence`, `CodingRuleResult`, `CodingReviewerAction`                                                                                                   |
+| Zod schemas      | `rcmCodingInputSchema`, `rcmCodingOutputSchema`, `codingCaseSchema`, `codingDecisionSchema`, and one schema for each additional contract type                                                          |
+| Validation       | `rcm*ValidationError` functions, `coding*ValidationError` functions, and `valid*` boolean helpers                                                                                                      |
+| Workflow policy  | `RCM_WORKFLOW_ID`, `PIN_TIME_WORKFLOW_ID`, `RCM_MODEL_POLICY_ID`, `RCM_HUMAN_REVIEW_POLICY_ID`, `RCM_HUMAN_REVIEW_INSTRUCTION`, `RCM_OUTPUT_SCHEMA_NAME`                                               |
+| Schema versions  | `RCM_INPUT_SCHEMA_VERSION`, `RCM_OUTPUT_SCHEMA_VERSION`, `RCM_REFERENCE_SCHEMA_VERSION`, `CODING_CASE_SCHEMA_VERSION`, `CODING_DECISION_SCHEMA_VERSION`, and the other contract wire-version constants |
+| Schema documents | `Rcm*SchemaJson`, `Coding*SchemaJson` values, JSON Schema package subpaths, `versions.json`, and `workflow-constants.json`                                                                             |
+
+## Canonical CodingCase and CodingDecision
+
+`CodingCase` is the canonical case envelope for encounter review, claim review,
+longitudinal review, monthly multi-activity time aggregation, and bounded batch
+review. `CodingDecision` is the corresponding reconstructable decision.
+
+- **CodingCase** carries case identity (`caseId` is client-supplied and may be
+  a direct reference; `analyticsId` is the separate analytics-safe identifier),
+  coding intent, the service period, setting/jurisdiction/provider context,
+  payer/plan/program/contract context, structured clinical facts (diagnoses,
+  procedures, medications, supplies, `timeUnits` with `durationMinutes` and
+  `activityCode`, notes, source references), existing claim lines, and
+  namespaced `extensions`.
+- **CodingDecision** references the case by the analytics-safe `caseRef` only,
+  proposes claim-line actions (`add`, `retain`, `replace`, `remove`, `review`)
+  with code identity, modifiers, units, linked diagnoses, and sequencing, and
+  records typed evidence, documentation gaps, conflicts, extracted facts, rule
+  traces, confidence, and the qualified-human-review disposition.
+- **Provenance** (`decisionSchemaVersion`, `caseSchemaVersion`, pack, model,
+  terminology editions with license status, rule versions, retrieval corpus,
+  and generation time) lets every recommendation be reconstructed.
+- **ReviewerAction** is appended immutably: the original decision and the
+  attributable reviewer disposition are both preserved.
+- **Extensions** are `{ namespace, schemaVersion, payload }` objects. Payloads
+  are bounded (at most 50 properties) but otherwise opaque; Nexalink reserves
+  `com.nexalink` and `org.nexalink` namespaces. Extensions keep pack-specific
+  data out of the shared envelope without making every field optional.
+- **Identifiers**: direct identifiers (`caseId`, provider NPIs/names, `memberId`)
+  are documented as such in the schemas and must never be promoted to analytics
+  surfaces. Decisions and metrics reference the analytics-safe `analyticsId` /
+  `caseRef` only.
+- **Batching**: `CodingBatch` wraps 1–100 cases for bounded batch review; one
+  execution stays within runtime limits.
+
+The current RCM example (`DEMO-ENC-1042`) and a monthly multi-activity
+time-aggregation workflow both have lossless, round-trip fixtures under
+`fixtures/coding-case/` and `fixtures/coding-decision/`.
 
 ## Use the raw JSON Schemas