How checking works
What a check compares, in three levels, and what a pass and a failure each mean. The same check runs in the reader's browser, in your code, and in the standalone checker.
Every check of a PacSpace record is the same check. The Shared Record runs it in the reader's browser when the record opens. records.check runs it in your own process. The standalone checker runs it for someone who holds only the history file. This page says what that check does and what its result means.
Three levels
Without a receipt. What can be read about a record with no receipt and no link is its entry numbers, each entry's lifecycle word, and when each was committed. Nothing else. No title, no time of the action, no actor, no fingerprint.
With a receipt. The holder of an entry's receipt has the sealed record as it was written. The check recomputes the seal from that sealed record and confirms it reproduces the seal that was committed, then confirms the entry sits where the record says it sits, among the entries committed with it. Change one character of the sealed record and the seal no longer reproduces.
Against the whole history. Each write seals everything written before it. A check of the full history confirms the entries run from the first to the last, that each one was committed after the one before it, and that the file carrying them is the file that was exported. This is the check the Shared Record runs, and it is why the count in the first sentence can be trusted: the record's own count of entries is part of what was committed.
What a pass means
The entries you hold are exactly what was committed, in this order, and nothing has been changed since. That is all. The check shows the record is unchanged since it was committed. It does not show that what was recorded was true. If a system wrote a false entry, the record holds a false entry, faithfully, with the time and the actor that wrote it.
What a failure means
A failed check names the first thing that failed, in the order the check runs.
| The check finds | What it means |
|---|---|
| The file's own fingerprint does not reproduce | The history file was changed after it was exported. Fetch it again. |
| An entry's sealed record does not reproduce its seal | The copy of that entry differs from what was committed. On the Shared Record this reads "Entry 2 does not match." |
| Entries the record says it has are not in the file | The file is incomplete. The check names the missing entries; on the Shared Record a gap reads as the entries on either side of it. |
| An amendment names an entry that is not there, not committed, or later than itself | The chain between entries is broken at that point. |
| The record's current state does not agree with the file | The file is older than the record, or it is a copy of a different record. Fetch the history again. |
A history the check cannot read at all is refused before any entry is checked, and the result says so rather than reporting a match.
Where the check runs
| Where | Over what | Reads from |
|---|---|---|
| The Shared Record | The history PacSpace served through the link | The reader's browser; it asks nothing of PacSpace or of you while it runs |
records.check | The history you fetched | Your process; with source, also the public source |
npx @pacspace-io/check | A history file on disk | The machine it runs on, and the public source unless --offline |
The reader's browser and the checker recompute; they do not ask PacSpace whether the record is fine. PacSpace serves the history and the receipts; the check is done by the party who needs the answer.
What the check does not read
The check never sees your files. It compares fingerprints: the ones sealed in the record with the ones the reader holds, if they hold any. It never reads a storage location, because none is in the record. And it reads no other record of yours.