chadtmiller.com/knotless

Switch repository

Loading…

What changes

A mirror goes stale only with the writes that can change its own repository. A ref, claim or pack record is kept under its repository's key (the start of its record key), so a feed event of one counts only for that repository's mirrors. A repository's own record, a redirect, an identity, account or sync event, and a write from the pages still count for every mirror of the account. The once-a-commit dedupe from "A push is one sync of its mirrors" is now kept per repository, so a commit that writes to two repositories syncs both.

A mirror's freshness is its account's account-wide events and its repository's own. A mirror whose key the server has yet to learn, before its first sync, goes stale with every event of the account, as before. Once a sync finds its key, the mirror counts as fresh only if no event of the account came during the sync.

Why

Freshness was counted per account. One push to chadtmiller.com/knotless bumped the DID's counter, which made every mirror of the account stale and synced each in the background at once. On prod at 19:28:46–48, about ten repositories (pds.js, hatk, steps, checkout-demo and the rest) synced within two seconds, each asking the same PDS and taking 0.5–1.5 s. A read of any of them could then wait on a sync it did not need.

How it was checked

a_record_of_one_repository_is_its_alone covers which records name a single repository. one_commit_is_one_touch is unchanged. Every serve test that reads a mirror after a feed event goes through the new freshness. clippy on knotless-serve passes locally; the rest is left to CI. After deploy, the check is that a push to knotless brings one mirror sync line, for knotless, rather than one for each of the account's repositories.

Shortcomings

Every mirror of the account is still visited in the background after an event. Those not written to are found fresh at once, with no PDS read. A private repository's mirror no longer goes stale with the owner's public pushes. Its own writes reach it through its space's sync or the pages, as before.

Changeset: none

🤖 Generated with Claude Code

This makes freshness two counters. One counts a DID's account-wide events. The other counts events for a single repository key, and only ref, claim and pack records produce it, since they're keyed <key>.…. A mirror's stamp is the pair, and a mirror whose key is still unknown goes stale with every event. The commit dedupe is now per (DID, key).

I found no bug in the logic. Repository keys are TIDs, so they contain no . and the split_once('.') is sound. settled keeps the old stamp when the key didn't change. When a sync first finds the key, it records a fresh stamp only if no event of the account arrived during the sync, and otherwise forces another sync. The design docs are updated, as AGENTS.md asks.

The check, test, docs and e2e runs hadn't finished when I looked. Please wait for them, in particular the 100% coverage gate in test. The Some(key) and None arms of heard_of and the settled paths need tests to reach them.

One small thing: the new docs/design/serve.md paragraph ends in one very long line, "event of a commit counts for each repository it writes…". Re-wrap it.