watertight 0.2.0 → 0.6.0

package/README.md

@@ -1,29 +1,43 @@
 # watertight
 
-**Reports that hold water — every number carries its receipt, and ungrounded
-claims fail the build.**
+[![npm](https://img.shields.io/npm/v/watertight.svg)](https://www.npmjs.com/package/watertight)
+[![CI](https://github.com/camosss/watertight/actions/workflows/ci.yml/badge.svg)](https://github.com/camosss/watertight/actions/workflows/ci.yml)
+![Node](https://img.shields.io/badge/Node-18%2B-brightgreen.svg)
+![Dependencies](https://img.shields.io/badge/Dependencies-0-lightgrey.svg)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+Reports that hold water — every number carries its **receipt**, and ungrounded claims **fail the build**.
+
+```bash
+npx watertight report.md metrics.json
 ```
-$ watertight report.md metrics.json
 
-watertight v0.1.0 · 20 grounded metrics · 4 claims · 5 identifiers
+```
+watertight v0.2.0 · 20 grounded metrics · 4 claims · 5 identifiers
 holds water → report.html
 ```
 
-A number typed into prose has no memory of where it came from. Two weeks
-later nobody can say which query produced it, whether it was rounded, or
-whether it was ever true — and when an LLM helps write the report, "never
-true" is a live possibility. watertight treats a report like source code:
-the narrative references metrics, the metrics carry provenance, and a
-compiler refuses to build anything it cannot trace.
+An ungrounded number is a **leak**. A report with zero leaks **holds water**:
+
+```
+2 leak(s) — the report does not hold water:
+
+  ✗ [naked-number] report.md:31 — "15%" appears in the narrative without a receipt
+  ✗ [derived-mismatch] metric "revenue_total" is 1440, but its parts sum to 1428
+```
 
-An ungrounded number is a **leak**. A report with zero leaks **holds water**.
+<br>
 
 ## Why this exists
 
+A number typed into prose has no memory of where it came from. Two weeks later
+nobody can say which query produced it, whether it was rounded, or whether it
+was ever true — and when an LLM helps write the report, "never true" is a live
+possibility.
+
 This came out of writing a real ad-revenue verification report with an AI
-assistant. Compiling the draft surfaced three distinct failure classes in
-one document:
+assistant. Compiling the draft surfaced three distinct failure classes in one
+document:
 
 - a human had written **+15%** for a delta that computed to **+15.5%** —
   a rounding transcription error nobody had caught;
@@ -31,10 +45,14 @@ one document:
 - the assistant confidently "remembered" a figure that appeared nowhere in
   any export.
 
-All three are the same disease — a number with no receipt — and all three
-are mechanically detectable. So: detect them, every build.
+All three are the same disease — a number with no receipt — and all three are
+mechanically detectable. So: detect them, every build. watertight treats a
+report like source code: the narrative references metrics, the metrics carry
+provenance, and a compiler refuses to build anything it cannot trace.
 
-## Install
+<br>
+
+## Quick start
 
 ```bash
 npm install -g watertight
@@ -42,25 +60,12 @@ npm install -g watertight
 npx watertight report.md metrics.json
 ```
 
-Node 18+, zero runtime dependencies.
-
-## How it works
-
-You write two files.
-
-**`metrics.json` — the IR.** Every value, with its receipt:
+You write two files. **`metrics.json`** holds every value with its receipt —
+a measured metric says where it was fetched, over what window, and when:
 
 ```json
 {
   "metrics": {
-    "conversion_before": {
-      "value": 0.031,
-      "unit": "ratio",
-      "definition": "purchases / sessions entering checkout",
-      "source": { "type": "sql", "query": "reports/checkout.sql" },
-      "window": "2026-08-15 ~ 2026-08-31",
-      "fetched_at": "2026-09-15"
-    },
     "conversion_after": {
       "value": 0.036,
       "unit": "ratio",
@@ -68,34 +73,42 @@ You write two files.
       "source": { "type": "sql", "query": "reports/checkout.sql" },
       "window": "2026-09-01 ~ 2026-09-14",
       "fetched_at": "2026-09-15"
-    },
-    "lift": {
-      "value": 0.161,
-      "unit": "ratio-point",
-      "definition": "relative change in conversion",
-      "derived": { "op": "pct_change", "before": "conversion_before", "after": "conversion_after" }
-    },
-    "revenue_total": {
-      "value": 1428,
-      "unit": "USD",
-      "derived": { "op": "sum", "of": ["revenue_ios", "revenue_android"] }
-    },
-    "revenue_target": {
-      "value": [1000, 5000],
-      "unit": "USD",
-      "source": { "type": "hypothesis", "doc": "PLAN-42" },
-      "window": "planning estimate",
-      "fetched_at": "-"
     }
   },
-  "identifiers": {
-    "app_version": "3.2.0",
-    "flag": "checkout_v2"
-  }
+  "identifiers": { "app_version": "3.2.0", "flag": "checkout_v2" }
+}
+```
+
+A **derived** metric is recomputed on every compile — a total that doesn't add
+up, or a delta that doesn't recompute, is a build failure:
+
+```json
+"lift": {
+  "value": 0.161,
+  "unit": "ratio-point",
+  "definition": "relative change in conversion",
+  "derived": { "op": "pct_change", "before": "conversion_before", "after": "conversion_after" }
+},
+"revenue_total": {
+  "value": 1428,
+  "unit": "USD",
+  "derived": { "op": "sum", "of": ["revenue_ios", "revenue_android"] }
+}
+```
+
+A **range** states a hypothesis honestly — plans are receipts too:
+
+```json
+"revenue_target": {
+  "value": [1000, 5000],
+  "unit": "USD",
+  "source": { "type": "hypothesis", "doc": "PLAN-42" },
+  "window": "planning estimate",
+  "fetched_at": "-"
 }
 ```
 
-**`report.md` — the narrative.** No literal figures, only references:
+**`report.md`** is the narrative. No literal figures, only references:
 
 ```markdown
 Rolled out in `{{id:app_version}}` behind `{{id:flag}}`.
@@ -113,32 +126,56 @@ Compile:
 
 ```bash
 watertight report.md metrics.json    # → report.html (self-contained, hover for receipts)
-watertight . --format md             # → grounded markdown: superscripts + receipts appendix
+watertight . --format md             # → grounded markdown (below)
 watertight . --check                 # verify only, write nothing (CI)
+watertight . --check --max-age 30    # also fail receipts older than 30 days
 watertight . --json                  # machine-readable result
 ```
 
-Any leak fails the build (exit 1) and names the line:
+<br>
 
-```
-2 leak(s) — the report does not hold water:
+## What the output looks like
 
-  ✗ [naked-number] "15%" appears in the narrative without a receipt
-  ✗ [derived-mismatch] metric "revenue_total" is 1440, but its parts sum to 1428
+`--format md` produces grounded markdown that pastes into Notion, a PR body,
+or Slack with its provenance intact — every figure bold with a superscript
+into a receipts appendix:
+
+```markdown
+Conversion moved from **3.1%** ⁽¹⁾ to **3.6%** ⁽²⁾, a lift of **+16.1%p** ⁽³⁾.
+
+---
+
+### Receipts (3 metrics)
+
+1. **conversion_before** = 3.1% — purchases / sessions entering checkout
+   sql · reports/checkout.sql · 2026-08-15 ~ 2026-08-31 · fetched 2026-09-15
+2. **conversion_after** = 3.6% — purchases / sessions entering checkout
+   sql · reports/checkout.sql · 2026-09-01 ~ 2026-09-14 · fetched 2026-09-15
+3. **lift** = +16.1%p — relative change in conversion
+   = conversion_before → conversion_after (recomputed)
 ```
 
+The default HTML render is a single self-contained file where hovering any
+figure shows its receipt.
+
+<br>
+
 ## What it checks
 
 | check | catches |
 |---|---|
-| `naked-number` | any digit in prose not covered by a reference (dates, headings, code spans and `{{raw:}}` are exempt) |
+| `naked-number` | any digit in prose not covered by a reference — heading text included; dates, URLs, code spans and `{{raw:}}` are exempt |
 | `unknown-ref` | `{{m:...}}` / `{{id:...}}` pointing at nothing |
 | `missing-field` | a measured metric without `source`, `window`, or `fetched_at` |
 | `definition-required` | a `ratio` / `ratio-point` metric with no stated basis — this is how a fill rate of 107% stays honest |
 | `derived-mismatch` | a `sum` that doesn't add up; a `pct_change` that doesn't recompute — to the stored value's own precision, so `0.161` passes as 16.1% but `0.15` for 15.5% fails |
 | `claim-without-evidence` | a `{{claim:}}` with no `evidence:` keys, or keys that don't exist |
+| `malformed-marker` | anything still marker-shaped after every recognised form — a typo'd `{{claim:…\|evidnce:…}}` must fail, not render verbatim |
 | `bad-derived` | derived ops referencing missing or non-numeric inputs |
 | `empty-ir` | a report "grounded" in nothing |
+| `stale-metric` | with `--max-age <days>`: a receipt whose `fetched_at` is older than the budget — numbers age |
+
+<br>
 
 ## Re-verification
 
@@ -150,25 +187,6 @@ can reach, rewrites `value` and `fetched_at`, and recomputes derived values:
 - `command` sources — run **only** with the explicit `--allow-commands` flag,
   because refreshing an IR you didn't author must never execute its shell
   commands
-- any other source type can be covered by a **custom fetcher** — a JS module
-  you point at explicitly:
-
-  ```bash
-  watertight refresh . --fetchers ./my-fetchers.mjs
-  ```
-
-  ```js
-  // my-fetchers.mjs — export one function per source type
-  export async function mixpanel(source) {
-    // credentials from the environment, receipt fields from the IR
-    return valueFetchedFrom(source.project, source.bookmark)
-  }
-  ```
-
-  [`examples/fetchers/mixpanel.mjs`](./examples/fetchers/mixpanel.mjs) is a
-  working example. Loading a module runs its code, so only pass files you
-  wrote or trust — the IR itself can never name a fetcher. Built-in csv/json/
-  command adapters always win over a custom one of the same name.
 - everything else (dashboards, vendor reports, hypotheses) is **named as
   skipped** — never silently assumed fresh
 
@@ -176,6 +194,34 @@ Derived values follow their inputs: sums are recomputed exactly, percentage
 changes at the precision the author stated. `--dry-run` previews changes
 without writing.
 
+<br>
+
+## Custom fetchers
+
+Any other source type can be refreshed through a JS module you point at
+explicitly:
+
+```bash
+watertight refresh . --fetchers ./my-fetchers.mjs
+```
+
+```js
+// my-fetchers.mjs — export one function per source type
+export async function mixpanel(source) {
+  // credentials from the environment, receipt fields from the IR
+  return valueFetchedFrom(source.project, source.bookmark)
+}
+```
+
+[`examples/fetchers/mixpanel.mjs`](./examples/fetchers/mixpanel.mjs) is a
+working reference. The trust boundary is explicit: a fetcher module loads only
+when the person running refresh names it on the command line — the IR itself
+can never designate one, so an untrusted `metrics.json` still cannot execute
+anything. Built-in `csv`/`json`/`command` adapters always win over a custom
+one of the same name.
+
+<br>
+
 ## For AI-authored reports
 
 [`SKILL.md`](./SKILL.md) is an authoring contract for coding agents: gather
@@ -183,6 +229,8 @@ receipts first, build the IR from real sources only, reference — never type
 figures, and fix leaks by re-fetching, not by weakening the text. The compile
 step turns "please don't hallucinate numbers" from a request into a gate.
 
+<br>
+
 ## What it deliberately does not do
 
 - **Judge whether evidence supports a claim.** `{{claim:}}` proves evidence
@@ -194,6 +242,8 @@ step turns "please don't hallucinate numbers" from a request into a gate.
 - **Use an LLM.** Every check is deterministic. The point is to be the fixed
   ground an LLM-assisted workflow can push against.
 
+<br>
+
 ## Related work
 
 - [Proof-Carrying Numbers (arXiv:2509.06902)](https://arxiv.org/abs/2509.06902)
@@ -204,6 +254,8 @@ step turns "please don't hallucinate numbers" from a request into a gate.
   proves the "reports as source code" mechanism — but doesn't enforce that
   prose figures stay grounded.
 
+<br>
+
 ## License
 
-MIT © [Hosung Kang](https://github.com/camosss)
+`watertight` is released under an MIT license. See [License](LICENSE) for more information.

package/SKILL.md

@@ -77,8 +77,10 @@ Never type a figure into prose. Reference it:
 watertight report.md metrics.json          # writes report.html
 watertight . --format md                    # grounded markdown (Notion / PR / Slack)
 watertight . --check                        # CI mode: verify, write nothing
+watertight . --check --max-age 30           # also fail receipts older than 30 days
 ```
 
+Every leak names its line (`report.md:31`), so fix them where they live.
 Fix leaks by *going and getting the receipt* — running the query, opening
 the export — never by deleting the number, weakening the claim, or wrapping
 a measurement in `{{raw:}}` to silence the checker. A `derived-mismatch` is

package/dist/cli.js

@@ -2,7 +2,9 @@
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { compile } from './compile.js';
+import { basename } from 'node:path';
 import { refresh } from './refresh.js';
+import { init } from './init.js';
 import { pathToFileURL } from 'node:url';
 const USAGE = `watertight — reports that hold water. Every number carries its receipt;
 an ungrounded claim is a leak, and a report with leaks does not build.
@@ -11,8 +13,11 @@ Usage
   watertight <dir>             compile <dir>/report.md + <dir>/metrics.json → <dir>/report.html
   watertight <report> <ir>     explicit file paths
   watertight refresh <dir>     re-fetch metric values from their sources, update metrics.json
+  watertight init [dir]        scaffold a report.md + metrics.json pair that already holds water
 
 Options
+  --max-age <days>   compile only: fail any metric whose fetched_at is older —
+                     numbers age, and a stale receipt is quietly becoming a leak
   --format <html|md> output format (default: html). md is grounded markdown with a
                      receipts appendix — pastes into Notion, PR bodies or Slack intact
   --out <file>       where to write the output (default: report.html / report.grounded.md)
@@ -39,6 +44,7 @@ function parseArgs(argv) {
     let allowCommands = false;
     let fetchersPath;
     let format = 'html';
+    let maxAgeDays;
     let help = false;
     let version = false;
     for (let i = 0; i < args.length; i++) {
@@ -55,19 +61,31 @@ function parseArgs(argv) {
             fetchersPath = args[++i];
         else if (arg === '--format')
             format = args[++i] === 'md' ? 'md' : 'html';
+        else if (arg === '--max-age') {
+            maxAgeDays = Number(args[++i]);
+            if (!Number.isFinite(maxAgeDays) || maxAgeDays < 0) {
+                console.error(`error: --max-age needs a number of days, got "${args[i]}"`);
+                process.exit(2);
+            }
+        }
         else if (arg === '--json')
             json = true;
         else if (arg === '-h' || arg === '--help')
             help = true;
         else if (arg === '-v' || arg === '--version')
             version = true;
-        else if (!arg.startsWith('-'))
+        else if (arg.startsWith('-')) {
+            // a strictness tool must not silently ignore a typo'd flag — --chekc writing a file is a betrayal
+            console.error(`error: unknown flag "${arg}" — see --help`);
+            process.exit(2);
+        }
+        else
             positional.push(arg);
     }
-    const command = positional[0] === 'refresh' ? 'refresh' : 'compile';
-    if (command === 'refresh')
+    const command = positional[0] === 'refresh' ? 'refresh' : positional[0] === 'init' ? 'init' : 'compile';
+    if (command !== 'compile')
         positional.shift();
-    return { command, positional, out, check, json, help, version, dryRun, allowCommands, format, fetchersPath };
+    return { command, positional, out, check, json, help, version, dryRun, allowCommands, format, fetchersPath, maxAgeDays };
 }
 async function exists(path) {
     try {
@@ -85,6 +103,20 @@ async function main() {
         return console.log(pkg.version);
     if (opts.help)
         return console.log(USAGE);
+    if (opts.command === 'init') {
+        const dir = resolve(opts.positional[0] ?? '.');
+        try {
+            const { written } = await init(dir);
+            for (const f of written)
+                console.log(`  + ${f}`);
+            console.log('\nCompile it: watertight ' + (opts.positional[0] ?? '.'));
+            process.exit(0);
+        }
+        catch (err) {
+            console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(2);
+        }
+    }
     // a mistyped path must fail loudly, never read as an empty report
     let reportPath;
     let irPath;
@@ -132,7 +164,7 @@ async function main() {
             : `\n${r.changes.length} change(s)${opts.dryRun ? ' (dry run — nothing written)' : r.wrote ? ` — updated ${irPath}` : ''}`);
         process.exit(r.errors.length > 0 ? 1 : 0);
     }
-    const result = await compile(reportPath, irPath, opts.format);
+    const result = await compile(reportPath, irPath, { format: opts.format, maxAgeDays: opts.maxAgeDays });
     const defaultName = opts.format === 'md' ? 'report.grounded.md' : 'report.html';
     const outPath = resolve(opts.out ?? join(reportPath, '..', defaultName));
     if (opts.json) {
@@ -143,7 +175,8 @@ async function main() {
         if (result.leaks.length > 0) {
             console.log(`\n${result.leaks.length} leak(s) — the report does not hold water:\n`);
             for (const leak of result.leaks) {
-                console.log(`  ✗ [${leak.rule}] ${leak.message}`);
+                const where = leak.line !== undefined ? `${basename(reportPath)}:${leak.line} — ` : '';
+                console.log(`  ✗ [${leak.rule}] ${where}${leak.message}`);
                 if (leak.detail)
                     console.log(`    ${leak.detail}`);
             }

package/dist/compile.js

@@ -2,16 +2,38 @@ import { readFile } from 'node:fs/promises';
 import { parseIr } from './ir.js';
 import { render } from './render.js';
 import { renderMarkdown } from './renderMd.js';
-import { scanNakedNumbers, scanRefs } from './scan.js';
-export async function compile(reportPath, irPath, format = 'html') {
+import { scanMarkers, scanNakedNumbers, scanRefs } from './scan.js';
+export async function compile(reportPath, irPath, options = 'html') {
+    const opts = typeof options === 'string' ? { format: options } : options;
+    const format = opts.format ?? 'html';
     const report = await readFile(reportPath, 'utf8');
     const { ir, leaks } = parseIr(JSON.parse(await readFile(irPath, 'utf8')));
+    if (ir && opts.maxAgeDays !== undefined) {
+        const now = opts.now ?? new Date();
+        for (const [key, m] of Object.entries(ir.metrics)) {
+            if (!m.fetched_at)
+                continue;
+            const fetched = new Date(m.fetched_at);
+            if (Number.isNaN(fetched.getTime()))
+                continue; // "-" and friends: no date to age
+            const days = Math.floor((now.getTime() - fetched.getTime()) / 86_400_000);
+            if (days > opts.maxAgeDays) {
+                leaks.push({
+                    severity: 'error',
+                    rule: 'stale-metric',
+                    message: `metric "${key}" was fetched ${m.fetched_at} — ${days} days ago, older than max-age ${opts.maxAgeDays}`,
+                    detail: 'Run watertight refresh, or re-fetch by hand and update fetched_at.',
+                });
+            }
+        }
+    }
     const grounded = {
         metrics: [...report.matchAll(/\{\{m:/g)].length,
         identifiers: [...report.matchAll(/\{\{id:/g)].length,
         claims: [...report.matchAll(/\{\{claim:/g)].length,
     };
     leaks.push(...scanNakedNumbers(report));
+    leaks.push(...scanMarkers(report));
     if (ir)
         leaks.push(...scanRefs(report, new Set(Object.keys(ir.metrics)), new Set(Object.keys(ir.identifiers))));
     if (leaks.length > 0 || !ir)

package/dist/init.js

@@ -0,0 +1,65 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Scaffold a report pair that holds water as written — the first compile a new
+ * user runs must succeed, so every figure in the template is already grounded.
+ */
+const REPORT = `# Checkout experiment — verification
+
+Rolled out in \`{{id:app_version}}\` behind \`{{id:flag}}\`.
+
+## Outcome
+
+Conversion moved from {{m:conversion_before}} to {{m:conversion_after}} —
+a change of {{m:conversion_change}}.
+
+{{claim: state your conclusion here, pinned to the metrics that support it | evidence: conversion_change}}
+
+## Next steps
+
+Replace these metrics with your own. Every number needs a receipt:
+run \`watertight .\` and fix what leaks.
+`;
+const METRICS = `${JSON.stringify({
+    metrics: {
+        conversion_before: {
+            value: 0.031,
+            unit: 'ratio',
+            definition: 'purchases / sessions entering checkout',
+            source: { type: 'sql', query: 'replace-with-your-query.sql' },
+            window: '2026-01-01 ~ 2026-01-14',
+            fetched_at: '2026-01-15',
+        },
+        conversion_after: {
+            value: 0.036,
+            unit: 'ratio',
+            definition: 'purchases / sessions entering checkout',
+            source: { type: 'sql', query: 'replace-with-your-query.sql' },
+            window: '2026-01-15 ~ 2026-01-28',
+            fetched_at: '2026-01-29',
+        },
+        conversion_change: {
+            value: 0.161,
+            unit: 'ratio-point',
+            definition: 'relative change in conversion',
+            derived: { op: 'pct_change', before: 'conversion_before', after: 'conversion_after' },
+        },
+    },
+    identifiers: { app_version: '1.0.0', flag: 'checkout_v2' },
+}, null, 2)}\n`;
+/** Refuses to touch anything that already exists — init never overwrites. */
+export async function init(dir) {
+    const files = [
+        [join(dir, 'report.md'), REPORT],
+        [join(dir, 'metrics.json'), METRICS],
+    ];
+    for (const [path] of files) {
+        if (existsSync(path))
+            throw new Error(`refusing to overwrite ${path}`);
+    }
+    await mkdir(dir, { recursive: true });
+    for (const [path, content] of files)
+        await writeFile(path, content);
+    return { written: files.map(([p]) => p) };
+}

package/dist/ir.js

@@ -2,9 +2,18 @@
 const DEFINITION_REQUIRED = new Set(['ratio', 'ratio-point']);
 function decimals(n) {
     const s = String(n);
+    const e = s.indexOf('e');
+    if (e !== -1) {
+        // 1e-7 has 7 decimals, 1.5e-7 has 8 — exponential notation must not disarm the precision check
+        const exp = Number(s.slice(e + 1));
+        const mantissa = s.slice(0, e);
+        const dot = mantissa.indexOf('.');
+        return Math.max(0, (dot === -1 ? 0 : mantissa.length - dot - 1) - exp);
+    }
     const dot = s.indexOf('.');
     return dot === -1 ? 0 : s.length - dot - 1;
 }
+const isFiniteNumber = (v) => typeof v === 'number' && Number.isFinite(v);
 /**
  * A stored derived value must be correctly rounded to its own precision: writing 0.15
  * for a computed 0.155 is a mismatch, writing 0.155 for 0.15517 is fine. This is what
@@ -31,8 +40,10 @@ export function parseIr(raw) {
         return { leaks };
     }
     for (const [key, m] of Object.entries(metrics)) {
-        if (m.value === undefined) {
-            leaks.push({ severity: 'error', rule: 'missing-field', message: `metric "${key}" has no value` });
+        const valueOk = isFiniteNumber(m.value) ||
+            (Array.isArray(m.value) && m.value.length === 2 && m.value.every(isFiniteNumber));
+        if (!valueOk) {
+            leaks.push({ severity: 'error', rule: 'missing-field', message: `metric "${key}" has no usable numeric value` });
             continue;
         }
         if (typeof m.unit !== 'string' || m.unit.length === 0) {
@@ -63,7 +74,7 @@ export function parseIr(raw) {
                     }
                     computed += part.value;
                 }
-                if (!broken && computed !== m.value) {
+                if (!broken && !roundsTo(m.value, computed)) {
                     leaks.push({
                         severity: 'error',
                         rule: 'derived-mismatch',
@@ -72,7 +83,23 @@ export function parseIr(raw) {
                 }
             }
             else if (m.derived.op === 'pct_change') {
-                const computed = (m.derived.after - m.derived.before) / m.derived.before;
+                const endpoint = (v) => {
+                    if (typeof v === 'number')
+                        return v;
+                    const ref = metrics[v];
+                    return ref && typeof ref.value === 'number' ? ref.value : undefined;
+                };
+                const before = endpoint(m.derived.before);
+                const after = endpoint(m.derived.after);
+                if (before === undefined || after === undefined || before === 0) {
+                    leaks.push({
+                        severity: 'error',
+                        rule: 'bad-derived',
+                        message: `metric "${key}": pct_change endpoints must be numbers or scalar metric keys (got ${m.derived.before} → ${m.derived.after})`,
+                    });
+                    continue;
+                }
+                const computed = (after - before) / before;
                 if (!roundsTo(m.value, computed)) {
                     leaks.push({
                         severity: 'error',
@@ -82,6 +109,15 @@ export function parseIr(raw) {
                     });
                 }
             }
+            else {
+                // an op the verifier cannot recompute must never pass as verified
+                leaks.push({
+                    severity: 'error',
+                    rule: 'bad-derived',
+                    message: `metric "${key}" has unknown derived op "${m.derived.op}"`,
+                    detail: 'Supported ops: sum, pct_change. A derivation the compiler cannot recompute cannot hold water.',
+                });
+            }
         }
         else {
             // a measured value must say where it came from and when

package/dist/refresh.js

@@ -74,7 +74,8 @@ export async function refresh(irPath, options) {
     const raw = JSON.parse(await readFile(irPath, 'utf8'));
     const baseDir = dirname(resolve(irPath));
     const result = { changes: [], skipped: [], errors: [], wrote: false };
-    const now = new Date().toISOString();
+    // date-only, matching the style people write by hand — receipts should look uniform
+    const now = new Date().toISOString().slice(0, 10);
     for (const [key, m] of Object.entries(raw.metrics)) {
         if (m.derived || !m.source || Array.isArray(m.value))
             continue;
@@ -107,31 +108,65 @@ export async function refresh(irPath, options) {
             result.errors.push({ key, message: err instanceof Error ? err.message : String(err) });
         }
     }
-    // inputs may have moved, so derived values are recomputed rather than left to go stale
-    for (const [key, m] of Object.entries(raw.metrics)) {
-        if (!m.derived || Array.isArray(m.value))
-            continue;
-        let computed;
-        if (m.derived.op === 'sum') {
-            computed = m.derived.of.reduce((acc, ref) => {
-                const part = raw.metrics[ref];
-                return acc + (part && typeof part.value === 'number' ? part.value : NaN);
-            }, 0);
-        }
-        else {
-            const before = raw.metrics[m.derived.before]?.value;
-            const after = raw.metrics[m.derived.after]?.value;
-            if (typeof before !== 'number' || typeof after !== 'number' || before === 0)
+    // inputs may have moved, so derived values are recomputed rather than left to go stale.
+    // Iterated to a fixpoint so a derived that reads another derived settles too; a derivation
+    // that cannot be recomputed is a named error — silence is impossible here as everywhere.
+    const derivedErrors = new Set();
+    const firstBefore = new Map();
+    for (let pass = 0, moved = true; moved && pass < 10; pass++) {
+        moved = false;
+        for (const [key, m] of Object.entries(raw.metrics)) {
+            if (!m.derived || Array.isArray(m.value))
                 continue;
-            // keep the author's stated precision — refresh must not turn 0.155 into 0.1551724
-            const decimals = (String(m.value).split('.')[1] ?? '').length;
-            computed = Number(((after - before) / before).toFixed(decimals));
-        }
-        if (Number.isFinite(computed) && computed !== m.value) {
-            result.changes.push({ key, before: m.value, after: computed });
-            m.value = computed;
+            const fail = (message) => {
+                if (!derivedErrors.has(key)) {
+                    derivedErrors.add(key);
+                    result.errors.push({ key, message });
+                }
+            };
+            let computed;
+            if (m.derived.op === 'sum') {
+                computed = m.derived.of.reduce((acc, ref) => {
+                    const part = raw.metrics[ref];
+                    return acc + (part && typeof part.value === 'number' ? part.value : NaN);
+                }, 0);
+                if (!Number.isFinite(computed)) {
+                    fail('sum references unknown or non-scalar metrics — not recomputed');
+                    continue;
+                }
+            }
+            else if (m.derived.op === 'pct_change') {
+                const endpoint = (v) => {
+                    if (typeof v === 'number')
+                        return v;
+                    const ref = raw.metrics[v];
+                    return ref && typeof ref.value === 'number' ? ref.value : undefined;
+                };
+                const before = endpoint(m.derived.before);
+                const after = endpoint(m.derived.after);
+                if (before === undefined || after === undefined || before === 0) {
+                    fail('pct_change endpoints are unresolvable or zero — not recomputed');
+                    continue;
+                }
+                // keep the author's stated precision — refresh must not turn 0.155 into 0.1551724
+                const decimals = (String(m.value).split('.')[1] ?? '').length;
+                computed = Number(((after - before) / before).toFixed(decimals));
+            }
+            else {
+                fail(`unknown derived op "${m.derived.op}" — not recomputed`);
+                continue;
+            }
+            if (computed !== m.value) {
+                if (!firstBefore.has(key))
+                    firstBefore.set(key, m.value);
+                m.value = computed;
+                moved = true;
+            }
         }
     }
+    for (const [key, before] of firstBefore) {
+        result.changes.push({ key, before, after: raw.metrics[key].value });
+    }
     if (!options.dryRun && (result.changes.length > 0 || result.errors.length === 0)) {
         await writeFile(irPath, `${JSON.stringify(raw, null, 2)}\n`);
         result.wrote = true;

package/dist/render.js

@@ -1,24 +1,41 @@
+/**
+ * Code shows syntax, it does not state facts — a fenced example of {{m:…}} must render
+ * verbatim, not substitute. Stash code regions before substitution, restore after.
+ */
+export function protectCode(text) {
+    const stash = [];
+    const protectedText = text.replace(/```[\s\S]*?```|`[^`\n]*`/g, (m) => {
+        stash.push(m);
+        return `\u0000${stash.length - 1}\u0000`;
+    });
+    return { text: protectedText, restore: (s) => s.replace(/\u0000(\d+)\u0000/g, (_, i) => stash[Number(i)]) };
+}
 function escapeHtml(s) {
     return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
 export function formatValue(m) {
     if (Array.isArray(m.value)) {
         const [lo, hi] = m.value;
-        return `${lo.toLocaleString()}~${hi.toLocaleString()}${m.unit === 'ratio' ? '%' : ` ${m.unit}`}`;
+        // a range keeps the same unit conversion as a scalar — [0.3, 0.5] ratio is 30~50%, not 0.3~0.5%
+        if (m.unit === 'ratio' || m.unit === 'ratio-point') {
+            const pct = (v) => (v * 100).toFixed(1);
+            return `${pct(lo)}~${pct(hi)}${m.unit === 'ratio' ? '%' : '%p'}`;
+        }
+        return `${lo.toLocaleString()}~${hi.toLocaleString()} ${m.unit}`.trim();
     }
     if (m.unit === 'ratio')
-        return `${(m.value * 100).toFixed(m.value < 0.01 ? 2 : 1)}%`;
+        return `${(m.value * 100).toFixed(Math.abs(m.value) < 0.01 ? 2 : 1)}%`;
     if (m.unit === 'ratio-point')
         return `${m.value >= 0 ? '+' : ''}${(m.value * 100).toFixed(1)}%p`;
     return `${m.value.toLocaleString()} ${m.unit}`.trim();
 }
-export function receipt(m) {
+export function receipt(m, includeDefinition = true) {
     const source = m.derived
         ? m.derived.op === 'sum'
             ? `= ${m.derived.of.join(' + ')} (recomputed)`
             : `= ${m.derived.before} → ${m.derived.after} (recomputed)`
         : [m.source?.type, ...Object.entries(m.source ?? {}).filter(([k]) => k !== 'type').map(([, v]) => String(v))].filter(Boolean).join(' · ');
-    return [source, m.window, m.fetched_at && `fetched ${m.fetched_at}`, m.definition].filter(Boolean).join(' · ');
+    return [source, m.window, m.fetched_at && `fetched ${m.fetched_at}`, includeDefinition && m.definition].filter(Boolean).join(' · ');
 }
 /** Minimal markdown: headings, paragraphs, bold, unordered lists. The narrative layer is deliberately thin. */
 function markdown(src) {
@@ -37,7 +54,8 @@ function markdown(src) {
         .replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>');
 }
 export function render(report, ir) {
-    const grounded = escapeHtml(report)
+    const { text: protectedReport, restore } = protectCode(escapeHtml(report));
+    const grounded = restore(protectedReport
         .replace(/\{\{m:([\w-]+)\}\}/g, (_, key) => {
         const m = ir.metrics[key];
         return `<b class="w" title="${escapeHtml(receipt(m))}">${formatValue(m)}<sup>†</sup></b>`;
@@ -50,7 +68,7 @@ export function render(report, ir) {
             .join(' | ');
         return `<span class="c" title="${escapeHtml(receipts)}">${text.trim()}<sup>‡</sup></span>`;
     })
-        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => escapeHtml(text));
+        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => escapeHtml(text)));
     return `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
 <style>
   body{font:15px/1.75 -apple-system,system-ui,sans-serif;max-width:720px;margin:40px auto;padding:0 16px;color:#1a1a1a}

package/dist/renderMd.js

@@ -1,4 +1,6 @@
-import { formatValue, receipt } from './render.js';
+import { formatValue, protectCode, receipt } from './render.js';
+const SUPERSCRIPT = '⁰¹²³⁴⁵⁶⁷⁸⁹';
+const sup = (n) => `⁽${String(n).split('').map((d) => SUPERSCRIPT[Number(d)]).join('')}⁾`;
 /**
  * Grounded markdown: the portable render target. Every figure is bold with a superscript
  * that points into a receipts appendix, so the output pastes into Notion, a PR body, or
@@ -7,21 +9,29 @@ import { formatValue, receipt } from './render.js';
  */
 export function renderMarkdown(report, ir) {
     const used = [];
-    const body = report
+    const { text: protectedReport, restore } = protectCode(report);
+    const body = restore(protectedReport
         .replace(/\{\{m:([\w-]+)\}\}/g, (_, key) => {
         if (!used.includes(key))
             used.push(key);
-        return `**${formatValue(ir.metrics[key])}** ⁽${used.indexOf(key) + 1}⁾`;
+        return `**${formatValue(ir.metrics[key])}** ${sup(used.indexOf(key) + 1)}`;
     })
         .replace(/\{\{id:([\w-]+)\}\}/g, (_, key) => `\`${ir.identifiers[key]}\``)
         .replace(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g, (_, text, evidence) => `**${text.trim()}** *(evidence: ${evidence.trim()})*`)
-        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => text);
+        .replace(/\{\{raw:([^}]*)\}\}/g, (_, text) => text));
+    // evidence-only metrics get receipts too — a claim's reader must be able to check its keys
+    for (const [, , evidence] of protectedReport.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
+        for (const key of evidence.split(',').map((k) => k.trim()).filter(Boolean)) {
+            if (ir.metrics[key] && !used.includes(key))
+                used.push(key);
+        }
+    }
     const appendix = used
         .map((key, i) => {
         const m = ir.metrics[key];
         const definition = m.definition ? ` — ${m.definition}` : '';
-        return `${i + 1}. **${key}** = ${formatValue(m)}${definition}\n   ${receipt(m)}`;
+        return `${i + 1}. **${key}** = ${formatValue(m)}${definition}\n   ${receipt(m, false)}`;
     })
         .join('\n');
-    return `${body}\n\n---\n\n### Receipts (${used.length} metrics)\n\n${appendix}\n`;
+    return `${body.trimEnd()}\n\n---\n\n### Receipts (${used.length} metrics)\n\n${appendix}\n`;
 }

package/dist/scan.js

@@ -1,3 +1,8 @@
+/** Same-length whitespace, newlines kept — stripping must not move anything */
+const blank = (s) => s.replace(/[^\n]/g, ' ');
+const lineAt = (text, index) => text.slice(0, index).split('\n').length;
+/** Code shows syntax, it does not state facts — refs and numbers inside it are exempt */
+const blankCode = (report) => report.replace(/```[\s\S]*?```/g, blank).replace(/`[^`\n]*`/g, blank);
 /**
  * Find numbers in the narrative that are not bound to the IR. These are the leaks the
  * tool exists to catch: a typed, transcribed, or hallucinated figure reads exactly like
@@ -5,24 +10,30 @@
  */
 export function scanNakedNumbers(report) {
     const stripped = report
-        .replace(/\{\{(m|id):[\w-]+\}\}/g, ' ')
-        // a claim's prose stays scanned — only its syntax is removed, so a number
-        // smuggled into claim text is still a leak
-        .replace(/\{\{claim:([^|}]*)\|[^}]*\}\}/g, (_, text) => ` ${text} `)
-        .replace(/\{\{raw:[^}]*\}\}/g, ' ') // explicit, greppable escape hatch
-        .replace(/```[\s\S]*?```/g, ' ') // fenced code
-        .replace(/`[^`\n]*`/g, ' ') // inline code
-        .replace(/\d{4}-\d{2}-\d{2}/g, ' ') // ISO dates locate, they do not measure
-        .replace(/^#+ .*$/gm, ' ') // headings
-        .replace(/^\s*\d+\.\s/gm, ' '); // ordered-list markers
+        .replace(/\{\{(m|id):[\w-]+\}\}/g, blank)
+        // a claim's prose stays scanned — only its syntax is blanked, so a number
+        // smuggled into claim text is still a leak, at its true position
+        .replace(/\{\{claim:([^|}]*)\|[^}]*\}\}/g, (whole, text) => {
+        const start = whole.indexOf(text);
+        return blank(whole.slice(0, start)) + text + blank(whole.slice(start + text.length));
+    })
+        .replace(/\{\{raw:[^}]*\}\}/g, blank) // explicit, greppable escape hatch
+        .replace(/```[\s\S]*?```/g, blank) // fenced code
+        .replace(/`[^`\n]*`/g, blank) // inline code
+        .replace(/\]\([^)\s]*\)/g, blank) // markdown link targets — URLs locate, they do not measure
+        .replace(/https?:\/\/\S+/g, blank) // bare URLs, same reason
+        .replace(/\d{4}-\d{2}-\d{2}/g, blank) // ISO dates locate, they do not measure
+        .replace(/^#{1,6}(?= )/gm, blank) // heading markers only — heading TEXT is scanned, people summarise numbers there
+        .replace(/^\s*\d+\.\s/gm, blank); // ordered-list markers
     const leaks = [];
     for (const m of stripped.matchAll(/\d[\d,.]*\s*(%p?|[가-힣]{1,2})?/g)) {
-        const token = m[0].trim();
+        const token = m[0].trim().replace(/[.,]+$/, '');
         if (!token)
             continue;
         leaks.push({
             severity: 'error',
             rule: 'naked-number',
+            line: lineAt(stripped, m.index),
             message: `"${token}" appears in the narrative without a receipt`,
             detail: 'Bind it to the IR as {{m:…}} or {{id:…}}, or mark deliberate prose as {{raw:…}}.',
         });
@@ -30,42 +41,69 @@ export function scanNakedNumbers(report) {
     return leaks;
 }
 /** Every reference in the narrative must resolve; a dangling one is authoring drift. */
-export function scanRefs(report, metricKeys, idKeys) {
+export function scanRefs(rawReport, metricKeys, idKeys) {
     const leaks = [];
-    for (const [, text, evidence] of report.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
+    const report = blankCode(rawReport);
+    for (const m of report.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
+        const [, text, evidence] = m;
+        const line = lineAt(report, m.index);
         const keys = evidence.split(',').map((k) => k.trim()).filter(Boolean);
         if (keys.length === 0) {
             leaks.push({
                 severity: 'error',
                 rule: 'claim-without-evidence',
+                line,
                 message: `claim "${text.trim()}" names no evidence`,
                 detail: 'A conclusion must point at the metrics it rests on. Whether they support it stays a human judgement — but they must be attached.',
             });
         }
         for (const key of keys) {
             if (!metricKeys.has(key)) {
-                leaks.push({ severity: 'error', rule: 'unknown-ref', message: `claim "${text.trim()}" cites unknown metric "${key}"` });
+                leaks.push({ severity: 'error', rule: 'unknown-ref', line, message: `claim "${text.trim()}" cites unknown metric "${key}"` });
             }
         }
     }
     // a claim marker missing its evidence clause entirely is malformed, not exempt
-    for (const [, text] of report.matchAll(/\{\{claim:([^|}]*)\}\}/g)) {
+    for (const m of report.matchAll(/\{\{claim:([^|}]*)\}\}/g)) {
         leaks.push({
             severity: 'error',
             rule: 'claim-without-evidence',
-            message: `claim "${text.trim()}" names no evidence`,
+            line: lineAt(report, m.index),
+            message: `claim "${m[1].trim()}" names no evidence`,
             detail: 'Write it as {{claim: … | evidence: metric_key}}.',
         });
     }
-    for (const [, key] of report.matchAll(/\{\{m:([\w-]+)\}\}/g)) {
-        if (!metricKeys.has(key)) {
-            leaks.push({ severity: 'error', rule: 'unknown-ref', message: `{{m:${key}}} is not in the IR` });
+    for (const m of report.matchAll(/\{\{m:([\w-]+)\}\}/g)) {
+        if (!metricKeys.has(m[1])) {
+            leaks.push({ severity: 'error', rule: 'unknown-ref', line: lineAt(report, m.index), message: `{{m:${m[1]}}} is not in the IR` });
         }
     }
-    for (const [, key] of report.matchAll(/\{\{id:([\w-]+)\}\}/g)) {
-        if (!idKeys.has(key)) {
-            leaks.push({ severity: 'error', rule: 'unknown-ref', message: `{{id:${key}}} is not in the IR` });
+    for (const m of report.matchAll(/\{\{id:([\w-]+)\}\}/g)) {
+        if (!idKeys.has(m[1])) {
+            leaks.push({ severity: 'error', rule: 'unknown-ref', line: lineAt(report, m.index), message: `{{id:${m[1]}}} is not in the IR` });
         }
     }
     return leaks;
 }
+/**
+ * Anything still shaped like a marker after every recognised form is removed was a typo —
+ * and a typo'd marker must be a leak, or it renders verbatim and its number sails through.
+ */
+export function scanMarkers(rawReport) {
+    const known = blankCode(rawReport)
+        .replace(/\{\{(m|id):[\w-]+\}\}/g, blank)
+        .replace(/\{\{raw:[^}]*\}\}/g, blank)
+        .replace(/\{\{claim:[^|}]*\|\s*evidence:[^}]*\}\}/g, blank)
+        .replace(/\{\{claim:[^|}]*\}\}/g, blank); // no-pipe form is already claim-without-evidence
+    const leaks = [];
+    for (const m of known.matchAll(/\{\{[^}]*\}\}?/g)) {
+        leaks.push({
+            severity: 'error',
+            rule: 'malformed-marker',
+            line: lineAt(known, m.index),
+            message: `"${m[0]}" is not a recognised marker`,
+            detail: 'Valid forms: {{m:key}}, {{id:key}}, {{raw:…}}, {{claim: text | evidence: keys}}.',
+        });
+    }
+    return leaks;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watertight",
-  "version": "0.2.0",
+  "version": "0.6.0",
   "description": "Reports that hold water — every number carries its receipt, and ungrounded claims fail the build.",
   "type": "module",
   "bin": {