IF Commons GitHub

Integrations exchange

0006Active

0006-integrations-exchange · owner if · domain commons

The tree

FR-001checkpassing

The abstract tree MUST be the sum of interchange, group, transaction, segment, loop and element, each a discriminated, readonly record, with the syntax of an interchange a reference of level syntax.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: a tree is made and walked

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/tree.ts

Tests: passed: suite/exchange.test.ts a tree is made and walked: entries, paths and occurrences

FR-002checkpassing

A path MUST be the ids from the transaction down joined by ., an element with an empty id adding nothing; entries MUST list every value with its path and its indexed path, pathsOf each path once, and occurrences the count of a path under each instance of its parent.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: paths, entries and occurrences

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/tree.ts

Tests: passed: suite/exchange.test.ts a tree is made and walked: entries, paths and occurrences

FR-003checkpassing

Redaction MUST be written once over the tree: redactTree MUST hide every value whose path, or an ancestor's, a predicate names, and hidingAllBut MUST express minimum-necessary as the elements a recipient may have.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: redaction hides what it names and keeps the rest

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/tree.ts

Tests: passed: suite/exchange.test.ts redaction hides what it names and keeps the rest

Constraints and validation

FR-004checkpassing

A schema MUST be the paths a kind of transaction has with constraints (cardinality, pattern, fixed, binding), and a profile MUST add constraints to a schema it names.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: a schema and a profile constrain a transaction

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/constraints.ts

Tests: passed: suite/exchange.test.ts a schema and a profile constrain a transaction, and validate finds each kind

FR-005checkpassing

A finding MUST have a level (syntax, schema, profile, terminology, business-rule), a severity, a code, a path and a message made of the code and the path only; a message MUST NOT hold a value of the payload.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: findings hold no value (property)

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/constraints.ts

Tests: passed: suite/exchange.test.ts findings hold no value of the payload (property)

FR-006checkpassing

A terminology MUST be the codes of a code system or value set loaded from data supplied, and a binding MUST produce an error for a required strength, a warning for extensible, information for preferred and nothing for example; an unloaded terminology MUST be a warning, never a pass.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: binding strengths

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/constraints.ts

Tests: passed: suite/exchange.test.ts binding strengths

FR-007checkpassing

validate MUST be total and pure: every finding of a transaction against a schema, a profile, the terminologies and the business rules supplied, in the order of the levels.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: validate finds each kind

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/constraints.ts

Tests: passed: suite/exchange.test.ts a schema and a profile constrain a transaction, and validate finds each kind

Mapping and the life of a message

FR-008checkpassing

A mapping MUST be data (map with a transform, carry, drop with a reason) between two schemas, and coverage MUST find a source path that ends in no rule (unmapped-source-field), a rule that names no path, two sources to one target, and every drop as lossy-mapping: a lossy mapping is a finding.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: coverage finds an unmapped, a conflict and a drop

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/mapping.ts

Tests: passed: suite/exchange.test.ts coverage finds an unmapped field, a conflict, a stray rule and a drop

FR-009checkpassing

translate MUST write each mapped or carried value to its target path, MUST NOT write a dropped one, and MUST stop with unmapped-source-field rather than lose a value silently; transforms are total.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: translate maps, carries and drops, and refuses an unmapped field

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/mapping.ts

Tests: passed: suite/exchange.test.ts translate maps, carries and drops, and refuses an unmapped field

FR-010checkpassing

An acknowledgement MUST be the sum of X12 TA1, X12 999, HL7 ACK and FHIR OperationOutcome, and statusOf MUST be total: HL7 AA and CA accepted, AE and CE accepted with errors, AR and CR rejected; an outcome with an error rejected.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: statusOf over every acknowledgement

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/exchange.ts

Tests: passed: suite/exchange.test.ts statusOf over every acknowledgement

FR-011checkpassing

transition MUST be a total function of a state (pending, sent, received, retrying, acknowledged, rejected, abandoned), an event and the agreement's attempts, and an illegal pair MUST be an error value, never a throw.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: transition over every state and event (property)

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/exchange.ts

Tests: passed: suite/exchange.test.ts transition over every state and event (property)

FR-012checkpassing

A send that times out MUST retry until maxAttempts and then be abandoned; a state that is final (acknowledged, rejected, abandoned) MUST accept no event.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: retries are bounded

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/exchange.ts

Tests: passed: suite/exchange.test.ts retries are bounded, and a final state accepts no event

The ledger and the codes

FR-013checkpassing

The library MUST give a structural LedgerPort, a typed record of functions that return a Result and never throw: append a stage event {loadId, stage, reasonCode?, at, contentHash?}, intake a content by its hash giving the closed union first-seen, duplicate (of a load) or conflict (with a load: another content of the same item), outcome to record a validation or acknowledgement outcome by code, and events and outcomes to read them back; a stage MUST be an opaque branded text whose code list belongs to the consumer, and an event MUST carry no payload value: each of its fields is made by a smart constructor that admits no free text.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: the identifiers admit no free text

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/ledger.ts

Tests: passed: suite/exchange.test.ts the identifiers of a ledger event admit no free text

FR-014checkpassing

The library MUST ship an in-memory ledger and a conformance suite, conformLedger, that any implementation (memory, a database) runs: it finds a ledger that does not keep events in order, does not tell first-seen from duplicate from conflict, accepts an outcome for a load it has no event of, does not read an outcome back, or remembers the contents of another ledger.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: the in-memory ledger conforms and a faulty one is found

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/ledger.ts

Tests: passed: suite/exchange.test.ts the in-memory ledger conforms and a faulty one is found

FR-015checkpassing

The codes the library produces MUST be exported as closed lists of strings that a consumer may carry as data, each held complete against its union by the compiler: the finding codes and levels, the acknowledgement kinds and statuses, and the rejection kinds.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/exchange.test.ts: the code lists are complete

Proved by: integrations/suite/exchange.test.ts

Written in: integrations/src/logical/ledger.ts

Tests: passed: suite/exchange.test.ts the code lists are complete

Acceptance scenarios

  1. Given a mapping that drops Claim.note, When its coverage is computed, Then lossy-mapping is found for Claim.note, per FR-008.
  2. Given a validation finding at Patient.name[0].family, When it is printed, Then the family name is not in the message, per FR-005.

Out of scope

  • Planned: a canonical model and the standard mappings (X12 837 to FHIR Claim); EDIFACT, HL7 v2 syntax and schemas, ISO 20022 and NIEM.

Edge cases

  • A source field below a dropped path: covered by the drop, per FR-008.
  • A retry event in a final state: an error, per FR-012.

Assumptions

  • The tree is flat in values and nested in structure; a codec decides how its syntax maps to it.

Open questions

  • None.

Key entities

  • Interchange - what is sent in one go.
  • Mapping - rules that account for every field.
  • Exchange state - where a message is in its life.

Success criteria

SC-001success criterion

A document is validated, mapped and redacted by code written once, whatever its syntax, and nothing is lost without being named.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Integrations, logical/constraints, logical/exchange, logical/ledger, logical/mapping, logical/tree

Titles, headings, exports, tables, columns and requirements. Esc closes.