@dzhechkov/harness-core 0.7.6 → 0.7.8

package/dist/telemetry-vocabulary.js

@@ -0,0 +1,109 @@
+/**
+ * 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';
+/**
+ * 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 = {
+    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 = {
+    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 = {
+    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) {
+    const key = LOCAL_FIELD_ALIASES[localName];
+    if (key === undefined)
+        return undefined;
+    return TELEMETRY_FIELDS[key] ?? PROVISIONAL_TELEMETRY_FIELDS[key];
+}
+//# sourceMappingURL=telemetry-vocabulary.js.map

package/dist/telemetry-vocabulary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-vocabulary.js","sourceRoot":"","sources":["../src/telemetry-vocabulary.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-core",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Shared harness logic - skill loading, additive apply, and the init/sync/verify/doctor operations.",
   "type": "module",
   "license": "MIT",
@@ -30,17 +30,17 @@
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.0.0",
     "@dzhechkov/adapter-agents-md": "0.1.3",
+    "@dzhechkov/adapter-claude": "^0.2.2",
     "@dzhechkov/adapter-codex": "^0.2.2",
-    "@dzhechkov/adapter-cursor": "0.1.3",
     "@dzhechkov/adapter-copilot": "0.1.3",
+    "@dzhechkov/adapter-cursor": "0.1.3",
     "@dzhechkov/adapter-gemini": "0.1.3",
-    "@dzhechkov/adapter-openclaude": "^0.1.2",
-    "@dzhechkov/adapter-claude": "^0.2.2",
     "@dzhechkov/adapter-hermes": "^0.2.2",
-    "@dzhechkov/adapter-opencode": "^0.2.2",
-    "@dzhechkov/core": "0.2.17",
+    "@dzhechkov/adapter-openclaude": "^0.1.2",
     "@dzhechkov/adapter-windsurf": "0.1.3",
-    "@dzhechkov/memory": "0.2.15"
+    "@dzhechkov/core": "0.2.17",
+    "@dzhechkov/memory": "0.2.15",
+    "@dzhechkov/adapter-opencode": "^0.2.2"
   },
   "peerDependenciesMeta": {
     "@ruvector/rvf": {

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6e0c7dc75ea18f37464949db1871dc6ab7a97b23e9dfff9af37bcdf19f4fbc83"
+          "content": "da09a44bfc467f67e142638f1a57e072c0dcfbf04f3f43229e7045bf51a0eb9d"
         }
       ]
     },
@@ -669,6 +669,46 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "dist/checkpoint-stamp.d.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "bcd22740dabf30df0b71f2164dd13c9c7fe619746a852929c7e8bd4edd049556"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/checkpoint-stamp.d.ts.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "ff59e5bc4e293a465dae508d6c50fead4d9925b890f33a737b8716ae0529287f"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/checkpoint-stamp.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "925ab26d210efe89d02924e979b6cb1598a3289af4c94c87734af04e7b992620"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/checkpoint-stamp.js.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "aa2887d4e9129aa14cb8b6dbd138307c1a9f06860cfe80cb985176b17db399e3"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "dist/claim-check-hook-policy.d.ts",
@@ -1355,7 +1395,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "13d7d90d33f6c30498b397f34c32d095bdc91e407901a51a9ccdf40a56c60124"
+          "content": "ba30eb15d8b125a3fbf71897fc848807b4636f676b2bc5c0cfb14c71d4667fa0"
         }
       ]
     },
@@ -1365,7 +1405,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "bd89f5965d7437b4cef069a9a34cec1ab9f6cee40acde29cdba3fd4a18f27422"
+          "content": "c1ee8730f59317e337b65fb200e2c2d6a817f87014ce84f192702aed9e38d14f"
         }
       ]
     },
@@ -1385,7 +1425,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "bdeac6f879ab1695a11bb2323dc03ba4fa25dd7bd6da19e47208a69df33576f5"
+          "content": "739d561a337682247f3341878b2c65254a2cf90db38513a73535a6f1dd7f0752"
         }
       ]
     },
@@ -1635,7 +1675,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4eadcf12e18ccfbe77f857d71e52b29d51b35ee8bb9bbdf3a34cfb6724826c10"
+          "content": "38dd2203725d14c8cc6a160b6dc5d5cc87a8a68fca1fc97adfe5dac2f4b614da"
         }
       ]
     },
@@ -1645,7 +1685,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "de6cd5f7de860105804f100e487b65a78f2edd67a40645a710ad81c12e1c5b72"
+          "content": "f332fe0f06b828770b57c108c2e0800a0357348d4ac3836f32cf7bb1d21c8bcc"
         }
       ]
     },
@@ -1655,7 +1695,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "bdb6933fa24b0e02ed293fe4e9c52910e2ed4f5652ea7bcb0dbbb7dc996cc224"
+          "content": "3bf1303754b6ef33cd1411eb5b66c8ab3dc23d0b64e08ec25f2eb2c89df2d605"
         }
       ]
     },
@@ -1665,7 +1705,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b47db4310de5fd7a586e795e10abe108e18cd164d1cb1862e67c227310a68001"
+          "content": "deefbbeece6faa04ae970a7bad4a2671922646e75a7206ac8f0b0119b8681ac6"
         }
       ]
     },
@@ -1709,6 +1749,46 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "dist/ledger-backfill.d.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "ef962a467ec121fa41ed346fe1ac619333f7e76c209173a7d4d5897ef9d6d5c7"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/ledger-backfill.d.ts.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "776d033d3aeffeb40af85cf2dd318ddff35bf08c8867cd56502f3240e841deb3"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/ledger-backfill.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "d8849acd78274c7f5ac82fda839899b1df107eab5cb4d58086d3b89a38fb30af"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/ledger-backfill.js.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "f3d4b2dfaef7cf56542d489bc57a6dcbca97f20181bc1fd2d293341be5dd3706"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "dist/loop-blobs.generated.d.ts",
@@ -2285,7 +2365,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "dfb99e5055b94eb46783f352095d00cfe096d657fd0d2697fa24f64078d3a681"
+          "content": "d1c3b12bfae90c560ccd3a20a988e219d215da92122da4729a1a549f32894656"
         }
       ]
     },
@@ -2295,7 +2375,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f865c6cacc965fbb445c4a8ccbcfd99420ffe7a6256cda79139d73cc24c33797"
+          "content": "e48fe1595148cc7b8859d8d89eef7c444c5d9c3025a3addfaa669d6762789c3f"
         }
       ]
     },
@@ -2305,7 +2385,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "3f1675b4e6a5c73197d330f1415c5a0baa352f7e9ce179a7c49a6630848c9e06"
+          "content": "cea487680c0fdfa429a06815ef5362f9c635bc3e9d3592efc8d7db526f3d21d4"
         }
       ]
     },
@@ -3355,7 +3435,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "337431dbd1999ee5ed97b00080c9044179998b4956381478331eda763cde23da"
+          "content": "0558d5a3ea988184f08459a3ed0c6e138541b86cb78cbca378a6ceef797f3c1f"
         }
       ]
     },
@@ -3365,7 +3445,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b259da2b621ff859700c5f1ca8084292f4a300261e3c4c9dc2e38f77fab3c137"
+          "content": "4775208c01c974b495c6001974902447bf3375ed675e4822dc8c1d5022b2e665"
         }
       ]
     },
@@ -3375,7 +3455,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ba4545d48692e799ad86f20839c0e225f38ddb9ea4be95134d7e0accecfb1cef"
+          "content": "ce87f3d528feaeb2f5c9d1c0287065078b388fd2b061a3412a49a836938ca7a8"
         }
       ]
     },
@@ -3385,7 +3465,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "24b30e4cfe58695e57ae07643cfd49352687ae10916713452a5a1c42f8fbdbf0"
+          "content": "7bcbb79b446908423948e131d1abfc3b01f6caf1ddcadeeffe083614bf119bbf"
         }
       ]
     },
@@ -3909,6 +3989,46 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "dist/telemetry-vocabulary.d.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "034f40510ecaa9ae9d867f482c87dbf3a1f771bc9b7ec67ff181fa4f9acf6499"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/telemetry-vocabulary.d.ts.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "9431269b10db42cba8796139d104a61182b08f080c7497b84542e7649c9947b5"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/telemetry-vocabulary.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "9cedc164e6d9b68583912a738c70b712763241c6b2d91a9e904505ebd31118e1"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/telemetry-vocabulary.js.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "a35a1fc29fc679ed9f27e43482a041a9d32f61289924f6e7599765043be8ec45"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "dist/tg-post.d.ts",
@@ -4315,7 +4435,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "18c9057f70d27a1c2183677a0e74a1e032a153b28d0d9292439ed294ab6104d9"
+          "content": "9f9f11a90c62c19e029e256d4ebf4d4e1b2c232103cfc0acb899e0760b3a6011"
         }
       ]
     },
@@ -4479,6 +4599,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "src/checkpoint-stamp.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "35fdc7c788149c846114641b8dca2594a800e8210062478de04f42d0a11cc076"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "src/claim-check-hook-policy.ts",
@@ -4655,7 +4785,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "92b50c6987a9dc04a7a81608df6f819ee759c86d68498adf7b51ff7459c77d5f"
+          "content": "1b857c02834026d729b35a2df5998bc8a8e42dc124c6f6f07dad3b5a08d2e6f2"
         }
       ]
     },
@@ -4725,7 +4855,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "18a9f1e7f84b56f0c7aa23b096a15c414418ecdd4fafc2f29d38d6dcbf761c84"
+          "content": "f708c193adde6854ca13b7bb6e1d2918a5216c249d67d5e10c83f846320082b5"
         }
       ]
     },
@@ -4739,6 +4869,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "src/ledger-backfill.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "5659ef646baec7a952a4c7bf9eddc1cde24205ae8eb39f43999c5656ace42224"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "src/loop-blobs.generated.ts",
@@ -4885,7 +5025,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "45875b1296fe035953aded1adba53cbc829f02d632a6c301640e4fedf0e08d38"
+          "content": "3b61b04d7fbcf6186695ea9afc8750d4d3c7dd633285a53b972e6544579a5c7b"
         }
       ]
     },
@@ -5135,7 +5275,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6a0522654d31a6e1e395d95450a7529c4bc64fd61a6a1c9d7a5f132aa2fb618d"
+          "content": "31c96e4bae47eedea0ef30b4a79997ef05e950dc8c61a3fd9b4c41070bb72ada"
         }
       ]
     },
@@ -5279,6 +5419,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "src/telemetry-vocabulary.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "8d6c4da15bb76eca46bff58a0519e4fc0f0b835e5a2b20fa701425ae8d518f10"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "src/tg-post.ts",

package/src/checkpoint-stamp.ts

@@ -0,0 +1,50 @@
+/**
+ * Stamp a checkpoint line with the instant it was WRITTEN.
+ *
+ * Deliberately NOT part of `feature-adr-checkpoints.ts`. That module's functions are mirrored
+ * verbatim into the sandboxed workflow through the loop-blob registry, and the sandbox has no
+ * `Date` — so a clock has no business inside a function the clockless copy also runs. Changing the
+ * mirrored serializer would also drag the whole blob regeneration + region re-render behind a
+ * one-field addition, which is a large machine for a small honest fact.
+ *
+ * The stamp belongs to the WRITER. Only the CLI performing the append has a clock, so only the CLI
+ * stamps, here, at the boundary.
+ *
+ * WHY IT EXISTS (MEASURED 2026-08-25): `.fa-state/checkpoints.jsonl` carried no time field of any
+ * kind, so across 241 feature dirs "how long did this stage take" had no answer for a single run —
+ * and no future run could answer it either.
+ *
+ * @packageDocumentation
+ */
+
+/** An ISO-8601 UTC instant exactly as `Date#toISOString` emits it. Anything else we did not write. */
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+
+/**
+ * Return `line` with a `ts` field, or `line` UNCHANGED when the stamp is absent or malformed.
+ *
+ * Three properties, each a test:
+ *  - an ABSENT stamp leaves the record with no `ts` — unknown, never zero and never "now". Inventing
+ *    one would make every pre-existing record indistinguishable from a measured one.
+ *  - a MALFORMED stamp is dropped. A wrong instant is worse than an absent one: only the absent one
+ *    is readable as unmeasured.
+ *  - an EXISTING `ts` is never overwritten, and a line that is not a JSON object is passed through
+ *    untouched — this runs on the way to an append-only log.
+ */
+export function stampCheckpointLine(line: string, ts: string): string {
+  if (!ISO_INSTANT.test(ts)) return line;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return line;
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return line;
+  const row = parsed as Record<string, unknown>;
+  if (typeof row['ts'] === 'string') return line;
+  try {
+    return JSON.stringify({ ...row, ts });
+  } catch {
+    return line;
+  }
+}

package/src/feature-adr-checkpoints.ts

@@ -56,6 +56,26 @@ export interface CheckpointEntry {
   stage: string;
   inputHash: string;
   result: unknown;
+  /**
+   * ISO-8601 UTC instant the checkpoint was WRITTEN, supplied by the writer.
+   *
+   * OPTIONAL by necessity and by design. The sandboxed workflow has no `Date` at all, so it cannot
+   * stamp its own records — only the CLI that performs the append can, and only for the write, not
+   * for the stage's start. Absent `ts` therefore means UNKNOWN, never zero and never "instant": a
+   * pre-2026-08-25 record simply predates the field, and a reader must say so rather than compute a
+   * duration from a missing number.
+   *
+   * Why this exists at all: until it was added, `.fa-state/checkpoints.jsonl` carried no time field
+   * of any kind, so across 241 feature dirs the question "how long did this stage take" had no
+   * answer for a single run — and no FUTURE run could answer it either. This is the whole of the
+   * fix: one optional field, and every run from now on can be placed on a timeline.
+   *
+   * Deliberately NOT accompanied by a {@link CKPT_SCHEMA_VERSION} bump. The version is SALTED into
+   * every input hash, so bumping it would hash every in-flight checkpoint stale and force each
+   * feature to re-run router+design+plan. Stage semantics did not change; an additive optional field
+   * that old readers ignore and new readers treat as unknown is not a format break.
+   */
+  ts?: string;
 }
 
 /** Oversize guard: a result JSON above this is NOT checkpointed (the stage simply re-runs on resume).

package/src/index.ts

@@ -77,6 +77,11 @@ export { checkUpstream, checkAllUpstream, discoverSourcePackages, loadSourcesMan
 export type { SyncUpstreamReport, UpstreamCheckResult, SourcesManifest, SourcePackageInfo } from './sync-upstream.js';
 export { sweepSkillDrift, syncCanonicalSkill } from './skill-drift.js';
 export { SKILL_INSTALL_ROOTS, SKILL_INSTALL_ROOT_BY_TARGET, DEV_SKILL_ROOT, TARGET_ENRICHMENT_ASSETS } from './skill-install-roots.js';
+export { stampCheckpointLine } from './checkpoint-stamp.js';
+export { TELEMETRY_VOCAB_VERSION, TELEMETRY_FIELDS, PROVISIONAL_TELEMETRY_FIELDS, LOCAL_FIELD_ALIASES, telemetryFieldFor } from './telemetry-vocabulary.js';
+export type { TelemetryField, FieldSource } from './telemetry-vocabulary.js';
+export { planLedgerBackfill, LEDGER_FILL_SOURCE, AMBIGUOUS, resolveLedgerRunId } from './ledger-backfill.js';
+export type { LedgerBackfillPlan, LedgerBackfillRow, RunCostFacts } from './ledger-backfill.js';
 export type { SweepResult, DriftedSkill, SyncResult, SyncCanonicalOptions } from './skill-drift.js';
 export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
 export { buildRegistry, searchRegistry, filterByCategory, skillPackBaseDirs, discoverSkillPackDirs, discoverVerifiablePackDirs } from './registry.js';