{"id":"ops/kpi-evidence","relativePath":"ops/kpi-evidence.md","title":"SOTA §26 KPI Evidence Input","markdown":"# SOTA §26 KPI Evidence Input\n\nThis runbook defines the optional aggregate KPI evidence file consumed by `pnpm monitoring:telemetry:sync`.\n\n## Purpose\n\n`monitoring/kpis.json` stays auto-generated. When `monitoring/kpi-evidence.json` is present, telemetry sync uses it for production-like SOTA §26 inputs that cannot be inferred reliably from local seed records:\n\n- record enrichment share (`dataQualityEnrichedShare`)\n- reconciliation auto-approval rate (`reconciliationAutoApproveRate`)\n- reviewed reconciliation precision (`reconciliationPrecisionReviewed`)\n\nIf the evidence file is missing or invalid, telemetry sync falls back to record-state heuristics and does **not** manufacture passing values.\n\n## Default Path\n\n- Default: `monitoring/kpi-evidence.json`\n- Override: `METAMUSEUM_KPI_EVIDENCE_PATH`\n\n## JSON Shape\n\n```json\n{\n  \"version\": 1,\n  \"updatedAt\": \"2026-06-10T00:00:00.000Z\",\n  \"records\": {\n    \"totalRecords\": 10000,\n    \"enrichedRecords\": 8300,\n    \"source\": \"warehouse materialized records\"\n  },\n  \"reconciliation\": {\n    \"scoreDistribution\": {\n      \"autoLink\": 920,\n      \"weeklyDigest\": 50,\n      \"humanReview\": 30,\n      \"dropCandidate\": 80\n    },\n    \"reviewedAutoLinkedCandidates\": 200,\n    \"acceptedAutoLinkedCandidates\": 190,\n    \"source\": \"curator review export\"\n  }\n}\n```\n\n## Validation Rules\n\n- `records.totalRecords` must be a positive integer.\n- `records.enrichedRecords` must be an integer from `0` to `totalRecords`.\n- Reconciliation considered candidates are `autoLink + weeklyDigest + humanReview`, or explicit `consideredCandidates`.\n- Auto-linked candidates are `scoreDistribution.autoLink`, `autoLinkedCandidates`, or `autoApprovedCandidates`.\n- Reviewed precision requires `acceptedAutoLinkedCandidates <= reviewedAutoLinkedCandidates <= autoLinkedCandidates`.\n- Invalid sections are ignored independently so one bad source cannot create false-green KPI evidence.\n\n## Workflow\n\n1. Export aggregate counts from production record materialization and curator review systems.\n2. Write the aggregate JSON to `monitoring/kpi-evidence.json` or set `METAMUSEUM_KPI_EVIDENCE_PATH`.\n3. Run `pnpm monitoring:telemetry:sync`.\n4. Inspect `monitoring/kpis.json` sources; evidence-backed sections cite the KPI evidence file and source label.\n","sections":[{"level":2,"heading":"Purpose","anchor":"purpose"},{"level":2,"heading":"Default Path","anchor":"default-path"},{"level":2,"heading":"JSON Shape","anchor":"json-shape"},{"level":2,"heading":"Validation Rules","anchor":"validation-rules"},{"level":2,"heading":"Workflow","anchor":"workflow"}],"html":"<h1 id=\"sota-26-kpi-evidence-input\">SOTA §26 KPI Evidence Input</h1>\n<p>This runbook defines the optional aggregate KPI evidence file consumed by `pnpm monitoring:telemetry:sync`.</p>\n<h2 id=\"purpose\">Purpose</h2>\n<p>`monitoring/kpis.json` stays auto-generated. When `monitoring/kpi-evidence.json` is present, telemetry sync uses it for production-like SOTA §26 inputs that cannot be inferred reliably from local seed records:</p>\n<ul><li>record enrichment share (`dataQualityEnrichedShare`)</li><li>reconciliation auto-approval rate (`reconciliationAutoApproveRate`)</li><li>reviewed reconciliation precision (`reconciliationPrecisionReviewed`)</li></ul>\n<p>If the evidence file is missing or invalid, telemetry sync falls back to record-state heuristics and does <strong>not</strong> manufacture passing values.</p>\n<h2 id=\"default-path\">Default Path</h2>\n<ul><li>Default: `monitoring/kpi-evidence.json`</li><li>Override: `METAMUSEUM_KPI_EVIDENCE_PATH`</li></ul>\n<h2 id=\"json-shape\">JSON Shape</h2>\n<pre><code>\n{\n  &quot;version&quot;: 1,\n  &quot;updatedAt&quot;: &quot;2026-06-10T00:00:00.000Z&quot;,\n  &quot;records&quot;: {\n    &quot;totalRecords&quot;: 10000,\n    &quot;enrichedRecords&quot;: 8300,\n    &quot;source&quot;: &quot;warehouse materialized records&quot;\n  },\n  &quot;reconciliation&quot;: {\n    &quot;scoreDistribution&quot;: {\n      &quot;autoLink&quot;: 920,\n      &quot;weeklyDigest&quot;: 50,\n      &quot;humanReview&quot;: 30,\n      &quot;dropCandidate&quot;: 80\n    },\n    &quot;reviewedAutoLinkedCandidates&quot;: 200,\n    &quot;acceptedAutoLinkedCandidates&quot;: 190,\n    &quot;source&quot;: &quot;curator review export&quot;\n  }\n}\n</code></pre>\n<h2 id=\"validation-rules\">Validation Rules</h2>\n<ul><li>`records.totalRecords` must be a positive integer.</li><li>`records.enrichedRecords` must be an integer from `0` to `totalRecords`.</li><li>Reconciliation considered candidates are `autoLink + weeklyDigest + humanReview`, or explicit `consideredCandidates`.</li><li>Auto-linked candidates are `scoreDistribution.autoLink`, `autoLinkedCandidates`, or `autoApprovedCandidates`.</li><li>Reviewed precision requires `acceptedAutoLinkedCandidates &lt;= reviewedAutoLinkedCandidates &lt;= autoLinkedCandidates`.</li><li>Invalid sections are ignored independently so one bad source cannot create false-green KPI evidence.</li></ul>\n<h2 id=\"workflow\">Workflow</h2>\n<ol><li>Export aggregate counts from production record materialization and curator review systems.</li></ol>\n<ol><li>Write the aggregate JSON to `monitoring/kpi-evidence.json` or set `METAMUSEUM_KPI_EVIDENCE_PATH`.</li></ol>\n<ol><li>Run `pnpm monitoring:telemetry:sync`.</li></ol>\n<ol><li>Inspect `monitoring/kpis.json` sources; evidence-backed sections cite the KPI evidence file and source label.</li></ol>","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"d7b2973d2927238f5efcc2a31a9f7056f2890d688aa41f903549cce8cd5ca4d0","checksumPrefix":"d7b2973d2927","anchorCount":5,"lineCount":60,"rawUrl":"/api/docs/content?path=ops%2Fkpi-evidence.md","htmlUrl":"/docs?doc=ops%2Fkpi-evidence.md","apiUrl":"/api/docs/content?path=ops%2Fkpi-evidence.md"}