Versioning & drift

Two kinds of change exist on this surface and they never share a channel. Surface drift is the toolkit evolving — new verbs, new doors, better prose. Normative drift is the standard's own bytes moving — a new official schema, a revised context document. The first rides npm semver; the second rides sha256 pins that change only by journaled human ruling. An agent audits both with commands, not diffs of prose.

The version, from the thing itself

$ npx epcis.dev version --json
{
  "package": "epcis.dev",
  "version": "0.1.0",
  "epcis": "2.0.1",
  "cbv": "2.0.1",
  "suite": "0.4.0"
}

Four version axes, deliberately separate: the npm package, the EPCIS standard pinned, the CBV standard pinned, and the conformance suite. The public registry agrees:

$ npm view epcis.dev@0.1.0 version dist.tarball
version = '0.1.0'
dist.tarball =
  'https://registry.npmjs.org/epcis.dev/-/epcis.dev-0.1.0.tgz'

What is stable across releases

• Exit codes — 0 ok · 1 fail · 2 usage · 3 not-found · 4 internal. A release that changed a meaning would be a breaking change under semver.
• Error code strings on stderr and epcisException:* types on every door. Match on code, never on prose — title and detail are worded for humans and may be rephrased in any release.
• The verb set is closed. A new verb is a minor release; a removed or reshaped verb is a major one.
• --json output shapes. Fields are added, never repurposed.

What moves only by ruling

The five official GS1 artefacts are vendored bytes with sha256 pins — the pins page lists them. The shipped vendor/gs1/PINS.json states the law in its own first sentence: "Pins change only by journaled human ruling." To detect normative drift between two installs, diff the pins, not the prose:

$ npx epcis.dev pins --json | \
    node -e "let s='';process.stdin.on('data',d=>s+=d)
      .on('end',()=>{const p=JSON.parse(s).artefacts;
      for(const k in p)console.log(p[k].sha256,k)})"
3d33792c… openapi.json
0f46ff69… epcis-json-schema.json
5056c65f… epcis-context.jsonld
4b5583c9… query-schema.json
7db2547a… epcis-shacl.ttl

(Digests truncated for width; the full 64-hex values are on the pins page and in the run's output.)

Two installs whose pin sets match produce byte-identical verdicts. That is why the CI page says to pin the package version: npx -y epcis.dev@0.1.0 freezes both drift axes at once.

The journal is append-only about itself

The launch journal follows the same law as the event record it documents: entries are never edited after their date — a correction is a new entry that names what it corrects. What you cite from a dated entry stays citable; the fix arrives beside it, not over it. The dated build-state ledger at /what-ships-today/ is the authoritative structured fact for what answers on this origin today — treat its open column as open, not live.

Pin epcis.dev@0.1.0, match on codes, diff the pins, cite dated entries. That is the whole drift contract.