feat(telemetry_policy): canary refactor — headers from canon at runtime

[klappy]

Canary refactor — the governance anti-pattern sweep begins here

Replaces the hardcoded self_report_headers dictionary in telemetry_policy with a runtime parse of the ### Self-Report Fields table in canon/constraints/telemetry-governance.md. Response envelope now declares governance_source: "canon" | "minimal".

Why this one first

This is the lowest-stakes instance of the Vodka anti-pattern cataloged in docs/oddkit/audit/governance-anti-pattern-sweep-2026-04-17.md (PR #105). The goal is to prove the refactor template — single feature PR, single promotion PR, canon-change-no-redeploy preview smoke — before applying it to higher-stakes tools (validate, orient, gate, encode).

Scope is deliberately tight: one tool, one helper, ~80 lines of diff. If this takes more than 2 PRs to ship, the sweep pauses and we diagnose the template.

Contract conformance

Implements the three-tier resolution stack from klappy/klappy.dev#101 (canon/constraints/core-governance-baseline):

• Tier 1 (canon): getFile("canon/constraints/telemetry-governance.md") → parseSelfReportHeadersTable → governance_source: "canon"
• Tier 2 (bundled baseline): deferred — the manifest + baseline directory + build-time schema check arrive in follow-up work once the contract graduates from status: draft to status: active
• Tier 3 (minimal): 8 stable headers hardcoded as the floor. governance_source: "minimal" signals degradation to callers.

The companion canon doc ships tier:1 status:draft and uses this refactor as its first validation case.

Verification

• npm run typecheck clean
• Parser unit-tested against live canon content: 8/8 headers parsed
• Parser degradation paths (no section, empty table) return null
• Preview smoke against Cloudflare preview env with canon-change-no-redeploy (run after merge to main)
• Prod smoke after promotion PR

Public contract — additive, not breaking

• self_report_headers keys unchanged (still the same 8 x-oddkit-* headers)
• self_report_headers values change slightly — canon's terser descriptions now win when the canon tier succeeds, which is the intended behavior per canon/principles/dry-canon-says-it-once
• New field governance_source added to the result object

Refactor discipline (from PR #100 post-mortem)

• Single site touched (workers/src/index.ts)
• No forward-fixes planned — if prod smoke fails, revert within 15 min and reopen
• Promotion PR follows only after preview smoke passes
• Audit row for telemetry_policy gets stamped when this lands

Related

• Audit: klappy/oddkit#105
• Canon contract (draft): klappy/klappy.dev#101
• Post-mortem this template was built from: klappy/oddkit#100, #101, #102, #103, #104

---

Note

Medium Risk
Adds runtime parsing of a governance markdown table to drive telemetry_policy output and introduces a new governance_source field; failures fall back to a minimal hardcoded baseline, but format drift or parsing bugs could change returned header descriptions.

Overview
telemetry_policy now derives self_report_headers from canon at runtime by parsing the ### Self-Report Fields markdown table in canon/constraints/telemetry-governance.md, and adds governance_source (canon|minimal) to explicitly signal whether canon parsing succeeded or the minimal fallback was used.

Introduces a shared parseTableRow helper in markdown-utils.ts (reused by orchestrate.ts) and extends the governance parser test to validate the self-report headers extraction and degradation behavior.

^{Reviewed by Cursor Bugbot for commit db1936d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	oddkit	db1936d	Commit Preview URL Branch Preview URL	Apr 18 2026, 10:21 PM

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Duplicated parseTableRow risks silent drift between copies
  • Extracted parseTableRow into a new shared workers/src/markdown-utils.ts module and updated both index.ts and orchestrate.ts to import from it, eliminating the duplicated implementations; typecheck passes.

Preview (7b2d68bcfb)

diff --git a/workers/src/index.ts b/workers/src/index.ts
--- a/workers/src/index.ts
+++ b/workers/src/index.ts
@@ -22,6 +22,7 @@
 import { RequestTracer } from "./tracing";
 import { parseConsumerLabel } from "./telemetry";
 import { renderNotFoundPage } from "./not-found-ui";
+import { parseTableRow } from "./markdown-utils";
 import pkg from "../package.json";
 
 export type { Env };
@@ -29,6 +30,40 @@
 const BUILD_VERSION = pkg.version;
 
 // ──────────────────────────────────────────────────────────────────────────────
+// Canon-table parsing helper.
+//
+// parseSelfReportHeadersTable extracts the self-report header contract from
+// canon/constraints/telemetry-governance.md. The table format is governed by
+// the canon doc itself; this parser is deliberately permissive (whitespace,
+// backticks around header name) and fails closed to null so the caller can
+// fall back to the minimal baseline without hiding the degradation.
+// ──────────────────────────────────────────────────────────────────────────────
+
+function parseSelfReportHeadersTable(markdown: string): Record<string, string> | null {
+  // Target section: "### Self-Report Fields" — grab the table that follows.
+  // Stop at the next `###` or `##` heading, whichever comes first.
+  const section = markdown.match(
+    /###\s+Self-Report Fields[^\n]*\n([\s\S]*?)(?=\n###|\n##|$)/,
+  );
+  if (!section) return null;
+
+  const headers: Record<string, string> = {};
+  for (const raw of section[1].split("\n")) {
+    if (!raw.includes("|")) continue;
+    const cols = parseTableRow(raw);
+    // Expected layout: | Field | Header | Source |
+    // Skip header row, separator row, and any malformed row.
+    if (cols.length < 2) continue;
+    const fieldDescription = cols[0];
+    const headerName = cols[1].replace(/`/g, "").trim();
+    if (!headerName.startsWith("x-oddkit-")) continue; // skip header/separator
+    headers[headerName] = fieldDescription;
+  }
+
+  return Object.keys(headers).length > 0 ? headers : null;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
 // Consumer identification nudge
 //
 // DO NOT add session caching, sticky identification, or per-session memory.
@@ -451,7 +486,7 @@
 
   server.tool(
     "telemetry_policy",
-    "Return oddkit telemetry and sharing policy guidance. What is tracked, what is excluded, and why. Fetched from canonical governance document at runtime.",
+    "Return oddkit telemetry and sharing policy guidance. What is tracked, what is excluded, and why. Fetched from canonical governance document at runtime. Response envelope declares governance_source (canon|baseline|minimal) per canon/constraints/core-governance-baseline.",
     {},
     {
       readOnlyHint: true,
@@ -460,17 +495,52 @@
       openWorldHint: true,
     },
     async () => {
-      // Fetch the governance doc from canon
+      // Governance resolution per canon/constraints/core-governance-baseline:
+      //   1. Live canon fetch (preferred) → governance_source: "canon"
+      //   2. Minimal baseline (shipped in code) → governance_source: "minimal"
+      //
+      // This canary refactor implements tiers 1 and 3 only. The bundled
+      // baseline tier (2) and the build-time schema check arrive in follow-up
+      // work; the manifest + baseline directory are not yet in place.
       const fetcher = new ZipBaselineFetcher(env);
-      let policyContent = "Governance document not found. See https://github.com/klappy/klappy.dev/blob/main/canon/constraints/telemetry-governance.md";
+      let policyContent: string | null = null;
+      let selfReportHeaders: Record<string, string> | null = null;
+      let governanceSource: "canon" | "baseline" | "minimal" = "minimal";
 
       try {
         const content = await fetcher.getFile("canon/constraints/telemetry-governance.md");
-        if (content) policyContent = content;
+        if (content) {
+          policyContent = content;
+          const parsed = parseSelfReportHeadersTable(content);
+          if (parsed && Object.keys(parsed).length > 0) {
+            selfReportHeaders = parsed;
+            governanceSource = "canon";
+          }
+        }
       } catch {
-        // Fall through to default message
+        // Fall through to minimal tier below
       }
 
+      if (governanceSource === "minimal") {
+        // Minimal baseline — the tool remains useful when canon is unreachable
+        // or the table cannot be parsed. These eight headers are the stable
+        // self-report contract; if canon adds a 9th, the "canon" tier delivers
+        // it and this list stays as the floor.
+        selfReportHeaders = {
+          "x-oddkit-client": "Your client name (highest priority identifier)",
+          "x-oddkit-client-version": "Your client version",
+          "x-oddkit-agent-name": "The AI agent name",
+          "x-oddkit-agent-version": "The AI agent version",
+          "x-oddkit-surface": "Where this is running (e.g. claude.ai, vscode)",
+          "x-oddkit-contact-url": "URL for your project or org",
+          "x-oddkit-policy-url": "Your privacy/telemetry policy URL",
+          "x-oddkit-capabilities": "Comma-separated capability list",
+        };
+        if (!policyContent) {
+          policyContent = "Governance document not reachable. See https://github.com/klappy/klappy.dev/blob/main/canon/constraints/telemetry-governance.md";
+        }
+      }
+
       return {
         content: [{
           type: "text" as const,
@@ -479,16 +549,8 @@
             result: {
               policy: policyContent,
               governance_uri: "klappy://canon/constraints/telemetry-governance",
-              self_report_headers: {
-                "x-oddkit-client": "Your client name (highest priority identifier)",
-                "x-oddkit-client-version": "Your client version",
-                "x-oddkit-agent-name": "The AI agent name",
-                "x-oddkit-agent-version": "The AI agent version",
-                "x-oddkit-surface": "Where this is running (e.g. claude.ai, vscode)",
-                "x-oddkit-contact-url": "URL for your project or org",
-                "x-oddkit-policy-url": "Your privacy/telemetry policy URL",
-                "x-oddkit-capabilities": "Comma-separated capability list",
-              },
+              governance_source: governanceSource,
+              self_report_headers: selfReportHeaders,
               generated_at: new Date().toISOString(),
             },
           }, null, 2),

diff --git a/workers/src/markdown-utils.ts b/workers/src/markdown-utils.ts
new file mode 100644
--- /dev/null
+++ b/workers/src/markdown-utils.ts
@@ -1,0 +1,24 @@
+/**
+ * Shared markdown parsing helpers.
+ *
+ * Keep this module dependency-free so it can be imported from any code path
+ * (orchestrate, index, future canon readers) without pulling in unrelated
+ * state. Every helper here must be pure and stateless.
+ */
+
+/**
+ * Parse a single markdown table row into trimmed cell values, preserving
+ * legitimately-empty middle cells. Only the leading and trailing empty strings
+ * produced by splitting a `| a | b |`-style row are stripped — a prior
+ * `.filter(c => c.length > 0)` approach also dropped empty interior cells,
+ * which silently collapsed the column count and caused `cols.length >= N`
+ * guards to misfire (e.g. a voice-dump row with an empty tiers cell).
+ */
+export function parseTableRow(row: string): string[] {
+  const parts = row.split("|");
+  // Strip the leading empty produced by a leading `|`, if present
+  if (parts.length > 0 && parts[0].trim() === "") parts.shift();
+  // Strip the trailing empty produced by a trailing `|`, if present
+  if (parts.length > 0 && parts[parts.length - 1].trim() === "") parts.pop();
+  return parts.map((c) => c.trim());
+}

diff --git a/workers/src/orchestrate.ts b/workers/src/orchestrate.ts
--- a/workers/src/orchestrate.ts
+++ b/workers/src/orchestrate.ts
@@ -18,6 +18,7 @@
   type SectionResult,
 } from "./zip-baseline-fetcher";
 import { buildBM25Index, searchBM25, type BM25Index } from "./bm25";
+import { parseTableRow } from "./markdown-utils";
 import type { RequestTracer } from "./tracing";
 import pkg from "../package.json";
 
@@ -155,27 +156,6 @@
 }
 
 // ──────────────────────────────────────────────────────────────────────────────
-// Markdown table helpers
-// ──────────────────────────────────────────────────────────────────────────────
-
-/**
- * Parse a single markdown table row into trimmed cell values, preserving
- * legitimately-empty middle cells. Only the leading and trailing empty strings
- * produced by splitting a `| a | b |`-style row are stripped — a prior
- * `.filter(c => c.length > 0)` approach also dropped empty interior cells,
- * which silently collapsed the column count and caused `cols.length >= N`
- * guards to misfire (e.g. a voice-dump row with an empty tiers cell).
- */
-function parseTableRow(row: string): string[] {
-  const parts = row.split("|");
-  // Strip the leading empty produced by a leading `|`, if present
-  if (parts.length > 0 && parts[0].trim() === "") parts.shift();
-  // Strip the trailing empty produced by a trailing `|`, if present
-  if (parts.length > 0 && parts[parts.length - 1].trim() === "") parts.pop();
-  return parts.map((c) => c.trim());
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
 // BM25 Index Cache (per-request, lazy)
 // ──────────────────────────────────────────────────────────────────────────────

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit af861a7. Configure here.}