watertight 0.6.0 → 0.8.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": {
@@ -96,6 +98,20 @@ up, or a delta that doesn't recompute, is a build failure:
 }
 ```
 
+An **assertion** is the arithmetic half of a conclusion — "under target",
+"no cannibalisation" — judged on every compile. When `refresh` moves a number
+far enough to flip it, the build breaks until the conclusion is rewritten:
+
+```json
+"assertions": {
+  "met_target": { "op": "gte", "a": "revenue_total", "b": "revenue_target.lo" }
+}
+```
+
+Ops: `lt`, `lte`, `gt`, `gte`. Operands are metric keys, inline numbers, or —
+for range metrics, always explicitly — `key.lo` / `key.hi`. Claims can cite
+assertion keys as evidence.
+
 A **range** states a hypothesis honestly — plans are receipts too:
 
 ```json
@@ -117,11 +133,15 @@ Conversion moved from {{m:conversion_before}} to {{m:conversion_after}},
 a lift of {{m:lift}}. Revenue impact was {{m:revenue_total}}, within the
 hypothesised {{m:revenue_target}}.
 
-{{claim: the experiment met its success criteria | evidence: lift, revenue_total}}
+{{claim: the experiment met its success criteria | evidence: lift, met_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
@@ -129,6 +149,7 @@ watertight report.md metrics.json    # → report.html (self-contained, hover fo
 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 . --strict                # promote warnings (worded-number) to errors
 watertight . --json                  # machine-readable result
 ```
 
@@ -174,13 +195,36 @@ figure shows its receipt.
 | `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 |
+| `worded-number` | *(warn)* a quantity written in words — "세 배", "절반", "a million" — that no receipt can bind to; `--strict` makes it fail |
+| `assertion-failed` | an `assertions` comparison that is false — the numbers no longer support the conclusion |
+| `bad-assertion` / `duplicate-key` | a malformed assertion (unknown op, missing operand, range without `.lo`/`.hi`), or a key that is both metric and assertion |
+| `unused-metric` | *(info)* a metric nothing references — drift signal, never fails, never promoted |
+
+Severities: **error** fails the build and suppresses output; **warn** and **info**
+are reported while the output still renders and the exit code stays 0.
 
 <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,13 +53,29 @@ 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` (`{ "op": "sum", "of": ["k1", "k2"] }`), `pct_change`
+  (`{ "op": "pct_change", "before": "k1", "after": "k2" }`), `ratio`/`diff`
+  (`{ "op": "ratio", "a": "k1", "b": "k2" }` — a/b and a−b). Operands are metric
+  keys (preferred) or inline numbers. 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
-  `{ "type": "hypothesis", ... }` pointing at the planning doc.
+  `{ "type": "hypothesis", ... }` pointing at the planning doc. It renders
+  visibly as an assumption, not a measurement.
+- When a conclusion is a comparison ("under target"), state it as an
+  assertion and cite it as evidence — the compiler judges it every build:
+
+  ```json
+  "assertions": { "under_target": { "op": "lt", "a": "revenue_total", "b": "revenue_target.lo" } }
+  ```
+
+  Ops: lt, lte, gt, gte. Range metrics are referenced with an explicit
+  `.lo` / `.hi` accessor — never bare.
 
 **3. Write the narrative (`report.md`).**
 Never type a figure into prose. Reference it:
@@ -81,13 +97,19 @@ watertight . --check --max-age 30           # also fail receipts older than 30 d
 ```
 
 Every leak names its line (`report.md:31`), so fix them where they live.
+A `worded-number` warning ("세 배", "half of") means a quantity is written in
+words: if it has a basis, restate it as a metric or derived; if it is
+rhetoric, mark it `{{raw:…}}`. Run with `--strict` to treat these as errors.
 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
 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 +127,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

@@ -4,6 +4,7 @@ import { join, resolve } from 'node:path';
 import { compile } from './compile.js';
 import { basename } from 'node:path';
 import { refresh } from './refresh.js';
+import { parseIr } from './ir.js';
 import { init } from './init.js';
 import { pathToFileURL } from 'node:url';
 const USAGE = `watertight — reports that hold water. Every number carries its receipt;
@@ -13,20 +14,26 @@ 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
+  --strict           compile only: promote warnings (worded-number) to errors.
+                     info (unused-metric) is a drift signal and never promotes
   --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 +52,8 @@ function parseArgs(argv) {
     let fetchersPath;
     let format = 'html';
     let maxAgeDays;
+    let maxRaw;
+    let strict = false;
     let help = false;
     let version = false;
     for (let i = 0; i < args.length; i++) {
@@ -68,6 +77,15 @@ function parseArgs(argv) {
                 process.exit(2);
             }
         }
+        else if (arg === '--strict')
+            strict = true;
+        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')
@@ -82,10 +100,10 @@ function parseArgs(argv) {
         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, strict };
 }
 async function exists(path) {
     try {
@@ -129,15 +147,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);
@@ -148,13 +166,62 @@ 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') {
+            // integrity first: a tampered derived (inputs unchanged, value edited) is not a
+            // cascade — parseIr recomputes every derivation, so verify alone catches it even
+            // in an IR-only directory where no compile ever runs
+            const integrity = parseIr(ir).leaks;
+            // a change on a MEASURED metric means the IR no longer matches its source —
+            // the receipt is real but the value is not. Derived drift is covered above.
+            const mismatches = r.changes.filter((c) => !ir.metrics?.[c.key]?.derived);
+            const failing = mismatches.length > 0 || integrity.length > 0 || r.errors.length > 0;
+            if (opts.json) {
+                console.log(JSON.stringify({ mismatches, integrity, skipped: r.skipped, errors: r.errors }, null, 2));
+                process.exit(failing ? 1 : 0);
+            }
+            for (const leak of integrity)
+                console.log(`  ✗ [${leak.rule}] ${leak.message}`);
+            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 (failing) {
+                console.log(`\n${mismatches.length} receipt mismatch(es), ${integrity.length} integrity leak(s), ${r.errors.length} fetch error(s) — the IR does not hold water`);
+                process.exit(1);
+            }
+            const verified = Object.keys(ir.metrics ?? {}).length - r.skipped.length;
+            console.log(`\nreceipts verified (${verified} checked, ${r.skipped.length} named as 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)
@@ -164,19 +231,28 @@ 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, strict: opts.strict });
     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`);
+            const count = (sev) => result.leaks.filter((l) => l.severity === sev).length;
+            const errors = count('error');
+            const parts = [
+                errors > 0 && `${errors} error(s)`,
+                count('warn') > 0 && `${count('warn')} warning(s)`,
+                count('info') > 0 && `${count('info')} info`,
+            ].filter(Boolean);
+            console.log(`\n${parts.join(', ')}${errors > 0 ? ' — the report does not hold water' : ''}:\n`);
+            const ICON = { error: '✗', warn: '⚠', info: 'ℹ' };
             for (const leak of result.leaks) {
                 const where = leak.line !== undefined ? `${basename(reportPath)}:${leak.line} — ` : '';
-                console.log(`  ✗ [${leak.rule}] ${where}${leak.message}`);
+                console.log(`  ${ICON[leak.severity]} [${leak.rule}] ${where}${leak.message}`);
                 if (leak.detail)
                     console.log(`    ${leak.detail}`);
             }
@@ -191,7 +267,8 @@ async function main() {
     else if (result.output && opts.check && !opts.json) {
         console.log('holds water (check only — nothing written)\n');
     }
-    process.exit(result.leaks.length > 0 ? 1 : 0);
+    // warn and info report without blocking; only an error (or a promoted warn) fails
+    process.exit(result.leaks.some((l) => l.severity === 'error') ? 1 : 0);
 }
 main().catch((err) => {
     console.error(err instanceof Error ? err.message : err);

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 { scanMarkers, scanNakedNumbers, scanRefs } from './scan.js';
+import { blankCode, scanMarkers, scanNakedNumbers, scanRefs, scanWordedNumbers } from './scan.js';
 export async function compile(reportPath, irPath, options = 'html') {
     const opts = typeof options === 'string' ? { format: options } : options;
     const format = opts.format ?? 'html';
@@ -27,16 +27,77 @@ export async function compile(reportPath, irPath, options = 'html') {
             }
         }
     }
+    // counted on code-blanked text so a fenced syntax example is neither a grounded
+    // metric nor a raw escape — the header, the scanner and the render must agree
+    const prose = blankCode(report);
     const grounded = {
-        metrics: [...report.matchAll(/\{\{m:/g)].length,
-        identifiers: [...report.matchAll(/\{\{id:/g)].length,
-        claims: [...report.matchAll(/\{\{claim:/g)].length,
+        metrics: [...prose.matchAll(/\{\{m:/g)].length,
+        identifiers: [...prose.matchAll(/\{\{id:/g)].length,
+        claims: [...prose.matchAll(/\{\{claim:/g)].length,
+        raw: [...prose.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)
+    leaks.push(...scanWordedNumbers(report));
+    if (ir) {
+        leaks.push(...scanRefs(report, new Set(Object.keys(ir.metrics)), new Set(Object.keys(ir.identifiers)), new Set(Object.keys(ir.assertions))));
+        // a metric nothing references is drift, not a failure — info, and never promoted
+        const referenced = new Set();
+        for (const m of prose.matchAll(/\{\{m:([\w-]+)\}\}/g))
+            referenced.add(m[1]);
+        for (const [, , evidence] of prose.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
+            for (const k of evidence.split(',').map((k) => k.trim()).filter(Boolean))
+                referenced.add(k);
+        }
+        for (const m of Object.values(ir.metrics)) {
+            const d = m?.derived;
+            if (!d)
+                continue;
+            if (d.op === 'sum' || d.op === 'avg') {
+                if (Array.isArray(d.of))
+                    for (const k of d.of)
+                        referenced.add(k);
+            }
+            else if (d.op === 'pct_change') {
+                for (const k of [d.before, d.after])
+                    if (typeof k === 'string')
+                        referenced.add(k);
+            }
+            else {
+                for (const k of [d.a, d.b])
+                    if (typeof k === 'string')
+                        referenced.add(k);
+            }
+        }
+        for (const a of Object.values(ir.assertions)) {
+            for (const k of [a.a, a.b])
+                if (typeof k === 'string')
+                    referenced.add(k.replace(/\.(lo|hi)$/, ''));
+        }
+        for (const key of Object.keys(ir.metrics)) {
+            if (!referenced.has(key)) {
+                leaks.push({ severity: 'info', rule: 'unused-metric', message: `metric "${key}" is in the IR but nothing references it`, detail: 'Drift signal — cite it, or remove it.' });
+            }
+        }
+    }
+    if (opts.strict) {
+        for (const leak of leaks)
+            if (leak.severity === 'warn')
+                leak.severity = 'error';
+    }
+    // only errors stop the build — warn and info are reported, and the output still renders
+    const hasErrors = leaks.some((l) => l.severity === 'error');
+    if (hasErrors || !ir)
         return { leaks, grounded };
     return { leaks, output: format === 'md' ? renderMarkdown(report, ir) : render(report, ir), grounded };
 }

package/dist/ir.js

@@ -26,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+)?$)|(^\d+(\.\d+)?\s*(원|건|명|회)$)/;
     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) {
@@ -40,6 +51,10 @@ export function parseIr(raw) {
         return { leaks };
     }
     for (const [key, m] of Object.entries(metrics)) {
+        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) {
@@ -62,33 +77,42 @@ 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') {
+                if (!Array.isArray(m.derived.of) || m.derived.of.length === 0) {
+                    leaks.push({
+                        severity: 'error',
+                        rule: 'bad-derived',
+                        message: `metric "${key}": ${m.derived.op} needs a non-empty "of" array of metric keys`,
+                    });
+                    continue;
+                }
+                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;
                 }
+                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) {
@@ -109,6 +133,27 @@ 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({
@@ -128,5 +173,66 @@ export function parseIr(raw) {
             }
         }
     }
-    return { ir: { identifiers, metrics }, leaks };
+    // assertions: the comparisons conclusions rest on, judged on every compile.
+    // Malformed input is a leak, never a crash — the derived.of lesson applies here too.
+    const OPS = { lt: (a, b) => a < b, lte: (a, b) => a <= b, gt: (a, b) => a > b, gte: (a, b) => a >= b };
+    const assertions = {};
+    for (const [key, raw] of Object.entries(root['assertions'] ?? {})) {
+        if (metrics[key]) {
+            leaks.push({ severity: 'error', rule: 'duplicate-key', message: `"${key}" is both a metric and an assertion — one namespace, one meaning` });
+            continue;
+        }
+        const a = raw;
+        const validOperand = (v) => (typeof v === 'number' && Number.isFinite(v)) || typeof v === 'string';
+        if (!a || typeof a !== 'object' || typeof a.op !== 'string' || !validOperand(a.a) || !validOperand(a.b)) {
+            // null, booleans, objects — a guard that only checks undefined lets a serialisation
+            // slip silently disarm the very device meant to guard the conclusion
+            leaks.push({ severity: 'error', rule: 'bad-assertion', message: `assertion "${key}" needs op, and operands that are numbers or metric keys` });
+            continue;
+        }
+        if (!(a.op in OPS)) {
+            leaks.push({ severity: 'error', rule: 'bad-assertion', message: `assertion "${key}" has unknown op "${a.op}" — supported: lt, lte, gt, gte` });
+            continue;
+        }
+        const operand = (v, side) => {
+            if (typeof v === 'number' && Number.isFinite(v))
+                return v;
+            if (typeof v !== 'string')
+                return undefined;
+            const accessor = /^([\w-]+)\.(lo|hi)$/.exec(v);
+            if (accessor) {
+                const m = metrics[accessor[1]];
+                if (!m || !Array.isArray(m.value)) {
+                    leaks.push({ severity: 'error', rule: 'bad-assertion', message: `assertion "${key}": ${side} "${v}" needs "${accessor[1]}" to be a range metric` });
+                    return undefined;
+                }
+                return accessor[2] === 'lo' ? m.value[0] : m.value[1];
+            }
+            const m = metrics[v];
+            if (!m) {
+                leaks.push({ severity: 'error', rule: 'bad-assertion', message: `assertion "${key}": ${side} "${v}" is not a metric` });
+                return undefined;
+            }
+            if (Array.isArray(m.value)) {
+                // no magic default — the author says which end of the range they mean
+                leaks.push({ severity: 'error', rule: 'bad-assertion', message: `assertion "${key}": "${v}" is a range — say ${v}.lo or ${v}.hi` });
+                return undefined;
+            }
+            return m.value;
+        };
+        const left = operand(a.a, 'a');
+        const right = operand(a.b, 'b');
+        if (left === undefined || right === undefined)
+            continue;
+        assertions[key] = a;
+        if (!OPS[a.op](left, right)) {
+            leaks.push({
+                severity: 'error',
+                rule: 'assertion-failed',
+                message: `assertion "${key}" does not hold: ${left.toLocaleString()} ${a.op} ${right.toLocaleString()} is false`,
+                detail: 'The numbers no longer support this conclusion — rewrite it, or fix the inputs.',
+            });
+        }
+    }
+    return { ir: { identifiers, metrics, assertions }, leaks };
 }

package/dist/refresh.js

@@ -77,8 +77,16 @@ export async function refresh(irPath, options) {
     // 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))
+        if (m.derived)
+            continue; // recomputed below, and verified by the compile pass
+        if (Array.isArray(m.value)) {
+            result.skipped.push({ key, reason: 'range values are not re-fetched' });
             continue;
+        }
+        if (!m.source) {
+            result.skipped.push({ key, reason: 'no source to fetch from' });
+            continue;
+        }
         try {
             let value;
             if (m.source.type === 'csv')
@@ -124,38 +132,58 @@ export async function refresh(irPath, options) {
                     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;
+            };
+            // 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') {
-                computed = m.derived.of.reduce((acc, ref) => {
+            if (m.derived.op === 'sum' || m.derived.op === 'avg') {
+                if (!Array.isArray(m.derived.of) || m.derived.of.length === 0) {
+                    fail(`${m.derived.op} needs a non-empty "of" array — not recomputed`);
+                    continue;
+                }
+                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(computed)) {
-                    fail('sum references unknown or non-scalar metrics — not recomputed');
+                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 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));
+                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;
             }
+            if (!Number.isFinite(computed)) {
+                fail('recomputation produced a non-finite value — the ledger is never overwritten with NaN');
+                continue;
+            }
             if (computed !== m.value) {
                 if (!firstBefore.has(key))
                     firstBefore.set(key, m.value);

package/dist/render.js

@@ -1,3 +1,16 @@
+/** How much a reader should trust the number: measured from a source, recomputed, or assumed. */
+export function metricKind(m) {
+    if (m.derived)
+        return 'derived';
+    if (m.source?.type === 'hypothesis')
+        return 'assumption';
+    return 'measured';
+}
+const URL_RE = /https?:\/\/[^\s<>"')]+/g;
+/** Conservative autolinks for markdown receipts — scheme-prefixed URLs only. */
+export function linkifyMd(text) {
+    return text.replace(URL_RE, (url) => `<${url}>`);
+}
 /**
  * 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.
@@ -33,7 +46,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(' · ');
 }
@@ -54,17 +71,32 @@ function markdown(src) {
         .replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>');
 }
 export function render(report, ir) {
+    const used = [];
+    const keysUsed = (k) => {
+        if (ir.metrics[k] && !used.includes(k))
+            used.push(k);
+    };
     const { text: protectedReport, restore } = protectCode(escapeHtml(report));
     const grounded = restore(protectedReport
         .replace(/\{\{m:([\w-]+)\}\}/g, (_, key) => {
+        if (!used.includes(key))
+            used.push(key);
         const m = ir.metrics[key];
-        return `<b class="w" title="${escapeHtml(receipt(m))}">${formatValue(m)}<sup>†</sup></b>`;
+        const assumption = metricKind(m) === 'assumption';
+        // an assumption is a different grade of receipt — the reader sees it without hovering
+        return `<b class="w${assumption ? ' a' : ''}" title="${escapeHtml(receipt(m))}">${formatValue(m)}<sup>${assumption ? '†ᵃ' : '†'}</sup></b>`;
     })
         .replace(/\{\{id:([\w-]+)\}\}/g, (_, key) => `<code>${escapeHtml(ir.identifiers[key])}</code>`)
         .replace(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g, (_, text, evidence) => {
         const keys = evidence.split(',').map((k) => k.trim()).filter(Boolean);
         const receipts = keys
-            .map((k) => `${k} = ${formatValue(ir.metrics[k])} (${receipt(ir.metrics[k])})`)
+            .map((k) => {
+            const a = ir.assertions[k];
+            if (a)
+                return `${k} = assertion (${a.a} ${a.op} ${a.b} — holds)`;
+            keysUsed(k);
+            return `${k} = ${formatValue(ir.metrics[k])} (${receipt(ir.metrics[k])})`;
+        })
             .join(' | ');
         return `<span class="c" title="${escapeHtml(receipts)}">${text.trim()}<sup>‡</sup></span>`;
     })
@@ -75,10 +107,23 @@ export function render(report, ir) {
   @media(prefers-color-scheme:dark){body{background:#111;color:#ddd}code{background:#222}}
   h1,h2,h3{line-height:1.3}
   .w{border-bottom:2px solid #4a9;cursor:help;font-weight:600}
+  .w.a{border-bottom-style:dotted}
   .c{border-bottom:2px dotted #4a9;cursor:help}
   code{background:#eee;padding:1px 5px;border-radius:4px;font-size:.9em}
   sup{font-size:.65em;color:#4a9}
 </style>
 <body>${markdown(grounded)}
-<hr><p style="color:#888;font-size:.85em">Compiled by watertight — every underlined figure carries its receipt (hover to see it).</p>`;
+<hr><h3>Receipts (${used.length} metrics)</h3>
+<ol style="font-size:.9em">
+${used
+        .map((key) => {
+        const m = ir.metrics[key];
+        const kind = metricKind(m);
+        const tag = kind === 'assumption' ? ' <em>(assumption — not measured)</em>' : '';
+        const line = escapeHtml(receipt(m)).replace(/https?:\/\/[^\s<>"')]+/g, (url) => `<a href="${url}">${url}</a>`);
+        return `<li><b>${escapeHtml(key)}</b> = ${formatValue(m)}${tag}<br><span style="color:#888">${line}</span></li>`;
+    })
+        .join('\n')}
+</ol>
+<p style="color:#888;font-size:.85em">Compiled by watertight — every underlined figure carries its receipt (hover to see it).</p>`;
 }

package/dist/renderMd.js

@@ -1,4 +1,4 @@
-import { formatValue, protectCode, receipt } from './render.js';
+import { formatValue, linkifyMd, metricKind, protectCode, receipt } from './render.js';
 const SUPERSCRIPT = '⁰¹²³⁴⁵⁶⁷⁸⁹';
 const sup = (n) => `⁽${String(n).split('').map((d) => SUPERSCRIPT[Number(d)]).join('')}⁾`;
 /**
@@ -14,7 +14,10 @@ export function renderMarkdown(report, ir) {
         .replace(/\{\{m:([\w-]+)\}\}/g, (_, key) => {
         if (!used.includes(key))
             used.push(key);
-        return `**${formatValue(ir.metrics[key])}** ${sup(used.indexOf(key) + 1)}`;
+        const m = ir.metrics[key];
+        const marker = sup(used.indexOf(key) + 1);
+        // an assumption reads differently at a glance: ⁽³ᵃ⁾, and the appendix says why
+        return `**${formatValue(m)}** ${metricKind(m) === 'assumption' ? marker.replace('⁾', 'ᵃ⁾') : marker}`;
     })
         .replace(/\{\{id:([\w-]+)\}\}/g, (_, key) => `\`${ir.identifiers[key]}\``)
         .replace(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g, (_, text, evidence) => `**${text.trim()}** *(evidence: ${evidence.trim()})*`)
@@ -26,12 +29,44 @@ export function renderMarkdown(report, ir) {
                 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')}`;
+    // assertions render their judgement, not just their name — the html reader gets it
+    // on hover, the markdown reader gets it here
+    const resolveOperand = (v) => {
+        if (typeof v === 'number')
+            return v;
+        const accessor = /^([\w-]+)\.(lo|hi)$/.exec(v);
+        const m = ir.metrics[accessor ? accessor[1] : v];
+        if (!m)
+            return undefined;
+        if (accessor && Array.isArray(m.value))
+            return accessor[2] === 'lo' ? m.value[0] : m.value[1];
+        return typeof m.value === 'number' ? m.value : undefined;
+    };
+    const assertionEntries = Object.entries(ir.assertions);
+    const assertionSection = assertionEntries.length === 0
+        ? ''
+        : `\n\n### Assertions (${assertionEntries.length})\n\n${assertionEntries
+            .map(([key, a]) => {
+            const left = resolveOperand(a.a);
+            const right = resolveOperand(a.b);
+            return `- **${key}**: ${left?.toLocaleString() ?? a.a} ${a.op} ${right?.toLocaleString() ?? a.b} — holds`;
+        })
+            .join('\n')}`;
     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, false)}`;
+        const tag = metricKind(m) === 'assumption' ? ' *(assumption — not measured)*' : '';
+        return `${i + 1}. **${key}** = ${formatValue(m)}${definition}${tag}\n   ${linkifyMd(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}${assertionSection}${rawSection}\n`;
 }

package/dist/scan.js

@@ -2,14 +2,15 @@
 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);
+export 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
  * a real one, so none are allowed outside a reference.
  */
-export function scanNakedNumbers(report) {
-    const stripped = report
+/** The prose that remains once every non-statement region is blanked in place. */
+function strippedProse(report) {
+    return report
         .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
@@ -23,8 +24,12 @@ export function scanNakedNumbers(report) {
         .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(/(?<![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
+}
+export function scanNakedNumbers(report) {
+    const stripped = strippedProse(report);
     const leaks = [];
     for (const m of stripped.matchAll(/\d[\d,.]*\s*(%p?|[가-힣]{1,2})?/g)) {
         const token = m[0].trim().replace(/[.,]+$/, '');
@@ -41,7 +46,7 @@ export function scanNakedNumbers(report) {
     return leaks;
 }
 /** Every reference in the narrative must resolve; a dangling one is authoring drift. */
-export function scanRefs(rawReport, metricKeys, idKeys) {
+export function scanRefs(rawReport, metricKeys, idKeys, assertionKeys = new Set()) {
     const leaks = [];
     const report = blankCode(rawReport);
     for (const m of report.matchAll(/\{\{claim:([^|}]*)\|\s*evidence:([^}]*)\}\}/g)) {
@@ -58,7 +63,7 @@ export function scanRefs(rawReport, metricKeys, idKeys) {
             });
         }
         for (const key of keys) {
-            if (!metricKeys.has(key)) {
+            if (!metricKeys.has(key) && !assertionKeys.has(key)) {
                 leaks.push({ severity: 'error', rule: 'unknown-ref', line, message: `claim "${text.trim()}" cites unknown metric "${key}"` });
             }
         }
@@ -107,3 +112,27 @@ export function scanMarkers(rawReport) {
     }
     return leaks;
 }
+// Narrow on purpose: a false worded-number on 배송 or 건물 costs more trust than a
+// missed 수사 표현. Longest alternatives first; boundaries block compound words.
+// "한 번" is far more often rhetoric ("한 번 더", "한 번에") than a count — excluded;
+// "두 번" and "몇 번" stay in
+const WORDED_KO_COUNTED = /(?<![가-힣])((두|세|네|다섯|여섯|일곱|여덟|아홉|열|몇)\s?(배|건|명|번|곳|개)|한\s?(배|건|명|곳|개))(?![가-힣])/g;
+const WORDED_KO_STANDALONE = /(?<![가-힣])(절반|과반|대다수|수십만|수백만|수천만|수억|수십|수백|수천|수만)(\s?(배|건|명|번|곳|개|원|회))?(?![가-힣])/g;
+const WORDED_EN = /\b(doubled?|tripled?|halved)(?![\w-])|\b(half of|a million|millions of|thousands of|dozens of)\b/gi;
+/** Quantities written in words — the digit scanner cannot see them, but a reader does. */
+export function scanWordedNumbers(report) {
+    const stripped = strippedProse(report);
+    const leaks = [];
+    for (const re of [WORDED_KO_COUNTED, WORDED_KO_STANDALONE, WORDED_EN]) {
+        for (const m of stripped.matchAll(re)) {
+            leaks.push({
+                severity: 'warn',
+                rule: 'worded-number',
+                line: lineAt(stripped, m.index),
+                message: `"${m[0].trim()}" is a quantity in words — no receipt can bind to it`,
+                detail: 'If it has a basis, state it as {{m:…}} or a derived metric; if it is rhetoric, mark it {{raw:…}}.',
+            });
+        }
+    }
+    return leaks.sort((x, y) => (x.line ?? 0) - (y.line ?? 0));
+}

package/package.json

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