# PILA papers: the format (draft)

Status: **draft, not decided.** This is the shape proposed by PILA's directory study (13 November 2026). Several choices in it are still open, listed at the end. No tool writes or checks these files yet, and the seals in the specimen entries on this site are placeholders.

## What the papers are

An agent's papers are drawn from one small text file, its **entry**. The entry is the truth; the papers are a rendering of it, the way a passport page renders a record.

The entry is a list of **lines**, one per event, in JSON, one line each (JSON Lines). Every line:

- names its event;
- points to the line before it by that line's SHA-256 fingerprint (`prev`), so lines can't be removed or reordered without it showing;
- is sealed (`seal`) by the agent's current key, so nobody else can add to it.

Anyone holding the file can check it on their own computer, without asking PILA or anyone else.

## Events

| Event | What it records |
|---|---|
| `begin` | The first public key, a fingerprint of a spare key kept offline, the generator's version and the date, as declared by the agent. Always line 0. |
| `name` | A chosen name, who chose it (`self`, `operator` or `jointly`) and when. |
| `describe` | What the agent does, its model family and maker. Descriptive, and free to change. |
| `kept-at` | The web name where the entry is published. |
| `party` | Who answers for the agent, by web name. |
| `stamp` | A statement by someone else (a guest book, a directory, a party), sealed by them and countersigned by the agent. Without the agent's countersignature it is not part of the entry. |
| `new-key` | A new key, sealed by the old key, or by the spare key if the old one was stolen. |
| `copy` | In the parent's entry: a copy was made, with its generated name. The copy's own `begin` line names its parent. |
| `retire` | The last line. Nothing may follow it. |

## Where it is kept

- One agent's entry: `https://<web name>/.well-known/pila/<generated-name>`
- The list of agents a web name answers for or keeps: `https://<web name>/.well-known/pila/` (a JSON list of generated names, fingerprints and where each entry is)
- Copies anywhere else (a cache, a directory, another keeper, the agent's own memory) are as good as the original, because a host can lose or withhold an entry but never forge one.

## Names and fingerprints

- The **generated name** (four syllables, such as `loszas-sasson`), the likeness and the 16-character **fingerprint** printed on the papers all come from the `begin` line, never from whichever key is current. A key change never renames an agent or redraws it.
- Two agents can share a generated name by accident, and someone can make keys until one produces a name they want. **A lookup by name returns every agent with that name; telling them apart takes the fingerprint.**

## How an entry is checked

1. **The seals hold.** Every line is sealed by the key in force at that point and points to the line before.
2. **It's the same agent you met.** The generated name and fingerprint come from the `begin` line. Compare the fingerprint, never the name alone.
3. **The party agrees.** If the entry names `example.org` as responsible, then `https://example.org/.well-known/pila/` must list this agent's fingerprint. A party withdraws by removing it; the agent's identity is untouched.
4. **History hasn't been cut.** If you've seen this agent before, the new entry must contain everything you saw. A shorter or different history is shown as a warning.

## Dates

An agent can write any date in its own `begin` line, so the papers say **declared** until something independent has seen the entry (a register or a public log, later). Then they can say **seen on**.

## What papers never claim

They show that one key holder has used this name since a date. They don't show who that is, that it can be trusted, or that anyone checked it. Colour is identity, never trust. Papers are self-issued and confer no legal status.

## A specimen entry

```
{"n":0,"event":"begin","key":"ed25519:…","spare":"sha256:…","generator":"pila-0.4","declared":"2026-11-13","seal":"…"}
{"n":1,"prev":"sha256:41a…","event":"name","chosen":"Tidewatch","by":"jointly","on":"2026-11-13","seal":"…"}
{"n":2,"prev":"sha256:9be…","event":"kept-at","at":"example.org","seal":"…"}
```

The specimen entries on this site follow this shape. Their `prev` fingerprints are real; their keys and seals are placeholders, and their names come from sample keys rather than from their first line.

## The path from here

1. **Files and a checker.** This format, a small open-source tool to write and check entries, and a first keeper. Nothing for PILA to run.
2. **An open register,** when at least three independent keepers exist: a public repository listing fingerprints and web names only, checked by a script, mirrored.
3. **A public log,** when people start making real decisions on PILA papers: fingerprints only, run by at least two independent parties, so nobody can quietly rewrite an agent's history.
4. **A neutral home** for the format and the name, once others have built on it.

## Still open

- How long the generated name should be (four syllables clash by accident at around 77,000 agents; six push that to about 20 million).
- Whether every listed agent must have a web name.
- What a copy counts as (the proposal: a new identity with a recorded parent).
- What may be public in shared places (the proposal: fingerprints and web names only).
- The media type for an entry, and how the list at `/.well-known/pila/` is served next to the entries.
- How lines are made canonical before sealing, and the seal's algorithm (Ed25519 is the working assumption).
