# Purchase orders, ASNs, invoices — as events understand them.

X12 in, EDIFACT in, JSON in: the same `bizTransaction` references and party GLNs out, on conformant EPCIS 2.0 events. EDI included, never EDI-only.

Every supply chain runs on two records that rarely meet: the documents the business trades on — the purchase order, the despatch advice, the invoice, the receiving advice — and the events the goods actually generate. CBV 2.0 closed that gap in the standard itself: `po`, `desadv`, `inv` and `recadv` are first-class `bizTransaction` types, and `bizTransactionList` sits on every EPCIS event type. The business-transaction layer is what compiles the documents down to those fields — whatever syntax they arrive in.

The layer ships as `biztx`, a sibling of the epcis.dev gateway with the same laws: pinned inputs, a golden corpus, `--json` on every verb, typed refusals, and an MCP door that re-dispatches through the same core. epcis.dev's pinned EPCIS 2.0.1 validators are its acceptance oracle: what comes out the event side validates against the same schema this origin validates against.

## Three syntaxes, one landing zone.

The layer is defined by where documents land, not where they come from:

- **X12** — the 856 despatch advice, the 850 purchase order, the 810 invoice. Parsed by grammars we authored ourselves, against a corpus where every fixture records its source repository and license. No X12 dictionary content ships here, ever: structure is stated in our own words, and segment-level element detail is a link to [Stedi's X12 reference](https://www.stedi.com/edi/x12-004010/856) — the canonical public reference, credited, never copied.
- **EDIFACT / EANCOM** — DESADV, ORDERS, INVOIC, RECADV. The UNTDID directories are published openly by UNECE, so this side of the house goes dictionary-deep, under the same pin law as everything else on this origin: the layer's committed provenance ledger (`vendor/untdid/PINS.json`) governs the directories file by file — sha256 per file, source URL, retrieval date, pins changed only by journaled human ruling — and every directory fact renders from that committed artifact.
- **API-native JSON** — a first-class peer, not an afterthought. The `biztx` canonical transaction shape is a plain JSON document — kind, id, references, parties, lines, hierarchy — validated against a published JSON Schema and normalized into the same internal model the parsers produce. A team whose orders live behind a REST API never touches EDI and still lands on the same joins.

## The verbs.

The CLI contract is the epcis.dev contract, verb for verb: `--json` on every verb, payload on stdout, typed errors on stderr, stable error codes, exit `0` ok / `1` negative verdict / `2` usage.

| verb | what it does | state |
|---|---|---|
| `parse` | X12 bytes → wire-canonical JSON: lossless, segment-order-preserving, delimiter-carrying — `emit(parse(x))` is byte-exact | shipped |
| `emit` | wire-canonical JSON → bytes, with a fidelity report per job: `byte-exact` or a recorded `canonical-equal` delta, never a silent pass | shipped |
| `validate` | envelope law for every input (control-number agreement, ISA fixed-width, delimiter consistency) + grammar-level for pinned sets, the 856 first | shipped |
| `ack` | a 997 functional acknowledgment from the validate verdict — the ack round-trips through our own `parse` and validates | shipped |
| `intake` | the API-native entry point: the canonical JSON transaction shape in, schema-validated, normalized — same downstream semantics as parsed EDI | shipped |
| `pins` | the provenance ledgers, verbatim: grammar pins, corpus pins, vendored-directory pins | shipped |
| `translate` | refuses honestly: a typed error, never a silent downgrade | honest refusal |
| `join` | refuses honestly: a typed error, never a fabricated event | honest refusal |

Both transcripts below are real runs over committed corpus fixtures — `corpus/join/856-ship-notice-01.edi` (the 856 half of the join fixture pair) and `corpus/tx/valid/desadv-hierarchy.json` (the API-native peer), elided only where marked:

```
biztx parse corpus/join/856-ship-notice-01.edi --json
{ "ok": true, "syntax": "x12",
  "delimiters": { "element": "*", "component": ">",
                  "segment": "~", "repetition": null,
                  "trailing": "segment-terminator",
                  "suffix": "\n" },
  "interchange": { "isa": { "elements": ["00", ...],
                            "raw106": true },
                   "groups": [ ... ] },
  "counts": { "segments": 26, "transactions": 1,
              "groups": 1 } }

biztx intake corpus/tx/valid/desadv-hierarchy.json --json
{ "ok": true,
  "schema": { "name": "biztx-canonical", "version": "0.1",
              "sha256": "e29db37b..." },
  "transaction": { "biztx": "0.1", "kind": "desadv", ... },
  "warnings": [ { "code": "SSCC_CHECK_DIGIT",
                  "path": "/hierarchy/2/sscc" } ] }
```

The two refusing verbs are the honesty law in verb form — the same law the epcis.dev `resolve` and `subscribe` tools keep. The join law is absolute: no event leaves this gateway unvalidated against the pinned official EPCIS 2.0.1 schema — a typed refusal, never an unproven event.

## What the hierarchy law holds.

A despatch advice is a tree — shipment, order, pack, item — whether it arrives as an X12 HL loop, an EANCOM CPS sequence, or a `hierarchy` array in plain JSON. One law validates all three: the tree must be rooted, orphan parents and cycles are typed rejections, and the same error codes fire regardless of arrival syntax. That tree is exactly the shape of EPCIS aggregation — SSCC parent, GTIN-grain children — which is why this layer lives beside an EPCIS gateway and not beside a mailroom.

## Provenance, pinned.

Same discipline as [the conformance page](/conformance/), applied to a harder licensing terrain:

- **Grammars are self-authored.** No X12 segment tables, no element dictionaries, no spec text — a provenance ledger records the public source of every structural fact, and descriptions are in our own words or omitted.
- **Every corpus fixture carries its papers.** Source repository, path, commit, license as verified at the pinned commit, retrieval date. A fixture with unclear papers stays out.
- **The directory ledger is committed.** The EDIFACT side answers to `vendor/untdid/PINS.json` — per-file sha256 over what UNECE publishes openly, source URL, retrieval date, pins changed only by journaled human ruling — and its state is the committed artifact itself, printed verbatim by `biztx pins`.
- **Ground truth is differential.** Independent open-source parsers cross-check every fixture; the parsers-agree subset is the oracle, and disagreements are adjudicated by journaled ruling, never by our own code winning ties.

## The agent door.

`biztx mcp` exposes `parse`, `validate`, `ack` and `intake` as typed MCP tools that re-dispatch through the same core functions the CLI runs — a door, not a second path. A tool exists only for a verb that runs: an agent never sees a phantom tool.

## Where this sits in the spine.

The document layer compiles to the fields the event layer already validates: `bizTransactionList` entries, `sourceList`/`destinationList` party GLNs, GTIN-grain quantity lists. The thesis — with the spec citations — is [Business transactions in EPCIS](/business-transactions-in-epcis/); the document-side mappings are worked end to end in [the 856 join](/856-asn-to-epcis-aggregation/) and [the DESADV join](/edifact-desadv-to-epcis/); and the event surface those fields land on is [this gateway](/), with the same key for a person and an agent.

**External reference, credited:** for X12 segment-level detail this site deliberately does not reproduce, use [Stedi's X12 reference](https://www.stedi.com/edi/x12-004010/856) — live, free, and the best of its kind.

---

**Proof, not adjectives.** This build could not verify the gateway's test suite green, so no sentence on this page claims a passing run — the last verified run is recorded in the repository's own CI, not here. Live on this origin, no key: POST /translate, /validate, /hash. No conformance attestation has ever been issued. The dated ledger is /what-ships-today/.