# 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 silently** — `OUT_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](/docs/errors/refusals/).

## 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](/docs/event-model/who-capturedby/).

## 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:

```json
{
  "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](/docs/errors/exceptions/)). The natural key is the CBV
§8.9 hash — computed identity, so it travels across any seam with the
event itself: [hash & identity](/docs/event-model/hash-identity/).

---

**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/.