@dzhechkov/harness-core 0.7.7 → 0.7.8

package/src/ledger-backfill.ts

@@ -0,0 +1,237 @@
+/**
+ * Fill the run-cost ledger's missing numbers from the host's own workflow record.
+ *
+ * THE DEFECT THIS CLOSES (MEASURED 2026-08-25). `.dz/feature-adr/run-cost-ledger.jsonl` had 87 rows:
+ * 66 hand-typed rows carried `tokens`/`minutes`, and ALL 20 rows written automatically by the
+ * pipeline carried `tokens:null, minutes:null, agents:null`. So "what did this feature cost" was
+ * answerable only for runs a human retyped — 76% of the data was manual transcription.
+ *
+ * The numbers were never MISSING. They sit in the Claude Code host's workflow record (per-agent
+ * `tokens` and `durationMs`, verified to sum to the record's own total), and `deriveCostLedger`
+ * already reads them. The sandboxed workflow legitimately cannot: it has no filesystem and never
+ * sees the completion notification, which is why it writes `null` rather than an estimate — the
+ * right call, and the reason this join belongs on the dz side, AFTER the run.
+ *
+ * FOUR RULES, each one a test:
+ *  1. A derived number is MARKED ({@link LEDGER_FILL_SOURCE}). A number we computed must never be
+ *     indistinguishable from a number the operator asserted.
+ *  2. A non-null value is NEVER overwritten. The operator's number is their claim about their run;
+ *     ours is a derivation. When they disagree, theirs stands and the disagreement is reported.
+ *  3. A row we cannot fill is REPORTED, never silently skipped — no `runId`, or a `runId` with no
+ *     host record, comes back named. Silence would read as "nothing left to fill".
+ *  4. Every other field and the row ORDER survive byte-for-byte. This rewrites an append-only log;
+ *     the only defensible rewrite is one that changes exactly the fields it says it changes.
+ *
+ * @packageDocumentation
+ */
+
+/** Marks a value this module derived from the host record rather than one a human typed. */
+export const LEDGER_FILL_SOURCE = 'host-record';
+
+/**
+ * HOW the row was matched to a host record. This is not decoration: the two are different strengths
+ * of evidence and a reader must be able to tell them apart.
+ *
+ *  - `runId` — the row named the run. Exact.
+ *  - `slug`  — the row named only the feature, and exactly ONE host run carried that slug. A feature
+ *    run twice has two runs with one slug, and attributing one run's spend to the other row would be
+ *    a fabrication, so an ambiguous slug is REFUSED rather than resolved to the first match.
+ */
+export type LedgerFillKey = 'runId' | 'slug';
+
+/** The facts lookup returns this when the row's key matches MORE THAN ONE host run. */
+export const AMBIGUOUS = 'ambiguous' as const;
+
+/** What the host record knows about one run. `null` for a field the record itself did not carry. */
+export interface RunCostFacts {
+  readonly tokens: number | null;
+  readonly minutes: number | null;
+  readonly agents: number | null;
+}
+
+/** One row's outcome. `filled` lists the field names that changed — empty means nothing did. */
+export interface LedgerBackfillRow {
+  readonly index: number;
+  readonly runId: string | null;
+  /** The row's feature slug, used as the fallback join key when it names no run. */
+  readonly slug: string | null;
+  /** Which key actually matched, when something was filled. */
+  readonly key: LedgerFillKey | null;
+  readonly filled: readonly string[];
+  /** Why nothing was filled. `null` when something was. */
+  readonly skipped: 'no-join-key' | 'no-host-record' | 'ambiguous-slug' | 'shared-run-claim' | 'already-complete' | 'malformed-line' | 'host-record-empty' | null;
+}
+
+export interface LedgerBackfillPlan {
+  /** The ledger's lines after the fill — same count, same order, one JSON object per line. */
+  readonly lines: readonly string[];
+  readonly rows: readonly LedgerBackfillRow[];
+  readonly filledRows: number;
+  /** Fields whose existing value DISAGREES with the derived one. Reported, never overwritten. */
+  readonly disagreements: readonly { index: number; field: string; existing: number; derived: number }[];
+}
+
+const FILLABLE = ['tokens', 'minutes', 'agents'] as const;
+
+const isNum = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+
+/**
+ * Plan the fill. PURE: takes the ledger's raw lines and a runId→facts lookup, returns the new lines.
+ * Nothing is read or written here — the caller owns the file and the atomic replace.
+ */
+export function planLedgerBackfill(input: {
+  readonly lines: readonly string[];
+  /**
+   * Resolve one join key to the host record's numbers. Returns {@link AMBIGUOUS} when the key
+   * matches more than one run — the caller must NOT collapse that to "no record": one is "we have
+   * nothing", the other is "we have too much to choose honestly", and only the second is a defect
+   * in the ledger's own key.
+   */
+  readonly facts: (key: LedgerFillKey, value: string) => RunCostFacts | typeof AMBIGUOUS | null;
+}): LedgerBackfillPlan {
+  // A run's spend belongs to ONE row. An L/XL feature writes a `plan` row and a `full` row under one
+  // slug, and giving both the same run total would double-count that run for anyone who sums the
+  // column — a fabrication produced by addition rather than by writing. This is the mirror of the
+  // ambiguous-slug rule: there, many runs claimed one row; here, one run would be claimed by many.
+  // Both are refused, and for the same reason: we cannot tell which claim is the true one.
+  const claimants = new Map<string, number>();
+  for (const raw of input.lines) {
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) continue;
+      const r = parsed as Record<string, unknown>;
+      if (FILLABLE.every((f) => isNum(r[f]))) continue;
+      const rid = typeof r['runId'] === 'string' && r['runId'] !== '' ? r['runId'] : null;
+      const slg = typeof r['slug'] === 'string' && r['slug'] !== '' ? r['slug'] : null;
+      const k = rid !== null ? 'runId:' + rid : slg !== null ? 'slug:' + slg : null;
+      if (k !== null) claimants.set(k, (claimants.get(k) ?? 0) + 1);
+    } catch { /* a torn line claims nothing */ }
+  }
+
+  const outLines: string[] = [];
+  const rows: LedgerBackfillRow[] = [];
+  const disagreements: { index: number; field: string; existing: number; derived: number }[] = [];
+  let filledRows = 0;
+
+  input.lines.forEach((raw, index) => {
+    // A line we cannot parse is passed through UNCHANGED. This rewrites an append-only log; a
+    // torn line is evidence, and dropping or "repairing" it would destroy the only trace of it.
+    let row: Record<string, unknown>;
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not an object');
+      row = parsed as Record<string, unknown>;
+    } catch {
+      outLines.push(raw);
+      if (raw.trim() !== '') rows.push({ index, runId: null, slug: null, key: null, filled: [], skipped: 'malformed-line' });
+      return;
+    }
+
+    const runId = typeof row['runId'] === 'string' && row['runId'] !== '' ? row['runId'] : null;
+    const slug = typeof row['slug'] === 'string' && row['slug'] !== '' ? row['slug'] : null;
+    const missing = FILLABLE.filter((f) => !isNum(row[f]));
+    if (missing.length === 0) {
+      outLines.push(raw);
+      rows.push({ index, runId, slug, key: null, filled: [], skipped: 'already-complete' });
+      return;
+    }
+    // runId is exact and wins. The slug is the FALLBACK, and only because the sandboxed workflow
+    // cannot know its own run id — it has no access to one, so a row it writes can never name one.
+    const key: LedgerFillKey | null = runId !== null ? 'runId' : slug !== null ? 'slug' : null;
+    const value = runId ?? slug;
+    if (key === null || value === null) {
+      outLines.push(raw);
+      rows.push({ index, runId, slug, key: null, filled: [], skipped: 'no-join-key' });
+      return;
+    }
+    if ((claimants.get(key + ':' + value) ?? 0) > 1) {
+      outLines.push(raw);
+      rows.push({ index, runId, slug, key: null, filled: [], skipped: 'shared-run-claim' });
+      return;
+    }
+    const facts = input.facts(key, value);
+    if (facts === AMBIGUOUS) {
+      // Refuse, do not guess. A feature run twice has two host runs under one slug; picking either
+      // would attribute one run's spend to the other row and call it measured.
+      outLines.push(raw);
+      rows.push({ index, runId, slug, key: null, filled: [], skipped: 'ambiguous-slug' });
+      return;
+    }
+    if (facts === null) {
+      outLines.push(raw);
+      rows.push({ index, runId, slug, key: null, filled: [], skipped: 'no-host-record' });
+      return;
+    }
+
+    const filled: string[] = [];
+    const next: Record<string, unknown> = { ...row };
+    for (const field of FILLABLE) {
+      const derived = facts[field];
+      if (!isNum(derived)) continue;
+      if (isNum(row[field])) {
+        // Rule 2: the operator's number stands. A disagreement is REPORTED so it can be looked at,
+        // never resolved silently in our favour.
+        if (row[field] !== derived) disagreements.push({ index, field, existing: row[field] as number, derived });
+        continue;
+      }
+      next[field] = derived;
+      filled.push(field);
+    }
+    if (filled.length === 0) {
+      outLines.push(raw);
+      rows.push({ index, runId, slug, key: null, filled: [], skipped: 'host-record-empty' });
+      return;
+    }
+    // Rule 1: say where these numbers came from, and HOW they were matched. A slug match is weaker
+    // evidence than a run id, and a reader who cannot tell them apart cannot weigh the number.
+    next['filledFrom'] = LEDGER_FILL_SOURCE;
+    next['filledBy'] = key;
+    next['filledFields'] = filled;
+    outLines.push(JSON.stringify(next));
+    rows.push({ index, runId, slug, key, filled, skipped: null });
+    filledRows++;
+  });
+
+  return { lines: outLines, rows, filledRows, disagreements };
+}
+
+/** A candidate host run, as {@link CostLedgerRunRef} exposes it. */
+export interface LedgerRunCandidate {
+  readonly runId: string;
+  readonly slug: string | null;
+  readonly startedAtMs: number | null;
+}
+
+/**
+ * Resolve the run a ledger row is being written FOR, at write time.
+ *
+ * This is the fix for the root defect behind the whole backfill: the sandboxed workflow has no
+ * access to its own run id — it is not in `args` and not a sandbox global — so a row it writes can
+ * never name one, and 16 of 20 automatic rows carried no join key at all (MEASURED 2026-08-25).
+ *
+ * The command that APPENDS the row does run on the host, where the records live, so it can answer
+ * the question the sandbox cannot. Resolving here rather than afterwards is strictly better: at
+ * write time the run is IN FLIGHT and is simply the newest one for that slug, while an hour later
+ * the same slug may have several and the choice becomes a guess.
+ *
+ * Refuses rather than guesses in every unclear case:
+ *  - no slug, or no candidate for it → `null`;
+ *  - the newest candidate is TIED with another on `startedAtMs`, or has no timestamp at all → `null`,
+ *    because "newest" is then not a fact;
+ *  - a row that already names a run keeps it — resolution never overwrites.
+ */
+export function resolveLedgerRunId(
+  row: { readonly runId?: unknown; readonly slug?: unknown },
+  runs: readonly LedgerRunCandidate[],
+): string | null {
+  if (typeof row.runId === 'string' && row.runId !== '') return null;
+  const slug = typeof row.slug === 'string' && row.slug !== '' ? row.slug : null;
+  if (slug === null) return null;
+  const dated = runs.filter((r) => r.slug === slug && typeof r.startedAtMs === 'number' && Number.isFinite(r.startedAtMs));
+  if (dated.length === 0) return null;
+  let newest = dated[0] as LedgerRunCandidate;
+  for (const r of dated) if ((r.startedAtMs as number) > (newest.startedAtMs as number)) newest = r;
+  // A tie means the newest is not a fact. Two runs cannot both be the one this row is for.
+  if (dated.filter((r) => r.startedAtMs === newest.startedAtMs).length > 1) return null;
+  return newest.runId;
+}

package/src/operations.ts

@@ -1166,6 +1166,42 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
     }
   } catch { /* advisory only — the vector tier must never fail doctor */ }
 
+  // 10. AQE store integrity (observability item 3/5). `.agentic-qe/integrity-log.jsonl` is the
+  // best-attested log in this repo — a UserPromptSubmit hook runs a REAL `PRAGMA quick_check`,
+  // stats the file and scans /proc for the process holding it, so unlike almost every other store
+  // here it is instrument-witnessed rather than self-reported. It had 1508 rows and ZERO readers
+  // (MEASURED 2026-08-25): on that day a live corruption was noticed from a prompt banner, while
+  // fourteen recorded corruption events and their on-disk `memory.db.corrupt-*` artifacts sat
+  // unread. A log nobody reads is not observability. This turns it into a health signal.
+  //
+  // Deliberately NOT an error exit. The reading is a HISTORY, and a corruption already recovered
+  // must not redden doctor forever; the LAST verdict decides ok, the history is reported beside it.
+  try {
+    const logPath = join(root, '.agentic-qe', 'integrity-log.jsonl');
+    if (existsSync(logPath)) {
+      const rows: { ts?: unknown; check?: unknown; error?: unknown }[] = [];
+      for (const line of readFileSync(logPath, 'utf-8').split('\n')) {
+        const t = line.trim();
+        if (t === '') continue;
+        try { rows.push(JSON.parse(t) as { ts?: unknown; check?: unknown; error?: unknown }); } catch { /* a torn line is not a verdict */ }
+      }
+      const last = rows.length > 0 ? rows[rows.length - 1] : undefined;
+      if (last !== undefined) {
+        const bad = rows.filter((r) => r.check !== 'ok').length;
+        const lastOk = last.check === 'ok';
+        const when = typeof last.ts === 'string' ? last.ts : 'unknown time';
+        const err = typeof last.error === 'string' && last.error !== '' ? ` (${last.error})` : '';
+        checks.push({
+          name: 'aqe store integrity',
+          ok: lastOk,
+          detail: lastOk
+            ? `last quick_check ok at ${when}; ${bad} corruption event(s) recorded in ${rows.length} checks`
+            : `last quick_check FAILED at ${when}${err} — ${bad} of ${rows.length} checks failed; back up .agentic-qe/memory.db before any repair`,
+        });
+      }
+    }
+  } catch { /* advisory only — a diagnostic never throws */ }
+
   return { node: process.version, checks, ok: checks.every((check) => check.ok) };
 }
 

package/src/score.ts

@@ -41,6 +41,71 @@ export interface RunScorecard {
 }
 
 /** The artifact texts of one run, keyed by RELATIVE path under `features/<slug>/`. */
+/**
+ * The exact heading Step 5 asks for, and the exact heading the check looks for — ONE constant, so
+ * the two cannot disagree by editing.
+ *
+ * This is not tidiness. A recalled lesson at 0.90 relevance records the same defect already shipped
+ * once here: "a generator prompt and its QE gate MUST agree on section vocabulary — Step-3's Write
+ * instruction listed legacy ADR sections while the injected brief listed the current ones." A prompt
+ * asking for one heading while a check greps another produces a gate that fails every honest run,
+ * and a gate that fails every honest run gets switched off.
+ *
+ * The sandboxed workflow cannot import, so it carries this string INLINE; a test asserts the inline
+ * literal equals this export, which turns "remember to update both" into a red test.
+ */
+export const OBSERVABILITY_SECTION = 'Observability';
+
+/**
+ * Does an architecture artifact answer how the shipped feature will be watched?
+ *
+ * THREE outcomes, and the third is why this is usable at all:
+ *  - `answered`      — the section is there.
+ *  - `nothing-to-observe` — the section is there and says the feature emits nothing at runtime. A
+ *    pure refactor or a CI-only gate genuinely does; a checker that cannot express a true fact is a
+ *    checker people disable. The requirement is that the question is ANSWERED, not that it is yes.
+ *  - `absent`        — no section. WARN-shaped by design: 107 architecture files predate this
+ *    requirement, and a blocking verdict on day one would redden every re-run of every past feature.
+ *
+ * Honest limit, stated in ADR-002: nothing here verifies that a `nothing-to-observe` claim is TRUE.
+ * The pipeline now asks. It does not ensure.
+ */
+export function observabilityAnswer(architectureMarkdown: string | undefined | null): 'answered' | 'nothing-to-observe' | 'empty' | 'absent' {
+  // Fenced blocks are stripped FIRST: a `## Observability` inside an example fence is not a section
+  // of this document, and accepting one is a false pass anybody could write by accident
+  // (cross-family review, finding 1).
+  const text = String(architectureMarkdown ?? '').replace(/\r\n/g, '\n').replace(/^ {0,3}(```|~~~)[\s\S]*?^ {0,3}\1[^\n]*$/gm, '');
+  // CommonMark: up to three leading spaces, then #s, then REQUIRED whitespace. `##Observability` is
+  // not a heading and must not pass; an indented one is, and must not be missed (finding 2).
+  const headingRe = new RegExp('^ {0,3}#{1,6}[ \t]+' + OBSERVABILITY_SECTION + '\\b.*$', 'gim');
+  const lines = text.split('\n');
+  const heads: number[] = [];
+  lines.forEach((l, i) => { headingRe.lastIndex = 0; if (new RegExp('^ {0,3}#{1,6}[ \t]+' + OBSERVABILITY_SECTION + '\\b', 'i').test(l)) heads.push(i); });
+  if (heads.length === 0) return 'absent';
+
+  // EVERY matching section is read, not just the first: a decoy or empty section at the top used to
+  // mask a real answer below it, making the verdict order-dependent (finding 3).
+  const verdicts: ('answered' | 'nothing-to-observe' | 'empty')[] = [];
+  for (const h of heads) {
+    let stop = lines.length;
+    for (let i = h + 1; i < lines.length; i++) {
+      if (/^ {0,3}#{1,6}[ \t]+/.test(lines[i] as string)) { stop = i; break; }
+    }
+    const body = lines.slice(h + 1, stop);
+    const first = body.map((l) => l.trim()).find((l) => l !== '' && !/^[-*]\s*$/.test(l));
+    if (first === undefined) { verdicts.push('empty'); continue; }
+    // A claim OPENS the answer. Merely containing the phrase is a MENTION — "The phrase 'nothing to
+    // observe' is not acceptable" opens with "The phrase" and is an answer, not a claim (finding 4).
+    const opener = first.replace(/^[-*>\s]*/, '').replace(/^\*\*/, '').replace(/^["'`]/, '');
+    verdicts.push(/^(nothing to observe|no runtime surface|emits nothing at runtime)/i.test(opener) ? 'nothing-to-observe' : 'answered');
+  }
+  // Best-of, in that order: one real answer anywhere beats a decoy; an explicit nothing-to-observe
+  // beats an empty section; all-empty is reported AS empty and never as answered (finding 5).
+  if (verdicts.includes('answered')) return 'answered';
+  if (verdicts.includes('nothing-to-observe')) return 'nothing-to-observe';
+  return 'empty';
+}
+
 export type RunArtifacts = Readonly<Record<string, string>>;
 
 function collect(artifacts: RunArtifacts, predicate: (path: string) => boolean): string {
@@ -186,6 +251,37 @@ export function scoreRun(slug: string, artifacts: RunArtifacts): RunScorecard {
     disciplines.push({ id, title, verdict, evidence });
   };
 
+  // 0. Observability — does the artifact say how anyone would know this feature works once it ships?
+  // DESCRIPTIVE by design (ADR-002): 107 architecture files predate the requirement, so a blocking
+  // verdict on day one would redden every re-run of every past feature. `dz score` describes process
+  // discipline and blocks nothing, which is exactly the shape this needs while the corpus catches up.
+  {
+    const archText = collect(artifacts, (p) => p === '05_architecture.md');
+    // An ABSENT artifact and an EMPTY one are different facts, and `collect` returns '' for both.
+    // Saying "no 05_architecture.md artifact" about a file that exists is a false evidence string —
+    // the exact class this discipline exists to police (cross-family review, finding 6).
+    const archPresent = Object.prototype.hasOwnProperty.call(artifacts, '05_architecture.md');
+    if (!archPresent) {
+      add('observability-declared', 'architecture says how it will be watched', 'absent', 'no 05_architecture.md artifact');
+    } else if (archText.trim() === '') {
+      add('observability-declared', 'architecture says how it will be watched', 'absent', '05_architecture.md exists but is empty');
+    } else {
+      const answer = observabilityAnswer(archText);
+      if (answer === 'answered') {
+        add('observability-declared', 'architecture says how it will be watched', 'pass', 'the ' + OBSERVABILITY_SECTION + ' section answers how the shipped feature is watched');
+      } else if (answer === 'nothing-to-observe') {
+        // A complete answer, not a gap — and NOT verified. ADR-002 says so out loud.
+        add('observability-declared', 'architecture says how it will be watched', 'pass', 'declares nothing to observe at runtime (a complete answer; nothing here checks that it is true)');
+      } else if (answer === 'empty') {
+        // The heading is there and says nothing. `pass` here would be a verdict its own evidence
+        // string contradicts — the section cannot "answer how" while containing no answer.
+        add('observability-declared', 'architecture says how it will be watched', 'partial', 'the ' + OBSERVABILITY_SECTION + ' section is present but EMPTY — a heading is not an answer');
+      } else {
+        add('observability-declared', 'architecture says how it will be watched', 'absent', 'no ' + OBSERVABILITY_SECTION + ' section — the artifact does not say how anyone would know this works');
+      }
+    }
+  }
+
   // 1. ADR with a Confirmation — a named decision whose load-bearing property names its test.
   if (adrText === '') {
     add('adr-confirmation', 'ADR present, property → named test', 'absent', 'no 03_adr/*.md artifact');

package/src/telemetry-vocabulary.ts

@@ -0,0 +1,138 @@
+/**
+ * One name per measured quantity — copied, not imported.
+ *
+ * THE PROBLEM (MEASURED 2026-08-25). Fifteen telemetry stores in this repo, each naming the same
+ * thing differently: `durationMs` here, `minutes` there, `wallMs` in a third; `tokens` vs
+ * `totalTokens` vs `tokensIn`/`tokensOut`. Joining two of them was interpretation, not lookup, which
+ * is why cost-per-feature was 76% typed by a human.
+ *
+ * WHY LITERALS AND NOT A DEPENDENCY. OpenTelemetry's `gen_ai.*` conventions are the right vocabulary
+ * and there is no package to depend on:
+ *   • `@opentelemetry/semantic-conventions-genai` → 404 on npm (verified 2026-08-25);
+ *   • in semconv v1.42.0 every `gen_ai.*` convention was DEPRECATED out of the main repo and moved
+ *     to a new one with zero tags and zero releases;
+ *   • 197 of 197 documents in that spec carry `stability: development`, which its own status page
+ *     defines as "SHOULD NOT be used in production";
+ *   • 40 fragments are queued, 6 of them breaking — and FOUR of those six are agent-layer.
+ * So: copy the names, version the copy, and mark the volatile half. A rename upstream then becomes a
+ * data migration against ONE file instead of a code change across call sites.
+ *
+ * WHAT THIS DOES NOT DO. It renames nothing. Migrating the existing stores onto these names is a
+ * separate change with its own risk; this module only makes the join possible.
+ *
+ * NOT in the loop-blob registry, deliberately: a module mirrored into the sandboxed workflow drags a
+ * registry regeneration and a region re-render behind every edit to it.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The contract's own version. Bump it when a name changes, and the change is then a migration
+ * against a versioned file — which is the whole point of copying rather than depending.
+ */
+export const TELEMETRY_VOCAB_VERSION = 'dz-telemetry-vocab-1';
+
+/**
+ * Where a name came from. This distinction is load-bearing and must not be flattened: `otel` means
+ * copied verbatim from the upstream convention, so a future reader can look it up and a future tool
+ * can consume it. `local` means OpenTelemetry carries the quantity as span STRUCTURE rather than as
+ * an attribute, so there was nothing to copy and we named it ourselves. Presenting a name we invented
+ * as a standard one would be the small lie that makes the whole contract untrustworthy.
+ */
+export type FieldSource = 'otel' | 'local';
+
+export interface TelemetryField {
+  /** The wire name to write into a record. */
+  readonly field: string;
+  readonly source: FieldSource;
+  /** What it holds, in one line. */
+  readonly means: string;
+  /**
+   * The UNIT the field is measured in, or `null` for a field that has none (an id, a label).
+   *
+   * Added after cross-family review found the hazard it closes: `minutes` was aliased onto a field
+   * whose name ends `_ms`, so a consumer following the alias would write minutes into a
+   * milliseconds field and nothing would say otherwise. A vocabulary that names a quantity without
+   * naming its unit invites exactly that.
+   */
+  readonly unit: 'ms' | 'tokens' | null;
+}
+
+/**
+ * The vocabulary. Keys are stable identifiers for OUR code to reference; `field` is what goes on
+ * disk, so an upstream rename touches the value and never the call sites.
+ */
+export const TELEMETRY_FIELDS: Readonly<Record<string, TelemetryField>> = {
+  requestModel:  { field: 'gen_ai.request.model',       source: 'otel',  means: 'the model id a stage asked for', unit: null },
+  // The upstream field means the SERVICE PROVIDER — anthropic, openai — not the product family.
+  // Cross-family review caught this being described as "claude, codex", which are our model
+  // families; those now have their own local field below rather than being smuggled in here.
+  providerName:  { field: 'gen_ai.provider.name',       source: 'otel',  means: 'the inference provider — anthropic, openai', unit: null },
+  operationName: { field: 'gen_ai.operation.name',      source: 'otel',  means: 'what the call was: invoke_agent, invoke_workflow, plan, execute_tool', unit: null },
+  inputTokens:   { field: 'gen_ai.usage.input_tokens',  source: 'otel',  means: 'tokens SENT — not a total', unit: 'tokens' },
+  outputTokens:  { field: 'gen_ai.usage.output_tokens', source: 'otel',  means: 'tokens PRODUCED — not a total', unit: 'tokens' },
+  evaluationLabel: { field: 'gen_ai.evaluation.score.label', source: 'otel', means: 'a graded verdict — our QE letter grade', unit: null },
+  // OpenTelemetry carries elapsed time as span structure, not as an attribute, so there is no
+  // upstream name to copy for a JSONL row. Ours, and said so.
+  durationMs:    { field: 'dz.duration_ms',             source: 'local', means: 'elapsed wall time of a stage or run', unit: 'ms' },
+  // Upstream splits usage into input and output and has no TOTAL. Ours are totals, and folding them
+  // into input_tokens would silently change the measured quantity (cross-family review).
+  totalTokens:   { field: 'dz.total_tokens',            source: 'local', means: 'input + output for a run or stage', unit: 'tokens' },
+  // Our routing families (claude, codex) are not providers; see providerName above.
+  modelFamily:   { field: 'dz.model_family',            source: 'local', means: 'the routing family — claude, codex', unit: null },
+  runId:         { field: 'dz.run_id',                  source: 'local', means: 'the host workflow run a record belongs to', unit: null },
+  stage:         { field: 'dz.stage',                   source: 'local', means: 'the feature-adr stage a record is about', unit: null },
+};
+
+/**
+ * The names whose upstream churn is highest — the agent layer, where FOUR of the six queued breaking
+ * changes land (`gen_ai.agent.version` removed from internal invoke_agent spans,
+ * `gen_ai.provider.name` dropped as required, `gen_ai.agent.id` scope changed).
+ *
+ * Separated by NAME rather than by footnote so a reader can tell "safe to build on" from "expect this
+ * to move" without reading a comment. Build on these only where a rename is cheap.
+ */
+export const PROVISIONAL_TELEMETRY_FIELDS: Readonly<Record<string, TelemetryField>> = {
+  agentId:      { field: 'gen_ai.agent.id',      source: 'otel', means: 'PROVISIONAL — the agent instance', unit: null },
+  agentName:    { field: 'gen_ai.agent.name',    source: 'otel', means: 'PROVISIONAL — the agent role/label', unit: null },
+  agentVersion: { field: 'gen_ai.agent.version', source: 'otel', means: 'PROVISIONAL — slated for removal from internal spans', unit: null },
+};
+
+/**
+ * What this repo already writes → which vocabulary key it means.
+ *
+ * Without this the contract is a glossary nobody can act on. With it, the cost join that was hand
+ * work becomes a lookup. Wrong BY OMISSION for any store added without updating it — which is why
+ * {@link telemetryFieldFor} returns nothing rather than guessing.
+ */
+export const LOCAL_FIELD_ALIASES: Readonly<Record<string, string>> = {
+  durationMs: 'durationMs',
+  wallMs: 'durationMs',
+  // `minutes` is DELIBERATELY absent. It names the same quantity in a different unit, and an alias
+  // carries no conversion — following it would write minutes into a field whose name ends `_ms`.
+  // An unmapped name is visible at the call site; a wrong unit is not (cross-family review).
+  tokens: 'totalTokens',
+  totalTokens: 'totalTokens',
+  recordTotalTokens: 'totalTokens',
+  tokensIn: 'inputTokens',
+  tokensOut: 'outputTokens',
+  model: 'requestModel',
+  coder: 'modelFamily',
+  family: 'modelFamily',
+  grade: 'evaluationLabel',
+  runId: 'runId',
+  stage: 'stage',
+};
+
+/**
+ * The vocabulary field a local name means, or `undefined` when we do not know.
+ *
+ * The unknown case is the load-bearing one. A vocabulary that invents a mapping for a field it has
+ * never seen produces a join that is silently wrong; one that returns nothing makes the gap visible
+ * at the call site, where somebody can fix it.
+ */
+export function telemetryFieldFor(localName: string): TelemetryField | undefined {
+  const key = LOCAL_FIELD_ALIASES[localName];
+  if (key === undefined) return undefined;
+  return TELEMETRY_FIELDS[key] ?? PROVISIONAL_TELEMETRY_FIELDS[key];
+}