Docs

Records and short signatures

How a buffer mutation log becomes a hash-addressed record with a short, shareable URL.

The primitive: a buffer mutation

Producers do not capture raw keystrokes. They capture buffer mutations: a single change to the underlying field, recorded as positions and lengths only, never as the content of the change.

{
  "seq": 412,
  "t": 184523,
  "op": "replace",
  "pos": 1043,
  "del_len": 12,
  "ins_len": 47,
  "source": "paste"
}

• seq is monotonic and gap-free, starting at 0.
• t is integer milliseconds since session start.
• pos, del_len, ins_len are Unicode codepoint offsets and lengths, never UTF-16 units or bytes. Each is a number, or an explicit null when the producer cannot derive a value content-blindly (e.g. multi-node HTML paste into a rich-text editor). Producers must not guess.
• op is one of insert, delete, or replace.
• source is one of typing, paste, cut, drop, ime, autocomplete, programmatic, or unknown. Producers must mark uncertain attribution as unknown rather than overclaiming typing.

The manifest

Every record carries a manifest with format version, BLAKE3 record_hash, session id, producer info, capture context, basic stats, and ingestion time. It may also carry an optional content-blind text_binding (a commitment to the signed document; see Bind and check a document). When no binding is present, the record_hash equals the final hash of the event log’s hash chain; when a binding is present, the record_hash is sealed over it too, so the binding cannot be altered without changing the hash.

Hash chain

The chain is computed deterministically over canonical JSON of each event, salted with the format version and session id at seq=0:

chain[0]   = BLAKE3(format_version || session_id || canonical(event[0]))
chain[i]   = BLAKE3(chain[i-1]      || canonical(event[i]))   for i > 0
event_tip  = chain[N-1]
record_hash = event_tip                                   # when no text_binding
record_hash = BLAKE3(event_tip || canonical(text_binding))  # when a binding is present

Any single-byte change to the events, or to a present binding, changes the hash, and the verifier shows a mismatch.

Short signatures

Long BLAKE3 hashes are painful to share, so the backend derives a short, URL-safe signature from the hash bytes and stores it alongside the full hash:

https://possiblymadebyahuman.com/<short_signature>

• Short signatures use a URL-safe alphabet and start around 10–12 characters.
• The backend collision-checks against the records table.
• Reserved route prefixes (api, docs, blog, write, assets, record-assets, images, health, ready, live, and similar) are never emitted as short signatures.
• The full record_hash is always shown on the record page and is what browser verification recomputes against.

Why a short URL still verifies safely

The short signature is only a friendlier index into the records table. The verifier in the browser recomputes the full BLAKE3 chain from the stored events and compares it to the full record_hash. Two records cannot accidentally share the same full hash; the short signature is only an aliasing convenience.