Architecture

From slot to canonical block

The peer is an unmodified cardano-node. TSUNAGI speaks the standard node-to-node mini-protocols; nothing on the other side knows or cares that the block came from an independent implementation. That is the point.

KAGAMI — Observe

A node that cannot see itself cannot be trusted. KAGAMI is TSUNAGI's self-observation layer: every forged block enters an acceptance tracker that follows it through forged → pending → arrived → canonical (or unknown, honestly recorded when a block is lost). Internal belief is continuously cross-checked against external reality — a poller queries the public Koios API and compares the chain's view of the pool's blocks against the node's own.

When the two disagree, that disagreement is itself a signal — the Zig 0.16 child-spawn regression (P5) was caught exactly this way: Koios said canonical, the internal verdict said unknown, and the gap became incident INC-013.

YAMORI — Protect

TSUNAGI refuses to broadcast any block it cannot prove valid to itself first. The forge path is a chain of gates, each born from a real incident:

• Envelope gate — block must begin 82 07 85 (Conway era 7). Born from INC-001, where era-6 tagging made cardano-node route blocks to the wrong decoder.
• Sigma gate — forge refuses if stake share drifts from the chain's view (INC-002).
• Nonce gate — epoch nonce must match the achieved value, not a stale bootstrap (INC-003).
• Parent gate — stale or cross-domain parent triples are refused (INC-004).
• Opcert pin — the operational certificate sequence is pinned; an accepted block can never poison the next forge (INC-005/006).
• Self-verify — the node runs its own ed25519/KES verification on the finished block. A block that fails any gate is never sent.

A refused forge is logged with its reason — visible, attributable, recoverable. A bad broadcast would be none of those.

TATE — Recover

Failure is contained, never cascaded. The orphan watchdog distinguishes a genuinely diverged block (quarantine, probe, roll back state) from a slow confirmation (disarm, assume accepted). Artifact publication is two-phase — a .ready sentinel renamed into place only after the full artifact is written — so a reader can never observe a half-written block. Every deployed binary keeps a verified rollback chain on disk: any version can be restored by swapping one file, with the environment and state never touched.

MUSUBI — Reconnect

Producing a valid block is half the job; the network must fetch it before a competing block wins the slot race. MUSUBI is the propagation layer, hardened through four incidents (P1 → P2.2):

• Park, don't close (P1) — peers are held in ChainSync MsgAwaitReply instead of being disconnected, so a serve-ready connection always exists at forge time.
• Freshest source wins (P2) — a stale artifact can never shadow the live chain tip.
• Sentinel ordering (P2.1) — the decider and the loader see identically; no starved reload loops.
• Contiguous push walk (P2.2) — the peer's candidate chain is advanced one block at a time, never jumped. A non-contiguous push looks like a protocol violation and earns a disconnect; the walk earns an instant fetch.

The measurable result: connection churn went from ~140 disconnect cycles to zero, and a single parked connection has served multiple canonical blocks across many hours of uptime.

KINTSUGI — Learn

Kintsugi is the Japanese art of repairing broken pottery with gold — the repair is displayed, not hidden. TSUNAGI's failure-memory system works the same way: every incident that ever cost a block is recorded with its root cause, fix, regression test, and live closure evidence. The record is machine-readable; a recurring log signature can be matched against past incidents before anyone debugs from scratch.

• 13 incidents, all verified-closed against live network behavior.
• An orphan ledger — every lost block published with its cause.
• A regression-test map — a failing test means a frontier is reopening, and the rule is fix the regression, never the test.

The full story — every crack and every gold seam — is on the Kintsugi page.

Facts