Docs

Seams

This spine is one property in a family that shares a single record: scans become events, events reconcile against business documents, documents cite events back. The family holds together because of one law, stated once and enforced at every edge.

The seam law

Every cross-property dependency is a typed contract with an owner: exactly one property homes each capability; the others reach it by reference — an id, a pinned artifact digest, a typed delegation refusal — and never re-journal it. A seam crossing always carries cross-property provenance ({property, objectId, journalRef, pinDigest}), is idempotent across the seam (the natural key travels with the reference), and fails typed, never silentlyOUT_OF_SCOPE {delegate}, BLOCKED {requiresGrant}, UNDERIVABLE. The seam is an answer, not a shrug. No capability exists twice.

Three consequences an integrator can build against:

  • One home per capability. Where two surfaces could carry the same engine, the registry rules which one homes it and which one aliases it. You never reconcile two journals that both claim to be the original.
  • References, not copies. What crosses a seam is an identifier and a digest, so the receiving side can verify what it was handed without re-storing it.
  • A typed no is a valid answer. A door that does not home a capability refuses with the delegation stated — machine-matchable, like every other refusal.

One edge, quoted as data

The registry types every edge. J1 — the scan-capture contract, the family's front door — reads as data, not prose:

edge:      J1  scan → event
producer:  barcoding capture        (constructs; free, stateless)
consumer:  epcis capture spine      (persists; the gate, exactly once)
contract:  {payload: DL URI | element string | EPC URN | image,
            context: {eventTime, bizStep, readPoint, who?,
                      bizTransactionList?}}
           → an EPCIS 2.0 ObjectEvent, validated against the
             pinned 2.0.1 schema BEFORE it returns,
             CBV §8.9 hash computed,
             spine:who and spine:capturedBy structurally separate
invariant: idempotent by CBV hash — a double-submit of the same
           scan returns the original receipt, never a second event;
           the producer never journals events

One constructor, two doors, stated as such: construction is free and stateless on both sides; the gate sits exactly once, at this spine's capture door. spine:who is the attested observer; spine:capturedBy is the warrantor account the gateway stamps — the two-grain law of the event model.

The invariant, executed

The idempotency half of the law is provable on your bench today. One stdio MCP session (npx -y epcis.dev mcp), the same shipped fixture captured twice, then queried back:

tools/call capture {document}   →  isError: false
   eventIDs: ["urn:uuid:6f9b62a2-5c1e-4c39-9e2b-1a2b3c4d5e6f"]
tools/call capture {document}   →  isError: false
   eventIDs: ["urn:uuid:6f9b62a2-5c1e-4c39-9e2b-1a2b3c4d5e6f"]
tools/call query {"EQ_bizStep":["shipping"]}
   → eventList.length = 1

The stored event, read back with the stamps visible:

{
  "type": "ObjectEvent",
  "eventID": "urn:uuid:6f9b62a2-5c1e-4c39-9e2b-1a2b3c4d5e6f",
  "bizStep": "shipping",
  "recordTime": "2026-07-31T18:45:36.052Z",
  "spine:capturedBy": "urn:epcis.dev:cli:local",
  "spine:attestationGrade": "anonymous"
}

(Standard fields elided for width; the stamps are verbatim.) Two identical submissions, one appended event, the original receipt both times — a benign replay is an ack, never a re-append, and the same identity resubmitted with different bytes is refused whole as epcisException:ResourceAlreadyExistsException (the taxonomy). The natural key is the CBV §8.9 hash — computed identity, so it travels across any seam with the event itself: hash & identity.

We answer in writing. We take at most five conversations a month, only when you ask for one, and only after you already have the written read.