Concepts

What a Ranke-Graph is, and how a system is composed from the parts that serve one

dev1 September 2026

The part manuals tell you how to configure and run each piece. This document is what sits above them: what the data structure is, what provenance means here, and how a server, a library and a client compose into something you can run.

Read it before the manuals if the model is new to you, and skip to the manuals if it is not. Every term links to the glossary, which is the vocabulary the papers, the specification and every manual share.

Part I — Concepts

1 The model

A Ranke-Graph is a Merkle DAG of attributed claims. Everything else in the series follows from that sentence, so it is worth taking apart.

1.1 A claim, and what makes it one

A claim carries a type, an encoding, a creation time, a height, its content, and its edges. An edge is a typed link from the claim that owns it to the claim it points at, which is that edge’s reference.

The id is not a name somebody chose. It is $id (𝑣) = 𝐻 (𝑆 (env (𝑣)))$ — the hash of the envelope the archive stores, which is the claim’s canonical bytes paired with the signature over them. Two consequences follow, and they are the whole reason for the construction:

identity is content

Recomputing the id from the stored bytes either gives you the same id or tells you the bytes changed. Nothing has to be trusted to check it.

authorship travels with the claim

The signature is inside the bytes the id is taken over, so it cannot be detached from what it attests.

1.2 Closures, and why reads are shaped like them

A single claim is rarely the answer to a question. What a reader wants is the claim and everything it stands on, which is its closure. Because every edge points at a content address, a closure is exactly reproducible: fetch it twice, from two archives, and you have the same set or a detectable difference.

1.3 Provenance is the type vocabulary

Provenance here is structure rather than metadata. Three node classes carry it:

source/*

An external data artifact captured into the graph — a source.

entity/*

An identifiable thing in the world — an entity.

derivation/*

A claim built from other claims, together with the provenance edges citing them — a derivation.

A contributor is the actor whose work brings a claim into the graph, human or program or agent, and is deliberately distinct from an entity the graph describes. Asking where a statement came from is therefore a graph traversal rather than a lookup in a side table that can fall out of step.

1.4 Archives, branches, and what is mutable

A Ranke-Archive is a pair — the Universe and one head id — where the head is a branch table claim indexing the archive’s branchs. Adding to an archive yields a new pair rather than changing the old one, so “the archive at 09:00” stays meaningful after 09:01.

1.5 Validity and verification

valid is a structural property: the id recomputes, references resolve, the construction rules hold. It says nothing about whether the content is true, which is a judgement no data structure can make.

verify is checking that property across a graph, recomputing each id and confirming the rules. Integrity and authenticity fall out of the same pass. anchoring is the separate act of witnessing a head externally, an RFC 3161 timestamp among the options, which fixes a closure in time for anyone who did not see it happen.

the foundation paper, for the definitions and the proofs behind them

Part II — Guides

2 Composing a system

The parts divide by what they do to an archive, so the shape of a system follows from which of those you need.

2.1 What each part is

RankeDB

The server. One instance serves one Ranke-Archive from one configuration file, over REST. It owns the Sequencer — the mechanism that verifies a contribution, persists it, and advances the head — and the account roster that decides who may do what. the RankeDB manual, at /docs/rankedb/

Ranke-Go

The reference implementation, as a Go library: the claim construction rules, verify, and the query language. A program that builds claims or checks a closure without running a server links this.

Ranke-TS

The TypeScript client, for browsers and for worker agents that reach an instance over its REST surface rather than in process.

Ranke-Tools

Command-line tools over an archive. ranke-git is the first of them.

Ranke-Go, Ranke-TS and Ranke-Tools have no manual in this section yet. Each gains one when its repository publishes a docs tree, and the importer already watches for it.

2.2 The usual shape

One instance holds the archive. Everything else talks to it:

  writers                     RankeDB                 readers
  ───────                     ───────                 ───────
  capture tools  ──REST──▶  sequencer  ◀──REST──  browser (Ranke-TS)
  agents         ──REST──▶  storage    ◀──REST──  agents
  programs (Ranke-Go, in process)

A writer opens a contribution against a base — the head id and a stamped time — and the sequencer either merges the whole set or none of it. A reader asks for a claim, or for a closure, or for a filtered path across one. Because every answer is content-addressed, a reader can check what it was given without trusting the instance that gave it.

2.3 Choosing storage

The archive rests on a blob store, and which one is the main decision in a deployment. RankeDB names several, and composes them: stack layers one over another and partition sends different content to different stores.

A laptop or a test

mem or fs. Nothing to run beside the server.

One machine, kept

fs or sqlite, backed up like any other file.

Shared, or large

s3 for the bytes, with a faster store stacked in front of it.

The manual states what each adapter takes, field by field. RankeDB, The ports the server drives

2.4 Identity and access

Two separate questions, and they are answered in different places. The signer section says which identity merges are attested under — that is what a reader checks a signature against. The account roster says who may act on the archive at all, as grants that can be attenuated rather than as roles.

2.5 Where to start

Example — a first archive

Install the RankeDB binary, write a configuration with fs storage and one account, run ranke-db verify config.json, then ranke-db run config.json. The manual’s first chapter is that walk, in full.

A tutorial that carries the reader from an empty archive to a queried one belongs here. It waits on the clients having manuals of their own, so that it can end somewhere rather than stopping at the REST surface.