watertight 0.7.0 → 0.8.0

package/README.md

@@ -98,6 +98,20 @@ do, so hand-computed values don't have to masquerade as measured ones:
 }
 ```
 
+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
@@ -119,7 +133,7 @@ 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}}.
 ```
@@ -135,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
 ```
 
@@ -182,6 +197,13 @@ figure shows its receipt.
 | `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>
 

package/SKILL.md

@@ -57,12 +57,25 @@ number yet.
   "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.
+  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:
@@ -84,6 +97,9 @@ 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

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;
@@ -22,6 +23,8 @@ Options
                      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)
@@ -50,6 +53,7 @@ function parseArgs(argv) {
     let format = 'html';
     let maxAgeDays;
     let maxRaw;
+    let strict = false;
     let help = false;
     let version = false;
     for (let i = 0; i < args.length; i++) {
@@ -73,6 +77,8 @@ 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) {
@@ -97,7 +103,7 @@ function parseArgs(argv) {
     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, maxRaw };
+    return { command, positional, out, check, json, help, version, dryRun, allowCommands, format, fetchersPath, maxAgeDays, maxRaw, strict };
 }
 async function exists(path) {
     try {
@@ -167,13 +173,20 @@ async function main() {
             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 changes just cascade.
+            // 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, skipped: r.skipped, errors: r.errors }, null, 2));
-                process.exit(mismatches.length > 0 || r.errors.length > 0 ? 1 : 0);
+                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()}`);
             }
@@ -181,12 +194,12 @@ async function main() {
                 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`);
+            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} skipped) — nothing written`);
+            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
@@ -218,7 +231,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, { format: opts.format, maxAgeDays: opts.maxAgeDays, maxRaw: opts.maxRaw });
+    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) {
@@ -228,10 +241,18 @@ async function main() {
         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}`);
             }
@@ -246,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,11 +27,14 @@ 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,
-        raw: [...report.matchAll(/\{\{raw:/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
@@ -45,9 +48,56 @@ export async function compile(reportPath, irPath, options = 'html') {
     }
     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

@@ -28,7 +28,7 @@ export function parseIr(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+)?$)/;
+    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())) {
@@ -84,6 +84,14 @@ export function parseIr(raw) {
                 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) {
@@ -165,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')
@@ -136,6 +144,10 @@ export async function refresh(irPath, options) {
             const rounded = (v) => Number(v.toFixed(authorDecimals));
             let computed;
             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);
@@ -168,6 +180,10 @@ export async function refresh(irPath, options) {
                 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.
@@ -58,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>`;
     })
@@ -79,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()})*`)
@@ -34,12 +37,36 @@ export function renderMarkdown(report, ir) {
         : `\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}${rawSection}\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
@@ -26,6 +27,9 @@ export function scanNakedNumbers(report) {
         .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(/[.,]+$/, '');
@@ -42,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)) {
@@ -59,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}"` });
             }
         }
@@ -108,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.7.0",
+  "version": "0.8.0",
   "description": "Reports that hold water — every number carries its receipt, and ungrounded claims fail the build.",
   "type": "module",
   "bin": {