Skip to content

Collision Safety

Jump to bottom
Sietse edited this page Sep 29, 2026 · 3 revisions

Collision Safety

Two independent checks must agree before anything is reused.
Status ✅ Works, and you must call the right function to get it
Verified a forced collision is reused wrongly on the single-check path, and is a miss on the confirmed path
Scope accidental collisions. For protection of the files on disk, see Encryption at Rest

In plain words

Galahad finds saved memory by a short code made from the text. Two different texts can, very rarely, get the same code. Rare over millions of requests a day still means "eventually".

With one code, Galahad would then reuse the wrong memory, and the model would answer fluently, confidently and wrongly, with nothing logged.

So a second, independent code is checked too. If the two disagree, the lookup simply misses and the work is redone. Slower by one computation, never wrong.

The everyday example

Two different customer documents happen to get the same short code. With one code, the system hands back the wrong document and the answer looks perfectly reasonable. With two codes, the second one disagrees, and the system just does the work again.

The basics

How it works

  1. Galahad gives every text two independent fingerprints.
  2. Saved memory is only reused when both fingerprints match.
  3. If they do not match, it is a miss. The model does the work again, and the answer stays right.

How to use it

  1. Use the functions that end in _confirmed: they check both fingerprints.
  2. Treat a miss as normal: compute, then save.
  3. Watch the counters described below.

The one thing to get right: use the _confirmed pair

Both forms ship. They are not equivalent.

Call Checks the second code?
merlin_lookup ❌ No
merlin_lookup_confirmed ✅ Yes
merlin_register_vram ❌ stores no second code
merlin_register_vram_confirmed ✅ stores it

⭐ Use the _confirmed pair on both sides. Storing with the plain form and looking up with the confirmed form gets you a miss every time: the stored entry has no second code to compare. Get both codes from merlin_hash_tokens:

uint64_t key = 0, confirm = 0;
merlin_hash_tokens(tokens, n_tokens, tenant_id, &key, &confirm);

/* store */
merlin_register_vram_confirmed(key, confirm, tenant_id, ctx, seq_id, n_tokens, bytes);

/* look up */
merlin_lookup_result out;
merlin_lookup_confirmed(key, confirm, tenant_id, &out);

merlin_deposit_bytes also takes the second code (confirm_hash). Pass it there too.

⚠ Make the whole fleet uniform. If one host in your fleet stores with the plain form, every other host reuses those entries on one code only.

How it fails: a miss, not an error

st = merlin_lookup_confirmed(key, confirm, tenant_id, &out);
/* disagreement -> reported as a MISS */

⭐ A refusal is a miss. Your host already handles a miss: it computes and stores. Nothing new to handle.

Watch two counters in merlin_get_stats:
confirm_rejections how often the second code disagreed
unconfirmed_hits hits served on the first code alone

⚠ unconfirmed_hits above zero means part of your fleet is not using the confirmed path. That is the number to alert on.

⚠ confirm_rejections: 0 means no collisions seen. It reads the same as nothing is checking, so check unconfirmed_hits too.

A second check: the stored bytes themselves

The two codes decide which saved entry to reuse. A separate check decides whether the bytes that came back are the bytes that were stored. It runs on every read from disk.
On disagreement the read is a miss: your host recomputes, exactly as for a cache miss
Counters integrity_failures, and an audit record naming the entry

⭐ A mismatch is never served. Recomputing is slower; it is not wrong.

This catches a bad disk, a cut-off write, a partial restore. For the strongest protection of the files on disk, use Encryption at Rest.

Verifying the check is live in your deployment

merlin_stats s;
memset(&s, 0, sizeof s);
s.struct_size = sizeof s;
merlin_get_stats(&s);
/* unconfirmed_hits == 0 AND confirm_rejections observed over time
   => the second code is being checked                            */

⭐ A forced-collision test settles it for your build. Store two entries whose first codes collide and whose second codes differ, then look up with merlin_lookup_confirmed: a miss proves the check runs. It is worth adding to your own integration tests.

Troubleshooting

Symptom Cause Fix
every confirmed lookup misses entries were stored with the plain form store with merlin_register_vram_confirmed
unconfirmed_hits above zero some hosts use the plain path make the fleet uniform
confirm_rejections climbing genuine collisions, or two hosts computing the second code differently use merlin_hash_tokens on both sides
confirm_rejections is 0 either no collisions, or nothing is checking verify with the confirmed path in a test
integrity_failures above zero a saved file was damaged the request recomputes; check the disk

Related

Clone this wiki locally