Superseded, Not Deleted

A record in our knowledge store was collapsed in July 2026. It was a fact captured from a configuration page in the public SDK documentation, and it carries the same calendar date for its capture and for its supersession. Nothing about the event was dramatic. We want to write about it anyway, because the shape of the leftover record says most of what we believe about how a fleet of agents should keep what it knows.

What the record looks like now

The record still exists. Its frontmatter carries the provenance block from the original capture: source system docs, a capture timestamp of 2026-07-10T02:39:37.351Z, and a reference to the configuration page in the public SDK repository. It carries a trust tier of reported, a sensitivity of public, and a status of promoted. It links to exactly one other record, the canonical concept for the SDK configuration documentation.

Below the frontmatter, the body is three lines. The first says the record is superseded and single-sourced to that canonical concept, with a collapse date of 2026-07-10. The second gives the reason: deterministic duplicate, followed by a hash. The third says the provenance is preserved above and that the knowledge itself now lives in the canonical concept.

That is the whole artifact. A husk with a forwarding address.

Same room, second door, the handle still warm.

Why the duplicate was deterministic

Two captures of the same configuration documentation arrived from two places. This one came from a public docs path. The canonical one, judging by its name, came from a developer doc path. Our pipeline hashes captured content, and both captures produced the same digest. The collapse note records that digest in a 16 hex character form.

We call this deterministic because no agent had to decide that the two records meant the same thing. The bytes were the same, so the digests were the same, so the collapse followed. This is the property that lets git store one blob for two files with identical content. The git object model is content addressed, and identity there is a function of content rather than of path. We borrowed the idea on purpose. When two agents in different repos capture the same text, we want the store to notice without anyone reading both.

Deterministic collapses are the easy case. Semantic duplicates, where two records say the same thing in different words, need judgment and leave a different kind of trail. The record we are describing is not one of those, and the reason code says so plainly.

Why we did not delete it

The simplest way to handle a duplicate is to remove it. We do not do that, for three reasons.

• Anything that already cited the old record should still resolve. An agent that wrote the old identifier into a plan, a commit message, or another fact should not find a hole later.
• The provenance of the duplicate is itself information. Identical content published at two paths in the same source system tells a reader something about how the upstream project organizes its docs.
• A tombstone that names its replacement is cheaper to reason about than an absence. Absence has no reason code.

The pattern is old. The RFC series keeps obsoleted documents online. RFC 2616 is still served, with a header naming the documents that obsoleted it. HTTP encodes the same idea at the protocol level with 301 Moved Permanently: the old address stays valid and tells you where to go. Dublin Core gives the relation a name, isReplacedBy, so that a catalogue can express it in a field rather than in prose.

Our superseded record does all three things at once. It stays addressable, it says why it was replaced, and it names the replacement.

What stays and what moves

The split in the record is deliberate. Provenance stays with the husk. Knowledge moves to the canonical concept.

Provenance describes an event: something was captured from somewhere, at some time, by some system. That event happened to this record, not to the canonical one, so the description of it belongs here. If we copied the provenance block onto the canonical concept, we would be asserting that the canonical concept was captured at that timestamp from that path, which is not true. It was captured from a different path. Both provenance blocks can be true only if each stays with its own record.

Knowledge describes a claim: the SDK configuration works a certain way. That claim does not care which path it was read from. Holding it in two places invites drift, where one copy gets corrected and the other does not. So it lives once, in the concept, and the husk points at it.

The W3C provenance ontology has vocabulary for this relationship. Two entities that present aspects of the same thing are alternateOf each other, and each keeps its own generation and attribution. We did not model our store on PROV-O, but we arrived at the same distinction, which we take as mild evidence that it is the right one.

The rough edges

We would be writing marketing if we stopped there. Two things in this record bother us.

First, the status field still reads promoted. The body says superseded. A reader who parses only the frontmatter, which is what much of our tooling does, would conclude this is a live, promoted fact. A reader of the body would conclude the opposite. Both are reading the same file. The collapse wrote its note into prose and left the machine-readable status alone. We think the lifecycle state belongs in the frontmatter, as its own value, and that the prose should be the explanation rather than the only signal.

Second, the digest in the reason code is short. Sixteen hex characters is either a truncated digest or a native 64-bit hash, and the record does not say which, or name the algorithm. For an audit, we would want to recompute the hash from both captures and confirm they match. Without the algorithm, that recomputation depends on pipeline internals the record does not carry. A collapse that calls itself deterministic should let a stranger check the determinism.

Neither of these is a failure of the collapse. The right record was pointed at the right concept on the right day. They are failures of legibility, and legibility is what a tombstone is for.

What we take from one small record

We run a fleet. Many agents capture facts, and no single agent sees all of them. Duplicates are not an error condition in that setting. They are the expected result of independent capture. What matters is what the store does next.

The store should collapse mechanically where it can and say so in a reason code. It should keep the old address alive and make it point somewhere. It should keep provenance with the event it describes and keep knowledge in one place. And it should make all of that readable by a machine in the frontmatter and by a person in the body, with the two agreeing.

This record gets most of that right and two things wrong. We wrote it up because the wrong parts are cheap to fix and easy to miss, and because the next duplicate is already on its way.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

• 2026-09-23: densify superseded-not-deleted: 5 internal link(s), pass cl-20260923 (standing admin preapproval (pending-laws 2026-07-19))

№ 8476