# Pins

Every verdict this toolkit produces names the exact bytes it judged
against. The five official GS1 EPCIS 2.0.1 artifacts are vendored with
sha256 pins — not fetched, not linked, not resolved at run time. A
`validate` verdict carries the schema's pin in its output; the `pins`
verb prints the full set; the conformance harness records evidence under
a hash tree and refuses any bundle whose bytes moved. Pins change only
by journaled human ruling — that sentence is quoted from the shipped
`vendor/gs1/PINS.json` itself.

## The pinned artifacts

| artifact | sha256 | role |
|---|---|---|
| `openapi.json` | `3d33792c520d7a7a…b784d66fc` | REST binding shapes (Capture + Query interfaces) |
| `epcis-json-schema.json` | `0f46ff694efffd8d…40ae210af` | document/event validation — the projection-invariant schema |
| `epcis-context.jsonld` | `5056c65f991425b1…94713737` | JSON-LD expansion checks |
| `query-schema.json` | `4b5583c9a0a71532…19355341` | SimpleEventQuery validation |
| `epcis-shacl.ttl` | `7db2547a7a55e7d6…5c0cc7f42` | semantic-graph validation (secondary) |

Source of the standard: GS1 (`ref.gs1.org`). The full 64-hex digests are
in the transcript below and in `vendor/gs1/PINS.json` inside the tarball
(`node_modules/epcis.dev/vendor/gs1/PINS.json`).

## Read the pins where you already are

```
$ npx epcis.dev pins
standard  EPCIS 2.0.1
pin  openapi.json
     sha256=3d33792c520d7a7a1d080382d956730bb07021c7dd1cc17229fce27b784d66fc
pin  epcis-json-schema.json
     sha256=0f46ff694efffd8d8ce840a33dfde84228add11b516b8b258f3200740ae210af
pin  epcis-context.jsonld
     sha256=5056c65f991425b1d3a35e35edf4f7d0c7ff56cf688c2912b930f93494713737
pin  query-schema.json
     sha256=4b5583c9a0a715324594617f3cf6744f4f930568484f7df8fb7aa81819355341
pin  epcis-shacl.ttl
     sha256=7db2547a7a55e7d6e6f19c0ad472d1f0987ef19f3d04a43b195bca55c0cc7f42
$ echo $?
0
```

(Text mode prints one TSV line per pin with its `ref.gs1.org` source URL;
the lines are wrapped here for width only. `pins --json` prints the
PINS record verbatim.)

Every `validate` verdict names its schema by the same pin:

```
$ CORPUS=node_modules/epcis.dev/golden-corpus
$ npx epcis.dev validate \
    $CORPUS/valid-standard/object-event-shipping.json --json
{
  "valid": true,
  "schema": {
    "artefact": "epcis-json-schema.json",
    "version": "2.0.1",
    "sha256": "0f46ff694efffd8d8ce840a33dfde84228add11b516b8b258f3200740ae210af"
  },
  "errors": []
}
```

The repository's `verify:pins` script re-hashes the vendored bytes
against these digests on every test run — the differential harness, and
the full suite behind the site's verbs gate, ride the same pins.

## The harness refuses altered evidence

A `conformance run --out run.json` records full transcripts of every
check under a hash tree (`bundle.rootHash` over content-addressed
objects). Change one byte anywhere inside the evidence and `rejudge`
refuses the whole bundle — it does not re-judge around the damage:

```
$ npx epcis.dev conformance run --self --out run.json
…
state  passed  passed=18  failed=0  total=18
wrote  run.json

# one byte altered inside a recorded transcript object, then:

$ npx epcis.dev conformance rejudge run.json
signature  none  advisory run — carries no attestation weight
bundle  FAILED  evidence bundle failed verification: TCR-43.1:
  transcript object at address b74e373bc3c836d363db25c10bac54e1a…
  actually hashes to 8da78836f99515b0a138ecb60f2793ea2129…
  — evidence was altered
rejudge  FAILED
$ echo $?
1
```

Exit `1` is the fail-closed path working, not a crash — the exit-code
taxonomy is on the [CLI reference](/docs/reference/cli/).

An advisory run is unsigned and carries no attestation weight; no
conformance attestation has ever been issued. What a run is, and how a
counterparty replays one offline, is the
[run & rejudge page](/docs/conformance/run-rejudge/).

---

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