About the implementation and examples
Engineering notes draw on author-supplied MailTrace development reports through 13 October 2026. They describe the documented revision, including local work, rather than independently verified live deployment. Experiment designs and architecture proposals describe work to evaluate. Examples are educational, use synthetic data and are not copied production code.
Reuse requires a complete identity
A cached result is safe only when its inputs and scope still match. For an embedding, that includes prepared content, model, dimensions and preparation version. For an answer, it also includes the question, authorised evidence scope and generation configuration. Two users asking the same question does not make their evidence interchangeable.
The documented embedding design allows compatible chunk reuse within the same case and builds immutable generations. Source hashes are checked before activation. These boundaries make reuse understandable: the system can explain exactly which work was reused and which change required a new result.
Separate current, stale and unavailable
The following teaching function expresses only freshness. Ownership and eligibility checks must happen before serving a saved result, even when this comparison succeeds. A matching revision is not an access token.
def freshness(saved, current):
keys = ("source_revision", "preparation_version", "model")
return "current" if all(saved.get(k) == current.get(k) for k in keys) else "stale"
saved = {"source_revision": 2, "preparation_version": "v1", "model": "demo"}
assert freshness(saved, dict(saved)) == "current"
assert freshness(saved, {**saved, "source_revision": 3}) == "stale"Measure work avoided as well as work accelerated
Useful metrics include paid calls per completed user task, duplicate submissions avoided, cache hit rate by operation and stale artifacts correctly blocked. End-to-end time includes queueing, retrieval, model generation and validation; optimising only provider latency may leave most of the delay untouched.
Invalidation should be explicit. A changed source can mark an answer stale without deleting its history. A failed replacement index should not silently remove the previous usable index. The user can then choose to prepare or analyse again with a clear explanation of the cost and coverage, while ordinary browsing remains a read operation.
References & further reading
Official documentation for the methods discussed. Application-specific details come from the development records described in the series note.