watertight 0.5.0 → 0.7.0

package/README.md

@@ -80,7 +80,9 @@ a measured metric says where it was fetched, over what window, and when:
 ```
 
 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:
+up, or a delta that doesn't recompute, is a build failure. Ops: `sum`, `avg`,
+`pct_change`, `ratio` (a / b), `diff` (a − b) — the arithmetic reports actually
+do, so hand-computed values don't have to masquerade as measured ones:
 
 ```json
 "lift": {
@@ -122,6 +124,10 @@ hypothesised {{m:revenue_target}}.
 Support runs {{raw:24/7}}.
 ```
 
+`{{raw:}}` is the escape hatch, and it stays visible: the compile header counts
+raw escapes, the markdown render lists them in an **Ungrounded** section, and
+`--max-raw <n>` turns the count into a gate.
+
 Compile:
 
 ```bash
@@ -164,22 +170,39 @@ figure shows its receipt.
 
 | 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 |
+| `identifier-measurement` | an identifier whose value is shaped like a measurement (`"47%"`, `"1,428"`) — a number smuggled past the receipt requirement through the id door |
+| `raw-budget` | with `--max-raw <n>`: more `{{raw:}}` escapes than the budget — the escape hatch stays boundable |
 
 <br>
 
 ## Re-verification
 
-Numbers age. `watertight refresh .` re-fetches every metric whose source it
-can reach, rewrites `value` and `fetched_at`, and recomputes derived values:
+**`watertight verify .`** re-fetches every reachable source and *compares* —
+a stored value the source no longer returns is a `receipt-mismatch`, nothing
+is written, and the run fails. This is the check that catches a plausible
+receipt attached to a wrong value (the "AI remembered a number" failure) and
+the natural CI companion to `--check`.
+
+`watertight refresh .` is the writing counterpart: it re-fetches, rewrites
+`value` and `fetched_at`, recomputes derived values — and when a changed
+metric is cited as claim evidence, it says so:
+
+```
+  fallback_revenue_total: 1,428 → 45,200
+  ⚠ claim "수익 가설 미달" cites fallback_revenue_total — the number moved, review the conclusion
+```
+
+Conclusions age like numbers do. Sources:
 
 - `csv` sources — `{ "type": "csv", "file": "data.csv", "cell": "B2" }`
 - `json` sources — `{ "type": "json", "file": "kpi.json", "path": "revenue.total" }`

package/SKILL.md

@@ -53,9 +53,12 @@ number yet.
 - `source.type` is free-form (`sql`, `mixpanel`, `csv`, `hypothesis`, …);
   put enough alongside it that a stranger could re-fetch the value.
 - Numbers that *name* rather than *measure* (versions, flags, unit IDs) go
-  in `identifiers`, not `metrics`.
+  in `identifiers`, not `metrics`. A measurement-shaped identifier ("47%",
+  "1,428") is a leak — the id door is not a receipt bypass.
 - Anything computed from other metrics must be `derived` — the compiler
   recomputes it and rejects mismatches beyond the value's own precision.
+  Ops: `sum`, `avg`, `pct_change`, `ratio`, `diff`. Never hand-compute one of
+  these and present it as measured — that is an unverified value.
 - `ratio` / `ratio-point` metrics require a `definition`. Ratios above 1.0
   are legal but the definition must explain the basis.
 - A hypothesis or plan figure is still a metric — source it as
@@ -87,7 +90,10 @@ a measurement in `{{raw:}}` to silence the checker. A `derived-mismatch` is
 the tool telling you a stated total or delta does not follow from its
 inputs: recompute at the source and correct whichever side is wrong.
 
-**5. Re-verify later with `watertight refresh .`** — re-fetches csv/json
+**5. Before shipping, run `watertight verify .`** — it re-fetches every
+reachable source and fails on any stored value the source does not return.
+A receipt you attached from memory will not survive this step; that is the
+point. Then re-verify later with `watertight refresh .` — re-fetches csv/json
 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.
@@ -105,5 +111,7 @@ exists to make that judgment inspectable, not to automate it away.
 ## Hard rules
 
 - Never invent, estimate, or "recall" a value into the IR. No source, no number.
+- Never wrap a measurement in `{{raw:}}` to pass the compile — raw counts are
+  printed, disclosed in the render, and gated by `--max-raw`.
 - Never edit a `value` to make a `derived-mismatch` pass. Fix the inputs.
 - Real company data stays in private storage; fixtures and examples are fictional.

package/dist/cli.js

@@ -13,20 +13,24 @@ 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 verify <dir>      re-fetch and COMPARE — a stored value its source no longer
+                               returns is a receipt-mismatch; nothing is written
   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
+  --max-raw <n>      compile only: fail when the report uses more than n {{raw:}}
+                     escapes — the escape hatch must stay boundable
   --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.
+  --fetchers <file>  refresh/verify: 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 —
+  --allow-commands   refresh/verify: 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
   -v, --version   print the version
@@ -45,6 +49,7 @@ function parseArgs(argv) {
     let fetchersPath;
     let format = 'html';
     let maxAgeDays;
+    let maxRaw;
     let help = false;
     let version = false;
     for (let i = 0; i < args.length; i++) {
@@ -68,19 +73,31 @@ function parseArgs(argv) {
                 process.exit(2);
             }
         }
+        else if (arg === '--max-raw') {
+            maxRaw = Number(args[++i]);
+            if (!Number.isFinite(maxRaw) || maxRaw < 0) {
+                console.error(`error: --max-raw needs a number, 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' : positional[0] === 'init' ? 'init' : 'compile';
+    const command = ['refresh', 'init', 'verify'].includes(positional[0]) ? positional[0] : 'compile';
     if (command !== 'compile')
         positional.shift();
-    return { command, positional, out, check, json, help, version, dryRun, allowCommands, format, fetchersPath, maxAgeDays };
+    return { command, positional, out, check, json, help, version, dryRun, allowCommands, format, fetchersPath, maxAgeDays, maxRaw };
 }
 async function exists(path) {
     try {
@@ -124,15 +141,15 @@ async function main() {
         reportPath = join(dir, 'report.md');
         irPath = join(dir, 'metrics.json');
     }
-    // refresh works on the IR alone — an IR-only directory is a legitimate workspace
-    for (const path of opts.command === 'refresh' ? [irPath] : [reportPath, irPath]) {
+    // refresh/verify work on the IR alone — an IR-only directory is a legitimate workspace
+    for (const path of opts.command === 'refresh' || opts.command === 'verify' ? [irPath] : [reportPath, irPath]) {
         if (!(await exists(path))) {
             console.error(`Not found: ${path}`);
             console.error('Expected report.md and metrics.json — see --help.');
             process.exit(2);
         }
     }
-    if (opts.command === 'refresh') {
+    if (opts.command === 'refresh' || opts.command === 'verify') {
         let fetchers;
         if (opts.fetchersPath) {
             const mod = await import(pathToFileURL(resolve(opts.fetchersPath)).href);
@@ -143,13 +160,55 @@ async function main() {
                 process.exit(2);
             }
         }
-        const r = await refresh(irPath, { allowCommands: opts.allowCommands, dryRun: opts.dryRun, fetchers });
+        const ir = JSON.parse(await readFile(irPath, 'utf8'));
+        const r = await refresh(irPath, {
+            allowCommands: opts.allowCommands,
+            dryRun: opts.dryRun || opts.command === 'verify',
+            fetchers,
+        });
+        if (opts.command === 'verify') {
+            // a change on a MEASURED metric means the IR no longer matches its source —
+            // the receipt is real but the value is not. Derived changes just cascade.
+            const mismatches = r.changes.filter((c) => !ir.metrics?.[c.key]?.derived);
+            if (opts.json) {
+                console.log(JSON.stringify({ mismatches, skipped: r.skipped, errors: r.errors }, null, 2));
+                process.exit(mismatches.length > 0 || r.errors.length > 0 ? 1 : 0);
+            }
+            for (const m of mismatches) {
+                console.log(`  ✗ [receipt-mismatch] metric "${m.key}" is ${m.before.toLocaleString()} in the IR, but its source now returns ${m.after.toLocaleString()}`);
+            }
+            for (const sk of r.skipped)
+                console.log(`  ~ ${sk.key} skipped — ${sk.reason}`);
+            for (const e of r.errors)
+                console.error(`  ✗ ${e.key}: ${e.message}`);
+            if (mismatches.length > 0 || r.errors.length > 0) {
+                console.log(`\n${mismatches.length} receipt mismatch(es), ${r.errors.length} fetch error(s) — the IR does not match its sources`);
+                process.exit(1);
+            }
+            const verified = Object.keys(ir.metrics ?? {}).length - r.skipped.length;
+            console.log(`\nreceipts verified (${verified} checked, ${r.skipped.length} skipped) — nothing written`);
+            process.exit(0);
+        }
+        // conclusions age too: a claim citing a metric that just moved needs a re-read
+        const changedKeys = new Set(r.changes.map((c) => c.key));
+        const reviewClaims = [];
+        if (changedKeys.size > 0 && (await exists(reportPath))) {
+            const report = await readFile(reportPath, 'utf8');
+            for (const [, text, evidence] of report.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
+                const cited = evidence.split(',').map((k) => k.trim()).filter((k) => changedKeys.has(k));
+                if (cited.length > 0)
+                    reviewClaims.push({ claim: text.trim(), evidence: cited });
+            }
+        }
         if (opts.json) {
-            console.log(JSON.stringify(r, null, 2));
+            console.log(JSON.stringify({ ...r, reviewClaims }, 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 rc of reviewClaims) {
+            console.log(`  ⚠ claim "${rc.claim}" cites ${rc.evidence.join(', ')} — the number moved, review the conclusion`);
+        }
         for (const s of r.skipped)
             console.log(`  ~ ${s.key} skipped — ${s.reason}`);
         for (const e of r.errors)
@@ -159,14 +218,15 @@ 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, { format: opts.format, maxAgeDays: opts.maxAgeDays });
+    const result = await compile(reportPath, irPath, { format: opts.format, maxAgeDays: opts.maxAgeDays, maxRaw: opts.maxRaw });
     const defaultName = opts.format === 'md' ? 'report.grounded.md' : 'report.html';
     const outPath = resolve(opts.out ?? join(reportPath, '..', defaultName));
     if (opts.json) {
         console.log(JSON.stringify({ version: pkg.version, ...result, output: undefined, wrote: result.output && !opts.check ? outPath : undefined }, null, 2));
     }
     else {
-        console.log(`\nwatertight v${pkg.version} · ${result.grounded.metrics} grounded metrics · ${result.grounded.claims} claims · ${result.grounded.identifiers} identifiers`);
+        const rawNote = result.grounded.raw > 0 ? ` · ${result.grounded.raw} raw escape(s)` : '';
+        console.log(`\nwatertight v${pkg.version} · ${result.grounded.metrics} grounded metrics · ${result.grounded.claims} claims · ${result.grounded.identifiers} identifiers${rawNote}`);
         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) {

package/dist/compile.js

@@ -2,7 +2,7 @@ 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';
+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';
@@ -31,8 +31,20 @@ export async function compile(reportPath, irPath, options = 'html') {
         metrics: [...report.matchAll(/\{\{m:/g)].length,
         identifiers: [...report.matchAll(/\{\{id:/g)].length,
         claims: [...report.matchAll(/\{\{claim:/g)].length,
+        raw: [...report.matchAll(/\{\{raw:/g)].length,
     };
+    // the escape hatch must stay visible and boundable — wrapping everything in raw
+    // is how an agent games the compile instead of grounding the numbers
+    if (opts.maxRaw !== undefined && grounded.raw > opts.maxRaw) {
+        leaks.push({
+            severity: 'error',
+            rule: 'raw-budget',
+            message: `${grounded.raw} raw escape(s) exceed the budget of ${opts.maxRaw}`,
+            detail: 'Ground the numbers instead, or raise --max-raw deliberately.',
+        });
+    }
     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

@@ -1,4 +1,4 @@
-import { writeFile } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 /**
@@ -58,6 +58,7 @@ export async function init(dir) {
         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
@@ -17,8 +26,19 @@ export function parseIr(raw) {
     const leaks = [];
     const root = (raw ?? {});
     const identifiers = {};
+    // an identifier names a thing (version, flag, unit id); a value shaped like a
+    // measurement is a number smuggled past the receipt requirement through the id door
+    const MEASUREMENT_SHAPE = /(%p?$)|(^\d{1,3}(,\d{3})+(\.\d+)?$)/;
     for (const [k, v] of Object.entries(root['identifiers'] ?? {})) {
         identifiers[k] = String(v);
+        if (MEASUREMENT_SHAPE.test(identifiers[k].trim())) {
+            leaks.push({
+                severity: 'error',
+                rule: 'identifier-measurement',
+                message: `identifier "${k}" is "${identifiers[k]}" — that is a measurement, not a name`,
+                detail: 'Move it to metrics with a source, or it is a number without a receipt.',
+            });
+        }
     }
     const metrics = root['metrics'] ?? {};
     if (Object.keys(metrics).length === 0) {
@@ -31,8 +51,14 @@ 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` });
+        if (!m || typeof m !== 'object') {
+            leaks.push({ severity: 'error', rule: 'missing-field', message: `metric "${key}" is not an object` });
+            continue;
+        }
+        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) {
@@ -51,33 +77,34 @@ export function parseIr(raw) {
                 leaks.push({ severity: 'error', rule: 'bad-derived', message: `metric "${key}": a range cannot be derived` });
                 continue;
             }
-            if (m.derived.op === 'sum') {
-                let computed = 0;
+            const endpoint = (v) => {
+                if (typeof v === 'number')
+                    return v;
+                const ref = metrics[v];
+                return ref && typeof ref.value === 'number' ? ref.value : undefined;
+            };
+            if (m.derived.op === 'sum' || m.derived.op === 'avg') {
+                let total = 0;
                 let broken = false;
                 for (const ref of m.derived.of) {
                     const part = metrics[ref];
                     if (!part || typeof part.value !== 'number') {
-                        leaks.push({ severity: 'error', rule: 'bad-derived', message: `metric "${key}" sums unknown or non-scalar metric "${ref}"` });
+                        leaks.push({ severity: 'error', rule: 'bad-derived', message: `metric "${key}" ${m.derived.op}s unknown or non-scalar metric "${ref}"` });
                         broken = true;
                         continue;
                     }
-                    computed += part.value;
+                    total += part.value;
                 }
-                if (!broken && computed !== m.value) {
+                const computed = m.derived.op === 'avg' ? total / m.derived.of.length : total;
+                if (!broken && !roundsTo(m.value, computed)) {
                     leaks.push({
                         severity: 'error',
                         rule: 'derived-mismatch',
-                        message: `metric "${key}" is ${m.value}, but its parts sum to ${computed}`,
+                        message: `metric "${key}" is ${m.value}, but its parts ${m.derived.op === 'avg' ? 'average' : 'sum'} to ${computed}`,
                     });
                 }
             }
             else if (m.derived.op === 'pct_change') {
-                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) {
@@ -98,6 +125,36 @@ export function parseIr(raw) {
                     });
                 }
             }
+            else if (m.derived.op === 'ratio' || m.derived.op === 'diff') {
+                const a = endpoint(m.derived.a);
+                const b = endpoint(m.derived.b);
+                if (a === undefined || b === undefined || (m.derived.op === 'ratio' && b === 0)) {
+                    leaks.push({
+                        severity: 'error',
+                        rule: 'bad-derived',
+                        message: `metric "${key}": ${m.derived.op} operands must be numbers or scalar metric keys (got ${m.derived.a}, ${m.derived.b})`,
+                    });
+                    continue;
+                }
+                const computed = m.derived.op === 'ratio' ? a / b : a - b;
+                if (!roundsTo(m.value, computed)) {
+                    leaks.push({
+                        severity: 'error',
+                        rule: 'derived-mismatch',
+                        message: `metric "${key}" is ${m.value}, but ${m.derived.a} ${m.derived.op === 'ratio' ? '/' : '−'} ${m.derived.b} computes to ${computed.toFixed(4)}`,
+                        detail: 'A derived value must be correctly rounded to its own precision.',
+                    });
+                }
+            }
+            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,37 +108,77 @@ 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 {
+    // 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;
+            const fail = (message) => {
+                if (!derivedErrors.has(key)) {
+                    derivedErrors.add(key);
+                    result.errors.push({ key, message });
+                }
+            };
             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)
+            // every recomputed value keeps the author's stated precision — refresh must not
+            // turn 0.155 into 0.1551724 or write float noise over an exact 0.3
+            const authorDecimals = (String(m.value).split('.')[1] ?? '').length;
+            const rounded = (v) => Number(v.toFixed(authorDecimals));
+            let computed;
+            if (m.derived.op === 'sum' || m.derived.op === 'avg') {
+                const total = 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(total)) {
+                    fail(`${m.derived.op} references unknown or non-scalar metrics — not recomputed`);
+                    continue;
+                }
+                computed = rounded(m.derived.op === 'avg' ? total / m.derived.of.length : total);
+            }
+            else if (m.derived.op === 'pct_change') {
+                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;
+                }
+                computed = rounded((after - before) / before);
+            }
+            else if (m.derived.op === 'ratio' || m.derived.op === 'diff') {
+                const a = endpoint(m.derived.a);
+                const b = endpoint(m.derived.b);
+                if (a === undefined || b === undefined || (m.derived.op === 'ratio' && b === 0)) {
+                    fail(`${m.derived.op} operands are unresolvable — not recomputed`);
+                    continue;
+                }
+                computed = rounded(m.derived.op === 'ratio' ? a / b : a - b);
+            }
+            else {
+                fail(`unknown derived op "${m.derived.op}" — 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));
-        }
-        if (Number.isFinite(computed) && computed !== m.value) {
-            result.changes.push({ key, before: m.value, after: computed });
-            m.value = computed;
+            }
+            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,13 +1,30 @@
+/**
+ * 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();
@@ -16,7 +33,11 @@ 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.derived.op === 'avg'
+                ? `= avg(${m.derived.of.join(', ')}) (recomputed)`
+                : m.derived.op === 'pct_change'
+                    ? `= ${m.derived.before} → ${m.derived.after} (recomputed)`
+                    : `= ${m.derived.a} ${m.derived.op === 'ratio' ? '/' : '−'} ${m.derived.b} (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}`, includeDefinition && m.definition].filter(Boolean).join(' · ');
 }
@@ -37,7 +58,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 +72,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,4 @@
-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('')}⁾`;
 /**
@@ -9,7 +9,8 @@ const sup = (n) => `⁽${String(n).split('').map((d) => SUPERSCRIPT[Number(d)]).
  */
 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);
@@ -17,7 +18,22 @@ export function renderMarkdown(report, ir) {
     })
         .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);
+        }
+    }
+    // the report discloses its own escape hatches — a reader (and a reviewer) sees
+    // exactly which prose numbers carry no receipt
+    const raws = [...protectedReport.matchAll(/\{\{raw:([^}]*)\}\}/g)].map((m) => m[1].trim());
+    const rawSection = raws.length === 0
+        ? ''
+        : `\n\n### Ungrounded (${raws.length} raw escape${raws.length === 1 ? '' : 's'})\n\n${raws
+            .map((r) => `- ${r}`)
+            .join('\n')}`;
     const appendix = used
         .map((key, i) => {
         const m = ir.metrics[key];
@@ -25,5 +41,5 @@ export function renderMarkdown(report, ir) {
         return `${i + 1}. **${key}** = ${formatValue(m)}${definition}\n   ${receipt(m, false)}`;
     })
         .join('\n');
-    return `${body.trimEnd()}\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}${rawSection}\n`;
 }

package/dist/scan.js

@@ -1,6 +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
@@ -18,12 +20,15 @@ export function scanNakedNumbers(report) {
         .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(/^#+ .*$/gm, blank) // headings
+        .replace(/(?<![A-Za-z0-9가-힣])[A-Za-z]+\d[\w.\-]*/g, blank) // Q3, v6.109.0, iOS15 — names, not measurements
+        .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({
@@ -37,8 +42,9 @@ 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 = [];
+    const report = blankCode(rawReport);
     for (const m of report.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
         const [, text, evidence] = m;
         const line = lineAt(report, m.index);
@@ -80,3 +86,25 @@ export function scanRefs(report, metricKeys, idKeys) {
     }
     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.5.0",
+  "version": "0.7.0",
   "description": "Reports that hold water — every number carries its receipt, and ungrounded claims fail the build.",
   "type": "module",
   "bin": {