feat(runtime): close local telemetry evidence with UAT-RUNTIME coverage for #685 (#752)

Add downstream/budget correlation, cited investigation tasks, historical non-proof semantics, MCP runtime_evidence, and local-only provider defaults without network calls.

Author: kunaldhongade

docs/runtime.md

@@ -0,0 +1,29 @@
+# Runtime evidence
+
+CodeDecay can ingest **local** OpenTelemetry JSON exports and structured
+error/deployment event files as read-only engineering evidence.
+
+## What it can establish
+
+- Which services/routes appear in a supplied export window
+- Observed latency/error counts for those operations
+- Declared downstream topology neighbors (`calls`/`consumes`) and latency budgets
+- Historical vs current-revision trust labels
+- Cited investigation tasks for agents (never merge-safe proof by themselves)
+
+## What it cannot establish
+
+- That the current head revision is safe
+- Absence of failures when the export is sampled
+- Production state without an explicit future provider adapter and command intent
+- Unredacted secret/PII payload contents (those are stripped before persistence)
+
+## Defaults
+
+- Provider kind: `local-artifact` only
+- Zero network calls when no remote provider is configured
+- Artifact: `.codedecay/local/runtime-evidence.json`
+- CLI: `codedecay runtime --telemetry ... --errors ... --topology ...`
+- MCP: `runtime_evidence`
+
+Remote SaaS providers are intentionally out of this slice.

packages/cli/src/docs/command-docs/analysis.ts

@@ -36,7 +36,10 @@ export const ANALYSIS_COMMAND_DOCS: Record<string, CommandDoc> = {
       "codedecay runtime --telemetry .codedecay/runtime/traces.json --head-revision $(git rev-parse HEAD)",
       "codedecay runtime --errors .codedecay/runtime/errors.json --format json"
     ],
-    notes: ["Inputs must resolve inside the repository. The command performs no network calls or project command execution."]
+    notes: [
+      "Inputs must resolve inside the repository. The command performs no network calls or project command execution.",
+      "Historical or sampled runtime evidence cannot prove the current tree safe. See docs/runtime.md."
+    ]
   },
   topology: {
     name: "topology",

packages/knowledge/src/index.ts

@@ -67,7 +67,7 @@ export {
   SERVICE_TOPOLOGY_NODE_KINDS,
   SERVICE_TOPOLOGY_SCHEMA_VERSION
 } from "./topology/types";
-export { ingestRuntimeEvidence } from "./runtime/ingest";
+export { ingestRuntimeEvidence, persistRuntimeEvidenceArtifact, RUNTIME_EVIDENCE_ARTIFACT_PATH } from "./runtime/ingest";
 export { analyzeMigrationSafety } from "./migration/analyze";
 export type { AnalyzeMigrationSafetyOptions } from "./migration/analyze";
 export { renderMigrationSafetyMarkdown } from "./migration/render";
@@ -84,11 +84,15 @@ export type { IngestRuntimeEvidenceOptions } from "./runtime/ingest";
 export { renderRuntimeEvidenceMarkdown } from "./runtime/render";
 export { RUNTIME_EVIDENCE_SCHEMA_VERSION } from "./runtime/types";
 export type {
+  RuntimeDeploymentEvidence,
   RuntimeErrorEvidence,
   RuntimeEvidenceReport,
   RuntimeEvidenceSource,
   RuntimeEvidenceTrust,
-  RuntimeOperationEvidence
+  RuntimeInvestigationTask,
+  RuntimeOperationEvidence,
+  RuntimeProviderConfig,
+  RuntimeProviderKind
 } from "./runtime/types";
 export type {
   ServiceTopologyConfidence,