@nexalink/coding-contracts 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,23 @@
+Nexalink Proprietary Software License
+
+Copyright (c) 2026 Nexalink Health, Inc. All rights reserved.
+
+This package and its source code are proprietary to Nexalink Health, Inc.
+Access to this package does not grant any ownership interest, sublicensing
+right, or right to redistribute the software except as expressly authorized in a
+written agreement with Nexalink Health, Inc.
+
+Authorized Nexalink customers and implementation partners may install and use
+this package solely to evaluate, integrate, test, and operate CareCompass coding
+workflow integrations for customer-approved healthcare deployments.
+
+You may not copy, modify, publish, distribute, sell, sublicense, reverse
+engineer, or use this software to provide a competing service except where
+expressly permitted by a written agreement with Nexalink or by applicable law.
+
+This software is provided "as is" without warranties of any kind, whether
+express, implied, statutory, or otherwise, including warranties of
+merchantability, fitness for a particular purpose, title, and non-infringement.
+Nexalink is not liable for any claim, damages, or other liability arising from
+use of this software except as required by applicable law or an executed written
+agreement with Nexalink.

package/README.md

@@ -0,0 +1,200 @@
+# `@nexalink/coding-contracts`
+
+Canonical TypeScript contracts for Nexalink CareCompass coding workflows.
+
+The package provides:
+
+- TypeScript types for coding inputs, grounded outputs, supporting references,
+  retrieval metadata, runtime events, model prompts, and workflow policy.
+- Strict [Zod](https://zod.dev/) schemas for parsing untrusted values.
+- Validation helpers that return stable, machine-readable error codes.
+- Canonical workflow identifiers and schema wire-version constants.
+- The underlying JSON Schema documents for non-TypeScript consumers and
+  tooling.
+
+This package defines data contracts only. It does not make network requests,
+persist data, submit claims, or replace review by a qualified human coder.
+
+## Install
+
+Pin an exact version so contract upgrades are deliberate:
+
+```sh
+bun add @nexalink/coding-contracts@0.2.0 --exact
+```
+
+The package supports both ES modules and CommonJS.
+
+## Validate a coding input
+
+Use the Zod schema when you want parsed, typed data and detailed issues:
+
+```ts
+import {
+  RCM_INPUT_SCHEMA_VERSION,
+  rcmCodingInputSchema,
+  type RcmCodingInput,
+} from "@nexalink/coding-contracts";
+
+const candidate: unknown = {
+  encounterId: "DEMO-ENC-1042",
+  diagnosisNarrative: "Synthetic example for integration testing.",
+  serviceDate: "2026-07-01",
+  claimContext: {
+    stage: "development",
+  },
+};
+
+const input: RcmCodingInput = rcmCodingInputSchema.parse(candidate);
+
+console.log(RCM_INPUT_SCHEMA_VERSION, input.encounterId);
+```
+
+Use the validation helper when a compact error code is more useful than a Zod
+error:
+
+```ts
+import { rcmCodingInputValidationError } from "@nexalink/coding-contracts";
+
+const errorCode = rcmCodingInputValidationError(candidate);
+if (errorCode !== null) {
+  throw new Error(`Invalid coding input: ${errorCode}`);
+}
+```
+
+## Validate a grounded coding output
+
+Output validation can enforce both the structural contract and evidence
+grounding. Pass the approved reference IDs and the corresponding evidence text
+when validating recommendations:
+
+```ts
+import { rcmCodingOutputValidationError } from "@nexalink/coding-contracts";
+
+const candidate: unknown = {
+  disposition: "review_required",
+  humanReviewRequired: true,
+  recommendations: [
+    {
+      code: "99236",
+      codeSystem: "CPT",
+      confidence: "medium",
+      rationale: "Synthetic example for qualified coder review.",
+      evidenceIds: ["reference-1"],
+    },
+  ],
+  documentationGaps: [],
+  rationale: "Synthetic grounded recommendation requiring human review.",
+};
+
+const errorCode = rcmCodingOutputValidationError(candidate, {
+  allowedReferenceIds: new Set(["reference-1"]),
+  referenceTextById: {
+    "reference-1": "Synthetic policy excerpt supporting CPT 99236.",
+  },
+});
+
+if (errorCode !== null) {
+  // Fail closed: do not present or act on an invalid recommendation.
+  throw new Error(`Invalid coding output: ${errorCode}`);
+}
+```
+
+When grounding options are supplied, each recommendation must cite an approved
+reference and its code must appear in at least one cited evidence text. Use both
+options at trust boundaries. Calling the Zod schema or boolean helper alone
+validates the structural and semantic contract, but not the caller-specific
+approved evidence set.
+
+## Main exports
+
+| Category         | Exports                                                                                                                                                                                                |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Types            | `RcmCodingInput`, `RcmCodingOutput`, `RcmSupportingReference`, `RcmModelPrompt`, `RcmRetrievalMetadata`, `RcmRuntimeEvent`, `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`, `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
+
+The schemas are available as package subpaths. For example, in CommonJS:
+
+```js
+const inputSchema = require("@nexalink/coding-contracts/schemas/rcm-coding-input.schema");
+const versions = require("@nexalink/coding-contracts/versions.json");
+```
+
+The same documents are also exported as JavaScript values from the package
+root, such as `RcmCodingInputSchemaJson`.
+
+## Versioning
+
+Package versions and wire-schema versions serve different purposes:
+
+- The npm package follows semantic versioning. Consumers should pin an exact
+  version and evaluate contract changes before upgrading.
+- Each schema also has a wire-version constant used in requests, results, and
+  runtime events. A package release can update implementation details without
+  changing every wire version.
+- Additive contract changes may ship in a minor package release. Breaking
+  contract changes require a major package release and a new wire version.
+
+The complete package-to-schema mapping is available from
+`@nexalink/coding-contracts/versions.json`.
+
+## Safety and licensing
+
+- `humanReviewRequired` is always `true` for coding outputs. Recommendations
+  must be reviewed by a qualified human coder before billing, coding, or claim
+  submission.
+- Treat validation failures as fail-closed conditions. Do not silently coerce
+  invalid input or continue with ungrounded output.
+- Examples in this README are synthetic and must not be interpreted as coding
+  guidance.
+- The package does not include licensed terminology descriptions and does not
+  grant rights to use licensed code-set content.
+
+Use of this package is governed by the included Nexalink Proprietary Software
+License.