Profiles Are Immutable

"Once an id has been minted from a rule, that rule can never quietly change its mind. Change the rule, change its name."

A Profile Is a Contract, Not a Setting

A chunking profile defines exactly how a document's text becomes chunks — paragraph boundaries, size limits, overlap, whatever the rules are. Its id (say md-para-v1) is baked into every chunk id it produces. That makes the profile something stronger than a config knob: it's a contract. Every chunk id ever computed is a promise that says "this exact text, sliced these exact ways, under this exact rule set."

Why Mutating a Profile Breaks the Past

Now suppose you decide bigger chunks are better and edit md-para-v1 in place to use them. Every chunk id that profile ever produced still says md-para-v1 — but the rule those ids described no longer exists. Re-index and the same document produces different slices, different offsets, different ids. Every citation minted under the old behavior now points into a void: the id it saved describes a chunk the current md-para-v1 would never create. You didn't improve the profile; you silently invalidated its entire history.

The Rule: New Behavior Gets a New Id

The discipline is simple and absolute: changing chunking behavior means minting a new profile id — md-para-v2 — and never touching md-para-v1. The old profile keeps meaning exactly what it always meant. Documents can be re-chunked under v2 going forward, while every citation anchored to a v1 run stays perfectly resolvable, because v1's behavior is frozen forever. Old and new coexist; nothing from the past is orphaned.

Version the transform; never mutate it in place. Any transform whose output feeds into a durable identity — a chunker, a converter, a schema, a serialization format — must be versioned, not edited. The moment its behavior changes silently, everything that recorded 'produced by version X' becomes a lie. New behavior is a new version, and the old version stays alive as long as anything still references its output.

This Pattern Is Everywhere Durable

The same immutability governs the capture converters (change a strip rule, mint a new converter id) and it's the same reason results record which embedding and reranker model produced them. Anytime a system says "this artifact was produced by transform T," T must be frozen at that version forever, or the record stops being reproducible. Immutable, versioned transforms are how you keep a decade of derived artifacts explainable instead of accumulating a pile of outputs nobody can reproduce.

Code

Add v2; freeze v1 forever·python

# Profiles are a frozen registry. You ADD versions; you never edit one.
PROFILES = {
    "md-para-v1": ChunkingProfile(max_chars=1200, overlap=0, split="paragraph"),
    # Want bigger chunks? Do NOT touch v1 above. Add v2:
    "md-para-v2": ChunkingProfile(max_chars=2400, overlap=100, split="paragraph"),
}

def get_profile(profile_id: str) -> ChunkingProfile:
    return PROFILES[profile_id]   # v1 always means exactly what it always meant

# WRONG — this one line silently invalidates every citation ever made under v1:
# PROFILES["md-para-v1"].max_chars = 2400   # never mutate a published profile

Exercise

Find a transform in your own work whose output other things depend on — a data export format, a naming scheme, a preprocessing step, a build config. Ask: if you changed its behavior tomorrow, what downstream artifacts would silently become wrong? Design the versioning that would protect them: how would you name versions, and what would make the old version stay valid after the new one ships?

Hint

The test is whether an old output plus its recorded version number is enough to reproduce or explain that output forever. If changing the transform in place would make old records lie, the transform needs a version id and a freeze-the-old-one rule.

A Profile Is a Contract, Not a Setting

Why Mutating a Profile Breaks the Past

The Rule: New Behavior Gets a New Id

This Pattern Is Everywhere Durable

Code

External links

Exercise

Progress

Comments 0