@rudra-js/attested 0.0.0 → 0.4.0

package/src/numerals.ts

@@ -0,0 +1,231 @@
+// Everything here is string work. No float ever holds a value, so a twenty-digit
+// order number compares exactly.
+
+import { stripInvisible, stripMarks } from './hidden.js';
+
+/** A dot or a comma. Either mark is a decimal point in one locale and grouping in another. */
+const AMBIGUOUS = '.,';
+/** The Arabic decimal separator, which is never grouping. */
+const DECIMAL_ONLY = '\u066b';
+/** Marks that are only ever grouping: Arabic thousands, the space family, the apostrophe. */
+const GROUPING_ONLY = '\u066c\u0020\u00a0\u2007\u2008\u2009\u202f\u0027\u2019';
+
+const SEPARATORS = AMBIGUOUS + DECIMAL_ONLY + GROUPING_ONLY;
+
+const RUN = `\\p{Nd}+(?:[${SEPARATORS}]\\p{Nd}+)*`;
+/** Marks that multiply the digits in front of them: 万 億 兆, and the k/M/B of English copy. */
+const MAGNITUDE = '(?:[十百千万萬億亿兆]|[kKMB](?!\\p{L}))';
+/** Numeric characters that are not decimal digits: ½ ² ② Ⅲ. */
+const OTHER_NUMERAL = '[\\p{No}\\p{Nl}]+';
+
+const SCAN = new RegExp(`${RUN}${MAGNITUDE}|${RUN}|${OTHER_NUMERAL}`, 'gu');
+const LOOSE = new RegExp(`[${GROUPING_ONLY}]`, 'u');
+
+const IS_DIGIT = /^\p{Nd}$/u;
+const STARTS_DIGIT = /^\p{Nd}/u;
+const ENDS_DIGIT = /\p{Nd}$/u;
+
+export interface Numeral {
+  /** The run exactly as it appears in the text. */
+  token: string;
+  /** Every reading of that run, canonical. Empty when the layer cannot read the run. */
+  forms: string[];
+  /** `digits` is a run this layer reads. The other two it cannot read at all. */
+  kind: 'digits' | 'magnitude' | 'other-numeral';
+}
+
+const zeros = new Map<number, number>();
+
+/**
+ * Unicode writes decimal digits in complete sets of ten, and adjacent sets abut, so
+ * the start of a maximal run of digit code points is a zero and the offset into that
+ * run, modulo ten, is the value. Walking back without that modulo reads every digit
+ * of the second and later sets in the maths block as a nine.
+ */
+function digitValue(char: string): number {
+  const code = char.codePointAt(0) ?? 0;
+
+  let zero = zeros.get(code);
+  if (zero === undefined) {
+    zero = code;
+    while (zero > 0 && IS_DIGIT.test(String.fromCodePoint(zero - 1))) zero -= 1;
+    zeros.set(code, zero);
+  }
+
+  return (code - zero) % 10;
+}
+
+function toAscii(token: string): string {
+  let out = '';
+  for (const char of token) {
+    out += SEPARATORS.includes(char) ? char : String(digitValue(char));
+  }
+  return out;
+}
+
+/** Strips the zeros that carry no value, so 39.00 and 39 are one string. */
+function canonical(whole: string, fraction: string): string {
+  let start = 0;
+  while (start < whole.length - 1 && whole[start] === '0') start += 1;
+
+  let end = fraction.length;
+  while (end > 0 && fraction[end - 1] === '0') end -= 1;
+
+  const head = whole.slice(start);
+  const tail = fraction.slice(0, end);
+  return tail.length === 0 ? head : `${head}.${tail}`;
+}
+
+/** Whether these runs read as one grouped whole number: 12,345,678 or 1,29,999. */
+function isGrouping(groups: string[]): boolean {
+  if (groups.length === 1) return true;
+  if ((groups[groups.length - 1] ?? '').length !== 3) return false;
+
+  let three = true;
+  let two = true;
+  for (let index = 1; index < groups.length - 1; index += 1) {
+    const size = (groups[index] ?? '').length;
+    if (size !== 3) three = false;
+    if (size !== 2) two = false;
+  }
+
+  const lead = (groups[0] ?? '').length;
+  if (three) return lead >= 1 && lead <= 3;
+  // 1,29,999 — the Indian grouping, two digits at a time above the last three.
+  if (two) return lead >= 1 && lead <= 2;
+  return false;
+}
+
+/** Whether every mark is the same one, and every one of them can be grouping. */
+function allGrouping(separators: string[]): boolean {
+  for (const separator of separators) {
+    if (separator !== separators[0]) return false;
+    if (DECIMAL_ONLY.includes(separator)) return false;
+  }
+  return true;
+}
+
+/** `1,299` is 1299 in London and in Berlin. `1234,567` is a decimal in both. */
+function formsOf(token: string): string[] {
+  const ascii = toAscii(token);
+
+  const groups: string[] = [];
+  const separators: string[] = [];
+  let current = '';
+  for (const char of ascii) {
+    if (SEPARATORS.includes(char)) {
+      groups.push(current);
+      separators.push(char);
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+  groups.push(current);
+
+  if (separators.length === 0) return [canonical(groups[0] ?? '', '')];
+
+  const forms: string[] = [];
+  if (allGrouping(separators) && isGrouping(groups)) forms.push(canonical(groups.join(''), ''));
+
+  const whole = groups.slice(0, -1);
+  const leading = separators.slice(0, -1);
+  const point = separators[separators.length - 1] ?? '';
+  const fraction = groups[groups.length - 1] ?? '';
+
+  // One dot or comma with exactly three digits behind it is grouping wherever it is
+  // written, so `4.800` is four thousand eight hundred and never the rating 4.8.
+  const groupingWins = forms.length > 0 && leading.length === 0 && fraction.length === 3;
+
+  if (
+    !groupingWins &&
+    !GROUPING_ONLY.includes(point) &&
+    allGrouping(leading) &&
+    leading[0] !== point &&
+    isGrouping(whole)
+  ) {
+    forms.push(canonical(whole.join(''), fraction));
+  }
+
+  return forms;
+}
+
+function collect(found: Numeral[], token: string): void {
+  if (!STARTS_DIGIT.test(token)) {
+    found.push({ token, forms: [], kind: 'other-numeral' });
+    return;
+  }
+  if (!ENDS_DIGIT.test(token)) {
+    found.push({ token, forms: [], kind: 'magnitude' });
+    return;
+  }
+
+  const forms = formsOf(token);
+  if (forms.length > 0) {
+    found.push({ token, forms, kind: 'digits' });
+    return;
+  }
+
+  // `8 10 12` is three numbers, not one badly grouped one.
+  if (LOOSE.test(token)) {
+    for (const part of token.split(LOOSE)) {
+      if (part.length > 0) collect(found, part);
+    }
+    return;
+  }
+
+  // No locale reads `24.12.2026` as a number, so only a fact written the same way
+  // stands behind it. The raw run carries a mark, and a reading never does, so it
+  // can never be mistaken for one.
+  found.push({ token, forms: [toAscii(token)], kind: 'digits' });
+}
+
+export function numeralsIn(text: string): Numeral[] {
+  const found: Numeral[] = [];
+  for (const match of stripMarks(stripInvisible(text)).matchAll(SCAN)) collect(found, match[0]);
+  return found;
+}
+
+/** A whole fact in exponent notation and nothing else, so expanding it swallows no prose. */
+const BARE_EXPONENT = /^[+-]?\d+(?:\.\d+)?[eE][+-]?\d+$/;
+
+/** `String(1e21)` is `1e+21`, which reads as the two numerals 1 and 21. Lay the same digits out in place. */
+function positional(written: string): string {
+  const marker = written.search(/[eE]/);
+  if (marker < 0) return written;
+
+  const power = Number(written.slice(marker + 1));
+  // The sign never reaches a numeral, so dropping it here mints no digit the host lacks.
+  const body = written.slice(0, marker).replace(/^[+-]/, '');
+  const point = body.indexOf('.');
+  const digits = point < 0 ? body : body.slice(0, point) + body.slice(point + 1);
+  const place = (point < 0 ? body.length : point) + power;
+
+  if (place <= 0) return `0.${'0'.repeat(-place)}${digits}`;
+  if (place >= digits.length) return `${digits}${'0'.repeat(place - digits.length)}`;
+  return `${digits.slice(0, place)}.${digits.slice(place)}`;
+}
+
+/**
+ * A string fact is read as the host typed it, except when the whole of it is a number
+ * in exponent notation: `String`, `JSON.stringify`, a CSV export and an API that writes
+ * 64-bit values as strings all produce that, and none of them is the host choosing digits.
+ */
+function digitsOf(value: string | number | bigint): string {
+  if (typeof value === 'number') return positional(String(value));
+  if (typeof value !== 'string') return String(value);
+
+  const trimmed = value.trim();
+  return BARE_EXPONENT.test(trimmed) ? positional(trimmed) : value;
+}
+
+/** Every reading of every numeral the host stands behind. */
+export function supportedValues(values: readonly (string | number | bigint)[]): Set<string> {
+  const supported = new Set<string>();
+  for (const value of values) {
+    for (const numeral of numeralsIn(digitsOf(value))) {
+      for (const form of numeral.forms) supported.add(form);
+    }
+  }
+  return supported;
+}

package/src/phrases.ts

@@ -0,0 +1,204 @@
+import { stripInvisible, stripMarks } from './hidden.js';
+
+/** Claims with no value behind them. Stored in the form `normalisePhrasing` produces. */
+export const BANNED_PHRASES: readonly string[] = [
+  'cheap',
+  'cheaper',
+  'cheapest',
+  'affordable',
+  'bargain',
+  'great value',
+  'best value',
+  'low price',
+  'lower price',
+  'lowest price',
+  'best price',
+  'price drop',
+  'price dropped',
+  'just dropped',
+  'price cut',
+  'reduced price',
+  'sale',
+  'marked down',
+  'half price',
+  'half off',
+  'discount',
+  'discounted',
+  'clearance',
+  'free delivery',
+  'free shipping',
+  'free postage',
+  'free returns',
+  'ships free',
+  'fast delivery',
+  'next day',
+  'same day',
+  'overnight delivery',
+  'arrives tomorrow',
+  'delivered tomorrow',
+  'by tomorrow',
+  'in stock',
+  'out of stock',
+  'low stock',
+  'limited stock',
+  'running low',
+  'running out',
+  'back in stock',
+  'restocked',
+  'sold out',
+  'selling out',
+  'almost sold out',
+  'nearly sold out',
+  'selling fast',
+  'going fast',
+  'going quick',
+  'flying off',
+  'while stocks last',
+  'almost gone',
+  'nearly gone',
+  'few left',
+  'last few',
+  'last chance',
+  'limited time',
+  'today only',
+  'ends soon',
+  'hurry',
+  'act fast',
+  'do not miss',
+  "don't miss",
+  'best seller',
+  'best selling',
+  'bestseller',
+  'bestselling',
+  'most popular',
+  'popular pick',
+  'top pick',
+  'top rated',
+  'highly rated',
+  'highest rated',
+  'rated highest',
+  'best rated',
+  'five star',
+  'star rating',
+  'customer favourite',
+  'customer favorite',
+  'money back',
+];
+
+/**
+ * Letters that render as a Latin letter but are not one. Folded so a Cyrillic о in
+ * "in stоck" cannot walk a claim past its own entry on the list. Both the text and
+ * the phrase are folded, so a genuine Cyrillic phrase still matches itself.
+ */
+const CONFUSABLES: Record<string, string> = {
+  а: 'a',
+  в: 'b',
+  е: 'e',
+  к: 'k',
+  м: 'm',
+  н: 'h',
+  о: 'o',
+  р: 'p',
+  с: 'c',
+  т: 't',
+  х: 'x',
+  у: 'y',
+  ѕ: 's',
+  і: 'i',
+  ј: 'j',
+  ԁ: 'd',
+  һ: 'h',
+  ӏ: 'l',
+  α: 'a',
+  ε: 'e',
+  ι: 'i',
+  κ: 'k',
+  ν: 'v',
+  ο: 'o',
+  ρ: 'p',
+  τ: 't',
+  υ: 'u',
+  χ: 'x',
+  ϲ: 'c',
+};
+
+/** A run of whitespace holding one of these is a break the shopper sees. */
+const LINE_BREAK = /[\n\v\f\r\u0085\u2028\u2029]/;
+
+/** One shape for text and phrases, so a hyphen or a stray mark cannot hide a claim. */
+export function normalisePhrasing(text: string): string {
+  // Marks come off after composition, so an accented e keeps its accent while an
+  // overline, which composes with nothing, does not hide `free` from its own entry.
+  const lowered = stripMarks(stripInvisible(text).normalize('NFKC').toLowerCase().normalize('NFC'));
+
+  let folded = '';
+  for (const char of lowered) folded += CONFUSABLES[char] ?? char;
+
+  // A line break survives as itself. Matching reads straight through it, and only
+  // the allowance in verify.ts cares, because it will not forgive across a break.
+  return folded
+    .replace(/[\u2018\u2019]/g, "'")
+    .replace(/[-_\u2010-\u2015]+/g, ' ')
+    .replace(/\s+/g, (run) => (LINE_BREAK.test(run) ? '\n' : ' '))
+    .trim();
+}
+
+const ASCII_WORD = /[a-z0-9]/;
+
+function isGlued(char: string | undefined): boolean {
+  return char !== undefined && ASCII_WORD.test(char);
+}
+
+export interface Span {
+  start: number;
+  /** The last character of the match, not one past it. */
+  end: number;
+}
+
+/** Both arguments must already be normalised. Spans index the text passed in. */
+// The word-gap rule only guards an ASCII edge, so `cheap` misses `cheapskate`
+// while a Japanese phrase — which has no word gaps to find — still matches.
+export function phraseSpans(text: string, phrase: string): Span[] {
+  // Matching runs with every space dropped, because 送料 無料 is 送料無料 to anyone
+  // and a space is free. `spots` carries each character back to where it really sat,
+  // so the word-gap guard still reads the neighbours the shopper sees.
+  const tight: string[] = [];
+  const spots: number[] = [];
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index] ?? '';
+    // A line break reads like a space here, so a claim split over two lines is caught.
+    if (char === ' ' || char === '\n') continue;
+    tight.push(char);
+    spots.push(index);
+  }
+
+  const spans: Span[] = [];
+  const needle = phrase.replaceAll(' ', '').replaceAll('\n', '');
+  if (needle.length === 0) return spans;
+
+  const guardStart = ASCII_WORD.test(needle[0] ?? '');
+  const guardEnd = ASCII_WORD.test(needle[needle.length - 1] ?? '');
+  const haystack = tight.join('');
+
+  let from = 0;
+  for (;;) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) return spans;
+
+    const start = spots[at] ?? 0;
+    const end = spots[at + needle.length - 1] ?? 0;
+    const next = text[end + 1];
+    // A trailing s is a plural, not a different word: `discount` catches `discounts`.
+    const plural = next === 's' && !isGlued(text[end + 2]);
+
+    const before = guardStart && isGlued(text[start - 1]);
+    const after = guardEnd && isGlued(next) && !plural;
+    if (!before && !after) spans.push({ start, end });
+
+    from = at + 1;
+  }
+}
+
+export function phraseIn(text: string, phrase: string): boolean {
+  return phraseSpans(text, phrase).length > 0;
+}

package/src/verify.ts

@@ -0,0 +1,193 @@
+import { numeralsIn, supportedValues, type Numeral } from './numerals.js';
+import { BANNED_PHRASES, normalisePhrasing, phraseSpans, type Span } from './phrases.js';
+
+// Two layers, reported apart, because only one of them is a proof.
+
+export type Layer = 'quantity' | 'wording';
+
+export interface Finding {
+  layer: Layer;
+  /** The numeral as the text wrote it, or the phrase as the denylist holds it. */
+  token: string;
+  /** Audit evidence. Names the layer and the token. */
+  reason: string;
+}
+
+export interface LayerReport {
+  supported: boolean;
+  /**
+   * What this layer's verdict is worth. `proof` means every numeral in the text is
+   * a value the host supplied — not that the sentence around it is true.
+   */
+  strength: 'proof' | 'best-effort';
+  /** Numerals found, or phrases screened against. Zero means nothing was checked. */
+  checked: number;
+  /** One per distinct token that failed. */
+  findings: Finding[];
+}
+
+export interface VerifyResult {
+  /** True when both layers are. */
+  supported: boolean;
+  quantity: LayerReport;
+  wording: LayerReport;
+}
+
+export interface Facts {
+  /** In any shape they are written: `39`, `'$1,299.00'`, `'4,8'`. Every numeral in one counts. */
+  values: readonly (string | number | bigint)[];
+  /** Claims to ban on top of the built-in English list, for the host's own language. */
+  bannedPhrases?: readonly string[];
+  /** Wording the shop stands behind. A banned claim inside one of these is not reported. */
+  allowedPhrases?: readonly string[];
+}
+
+export interface FieldResult {
+  field: string;
+  result: VerifyResult;
+}
+
+export interface BatchResult {
+  /** True when every field is, and when the fields read as one carry no banned claim. */
+  supported: boolean;
+  fields: FieldResult[];
+  /** The wording layer over every field joined, so a phrase split across two fields still reads. */
+  acrossFields: LayerReport;
+}
+
+function phrasesOf(facts: Facts): string[] {
+  const phrases = new Set<string>(BANNED_PHRASES);
+
+  for (const phrase of facts.bannedPhrases ?? []) {
+    const normalised = normalisePhrasing(phrase);
+    if (normalised.length > 0) phrases.add(normalised);
+  }
+  return [...phrases];
+}
+
+function allowedOf(facts: Facts): string[] {
+  const allowed: string[] = [];
+  for (const phrase of facts.allowedPhrases ?? []) {
+    const normalised = normalisePhrasing(phrase);
+    if (normalised.length > 0) allowed.push(normalised);
+  }
+  return allowed;
+}
+
+function reasonFor(numeral: Numeral): string {
+  if (numeral.kind === 'other-numeral') {
+    return `quantity: "${numeral.token}" is a numeric character this layer cannot read, so no fact can back it`;
+  }
+  if (numeral.kind === 'magnitude') {
+    return `quantity: "${numeral.token}" ends in a magnitude mark this layer cannot read, so the value it shows is unchecked`;
+  }
+  return `quantity: "${numeral.token}" is not a value the supplied facts carry`;
+}
+
+function checkQuantities(text: string, supported: Set<string>): LayerReport {
+  const numerals = numeralsIn(text);
+  const findings: Finding[] = [];
+  const reported = new Set<string>();
+
+  for (const numeral of numerals) {
+    let backed = false;
+    for (const form of numeral.forms) {
+      if (supported.has(form)) backed = true;
+    }
+    if (backed || reported.has(numeral.token)) continue;
+
+    reported.add(numeral.token);
+    findings.push({ layer: 'quantity', token: numeral.token, reason: reasonFor(numeral) });
+  }
+
+  return {
+    supported: findings.length === 0,
+    strength: 'proof',
+    checked: numerals.length,
+    findings,
+  };
+}
+
+function standsBehind(allowed: Span[], hit: Span): boolean {
+  for (const span of allowed) {
+    if (span.start <= hit.start && hit.end <= span.end) return true;
+  }
+  return false;
+}
+
+function checkWording(text: string, phrases: string[], allowed: string[]): LayerReport {
+  const normalised = normalisePhrasing(text);
+
+  const spans: Span[] = [];
+  for (const phrase of allowed) {
+    for (const span of phraseSpans(normalised, phrase)) {
+      // The denylist reads through a break and the allowance does not, so both rules
+      // err toward reporting. A model that puts the negation in one block and the
+      // claim in another has written two things the shopper reads apart.
+      if (!normalised.slice(span.start, span.end + 1).includes('\n')) spans.push(span);
+    }
+  }
+
+  const findings: Finding[] = [];
+  for (const phrase of phrases) {
+    // One hit inside allowed wording is forgiven; the same phrase elsewhere is not.
+    let caught = false;
+    for (const hit of phraseSpans(normalised, phrase)) {
+      if (!standsBehind(spans, hit)) caught = true;
+    }
+    if (!caught) continue;
+
+    findings.push({
+      layer: 'wording',
+      token: phrase,
+      reason: `wording: "${phrase}" is a claim with no value to check, caught by a best-effort denylist`,
+    });
+  }
+
+  return {
+    supported: findings.length === 0,
+    strength: 'best-effort',
+    checked: phrases.length,
+    findings,
+  };
+}
+
+function check(
+  text: string,
+  supported: Set<string>,
+  phrases: string[],
+  allowed: string[],
+): VerifyResult {
+  const quantity = checkQuantities(text, supported);
+  const wording = checkWording(text, phrases, allowed);
+  return { supported: quantity.supported && wording.supported, quantity, wording };
+}
+
+/** Whether one piece of model-written text stands on the facts the host supplied. */
+export function verify(text: string, facts: Facts): VerifyResult {
+  return check(text, supportedValues(facts.values), phrasesOf(facts), allowedOf(facts));
+}
+
+/** The same check over every field of one product, without repeating the facts. */
+export function verifyFields(fields: Record<string, string>, facts: Facts): BatchResult {
+  const supported = supportedValues(facts.values);
+  const phrases = phrasesOf(facts);
+  const allowed = allowedOf(facts);
+
+  const results: FieldResult[] = [];
+  const written: string[] = [];
+  let allSupported = true;
+  for (const field of Object.keys(fields)) {
+    const text = fields[field] ?? '';
+    const result = check(text, supported, phrases, allowed);
+    if (!result.supported) allSupported = false;
+    results.push({ field, result });
+    written.push(text);
+  }
+
+  // A card renders its fields next to each other, so `Free` and `delivery on every
+  // order` are one sentence to a shopper even though neither field carries one.
+  const acrossFields = checkWording(written.join(' '), phrases, allowed);
+
+  return { supported: allSupported && acrossFields.supported, fields: results, acrossFields };
+}