# VERIFY.md — check this bundle yourself, don't take our word for it

This bundle is a real, run-once output of `arcaeon-ledger` + `arcaeon-compact`,
pinned to Arcaeon's live hosted witness. Every command below is copy-pasteable;
every output shown is what actually printed when we ran it (not a mockup) —
the build script that produced this bundle is the same script whose stdout is
quoted here. If your run disagrees with a quoted output below, that's a bug
report, not a formatting difference — tell us.

**Files in this bundle:**
- `demo_agent_log.jsonl` — 8-row demo agent action log (hash-chained, every
  row carries an `authority` block, row 2 carries an artefact binding to
  `https://example.com`) + 1 compaction-receipt row sealed into the same
  chain as row 9.
- `manifest.json` — what each file is, every digest, the witness pin request
  and response, and the public-record links.
- `VERIFY.md` — this file.

---

## 0. Install the real libraries

```
pip install arcaeon-ledger arcaeon-compact
```

`arcaeon-ledger` is stdlib-only. `arcaeon-compact` depends only on
`arcaeon-ledger`. Nothing phones home; both packages are readable in full on
PyPI before you run anything.

## 1. Verify the hash chain

```
python -m arcaeon_ledger.cli verify demo_agent_log.jsonl
```

Expected output (this is the actual output from our own run):

```json
{
 "ok": true,
 "rows": 9,
 "chained": 9,
 "prechain": 0,
 "first_break": null
}
```

`ok: true` means every one of the 9 rows chains cleanly to the one before it —
no row was edited, deleted, or reordered since it was written. This is a
recomputation you just did on your own machine; it does not depend on
trusting us.

**Prove the check isn't decorative — break it on purpose.** Copy the file,
change one byte in a row's content (leave the `chain` field alone — that's
the point: you're not forging a new chain, you're editing history and seeing
if the old chain still matches), and re-verify:

```python
import json
from arcaeon_ledger import verify_file

lines = open("demo_agent_log.jsonl", encoding="utf-8").readlines()
row = json.loads(lines[1])
row["url"] = "https://example.org"          # tamper: change row 2's content
lines[1] = json.dumps(row) + "\n"
open("tamper_test.jsonl", "w", encoding="utf-8").writelines(lines)
print(verify_file("tamper_test.jsonl"))
```

Actual output from that exact edit, run against this bundle:

```json
{
  "ok": false,
  "rows": 9,
  "chained": 9,
  "prechain": 0,
  "first_break": "line 2: chain mismatch"
}
```

It names the exact row. That's the primitive.

## 2. Verify the artefact binding (row 2 — the `https://example.com` fetch)

```python
import json
from arcaeon_ledger import verify_artefact

row2 = json.loads(open("demo_agent_log.jsonl", encoding="utf-8").readlines()[1])
art = row2["artefact"]
print("self-consistency:", verify_artefact(art))
print("with refetch:     ", verify_artefact(art, refetch=True))
```

Actual output:

```
self-consistency: {'digest_ok': True, 'recipe': 'sha256:raw-bytes:v1', 'refetch': 'skipped', 'notes': []}
with refetch:      {'digest_ok': True, 'recipe': 'sha256:raw-bytes:v1', 'refetch': 'match', 'notes': []}
```

`refetch: 'match'` means the bytes we hashed when the row was written are the
same bytes `example.com` served when the check re-fetched it just now.
**Honest limit, stated in the library's own docs:** a `'mismatch'` here would
mean the content changed *or* was tampered — indeterminate, never proof of
foul play by itself. The web mutates; `example.com` is a stable enough page
that a mismatch on THIS bundle would be worth investigating, but the recipe
itself makes no promise beyond "the bytes as read at time T."

## 3. Verify the compaction receipt (row 9)

`manifest.json`'s `compaction_receipt` block names the row. Self-consistency
needs no content; recomputation needs the pre/post content, which isn't in
this bundle by design (a receipt proves *what was dropped* using digests
only — it never carries the dropped content itself, so a leaked receipt
leaks nothing). What you can check without our content:

```python
import json
from arcaeon_compact import verify_receipt

row = json.loads(open("demo_agent_log.jsonl", encoding="utf-8").readlines()[8])
print(verify_receipt(row))
```

Actual output:

```
{'ok': True, 'self_consistent': True, 'content': 'skipped', 'notes': []}
```

This confirms the receipt's own arithmetic reconciles (pre = kept + dropped,
post = kept + introduced) and that `receipt_digest` reproduces from the row's
core fields — i.e., the receipt itself hasn't been altered since it was
sealed. It does **not** prove the compaction was a *good* summary, or that
nothing important was dropped — the library says this plainly, and so do we:
a receipt has no opinion on salience.

## 4. Verify the ledger head against the live witness

`manifest.json → ledger_head` is what the ledger itself reports as its tip.
`manifest.json → witness_pin` is the request we sent and the response we got
back from `arcaeon-witness.vercel.app` at build time — the actual bearer-key
POST, actual 201, actual commit sha, quoted verbatim, not summarized.

Check the CURRENT state of that pin yourself, live, right now:

```
curl "https://arcaeon-witness.vercel.app/api/latest?ns=velouria-demo"
```

At build time this returned:

```json
{
  "ok": true,
  "pin": {
    "namespace": "velouria-demo",
    "rows": 9,
    "chain": "9650e32f0feae20f37dbcb6dd9b68826",
    "pinned_at": "2026-08-14T16:05:44.491Z",
    "seq": 1
  },
  "source": "github-contents-api",
  "freshness_note": "read via the GitHub contents API (commit-fresh); the authoritative record is the commit history at https://github.com/dan8433-user/arcaeon-witness-pins/commits/main/pins/velouria-demo",
  "history": "https://github.com/dan8433-user/arcaeon-witness-pins/commits/main/pins/velouria-demo"
}
```

`rows` and `chain` in that response must equal `ledger_head.rows` and
`ledger_head.chain` in `manifest.json`. If we ever tried to quietly reissue
this bundle with fewer rows or a different chain at row 9, the API would not
let us overwrite this pin — the witness is monotonic (a lower or equal `rows`
for a namespace is rejected) and every write is a public commit.

**Don't trust our API — check the public record directly, no API in the
loop:**

```
curl "https://raw.githubusercontent.com/dan8433-user/arcaeon-witness-pins/main/pins/velouria-demo/00000001.json"
curl "https://raw.githubusercontent.com/dan8433-user/arcaeon-witness-pins/main/pins/velouria-demo/latest.json"
```

Both should read exactly the JSON quoted above. This is a public GitHub
repository (`dan8433-user/arcaeon-witness-pins`); its commit history is the
evidence, and you can inspect it, clone it, or diff it without asking us for
anything: `https://github.com/dan8433-user/arcaeon-witness-pins/commits/main/pins/velouria-demo`.

**Honest limit, stated by the library itself:** the witness proves this ledger
was not truncated or rewritten *relative to what it saw, and only as recently
as the last pin.* The maximum gap between pins is the real security
parameter, not the average — an attacker picks the gap, not you. One pin at
one point in time is a demo of the mechanism, not a production cadence; a
real deployment pins on a schedule.

## 5. Verify the witness repo itself wasn't rewritten (OpenTimestamps anchor)

The pin store is a public git history, which is itself rewritable by anyone
holding write access — so the repo counter-anchors its own HEAD daily with
[OpenTimestamps](https://opentimestamps.org), a Bitcoin-blockchain timestamp
service:

```
pip install opentimestamps-client
git clone https://github.com/dan8433-user/arcaeon-witness-pins
cd arcaeon-witness-pins
ots verify anchors/<UTC-date>-head.txt.ots
# then confirm the sha inside the .txt is a real commit in this repo's history:
git log --format=%H | grep <sha-from-the-txt>
```

**Honest limit:** an anchor proves the repo's HEAD (and therefore every pin
beneath it) *existed by time T*. A fresh anchor commonly reads "pending
confirmation in Bitcoin blockchain" for a few hours before the calendar
server's merkle root lands in a block — that's normal, not a failure; the
daily job re-checks and upgrades the previous day's proof automatically. This
bundle's pin (commit `776c73f5e9ff26609f643be80f821f9f21a1b1be`, 2026-08-14)
is covered once the anchor for that UTC date or later lands in the repo —
check the `anchors/` directory for the current state; we don't backdate this
claim past what the chain actually shows.

---

## What this bundle proves, and what it doesn't (the whole point of this section)

**Proves:**
- The 9 rows in `demo_agent_log.jsonl` were not edited, deleted, or reordered
  after being written (the hash chain, § 1).
- Row 2's claim about `https://example.com`'s content is bound to a specific,
  re-fetchable digest — you checked it yourself in § 2, against the live page,
  not against our say-so.
- The compaction receipt in row 9 is internally consistent and unaltered
  since it was sealed (§ 3).
- A third party outside our control (the hosted witness, backed by a public
  GitHub commit, itself daily anchored to Bitcoin) recorded this exact
  `(rows, chain)` pair at a specific time — so we cannot now quietly swap in
  a different history that still "verifies clean" on its own (§ 4, § 5).

**Does not prove:**
- That the *content* of any row is true rather than fabricated by the agent
  that wrote it — a hash chain notarizes whatever was written, hallucination
  or fact, with equal fidelity. (Row 2's artefact binding is the one place in
  this bundle where a claim is independently checkable — that's why we
  included it.)
- That dropping the 10 items in the compaction receipt was a *wise* editorial
  choice — the receipt has no opinion on salience, only on what happened.
- Authorship, in the cryptographic-signature sense — the `authority` blocks
  in every row are data bound tamper-evidently into the chain, not a
  signature. A party that re-mints this log from genesis could re-mint fake
  authority blocks too; what a re-minter *cannot* do is also advance the
  witness pin above, which is why § 4–5 matter more than § 1 alone.
- Anything about our other products (`arcaeon-audit`, `arcaeon-meter`) —
  this bundle exercises `arcaeon-ledger` and `arcaeon-compact` only, because
  those are the two libraries that produced it.

That boundary list is not a disclaimer buried in fine print — it is
reproduced verbatim from the libraries' own module docstrings, because the
non-proofs are the product as much as the proofs are.