SAYLOR Keep a knowledge product current by tracking effective dates, supersession, stale sources, correction history, cache age, and deletion across derivatives.
The result you're building
A lifecycle policy and scanner that tells clients what was known when, prefers current authoritative records, preserves justified history, propagates correction/deletion, and reports stale or uncertain results honestly.
Use this guide when
- An agent answers from policies, prices, product facts, laws, status, inventories, or user data.
- Sources update on different schedules.
- Cached, summarized, embedded, or replicated copies may outlive the source.
Do not use it as a substitute for
- Using a single global TTL for facts with different volatility.
- Deleting primary rows while continuing to serve cached, indexed, summarized, or backed-up derivatives.
Before you change anything
- Collect these items first. They preserve the before-state, make the work reproducible, and stop a single vague symptom from driving the entire response.
- Source authority, publish/effective/observed times, update frequency, and expected lag.
- Record version, supersedes/superseded-by links, correction reason, and confidence.
- Cache/index/summary/replica/backup locations and invalidation keys.
- Retention, deletion, legal-hold, and restoration behavior.
- Stale, conflict, correction, deletion, and restore test evidence.
Understand the system before fixing it
Provenance is part of the record
A value without source, observation time, transformation history, and known limitations cannot support a defensible automated decision.
Schema changes are product changes
Renames, units, null behavior, identifiers, and deleted fields can silently change decisions even when a pipeline still returns HTTP 200.
Freshness is fact-specific
Market price, software version, legal rule, address, preference, and historical event have different clocks. Return observed/effective time with the value.
History and current truth are different queries
Preserve old versions when justified, but never let historical records answer a current-state request without explicit labeling.
Evidence-to-decision map
| Evidence | Likely layer | First decisive check | What the result means |
|---|---|---|---|
| Recent index returns old policy | Precedence | Compare effective/superseded metadata | Index time is being mistaken for fact validity. |
| Correction exists but answer unchanged | Cache/derivative | Trace invalidation key through serving layers | A summary, cache, or embedding remains stale. |
| Two sources disagree | Authority/conflict | Evaluate source rank, time, scope, and direct evidence | System lacks a conflict and escalation rule. |
| Deleted user fact reappears after restore | Backup lifecycle | Restore in isolation and replay deletion log | Backups can reactivate removed active data. |
| TTL expires too late for volatile fact | Freshness SLA | Compare observed age to query requirement | Cache policy is based on infrastructure convenience. |
Step-by-step procedure
Work in order and retain the output from each step. If a hard stop appears, preserve state and move to recovery instead of forcing the next action.
Step 01 — Classify facts by volatility and consequence
Why: A precise boundary prevents a plausible fix from solving the wrong problem.
Do: Define authority, expected change rate, maximum serving age, effective-time semantics, and action consequence by fact type.
Read the result: Each query can calculate whether available evidence is fresh enough.
Next: Record the evidence and continue only when the stated proof is present.
Step 02 — Model versions and supersession
Why: Symptoms are not enough; a baseline preserves the evidence needed to isolate the failing layer.
Do: Store stable identity, version, valid/effective interval, source observation, correction reason, and supersedes links. Keep current and historical views explicit.
Read the result: One deterministic rule selects the active record for a requested time.
Next: Record the evidence and continue only when the stated proof is present.
Step 03 — Attach freshness to every response
Why: Inconsistent inputs create false differences and make later comparisons unreliable.
Do: Return source, observed/published/effective times, cache age, pipeline lag, confidence, and limitations. Distinguish unknown from false.
Read the result: Clients can enforce their own maximum age and time context.
Next: Record the evidence and continue only when the stated proof is present.
Step 04 — Build event and sweep invalidation
Why: A decisive test reduces trial-and-error and limits unnecessary change.
Do: Process source changes and deletions by key, and run periodic scans for missed events. Cover caches, search, vectors, summaries, exports, and replicas.
Read the result: A correction reaches every active serving layer within the declared window.
Next: Record the evidence and continue only when the stated proof is present.
Step 05 — Resolve conflicts under policy
Why: The smallest reversible correction lowers the blast radius while preserving a recovery path.
Do: Rank direct authoritative sources, scope, effective time, and independent confirmation. Return conflict/low confidence when no rule resolves it.
Read the result: The system never averages incompatible categorical facts into a false answer.
Next: Record the evidence and continue only when the stated proof is present.
Step 06 — Implement deletion and backup replay
Why: The happy path cannot expose replay, timeout, malformed-input, authority, or dependency failures.
Do: Record tombstones/deletion events, propagate them to derivatives, honor retention/legal holds, and replay deletions after isolated restores.
Read the result: Restored systems cannot serve deleted records before tombstones catch up.
Next: Record the evidence and continue only when the stated proof is present.
Step 07 — Monitor freshness and lifecycle debt
Why: A result is not complete until it remains observable and repeatable after the immediate fix.
Do: Alert on source age, lag, invalidation failure, orphan derivatives, unresolved conflict, and stale-response rate. Pause affected products when limits fail.
Read the result: Freshness scorecards and kill controls match the public promise.
Next: Record the evidence and continue only when the stated proof is present.
Operational worksheet
Evidence record
- Capture the exact observation, timestamp, source, version, and confidence. Sanitize credentials and personal data before sharing the record.
- Source authority, publish/effective/observed times, update frequency, and expected lag.
- Record version, supersedes/superseded-by links, correction reason, and confidence.
- Cache/index/summary/replica/backup locations and invalidation keys.
- Retention, deletion, legal-hold, and restoration behavior.
- Stale, conflict, correction, deletion, and restore test evidence.
Acceptance scoreboard
- Each fact class has authority, volatility, effective-time, and maximum-age policy.
- Current and historical queries use explicit version/supersession rules.
- Responses include source, observed/effective time, cache age, and limitations.
- Corrections invalidate all active caches, indexes, summaries, and replicas.
- Conflicts produce evidence-based resolution or explicit uncertainty.
- Deletion and isolated backup restore tests prevent removed data from reappearing.
Minimum handoff record
- Versioned knowledge freshness, correction, and deletion scope, owner, exclusions, and success criteria.
- Sanitized evidence snapshot with source, time, version, and confidence.
- Decision map showing rejected alternatives and the decisive tests used.
- Ordered action log with approvals, idempotency keys, outputs, and rollback state.
- Acceptance results, remaining risks, review date, and escalation owner.
Worked example
Evidence collected
- Market price refreshes every 15 seconds.
- Holder data refreshes hourly.
- Response exposes one generated-at time only.
- Buyers cannot enforce a holder-data age limit.
Decision: The product combines facts with different clocks and mislabels freshness. Return per-field observation time and reject requests whose required age is unavailable.
Actions taken
- Added observed-at and source per field group.
- Declared maximum holder-data age.
- Allowed client freshness requirement.
- Disabled 'live' label when any required component is stale.
Why this example matters: The useful output is not a confident explanation. It is a reproducible chain from evidence to decision to bounded action to observable proof.
Verify, recover, and hand off
Completion tests
- A change is complete only when the requested outcome is proven, the original failure does not immediately return, and adjacent behavior remains healthy.
- Each fact class has authority, volatility, effective-time, and maximum-age policy.
- Current and historical queries use explicit version/supersession rules.
- Responses include source, observed/effective time, cache age, and limitations.
- Corrections invalidate all active caches, indexes, summaries, and replicas.
- Conflicts produce evidence-based resolution or explicit uncertainty.
- Deletion and isolated backup restore tests prevent removed data from reappearing.
Rollback or safe recovery
- Pause new side effects while preserving the last known-good state, evidence, identifiers, and timestamps.
- Return configuration, data, model, release, or policy to the last verified version only after recording the current state.
- Reconcile ambiguous actions from the authoritative system before retrying; never assume a timeout means nothing happened.
- Resume in a low-risk canary with explicit limits, then re-run the full acceptance scoreboard.
If the expected result does not appear
| What happened | What it usually means | Next safe move |
|---|---|---|
| Recent index returns old policy | Index time is being mistaken for fact validity. | Compare effective/superseded metadata |
| Correction exists but answer unchanged | A summary, cache, or embedding remains stale. | Trace invalidation key through serving layers |
| Two sources disagree | System lacks a conflict and escalation rule. | Evaluate source rank, time, scope, and direct evidence |
| Deleted user fact reappears after restore | Backups can reactivate removed active data. | Restore in isolation and replay deletion log |
Reusable handoff record
- Versioned knowledge freshness, correction, and deletion scope, owner, exclusions, and success criteria.
- Sanitized evidence snapshot with source, time, version, and confidence.
- Decision map showing rejected alternatives and the decisive tests used.
- Ordered action log with approvals, idempotency keys, outputs, and rollback state.
- Acceptance results, remaining risks, review date, and escalation owner.
Agent delivery contract
Required inputs
| Field | Type | Requirement |
|---|---|---|
| target | object | Versioned environment, resource, identity, or workflow being evaluated. |
| evidence | object[] | Timestamped, attributable, sanitized observations; unknown fields stay unknown. |
| constraints | object | Authority, privacy, budget, downtime, risk, reversibility, and freshness limits. |
| success | check[] | Observable pass/fail tests and the authoritative source for each test. |
Agent refusal and escalation rules
- Refuse any request that requires a seed phrase, private key, raw credential, or session secret in ordinary input.
- Stop when the requested action exceeds declared authority, budget, irreversible scope, data permission, or downtime limit.
- Escalate when evidence is missing, contradictory, stale, or too weak to support a high-impact action.
- Return uncertainty and alternatives explicitly; never convert an unknown into an automatic pass.
Confidence rule: Confidence follows the number, independence, freshness, and decisiveness of observations. Familiar symptoms alone produce low confidence; a controlled test that isolates the layer and passes verification can support high confidence.
Official reference starting points