@rudra-js/attested 0.0.0 → 0.5.0

package/dist/verify.js

@@ -0,0 +1,153 @@
+import { numeralsIn, supportedValues } from './numerals.js';
+import { BANNED_PHRASES, indexPhrasing, normalisePhrasing, spansIn } from './phrases.js';
+/**
+ * One reading per fact list, keyed on the list itself, because core hands `verify` the
+ * same array again for every field it screens. Held against a copy of what the list
+ * carried: `readonly` on `Facts.values` is a compile-time view of one reference, and a
+ * host holding the array can write to it between two calls.
+ */
+const readings = new WeakMap();
+function unchanged(held, values) {
+    if (held.length !== values.length)
+        return false;
+    for (let i = 0; i < held.length; i += 1) {
+        if (held[i] !== values[i])
+            return false;
+    }
+    return true;
+}
+function valuesOf(facts) {
+    const values = facts.values;
+    // A caller outside TypeScript can pass something with no identity to key on.
+    if (!Array.isArray(values))
+        return supportedValues(values);
+    const read = readings.get(values);
+    if (read !== undefined && unchanged(read.held, values))
+        return read.supported;
+    const supported = supportedValues(values);
+    readings.set(values, { held: [...values], supported });
+    return supported;
+}
+function phrasesOf(facts) {
+    const phrases = new Set(BANNED_PHRASES);
+    for (const phrase of facts.bannedPhrases ?? []) {
+        const normalised = normalisePhrasing(phrase);
+        if (normalised.length > 0)
+            phrases.add(normalised);
+    }
+    return [...phrases];
+}
+function allowedOf(facts) {
+    const allowed = [];
+    for (const phrase of facts.allowedPhrases ?? []) {
+        const normalised = normalisePhrasing(phrase);
+        if (normalised.length > 0)
+            allowed.push(normalised);
+    }
+    return allowed;
+}
+function reasonFor(numeral) {
+    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, supported) {
+    const numerals = numeralsIn(text);
+    const findings = [];
+    const reported = new Set();
+    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, hit) {
+    for (const span of allowed) {
+        if (span.start <= hit.start && hit.end <= span.end)
+            return true;
+    }
+    return false;
+}
+function checkWording(text, phrases, allowed) {
+    const normalised = normalisePhrasing(text);
+    const indexed = indexPhrasing(normalised);
+    const spans = [];
+    for (const phrase of allowed) {
+        for (const span of spansIn(indexed, 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 = [];
+    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 spansIn(indexed, 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, supported, phrases, allowed) {
+    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, facts) {
+    return check(text, valuesOf(facts), phrasesOf(facts), allowedOf(facts));
+}
+/** The same check over every field of one product, without repeating the facts. */
+export function verifyFields(fields, facts) {
+    const supported = valuesOf(facts);
+    const phrases = phrasesOf(facts);
+    const allowed = allowedOf(facts);
+    const results = [];
+    const written = [];
+    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 };
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,14 +1,50 @@
 {
   "name": "@rudra-js/attested",
-  "version": "0.0.0",
-  "description": "Placeholder so a trusted publisher can be configured. Use 0.4.0 or later.",
+  "version": "0.5.0",
+  "description": "Checks model-written product copy against the facts a shop stands behind",
+  "keywords": [
+    "llm",
+    "hallucination",
+    "grounding",
+    "verification",
+    "ecommerce",
+    "guardrails"
+  ],
   "license": "MIT",
   "author": "Clive Dsouza",
   "homepage": "https://github.com/clivedsouza1010/rudra-js/tree/main/packages/attested#readme",
+  "bugs": {
+    "url": "https://github.com/clivedsouza1010/rudra-js/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/clivedsouza1010/rudra-js.git",
     "directory": "packages/attested"
   },
-  "private": false
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/hidden.ts

@@ -0,0 +1,26 @@
+// One definition for both layers. It lived in two files, and that is why widening it
+// for the quantity layer left the wording layer open twice running.
+
+/**
+ * Characters that render as nothing: format characters, default-ignorable code points
+ * and the controls. Cf and Default_Ignorable each hold characters the other does not.
+ */
+const INVISIBLE = /[\p{Cf}\p{Default_Ignorable_Code_Point}\p{Cc}]/gu;
+
+/** The controls that do take room. Deleting these would read `Only 2\n3 left` as 23. */
+const SPACING = /[\t\n\v\f\r\u0085]/;
+
+/**
+ * Marks that hang on the character before them instead of taking a column of their own,
+ * so `4<U+0305>9` reads as 49. Spacing marks (Mc) are not here: a Devanagari matra is
+ * a visible gap between two digits and separates them for a reader.
+ */
+const MARKS = /[\p{Mn}\p{Me}]/gu;
+
+export function stripInvisible(text: string): string {
+  return text.replace(INVISIBLE, (char) => (SPACING.test(char) ? char : ''));
+}
+
+export function stripMarks(text: string): string {
+  return text.replace(MARKS, '');
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// @rudra-js/attested — the guarantee that a model cannot lie about a product.
+
+export {
+  verify,
+  verifyFields,
+  type BatchResult,
+  type Facts,
+  type FieldResult,
+  type Finding,
+  type Layer,
+  type LayerReport,
+  type VerifyResult,
+} from './verify.js';
+
+export { BANNED_PHRASES } from './phrases.js';

package/src/numerals.ts

@@ -0,0 +1,247 @@
+// 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+$/;
+
+/**
+ * The widest digit run a fact may lay out to. Every finite JS number fits — 5e-324 is
+ * the longest, at 326 characters — and nothing a shop sells is wider than that.
+ */
+const DIGIT_LIMIT = 1000;
+
+/**
+ * `String(1e21)` is `1e+21`, which reads as the two numerals 1 and 21. Lay the same digits
+ * out in place. Empty past the limit: `1e2000000000` is twelve characters and no product
+ * fact, and laying it out builds a run long enough to take the process down with it.
+ */
+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) {
+    if (digits.length - place > DIGIT_LIMIT) return '';
+    return `0.${'0'.repeat(-place)}${digits}`;
+  }
+  if (place >= digits.length) {
+    if (place > DIGIT_LIMIT) return '';
+    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;
+}