watertight 0.1.0 → 0.5.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,20 +126,40 @@ 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 |
@@ -139,6 +172,9 @@ Any leak fails the build (exit 1) and names the line:
 | `claim-without-evidence` | a `{{claim:}}` with no `evidence:` keys, or keys that don't exist |
 | `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
 
@@ -153,7 +189,37 @@ can reach, rewrites `value` and `fetched_at`, and recomputes derived values:
 - everything else (dashboards, vendor reports, hypotheses) is **named as
   skipped** — never silently assumed fresh
 
-`--dry-run` previews changes without writing.
+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
 
@@ -162,6 +228,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
@@ -173,6 +241,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)
@@ -183,6 +253,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
@@ -89,6 +91,9 @@ inputs: recompute at the source and correct whichever side is wrong.
 sources, updates `fetched_at`, recomputes derived values, and names every
 metric it could *not* refresh. `command` sources run only under
 `--allow-commands`; never pass that flag on an IR you did not author.
+Other source types (vendor APIs, analytics tools) can be refreshed through
+`--fetchers <module.mjs>` — one exported function per source type, with
+credentials from the environment, never from the IR.
 
 ## What stays yours
 

package/dist/cli.js

@@ -2,7 +2,10 @@
 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.
 
@@ -10,13 +13,19 @@ 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)
   --check            verify only, write nothing
   --dry-run          refresh only: show what would change, write nothing
+  --fetchers <file>  refresh only: a JS module of custom source adapters, e.g.
+                     export function mixpanel(source) { ... return value }
+                     Loading a module runs its code — only pass files you wrote or trust.
   --allow-commands   refresh only: let "command" sources run shell (off by default —
                      an IR from someone else's repo must not execute code on your machine)
   --json          machine-readable result on stdout
@@ -33,7 +42,9 @@ function parseArgs(argv) {
     let json = false;
     let dryRun = false;
     let allowCommands = false;
+    let fetchersPath;
     let format = 'html';
+    let maxAgeDays;
     let help = false;
     let version = false;
     for (let i = 0; i < args.length; i++) {
@@ -46,8 +57,17 @@ function parseArgs(argv) {
             dryRun = true;
         else if (arg === '--allow-commands')
             allowCommands = true;
+        else if (arg === '--fetchers')
+            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')
@@ -57,10 +77,10 @@ function parseArgs(argv) {
         else if (!arg.startsWith('-'))
             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 };
+    return { command, positional, out, check, json, help, version, dryRun, allowCommands, format, fetchersPath, maxAgeDays };
 }
 async function exists(path) {
     try {
@@ -78,6 +98,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;
@@ -90,7 +124,8 @@ async function main() {
         reportPath = join(dir, 'report.md');
         irPath = join(dir, 'metrics.json');
     }
-    for (const path of [reportPath, irPath]) {
+    // refresh works on the IR alone — an IR-only directory is a legitimate workspace
+    for (const path of opts.command === 'refresh' ? [irPath] : [reportPath, irPath]) {
         if (!(await exists(path))) {
             console.error(`Not found: ${path}`);
             console.error('Expected report.md and metrics.json — see --help.');
@@ -98,7 +133,21 @@ async function main() {
         }
     }
     if (opts.command === 'refresh') {
-        const r = await refresh(irPath, { allowCommands: opts.allowCommands, dryRun: opts.dryRun });
+        let fetchers;
+        if (opts.fetchersPath) {
+            const mod = await import(pathToFileURL(resolve(opts.fetchersPath)).href);
+            const exports = (typeof mod.default === 'object' && mod.default !== null ? mod.default : mod);
+            fetchers = Object.fromEntries(Object.entries(exports).filter(([, v]) => typeof v === 'function'));
+            if (Object.keys(fetchers).length === 0) {
+                console.error(`error: ${opts.fetchersPath} exports no functions — nothing to fetch with`);
+                process.exit(2);
+            }
+        }
+        const r = await refresh(irPath, { allowCommands: opts.allowCommands, dryRun: opts.dryRun, fetchers });
+        if (opts.json) {
+            console.log(JSON.stringify(r, null, 2));
+            process.exit(r.errors.length > 0 ? 1 : 0);
+        }
         for (const c of r.changes)
             console.log(`  ${c.key}: ${c.before.toLocaleString()} → ${c.after.toLocaleString()}`);
         for (const s of r.skipped)
@@ -110,7 +159,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) {
@@ -121,7 +170,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

@@ -3,9 +3,30 @@ 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') {
+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,

package/dist/init.js

@@ -0,0 +1,64 @@
+import { 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}`);
+    }
+    for (const [path, content] of files)
+        await writeFile(path, content);
+    return { written: files.map(([p]) => p) };
+}

package/dist/ir.js

@@ -72,7 +72,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',

package/dist/refresh.js

@@ -91,8 +91,11 @@ export async function refresh(irPath, options) {
                 }
                 value = fetchCommand(m.source, baseDir);
             }
+            else if (options.fetchers?.[m.source.type]) {
+                value = toNumber(await options.fetchers[m.source.type](m.source, { key, metric: m, baseDir }), `fetcher "${m.source.type}" for "${key}"`);
+            }
             else {
-                result.skipped.push({ key, reason: `no built-in adapter for source type "${m.source.type}"` });
+                result.skipped.push({ key, reason: `no adapter for source type "${m.source.type}"` });
                 continue;
             }
             if (value !== m.value)
@@ -104,14 +107,32 @@ export async function refresh(irPath, options) {
             result.errors.push({ key, message: err instanceof Error ? err.message : String(err) });
         }
     }
-    // parts may have moved, so stored sums are recomputed rather than left to go stale
+    // 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?.op !== 'sum' || Array.isArray(m.value))
+        if (!m.derived || Array.isArray(m.value))
             continue;
-        const computed = m.derived.of.reduce((acc, ref) => {
-            const part = raw.metrics[ref];
-            return acc + (part && typeof part.value === 'number' ? part.value : NaN);
-        }, 0);
+        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 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)
+                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;

package/dist/render.js

@@ -12,13 +12,13 @@ export function formatValue(m) {
         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) {

package/dist/renderMd.js

@@ -1,4 +1,6 @@
 import { formatValue, 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
@@ -11,7 +13,7 @@ export function renderMarkdown(report, ir) {
         .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()})*`)
@@ -20,8 +22,8 @@ export function renderMarkdown(report, ir) {
         .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,6 @@
+/** 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;
 /**
  * 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,16 +8,19 @@
  */
 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(/\d{4}-\d{2}-\d{2}/g, blank) // ISO dates locate, they do not measure
+        .replace(/^#+ .*$/gm, blank) // headings
+        .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();
@@ -23,6 +29,7 @@ export function scanNakedNumbers(report) {
         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:…}}.',
         });
@@ -32,39 +39,43 @@ export function scanNakedNumbers(report) {
 /** Every reference in the narrative must resolve; a dangling one is authoring drift. */
 export function scanRefs(report, metricKeys, idKeys) {
     const leaks = [];
-    for (const [, text, evidence] of report.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
+    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;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "watertight",
-  "version": "0.1.0",
-  "description": "Reports that hold water \u2014 every number carries its receipt, and ungrounded claims fail the build.",
+  "version": "0.5.0",
+  "description": "Reports that hold water — every number carries its receipt, and ungrounded claims fail the build.",
   "type": "module",
   "bin": {
-    "watertight": "./dist/cli.js"
+    "watertight": "dist/cli.js"
   },
   "files": [
     "dist",