Proof and replay

KyroDB evidence workflows exist so a developer can answer:

Why was this answer fresh, stale-blocked, degraded, irrelevant, or wrong-scope?

Trace-first debugging

Every retrieve response includes a trace_id.

Use it immediately:

const trace = await client.observability.getTrace(packet.trace_id);
const diagnosis = await client.observability.diagnoseTrace(packet.trace_id);

Trace and diagnosis help separate:

• stale source data;
• missed invalidation;
• backend unavailable;
• strict freshness blocked;
• cache reuse hit;
• fresh but irrelevant context;
• wrong-scope feedback.

Feedback

Record feedback when the served context was useful, stale, irrelevant, or wrong-scope.

await client.recordFeedback({
  trace_id: packet.trace_id,
  signal: "stale",
  comment: "The answer used the old refund policy."
});

Feedback becomes evidence for root-cause reports and proof workflows. It should be treated as operational signal, not analytics fluff.

Proof bundles

Proof bundles are redacted artifacts for adoption reviews and incident analysis.

const bundle = await client.admin.buildProofBundle({ recent: 100 });

A proof bundle should answer:

• what traffic was evaluated;
• what stale incidents were prevented;
• what degraded behavior remains;
• which evidence was redacted;
• whether proof quality is strong enough for cutover.

Do not send raw replay capture to customers. Use redacted proof bundles or root-cause reports.

Replay and shadow

Replay is the adoption gate. Capture traffic, replay it, compare baseline and candidate behavior, then cut over only if safety gates pass.

const capture = await client.admin.exportReplayCapture({ recent: 100 });
 
const shadow = await client.admin.createShadowSession({
  schema_version: 1,
  replay_primer: capture.replay_primer
});

Cutover should fail on:

• strict freshness regressions;
• scope incidents;
• artifact alignment failures;
• candidate serving stale context where baseline blocked;
• proof-validation warnings that weaken the freshness claim.

Latency jitter should not be treated as semantic replay difference.