npm - @nexalink/coding-contracts - Versions diffs - 0.1.0 - Mend

@nexalink/coding-contracts 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/dist/cjs/index.cjs +1613 -0
package/dist/index.d.ts +252 -0
package/dist/index.js +1596 -0
package/package.json +35 -0
package/schemas/rcm-coding-input.schema.json +82 -0
package/schemas/rcm-coding-output.schema.json +146 -0
package/schemas/rcm-model-prompt.schema.json +91 -0
package/schemas/rcm-retrieval-metadata.schema.json +61 -0
package/schemas/rcm-runtime-event.schema.json +170 -0
package/schemas/rcm-supporting-reference.schema.json +81 -0
package/schemas/rcm-workflow-catalog.schema.json +123 -0
package/versions.json +42 -0
package/workflow-constants.json +10 -0

package/package.json ADDED Viewed

@@ -0,0 +1,35 @@
+{
+  "name": "@nexalink/coding-contracts",
+  "version": "0.1.0",
+  "description": "Versioned coding workflow contracts shared by nexalink-cloud, carecompass-sdk, and nexalink-webapp. Generated from contracts/schemas; includes TypeScript types, zod validators, canonical constants, and raw schema documents.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./schemas/*": "./schemas/*.json",
+    "./versions.json": "./versions.json",
+    "./workflow-constants.json": "./workflow-constants.json"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "versions.json",
+    "workflow-constants.json"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "license": "UNLICENSED"
+}

package/schemas/rcm-coding-input.schema.json ADDED Viewed

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/rcm-coding-input.schema.json",
+  "title": "RcmCodingInput",
+  "description": "Structured coding-case context for a single encounter-based RCM coding-review request. Canonical source for the SDK input shape, the portal request context, and the cloud-hosted encounter payload.",
+  "version": "1.0.0",
+  "x-wire-version": "rcm-coding-input-v1",
+  "x-code": "coding_input",
+  "x-keys-code": "coding_input_keys",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["encounterId", "diagnosisNarrative"],
+  "properties": {
+    "encounterId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 160,
+      "x-code": "encounter_id"
+    },
+    "diagnosisNarrative": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "x-code": "diagnosis_narrative"
+    },
+    "procedureNarrative": {
+      "type": "string",
+      "maxLength": 2000,
+      "x-code": "procedure_narrative"
+    },
+    "serviceDate": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "x-code": "service_date"
+    },
+    "placeOfService": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 20,
+      "x-code": "place_of_service"
+    },
+    "claimContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "x-code": "claim_context",
+      "x-keys-code": "claim_context",
+      "properties": {
+        "stage": {
+          "type": "string",
+          "enum": ["development", "staging", "production"],
+          "x-code": "claim_context_stage"
+        },
+        "payerName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "x-code": "claim_context_payer_name"
+        },
+        "submittedCodes": {
+          "type": "array",
+          "maxItems": 20,
+          "x-code": "claim_context_submitted_codes",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 20,
+            "x-code": "claim_context_submitted_codes"
+          }
+        }
+      }
+    },
+    "supportingReferences": {
+      "type": "array",
+      "maxItems": 10,
+      "x-code": "supporting_references",
+      "items": {
+        "$ref": "rcm-supporting-reference.schema.json"
+      }
+    }
+  },
+  "x-wire-constant": "RCM_INPUT_SCHEMA_VERSION"
+}

package/schemas/rcm-coding-output.schema.json ADDED Viewed

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/rcm-coding-output.schema.json",
+  "title": "RcmCodingOutput",
+  "description": "Grounded RCM coding-review result returned by the hosted runtime. This is the stable compatibility contract behind the legacy rcm-grounded-human-review-v2 output schema version. The runtime postcondition fails closed: any structural or grounding violation is replaced with an escalate response carrying rcm_validation_error.",
+  "version": "1.0.0",
+  "x-wire-version": "rcm-grounded-human-review-v2",
+  "x-code": "not_object",
+  "x-keys-code": "top_level_keys",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "disposition",
+    "humanReviewRequired",
+    "recommendations",
+    "documentationGaps",
+    "rationale"
+  ],
+  "properties": {
+    "disposition": {
+      "type": "string",
+      "enum": ["review_required", "abstain", "escalate"],
+      "x-code": "disposition"
+    },
+    "humanReviewRequired": {
+      "type": "boolean",
+      "const": true,
+      "x-code": "human_review_required"
+    },
+    "rationale": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "x-strip-nonempty": true,
+      "x-code": "rationale"
+    },
+    "recommendations": {
+      "type": "array",
+      "maxItems": 20,
+      "x-code": "recommendations",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "x-code": "recommendation_keys",
+        "x-keys-code": "recommendation_keys",
+        "required": [
+          "code",
+          "codeSystem",
+          "confidence",
+          "rationale",
+          "evidenceIds"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64,
+            "x-strip-nonempty": true,
+            "x-code": "recommendation_code"
+          },
+          "codeSystem": {
+            "type": "string",
+            "enum": ["ICD-10-CM", "CPT", "HCPCS"],
+            "x-code": "recommendation_code_system"
+          },
+          "confidence": {
+            "type": "string",
+            "enum": ["low", "medium", "high"],
+            "x-code": "recommendation_confidence"
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "x-strip-nonempty": true,
+            "x-code": "recommendation_rationale"
+          },
+          "evidenceIds": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 5,
+            "x-code": "recommendation_evidence_ids",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128,
+              "x-strip-nonempty": true,
+              "x-code": "recommendation_evidence_ids"
+            }
+          }
+        }
+      }
+    },
+    "documentationGaps": {
+      "type": "array",
+      "maxItems": 20,
+      "x-code": "documentation_gaps",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 1000,
+        "x-strip-nonempty": true,
+        "x-code": "documentation_gaps"
+      }
+    }
+  },
+  "if": {
+    "properties": {
+      "disposition": {
+        "const": "review_required"
+      }
+    },
+    "required": ["disposition"]
+  },
+  "then": {
+    "properties": {
+      "recommendations": {
+        "minItems": 1
+      }
+    },
+    "x-code": "review_required_recommendations"
+  },
+  "else": {
+    "properties": {
+      "recommendations": {
+        "maxItems": 0
+      }
+    },
+    "x-code": "disposition_recommendations"
+  },
+  "x-semantic": [
+    {
+      "rule": "grounded_evidence_ids",
+      "code": "recommendation_unapproved_evidence",
+      "on": "recommendations",
+      "option": "allowedReferenceIds"
+    },
+    {
+      "rule": "code_in_cited_excerpt",
+      "code": "recommendation_code_not_in_evidence",
+      "on": "recommendations",
+      "options": ["allowedReferenceIds", "referenceTextById"]
+    }
+  ],
+  "x-wire-constant": "RCM_OUTPUT_SCHEMA_VERSION"
+}

package/schemas/rcm-model-prompt.schema.json ADDED Viewed

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/rcm-model-prompt.schema.json",
+  "title": "RcmModelPrompt",
+  "description": "Structured JSON presented to the coding model. The encounter carries the request case fields and supportingReferences carry server-resolved or development-approved evidence. The hosted runtime builds this itself from retrieval and never accepts caller-supplied references outside development.",
+  "version": "1.0.0",
+  "x-wire-version": "rcm-model-prompt-v1",
+  "x-code": "model_prompt",
+  "x-keys-code": "model_prompt_keys",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["encounter", "supportingReferences"],
+  "properties": {
+    "encounter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["encounterId", "diagnosisNarrative"],
+      "x-code": "encounter",
+      "x-keys-code": "encounter_keys",
+      "properties": {
+        "encounterId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160,
+          "x-code": "encounter_id"
+        },
+        "diagnosisNarrative": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000,
+          "x-code": "diagnosis_narrative"
+        },
+        "procedureNarrative": {
+          "type": "string",
+          "maxLength": 2000,
+          "x-code": "procedure_narrative"
+        },
+        "serviceDate": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "x-code": "service_date"
+        },
+        "placeOfService": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 20,
+          "x-code": "place_of_service"
+        },
+        "claimContext": {
+          "type": "object",
+          "additionalProperties": false,
+          "x-code": "claim_context",
+          "x-keys-code": "claim_context",
+          "properties": {
+            "stage": {
+              "type": "string",
+              "enum": ["development", "staging", "production"],
+              "x-code": "claim_context_stage"
+            },
+            "payerName": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 160,
+              "x-code": "claim_context_payer_name"
+            },
+            "submittedCodes": {
+              "type": "array",
+              "maxItems": 20,
+              "x-code": "claim_context_submitted_codes",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 20,
+                "x-code": "claim_context_submitted_codes"
+              }
+            }
+          }
+        }
+      }
+    },
+    "supportingReferences": {
+      "type": "array",
+      "maxItems": 5,
+      "x-code": "model_prompt_references",
+      "items": {
+        "$ref": "rcm-supporting-reference.schema.json"
+      }
+    }
+  },
+  "x-wire-constant": "RCM_MODEL_PROMPT_SCHEMA_VERSION"
+}

package/schemas/rcm-retrieval-metadata.schema.json ADDED Viewed

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/rcm-retrieval-metadata.schema.json",
+  "title": "RcmRetrievalMetadata",
+  "description": "Bounded metadata attached to a hosted RCM retrieval outcome. The client-visible shape omits tenantId and knowledgeBaseId; both are included here as optional so the full runtime envelope and the persisted client-facing metadata validate against the same contract.",
+  "version": "1.0.0",
+  "x-wire-version": "rcm-retrieval-metadata-v1",
+  "x-code": "retrieval_metadata",
+  "x-keys-code": "retrieval_metadata_keys",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "corpusId",
+    "corpusVersion",
+    "outcome",
+    "latencyMs",
+    "references"
+  ],
+  "properties": {
+    "corpusId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "x-code": "corpus_id"
+    },
+    "corpusVersion": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "x-code": "corpus_version"
+    },
+    "outcome": {
+      "type": "string",
+      "enum": ["completed", "empty", "failed"],
+      "x-code": "retrieval_outcome"
+    },
+    "latencyMs": {
+      "type": "integer",
+      "minimum": 0,
+      "x-code": "retrieval_latency_ms"
+    },
+    "knowledgeBaseId": {
+      "type": "string",
+      "maxLength": 128,
+      "x-code": "knowledge_base_id"
+    },
+    "tenantId": {
+      "type": "string",
+      "maxLength": 128,
+      "x-code": "retrieval_tenant_id"
+    },
+    "references": {
+      "type": "array",
+      "x-code": "retrieval_references",
+      "items": {
+        "$ref": "rcm-supporting-reference.schema.json"
+      }
+    }
+  },
+  "x-wire-constant": "RCM_RETRIEVAL_SCHEMA_VERSION"
+}

package/schemas/rcm-runtime-event.schema.json ADDED Viewed

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/rcm-runtime-event.schema.json",
+  "title": "RcmRuntimeEvent",
+  "description": "Sanitized audit or safety event emitted along a workflow runtime lifecycle. Events never carry prompts, raw PHI, or unrestricted guardrail trace content.",
+  "version": "1.0.0",
+  "x-wire-version": "rcm-runtime-event-v1",
+  "x-code": "runtime_event",
+  "x-keys-code": "runtime_event_keys",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "outcome", "reason", "occurredAt", "workflowId"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["audit", "safety"],
+      "x-code": "runtime_event_type"
+    },
+    "outcome": {
+      "type": "string",
+      "enum": ["authorized", "validated", "escalated"],
+      "x-code": "runtime_event_outcome"
+    },
+    "reason": {
+      "type": "string",
+      "enum": [
+        "workflow_authorized",
+        "output_validated",
+        "output_invalid",
+        "workflow_escalated",
+        "guardrail_blocked",
+        "retrieval_completed",
+        "retrieval_failed"
+      ],
+      "x-code": "runtime_event_reason"
+    },
+    "occurredAt": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}",
+      "maxLength": 64,
+      "x-code": "runtime_event_occurred_at"
+    },
+    "workflowId": {
+      "type": "string",
+      "enum": ["rcm-coding-assistance"],
+      "x-code": "runtime_event_workflow_id"
+    },
+    "guardrail": {
+      "type": "object",
+      "additionalProperties": false,
+      "x-code": "runtime_event_guardrail",
+      "x-keys-code": "runtime_event_guardrail_keys",
+      "properties": {
+        "stopReason": {
+          "type": "string",
+          "maxLength": 64,
+          "x-code": "runtime_event_guardrail_stop_reason"
+        },
+        "actions": {
+          "type": "array",
+          "x-code": "runtime_event_guardrail_actions",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["scope", "policyType", "rule", "action"],
+            "x-code": "runtime_event_guardrail_action",
+            "x-keys-code": "runtime_event_guardrail_action_keys",
+            "properties": {
+              "scope": {
+                "type": "string",
+                "maxLength": 64,
+                "x-code": "runtime_event_guardrail_action_scope"
+              },
+              "policyType": {
+                "type": "string",
+                "maxLength": 64,
+                "x-code": "runtime_event_guardrail_action_policy_type"
+              },
+              "rule": {
+                "type": "string",
+                "maxLength": 128,
+                "x-code": "runtime_event_guardrail_action_rule"
+              },
+              "action": {
+                "type": "string",
+                "maxLength": 64,
+                "x-code": "runtime_event_guardrail_action_type"
+              }
+            }
+          }
+        }
+      }
+    },
+    "retrieval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "corpusId",
+        "corpusVersion",
+        "outcome",
+        "referenceCount",
+        "latencyMs",
+        "references"
+      ],
+      "x-code": "runtime_event_retrieval",
+      "x-keys-code": "runtime_event_retrieval_keys",
+      "properties": {
+        "corpusId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "x-code": "runtime_event_retrieval_corpus_id"
+        },
+        "corpusVersion": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "x-code": "runtime_event_retrieval_corpus_version"
+        },
+        "outcome": {
+          "type": "string",
+          "maxLength": 64,
+          "x-code": "runtime_event_retrieval_outcome"
+        },
+        "referenceCount": {
+          "type": "integer",
+          "minimum": 0,
+          "x-code": "runtime_event_retrieval_reference_count"
+        },
+        "latencyMs": {
+          "type": "integer",
+          "minimum": 0,
+          "x-code": "runtime_event_retrieval_latency_ms"
+        },
+        "references": {
+          "type": "array",
+          "x-code": "runtime_event_retrieval_references",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["referenceId", "documentId", "version"],
+            "x-code": "runtime_event_retrieval_reference",
+            "x-keys-code": "runtime_event_retrieval_reference_keys",
+            "properties": {
+              "referenceId": {
+                "type": "string",
+                "pattern": "^reference-[1-9][0-9]*$",
+                "maxLength": 32,
+                "x-code": "runtime_event_retrieval_reference_id"
+              },
+              "documentId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 240,
+                "x-code": "runtime_event_retrieval_document_id"
+              },
+              "version": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 80,
+                "x-code": "runtime_event_retrieval_reference_version"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "x-wire-constant": "RCM_RUNTIME_EVENT_SCHEMA_VERSION"
+}

package/schemas/rcm-supporting-reference.schema.json ADDED Viewed

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nexalink.care/contracts/rcm-supporting-reference.schema.json",
+  "title": "RcmSupportingReference",
+  "description": "One policy/evidence reference attached to an RCM coding request or returned by the tenant-scoped hosted retrieval. Core fields are the portable minimum; the remaining fields are populated by the hosted runtime and may be absent for customer-injected development references.",
+  "version": "1.0.0",
+  "x-wire-version": "rcm-supporting-reference-v1",
+  "x-code": "reference",
+  "x-keys-code": "reference_keys",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["referenceId", "title", "excerpt"],
+  "properties": {
+    "referenceId": {
+      "type": "string",
+      "pattern": "^reference-[1-9][0-9]*$",
+      "maxLength": 32,
+      "x-code": "reference_id"
+    },
+    "documentId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240,
+      "x-code": "reference_document_id"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240,
+      "x-code": "reference_title"
+    },
+    "excerpt": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "x-code": "reference_excerpt"
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "x-code": "reference_version"
+    },
+    "corpusScope": {
+      "type": "string",
+      "enum": ["base", "tenant"],
+      "x-code": "reference_corpus_scope"
+    },
+    "publisher": {
+      "type": "string",
+      "maxLength": 240,
+      "x-code": "reference_publisher"
+    },
+    "effectiveDate": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "x-code": "reference_effective_date"
+    },
+    "retrievalDate": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "x-code": "reference_retrieval_date"
+    },
+    "coveredPayerProgram": {
+      "type": "string",
+      "maxLength": 240,
+      "x-code": "reference_covered_payer_program"
+    },
+    "sourceUrl": {
+      "type": "string",
+      "maxLength": 2048,
+      "x-code": "reference_source_url"
+    },
+    "humanReviewRequired": {
+      "type": "boolean",
+      "const": true,
+      "x-code": "reference_human_review_required"
+    }
+  },
+  "x-wire-constant": "RCM_REFERENCE_SCHEMA_VERSION"
+}