[OfficialAbhinavSingh]

Part of #72 — not closing it yet: the issue's own "Done when" needs a real write plus a working
panel on mergit.site, neither of which has happened (no funded wallet yet).

Summary

First version of this PR used the Python arkiv-sdk and claimed it worked end to end. It didn't —
a self-review checked it live against Rabdi instead of trusting the SDK's docs, and found the
Python SDK targets a different, incompatible network entirely (wrong write address, rejected query
options). arkiv/friction.md has the exact RPC errors and how to reproduce them.

Current state, rebuilt on what's actually confirmed live against Rabdi:

• Reads: plain httpx against arkiv_query (no SDK), filtered by schema tag, plan id, and
  $owner — the first version was missing the owner filter, which left it open to anyone writing a
  spoofed entity with Mergit's own schema tag. Ordered by key (ORDER BY $key ASC).
• Writes: a small Node sidecar (chain/arkiv/), using the official JS SDK (confirmed live to
  target Rabdi's real write address), holding the service wallet's private key — the control
  plane's own process/env never hold it. One HTTP call batches every task's decision for a plan
  into one on-chain transaction (executeBatch), serialized through an in-process queue so two
  concurrent explore calls can't race on the wallet's nonce.
• Writes run as a BackgroundTasks entry, not awaited inline — blocking the response on the write
  (the SDK call waits for a transaction receipt) was the first version's bug; fixed.
• GET /v0/plans/{uuid}/arkiv-suggestions reads the mirror back, owner-only, degrading to
  {enabled: true, decisions: [], error: "..."} instead of a 500 if Arkiv is unreachable.
• Frontend: "View on Arkiv" panel in SuggestAgents.tsx, shown only after an exploring suggestion,
  reading live from the endpoint above, each entity linking straight to its own Arkiv explorer page
  (rabdi.explorer.arkiv.network/entity/<key>, confirmed real against a live entity), with a
  "matches ✓" check against what Postgres answered with for the same task.
• The mirror is actually replayable now, not just a record of the outcome: each entity carries
  decisionId, seed and budgetMicros (via INSERT ... RETURNING on the Postgres row, not
  recomputed), matching migration 0016's own reason routing_decisions exists — "any draw can be
  replayed from its seed and the posteriors it saw."
• No requester attribute on the entity: it was never queried, and Arkiv entities are append-only
  (only expiry removes them), so attaching a wallet address to data that outlives a requester's own
  "discard this draft" was wrong.
• docker-compose: arkiv-sidecar service, gated by the arkiv profile (same opt-in pattern as
  keyrelay); validated with docker compose config, and the image was actually built and run
  twice (docker build + docker run, hit its real /healthz and /internal/mirror, including
  after the schema change below).
• arkiv/{schema,friction,reach,why-arkiv,how-you-use-arkiv}.md + both READMEs, rewritten to state
  only what was actually checked live.

Review round 2 (Yash)

Caught one real, confirmed bug: server.js mapped createdEntities.map(e => e.key), but the SDK's
own type (ExecuteBatchReturnType.createdEntities: Hex[]) says those are already plain strings —
entity_keys always came back [null, ...]. Fixed. Also acted on the privacy point above
(requester dropped) and the replayability gap (decisionId/seed/budgetMicros added) — both
real, both fixed. Deferred: an arkiv_mirrors table + outbox-style retry loop for lost writes (real
engineering, not required by the track's rules, ~1 day left); deduping entities across repeated
explore clicks (not a bug — each explore call is a genuinely new Thompson draw, same as Postgres's
own append-only table); the posteriors-snapshot-instead-of-routing_decisions redesign (legitimate
question, too large a change to make now without re-verifying everything live again).

What's verified, concretely

An unfunded test wallet, run against the real Rabdi RPC from the sidecar process, the built Docker
image, and again after the schema/payload changes above (now a 2-entity batch), reaches real
on-chain gas estimation and fails there every time ("Execution error without revert data", wallet
confirmed via eth_getBalance to hold 0 tGLM) — not at encoding, not at signing, not at the RPC
connection. That's as far as this can be verified without a funded wallet. The read-side query
syntax, including ORDER BY $key ASC, was run live against the real RPC and returns correctly
(empty, since nothing matches yet).

The Arkiv panel itself was exercised in a real browser against mocked network responses (not a real
backend) by temporarily swapping the app's render root for a direct mount — reverted before
committing, never shipped; confirmed via screenshot and DOM/accessibility-tree inspection that the
real shipped component renders both the picks list and the "View on Arkiv" decisions panel
correctly.

Still needed before this is live end to end

A funded service wallet (hub.arkiv.network/faucet, wallet-connect gated — not a plain API, so
this can't be done from here) and an access key (hub.arkiv.network/access-keys), set as
ARKIV_PRIVATE_KEY/ARKIV_SIDECAR_TOKEN on chain/arkiv/'s own deploy and
ARKIV_RPC_URL/ARKIV_OWNER_ADDRESS/ARKIV_ACCESS_KEY/ARKIV_SIDECAR_URL/ARKIV_SIDECAR_TOKEN
on the control plane's. Once set, the wallet address and one live query need to be filled into
README.md and arkiv/schema.md (currently placeholders, clearly marked).

Test plan

• uv run pytest -q — 546 passed, 1 skipped
• uv run pytest -m postgres -q — 450 passed
• uv run ruff check . — clean
• uv run pyright — 0 errors (strict, mergit_cp/mergit_worker)
• Frontend: tsc -b, eslint ., vitest run (292 passed), vite build — all clean
• docker build chain/arkiv + docker run, hit /healthz and /internal/mirror against the
  real Rabdi RPC with an unfunded wallet (fails at gas estimation, as expected), re-checked
  after the schema fix with a 2-entity batch
• docker compose config with the arkiv profile active
• Real-browser render of the frontend panel (mocked network, see above)
• A real write/read against Arkiv's live Rabdi testnet with a funded wallet