Freshness and reindexing: Evaluation and operations

Defines freshness objectives, version propagation, reindex workflows, deletion visibility, and reconciliation evidence for a RAG index derived from changing source documents.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Model indexing as a versioned projection, not a copy job. Each chunk points to an immutable source version; active aliases switch only after validation, and deletions or access revocations have a stricter visibility objective than ordinary updates.

Scope

• Source discovery, change identity, chunking profile, embedding, index build, alias switch, deletion, access revocation, reconciliation, and rollback.
• Incremental and full rebuild paths.
• Freshness metrics from source observation to searchable visibility.

Outside this block

• Source-system backup or editorial approval of document truth.
• Answer-cache invalidation beyond recording source versions for a separate cache policy.

Contract

• Every indexed chunk records source ID, source version, content digest, chunk profile, embedding profile, observed time, and visibility policy version.
• Repeated processing of the same source version is idempotent.
• An active index generation becomes visible only after count, sampling, authorization, and retrieval smoke checks pass.
• Deletion and access revocation create durable tombstones that suppress matching chunks across active and rebuilding generations.
• A full rebuild can run beside the active index and switches through a reversible alias or routing version.
• Freshness SLOs are measured separately for creates, updates, deletes, and authorization changes.

Implementation guidance

• Use a change ledger with monotonic source offsets or durable per-source version events.
• Propagate tombstones before expensive embedding work.
• Reconcile source inventory, ledger, object/chunk counts, and active index samples.
• Keep the previous accepted generation through a configured rollback window.

Failure handling and safeguards

• If embedding fails, retry the immutable version and keep the previous source version active when policy permits.
• If authorization data is stale, suppress the affected source rather than exposing it under an old policy.
• If validation fails, do not switch the active alias; retain evidence and repair the candidate generation.

Verification and operations

• Measure observe-to-searchable lag by change class, backlog age, failed versions, stale-active documents, tombstone propagation, reconciliation deltas, and alias rollback time.
• Alert on authorization/deletion SLO breaches more aggressively than content-update lag.
• Run scheduled retrieval probes for newly updated and revoked fixtures.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Names and numeric values in example.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• No external normative source is required; this package defines a project decision.