Knowledge Versioning — Patterns

A composite corpus revision over every input that changes a result

Problem. Versioning documents explains nothing about a quality change caused by a new segmentation rule or a new encoder, and versioning the index explains nothing about which document revisions went into it. Each layer alone leaves the most common questions unanswerable.

Approach. Define a corpus revision as a tuple — the source snapshot identifier, the extraction and segmentation configuration identity, the encoding configuration identity, and the index generation — hashed into a single short identifier. Record it on the index, emit it on every retrieval response, and store it on every answer. Any difference between two results then has a first question with a cheap answer: were they the same revision.

Trade-off. The tuple must cover everything that changes a result, and anything omitted produces false equivalence that is worse than no identifier. Revisions also churn rapidly on a continuously updating corpus, so the identifier is better understood as a label on a configuration plus a point in a stream than as a discrete release.

Separate explanation from reproduction, and price them differently

Problem. Retaining enough to re-run a query against a past state means retaining its vectors, which for a large corpus is the single most expensive retention decision available. Retaining nothing means a disputed answer cannot be examined at all. Teams tend to choose between these two without noticing there is a middle.

Approach. Default to explanation: retain the extracted text and unit content for every state long enough to say what a citation pointed at, which is small, compresses well and answers most disputes. Reserve reproduction — a retained index generation that can actually be queried — for the narrow cases that need it, scoped by document class or by a legal hold, and give each one an expiry.

Trade-off. Explanation cannot answer counterfactual questions such as what else would have been retrieved, which is exactly what a regression investigation wants. The scoping rule for reproduction is also a prediction about which disputes will arise, and predictions of that kind are usually wrong in the direction of retaining too little.

Retained states inside the deletion boundary by construction

Problem. Retention for audit and erasure on request pull in opposite directions, and the default resolution is accidental: deletions are executed against the live corpus because that is what the pipeline knows about, and retained states quietly keep the content.

Approach. Make every retained state enumerable by the same mechanism that enumerates the live one, and make the deletion path iterate over states rather than assume one. Where a state must remain byte-identical for evidentiary reasons, hold it under an explicit legal hold with a named owner and an expiry, so the exception is a recorded decision rather than an oversight.

Trade-off. Deleting from an immutable retained state either breaks its immutability or requires rebuilding it, and both undermine what the retention was for. Holding exceptions needs governance that most teams do not have, and an unreviewed hold becomes indefinite retention under another name.

Pin the state for a comparison, not for serving

Problem. Point-in-time serving is attractive and expensive: it keeps old generations alive, old encoders deployed and old schemas supported, and a pin taken for a short audit tends to outlive its reason.

Approach. Treat pinning as an evaluation and investigation facility rather than a serving feature. Comparisons between configurations run against one frozen revision so the content is held constant; production always serves the current revision and records which one that was. Where a user-facing historical view is genuinely required, serve it from the retained content rather than from a retained index, which answers "what did this say" without keeping a whole retrieval stack alive.

Trade-off. This forecloses genuine point-in-time retrieval — the question of what the system would have returned in March cannot be answered without March's index. Freezing a revision for comparison also means the comparison is against a corpus that is progressively less like production the longer the frozen revision is used.