provenry

Published records change: a company updates an offer, a source is corrected, or two entries turn out to describe the same thing. Someone may already have cited the old version. Updating the website must not make that citation mean something else.

Provenry is the engine behind Sourcey’s public record of software companies. It packages records into releases that name their predecessors and carry their changes. A reader with the release files and the installed product composition can verify them without asking the current website what used to be true.

The old citation still has a job

Suppose a company changes the conditions of an offer. The current listing needs new terms. An article citing last month’s offer still needs the terms it referred to.

Provenry puts the corrected record in a successor release. That release names its exact parent and carries the diff. The old reference keeps pointing to the old revision; the current record can move forward.

captured source -> record -> release one <- existing citation
                                 |
new source -> corrected record -> release two

The same applies when two entries turn out to name one company, or one company splits into two. Identity transitions are records, and references remain bound to the revisions they named.

Files a reader can verify

A product composes Provenry with its own record types, policies, trust roots and adapters. Provenry owns the canonical bytes, the digests and the rules that bind each release to the one before it; the product’s own validators decide what its records mean.

Everything rests on one rule: every accepted value has exactly one byte form. Values are canonical JSON, with NFC text and keys in code-unit order, and anything that cannot be encoded one way (a sparse array, a getter, a cycle, a class instance) is refused before it reaches a hash. That gives independent implementations a precise byte contract to check, instead of relying on whichever JSON serializer a publisher happened to use.

Seal, then verify

The example that ships in the package composes a one-adapter instance, seals a first release and verifies it from its files:

npm install provenry
node node_modules/provenry/examples/basic.mjs

{"bundle_digest":"sha256:78fa2c913c408cf23b606e157be086af340a2b062fe6e2bc2a55fef928aae8f0","release_id":"sha256:bc9094614426c3b2912b43042258f0e39fbf7657a140b88b1db7dfe6848b627f","objects":1}

Those digests come out the same everywhere; the package’s own checks install it fresh and compare the output byte for byte. The consumer’s half is four lines:

const files = new Map([...sealed.files].map(([path, bytes]) => [path, Buffer.from(bytes)]));
files.set("bundle.json", Buffer.from(sealed.bundleBytes));
const verified = envelope.verify(files);
envelope.assertSuccessor({ descriptor: verified.descriptor, diff: verified.diff, parent: null });

verify checks every binding in the envelope and that an installed adapter owns every object in it, then assertSuccessor binds the release to its parent. Neither touches the filesystem or the network, so the same check runs in CI, on a laptop, or years later against an archive.

A release is a chain

Genesis is sequence one. Every successor names its exact parent at the next sequence, and policy time never runs backwards. A release carries its object manifest, the change log, the diff against its parent, a descriptor and a bundle, each bound to the others by digest. Ownership is exclusive: every adapter declares the objects, resources and subject types it owns, and nothing unowned enters a release.

Contract identifiers and signature domains are signed bytes too. Once evidence is signed under one, changing it invalidates the signature, and a historical release is read by the exact verifier it names.

Evidence before the fact

Facts about the outside world start as captures: a page fetched, a file read. Provenry reserves each capture before anything is fetched and seals the result after, whether the fetch worked or not. An Ed25519 attestation then binds the attempt to its signer, and the signer registry keeps its history, so an old signature is checked against the key that was valid when it was made rather than the one in use today.

Identity that lasts

Companies merge, split, succeed one another and retire. Each of those transitions is a record in its own right, and every reference between records is bound to the exact revision it named. A citation made two years ago still points at what it meant then.

Check the publication and the claim separately

A checksum can establish that the files match the release. A signed capture can identify an observation and its signer. Neither decides whether the publisher drew the right conclusion from the source.

Provenry checks the release bindings and ownership; the product supplies validators, evidence rules and trust roots. That division lets a reader distinguish a damaged file from a disputed claim.

Keep the release files with the verifier and composition they require, and those integrity checks can run after the publishing site is gone.

In production

Sourcey seals every release of its public record of software companies with Provenry, and its evidence captures go through the engine: reserved before the fetch, sealed after, signed. Each release page on sourcey.com lists the release, its parent, the bundle and the verifier that bind it; sourcey.com/provenry shows the current one.

Install

npm install provenry

Node.js 22.12 or newer, ES modules only. Subpath exports let a product use canonical primitives, capture, identity or publication without treating the engine as one undifferentiated API. MIT licensed. The format contract states the exact byte preimages, verification stages and read limits.