neuralos 3.9.6 → 3.10.1

package/README.md

@@ -54,7 +54,72 @@ neuralos info
 
 ## Platforms
 
-Bundled engines: macOS arm64/x64, Linux x64/arm64 (glibc), Windows x64.
+## Structured extraction (same API as Python)
+
+Declare the record, hand over messy text, get typed fields back. The API is the
+Node mirror of the Python `needle.extract` — same semantics, same validation:
+
+```js
+const { extract, Field } = require('neuralos');
+
+const invoice = extract('Invoice INV-1042 issued 12 May 2024, total 49.62 USD.', {
+  name: 'Invoice',                       // named schema = the engine's call target
+  parameters: {
+    type: 'object',
+    properties: {
+      invoice_no: Field({ type: 'string' }),
+      issue_date: Field({ type: 'string', format: 'date' }),
+      total:      Field({ type: 'number', ge: 0 }),
+    },
+    required: ['invoice_no', 'total'],
+  },
+});
+// { invoice_no: 'INV-1042', issue_date: '2024-05-12', total: 49.62 }
+```
+
+With `strict: true` (the default) a value the input does not license raises
+`ExtractionValidationError` instead of being returned silently — a date whose
+year is not written in the text, an invented number, or a negated request:
+
+```js
+const { extract, ExtractionValidationError } = require('neuralos');
+try {
+  extract('Invoice with no date mentioned', { name: 'Invoice', parameters: { /* … */ } });
+} catch (err) {
+  if (err instanceof ExtractionValidationError) console.error(err.message);
+}
+```
+
+Return value: the extracted record, or `null` when the model emits no call.
+Pass `strict: false` to receive unvalidated values.
+
+### CLI
+
+```bash
+neuralos extract --schema invoice.schema.json --text "Invoice INV-7, 3 March 2024, total 12.50"
+neuralos extract --schema invoice.schema.json --text "…" --no-strict
+```
+
+Exits `1` with the grounding message when strict validation fails.
+
+## Feature parity with the Python distribution
+
+| Capability | Python (`pip install neuralos`) | Node (this package) |
+|---|---|---|
+| Tool calling | `Needle().run()` | `new Needle().run()` |
+| Structured extraction | `needle.extract()` | `extract()` |
+| Field constraints | `needle.Field(...)` | `Field(...)` |
+| Grounding validation | `ExtractionValidationError` | `ExtractionValidationError` |
+| Embeddings | `.embed()` | `.embed()` |
+| CLI | `run \| embed \| info` | `run \| extract \| embed \| info` |
+| Engine + weights bundled | wheels | platform packages |
+
+Both distributions are released **at the same version number** from the same
+tag, so `npm view neuralos version` and `pip index versions neuralos` agree.
+
+Bundled engines: macOS arm64/x64, Linux x64/arm64 (glibc), **Windows x64**.
+Other platforms are not packaged — the Python distribution
+(`pip install neuralos`) carries a broader engine matrix.
 Other platforms are not packaged — the Python distribution
 (`pip install neuralos`) carries a broader engine matrix.
 

package/cli.js

@@ -3,19 +3,23 @@
 
 const fs = require('fs');
 const path = require('path');
-const { Needle } = require('./index');
+const { Needle, extract, ExtractionValidationError } = require('./index');
 
 function usage(code = 0) {
   const text = `neuralos ${require('./package.json').version} — offline tool-calling + embeddings engine
 
 Usage:
-  neuralos run   --tools <tools.json> [--impl <impl.js>] [--system <text>]
-                 [--query <text>] [--max-steps <n>] [--max-new-tokens <n>]
-  neuralos embed --text <text>
+  neuralos run     --tools <tools.json> [--impl <impl.js>] [--system <text>]
+                   [--query <text>] [--max-steps <n>] [--max-new-tokens <n>]
+  neuralos extract --schema <schema.json> --text <text> [--system <text>]
+                   [--max-new-tokens <n>] [--no-strict]
+  neuralos embed   --text <text>
   neuralos info
 
-tools.json: array of { name, description, parameters }
-impl.js:    optional module exporting { toolName: (args) => result } functions
+tools.json:  array of { name, description, parameters }
+impl.js:     optional module exporting { toolName: (args) => result } functions
+schema.json: a JSON schema object (the record is the only tool). Prints the
+             extracted record, or exits 1 with the grounding failure.
 `;
   process.stdout.write(text);
   process.exit(code);
@@ -38,6 +42,27 @@ try {
     process.exit(0);
   }
 
+  if (command === 'extract') {
+    const schemaPath = argValue('--schema', argv);
+    const text = argValue('--text', argv);
+    if (!schemaPath || !text) usage(1);
+    const schema = JSON.parse(fs.readFileSync(path.resolve(schemaPath), 'utf8'));
+    const system = argValue('--system', argv) || '';
+    const maxNewTokens = Number(argValue('--max-new-tokens', argv) || 512);
+    const strict = !argv.includes('--no-strict');
+    try {
+      const record = extract(text, schema, { system, maxNewTokens, strict });
+      process.stdout.write(JSON.stringify(record, null, 2) + '\n');
+      process.exit(0);
+    } catch (err) {
+      if (err instanceof ExtractionValidationError) {
+        process.stderr.write(`neuralos: ${err.message}\n`);
+        process.exit(1);
+      }
+      throw err;
+    }
+  }
+
   if (command === 'embed') {
     const text = argValue('--text', argv);
     if (!text) usage(1);

package/engine.js

@@ -22,7 +22,9 @@ const PLATFORM_PACKAGES = {
   'darwin-x64': { pkg: 'neuralos-darwin-x64', lib: 'libneedle3.dylib' },
   'linux-x64-gnu': { pkg: 'neuralos-linux-x64-gnu', lib: 'libneedle3.so' },
   'linux-arm64-gnu': { pkg: 'neuralos-linux-arm64-gnu', lib: 'libneedle3.so' },
-  'win32-x64': { pkg: 'neuralos-win32-x64', lib: 'libneedle3.dll' },
+  // npm blocks "neuralos-win32-x64" as a look-alike name (403 spam
+  // detection), so the Windows payload ships as this package instead.
+  'win32-x64': { pkg: 'neuralos-engine-windows-x64', lib: 'libneedle3.dll' },
 };
 
 function platformKey() {

package/index.js

@@ -17,10 +17,25 @@
  *
  *   const agent = new Needle({ tools: [getWeather] });
  *   console.log(agent.run("What's the weather in Lagos?"));
+ *
+ * Structured extraction (Python parity):
+ *
+ *   const { extract, Field } = require('neuralos');
+ *   const invoice = extract('Invoice INV-7, 12 May 2024, total 49.62', {
+ *     type: 'object',
+ *     properties: {
+ *       invoice_no: Field({ type: 'string' }),
+ *       issue_date: Field({ type: 'string', format: 'date' }),
+ *       total:      Field({ type: 'number', ge: 0 }),
+ *     },
+ *     required: ['invoice_no', 'total'],
+ *   });
  */
 
 const engineLoader = require('./engine');
-const { normalizeTools, tool } = require('./tools');
+const { normalizeTools, tool, Field } = require('./tools');
+const { ExtractionValidationError, sourceYears, groundedNumberPaths,
+        ungroundedPaths, annotateUngrounded, validateExtraction } = require('./validate');
 
 const UNRESET_TURNS = 4;
 
@@ -52,6 +67,7 @@ class Needle {
     this.systemText = withDateFact(system, autoDate);
     this.toolsJson = JSON.stringify(this._schemas);
     this._stateless = !!stateless;
+    this._seenYears = new Set();
     this._turns = 0;
     this._bufferSize = bufferSize;
     this._bind();
@@ -76,7 +92,7 @@ class Needle {
     return this._complete(text, maxNewTokens);
   }
 
-  _complete(text, maxNewTokens, parse = true) {
+  _complete(text, maxNewTokens, parse = true, annotate = true) {
     this._bind();
     const e = engineLoader.engine();
     const buffer = e.allocBuffer(this._bufferSize);
@@ -93,11 +109,15 @@ class Needle {
     } catch (err) {
       throw new Error(`neuralOS: engine returned an unparseable envelope (${err.message})`);
     }
+    for (const year of sourceYears(text || '')) this._seenYears.add(year);
+    if (annotate) {
+      annotateUngrounded(response, this._schemas, this._seenYears, this.systemText, text);
+    }
     return response;
   }
 
   /** Execute tool calls until the model responds. Mirrors Python's run(). */
-  run(query = '', { maxSteps = 8, maxNewTokens = 512 } = {}) {
+  run(query = '', { maxSteps = 8, maxNewTokens = 512, strict = true } = {}) {
     if (this._stateless) this.reset();
     this._countQuery();
     let response = this._complete(query, maxNewTokens);
@@ -106,8 +126,18 @@ class Needle {
       const calls = response.function_calls || [];
       if (response.type !== 'call' || !calls.length) break;
       const results = [];
+      const ungrounded = ungroundedPaths(response);
       for (const call of calls) {
         const name = String(call.name);
+        let fabricated = [...(ungrounded.get(name) || [])].sort();
+        if (strict && fabricated.length) {
+          const grounded = groundedNumberPaths(call.arguments || {}, query, this.systemText);
+          fabricated = fabricated.filter((path) => !grounded.has(path));
+        }
+        if (strict && fabricated.length) {
+          results.push({ error: 'ungrounded ' + fabricated.join(', ') });
+          continue;
+        }
         const fn = this._functions.get(name);
         if (!fn) {
           results.push({ error: 'unknown tool: ' + name });
@@ -120,7 +150,7 @@ class Needle {
         }
       }
       executed.push(...results);
-      response = this._complete(JSON.stringify(results), maxNewTokens, false);
+      response = this._complete(JSON.stringify(results), maxNewTokens, false, false);
       try { response = JSON.parse(response); } catch (_) { /* handled below */ }
       if (typeof response !== 'object' || response === null) {
         throw new Error('neuralOS: engine returned an unparseable envelope');
@@ -141,16 +171,56 @@ class Needle {
     return e.decodeFloats(out, dim);
   }
 
+  /** One-shot structured extraction against this agent's system prompt. */
+  extract(text, schema, { maxNewTokens = 512, strict = true } = {}) {
+    return extract(text, schema, {
+      system: this.systemText, maxNewTokens, strict, autoDate: false,
+    });
+  }
+
   reset() {
     this._bind();
     engineLoader.engine().reset();
     this._turns = 0;
+    this._seenYears = new Set();
+  }
+
+  close() {
+    this._closed = true;
+  }
+}
+
+/**
+ * One-shot structured extraction — Python-parity semantics:
+ * the record is the only tool, the first call is the answer, and with
+ * strict=true (default) ungrounded values raise ExtractionValidationError
+ * instead of being returned silently.
+ */
+function extract(text, schema, { system = '', maxNewTokens = 512, strict = true,
+                                  autoDate = true } = {}) {
+  const agent = new Needle({ tools: [schema], system, autoDate });
+  let response;
+  try {
+    response = agent._complete(text, maxNewTokens);
+  } finally {
+    agent.close();
   }
+  const calls = (response.function_calls && response.function_calls.length)
+    ? response.function_calls
+    : (response.suppressed_calls || []);
+  if (!calls.length) return null;
+  const arguments_ = calls[0].arguments || {};
+  if (strict) validateExtraction(text, schema, arguments_, response, agent.systemText);
+  return arguments_;
 }
 
 module.exports = {
   Needle,
   tool,
+  Field,
+  extract,
+  ExtractionValidationError,
+  validate: require('./validate'),
   version: require('./package.json').version,
   platformKey: engineLoader.platformKey,
   engineInfo: () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "neuralos",
-  "version": "3.9.6",
-  "description": "neuralOS - automation foundation model for tiny devices: offline tool-calling + embeddings engine for Node.js, weights bundled",
+  "version": "3.10.1",
+  "description": "neuralOS - automation foundation model for tiny devices: offline tool-calling, structured extraction and embeddings for Node.js, weights bundled",
   "main": "index.js",
   "bin": {
     "neuralos": "cli.js"
@@ -9,6 +9,7 @@
   "files": [
     "index.js",
     "engine.js",
+    "validate.js",
     "tools.js",
     "cli.js",
     "test.js",
@@ -40,10 +41,10 @@
     "koffi": "^2.9.0"
   },
   "optionalDependencies": {
-    "neuralos-darwin-arm64": "3.9.6",
-    "neuralos-darwin-x64": "3.9.6",
-    "neuralos-linux-x64-gnu": "3.9.6",
-    "neuralos-linux-arm64-gnu": "3.9.6",
-    "neuralos-win32-x64": "3.9.6"
+    "neuralos-darwin-arm64": "3.10.1",
+    "neuralos-darwin-x64": "3.10.1",
+    "neuralos-linux-x64-gnu": "3.10.1",
+    "neuralos-linux-arm64-gnu": "3.10.1",
+    "neuralos-engine-windows-x64": "3.10.1"
   }
 }

package/tools.js

@@ -28,6 +28,11 @@ function normalizeTools(tools, functions) {
       if (typeof entry.implementation === 'function') {
         functions.set(entry.name, entry.implementation);
       }
+    } else if (entry && typeof entry === 'object') {
+      // An ANONYMOUS schema: the record itself is the only tool (Python parity —
+      // needle._resolve passes plain dicts through unwrapped, which is what
+      // extract() relies on: the engine answers with arguments only).
+      schemas.push(entry);
     } else {
       throw new TypeError(
         'neuralOS: each tool must be a schema object {name, description, parameters, implementation?} ' +
@@ -44,4 +49,41 @@ function tool(schema, fn) {
   return wrapped;
 }
 
-module.exports = { normalizeTools, tool };
+/**
+ * Field — declarative constraints for a schema property, mirroring the Python
+ * `needle.Field`. Build the property, then attach it to your JSON schema:
+ *
+ *   parameters: {
+ *     type: 'object',
+ *     properties: {
+ *       total: Field({ type: 'number', description: 'invoice total', ge: 0 }),
+ *       status: Field({ type: 'string', enum: ['paid', 'unpaid', 'overdue'] }),
+ *     },
+ *     required: ['total'],
+ *   }
+ *
+ * Python parity: ge/le → minimum/maximum, gt/lt → exclusiveMinimum/Maximum,
+ * min_length/max_length → minLength/maxLength, min_items/max_items →
+ * minItems/maxItems, plus enum/const/pattern/format/multipleOf.
+ */
+function Field({ default: defaultValue, description, enum: enum_, const: const_,
+                 ge, le, gt, lt, multiple_of: multipleOf, min_length: minLength,
+                 max_length: maxLength, pattern, format, min_items: minItems,
+                 max_items: maxItems, unique_items: uniqueItems, ...rest } = {}) {
+  const schema = { ...rest };
+  const pairs = [['description', description], ['enum', enum_],
+                 ['minimum', ge], ['maximum', le],
+                 ['exclusiveMinimum', gt], ['exclusiveMaximum', lt],
+                 ['multipleOf', multipleOf], ['minLength', minLength],
+                 ['maxLength', maxLength], ['pattern', pattern], ['format', format],
+                 ['minItems', minItems], ['maxItems', maxItems],
+                 ['uniqueItems', uniqueItems]];
+  for (const [key, value] of pairs) {
+    if (value !== undefined && value !== null) schema[key] = value;
+  }
+  if (const_ !== undefined) schema.const = const_;
+  if (defaultValue !== undefined) schema.default = defaultValue;
+  return schema;
+}
+
+module.exports = { normalizeTools, tool, Field };

package/validate.js

@@ -0,0 +1,263 @@
+/**
+ * Grounding + extraction validation — the Node port of the Python
+ * `needle` validation core (needle/__init__.py), kept behaviour-compatible:
+ *
+ *   * sourceYears()      — years literally written in the input
+ *   * licensedYears()    — those years, plus the system date's year when the
+ *                          input reasons relatively ("tomorrow", "next week")
+ *   * walkGrounding()    — date arguments must carry a licensed year
+ *   * groundedNumberPaths() — numbers a value may carry without being invented
+ *   * annotateUngrounded() — the engine's own fabrication report, re-checked
+ *   * validateExtraction() — strict mode: raise instead of returning
+ *                            ungrounded values silently
+ *
+ * Python raises ExtractionValidationError; so do we.
+ */
+'use strict';
+
+class ExtractionValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ExtractionValidationError';
+  }
+}
+
+const MONTHS =
+  '(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|' +
+  'jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:t(?:ember)?)?|' +
+  'oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)';
+
+// The number after a day+month is its year, unless it is the hour of a time
+// ("5 June 19:30", "June 5 7 pm"): no ISO argument can carry that as a year,
+// so licensing it would reject every date. Year-first numeric dates only
+// (2024-03-15) — a day/month-first date must not mint its leading component.
+const SOURCE_YEAR_PATTERNS = [
+  new RegExp(`\\b\\d{1,2}(?:st|nd|rd|th)?\\s+${MONTHS}[\\s,]+(\\d{1,4})(?![0-9A-Za-z]|:\\d|\\s*[ap]\\.?m\\b)`, 'g'),
+  new RegExp(`\\b${MONTHS}\\s+\\d{1,2}(?:st|nd|rd|th)?\\s*,?\\s+(\\d{1,4})(?![0-9A-Za-z]|:\\d|\\s*[ap]\\.?m\\b)`, 'g'),
+  new RegExp(`\\b${MONTHS}[\\s,]+(\\d{3,4})(?![0-9A-Za-z])`, 'g'),
+  /\byear\s+(\d{1,4})(?![0-9A-Za-z])/g,
+  /(?<![0-9])(\d{4})(?=[-/]\d{1,2}[-/]\d{1,2}(?![0-9]))/g,
+];
+
+const RELATIVE_CUE = new RegExp(
+  '\\b(today|tonight|tomorrow|yesterday|next|this|coming|now|in \\d+ (?:days?|weeks?|months?|years?)|' +
+  'monday|tuesday|wednesday|thursday|friday|saturday|sunday)\\b', 'i');
+
+const NUMBER_TOKEN =
+  /(?<![\w.,])(?:[-+]?\d{1,3}(?:,\d{3})+(?:\.\d+)?|[-+]?\d+(?:\.\d+)?)(?!\d)/g;
+
+const DATE_FACT =
+  /date:\s*\d{4}-\d{2}-\d{2}(?:\s+[A-Za-z]{3})?(?:\s+\d{2}:\d{2})?|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?/g;
+
+/** Years literally written in the text. */
+function sourceYears(text) {
+  const lowered = String(text || '').toLowerCase();
+  const years = new Set();
+  for (const pattern of SOURCE_YEAR_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(lowered)) !== null) {
+      years.add(parseInt(match[1], 10));
+    }
+  }
+  return years;
+}
+
+function relativeCue(text) {
+  return !!text && RELATIVE_CUE.test(String(text));
+}
+
+/** Years a date argument may carry without being fabricated. */
+function licensedYears(seenYears, system, relative = true) {
+  const years = new Set(seenYears || []);
+  if (years.size && system && relative) {
+    for (const year of sourceYears(system)) years.add(year);
+  }
+  return years;
+}
+
+function schemaParameters(schema) {
+  if (schema && typeof schema === 'object' && schema.parameters) return schema.parameters;
+  return schema || {};
+}
+
+function resolveRef(node, root) {
+  const seen = new Set();
+  let current = node;
+  while (current && typeof current === 'object' && current.$ref) {
+    if (seen.has(current.$ref)) break;
+    seen.add(current.$ref);
+    const parts = String(current.$ref).replace(/^#\//, '').split('/');
+    let target = root;
+    for (const part of parts) {
+      target = (target || {})[part.replace(/~1/g, '/').replace(/~0/g, '~')] || {};
+    }
+    if (target === current) break;
+    current = target;
+  }
+  return current;
+}
+
+/** Date arguments must carry a year that is licensed by the input. */
+function walkGrounding(schema, arguments_, years) {
+  const root = schemaParameters(schema);
+  const checked = new Set();
+  const failures = new Set();
+
+  const walk = (value, node, path) => {
+    node = resolveRef(node, root) || {};
+    const variants = node.anyOf || node.oneOf || [];
+    const concrete = variants.filter((v) => (resolveRef(v, root) || {}).type !== 'null');
+    if (concrete.length === 1) node = resolveRef(concrete[0], root) || {};
+
+    if ((node.format === 'date' || node.format === 'date-time') && typeof value === 'string') {
+      const match = /^(\d{4})-/.exec(value);
+      if (match && years.size) {
+        checked.add(path);
+        if (!years.has(parseInt(match[1], 10))) failures.add(path);
+      }
+      return;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      const properties = node.properties || {};
+      for (const [key, item] of Object.entries(value)) {
+        if (key in properties) walk(item, properties[key], path ? `${path}.${key}` : key);
+      }
+    } else if (Array.isArray(value) && node.items) {
+      value.forEach((item, index) => walk(item, node.items, `${path}[${index}]`));
+    }
+  };
+
+  walk(arguments_, root, '');
+  return { checked, failures };
+}
+
+function temporalGrounding(text, schema, arguments_, system) {
+  const years = licensedYears(sourceYears(text), system, relativeCue(text));
+  return walkGrounding(schema, arguments_, years);
+}
+
+function withoutDateFacts(text) {
+  return String(text || '').replace(DATE_FACT, ' ');
+}
+
+/** (path, value) for every numeric leaf, arguments-relative. */
+function numericPaths(arguments_, path = '') {
+  const out = [];
+  const walk = (value, currentPath) => {
+    if (typeof value === 'boolean') return;
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      out.push([currentPath, value]);
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk(item, `${currentPath}[${index}]`));
+    } else if (value && typeof value === 'object') {
+      for (const [key, item] of Object.entries(value)) {
+        walk(item, currentPath ? `${currentPath}.${key}` : String(key));
+      }
+    }
+  };
+  walk(arguments_, path);
+  return out;
+}
+
+/** Numeric values written in the source texts (separators normalized). */
+function sourceNumbers(...sources) {
+  const text = sources
+    .map((source) => withoutDateFacts(source))
+    .filter((source) => source)
+    .join('\n');
+  const numbers = new Set();
+  NUMBER_TOKEN.lastIndex = 0;
+  let match;
+  while ((match = NUMBER_TOKEN.exec(text)) !== null) {
+    const normalized = match[0].replace(/,/g, '');
+    const asNumber = Number(normalized);
+    if (Number.isFinite(asNumber)) numbers.add(asNumber);
+  }
+  return numbers;
+}
+
+function groundedNumberPaths(arguments_, ...sources) {
+  const numbers = sourceNumbers(...sources);
+  const grounded = new Set();
+  if (!numbers.size) return grounded;
+  for (const [path, value] of numericPaths(arguments_)) {
+    if (numbers.has(value)) grounded.add(path);
+  }
+  return grounded;
+}
+
+/** The engine's fabrication report, grouped by tool. */
+function ungroundedPaths(response) {
+  const validation = (response && response.validation) || {};
+  const grouped = new Map();
+  for (const name of validation.ungrounded || []) {
+    const text = String(name);
+    const dot = text.indexOf('.');
+    const tool = dot === -1 ? text : text.slice(0, dot);
+    const path = dot === -1 ? text : text.slice(dot + 1);
+    if (!grouped.has(tool)) grouped.set(tool, new Set());
+    grouped.get(tool).add(path || tool);
+  }
+  return grouped;
+}
+
+/** Add engine-reported ungrounded values to response.validation.ungrounded. */
+function annotateUngrounded(response, toolSchemas, seenYears, system, text) {
+  const calls = response.function_calls || [];
+  const years = licensedYears(seenYears, system, text !== undefined && text !== null ? relativeCue(text) : true);
+  if (!calls.length || !years.size) return;
+  const schemas = new Map();
+  for (const entry of toolSchemas || []) {
+    if (entry && entry.name) schemas.set(entry.name, entry);
+  }
+  const found = [];
+  for (const call of calls) {
+    const schema = schemas.get(call.name);
+    if (!schema) continue;
+    const { failures } = walkGrounding(schema, call.arguments || {}, years);
+    for (const path of [...failures].sort()) found.push(`${call.name}.${path}`);
+  }
+  if (!found.length) return;
+  const validation = response.validation || {};
+  const existing = [...(validation.ungrounded || [])];
+  validation.ungrounded = existing.concat(found.filter((name) => !existing.includes(name)));
+  response.validation = validation;
+}
+
+/** Strict mode: raise instead of returning values the input does not license. */
+function validateExtraction(text, schema, arguments_, response, system) {
+  const { checked, failures } = temporalGrounding(text, schema, arguments_, system);
+  const validation = (response && response.validation) || {};
+  const flagged = validation.ungrounded || [];
+  const grounded = flagged.length ? groundedNumberPaths(arguments_, text, system) : new Set();
+  for (const name of flagged) {
+    const path = String(name).includes('.') ? String(name).split('.').slice(1).join('.') : String(name);
+    if (grounded.has(path)) continue;
+    if (!checked.has(path) || failures.has(path)) failures.add(path);
+  }
+  if (validation.negation) failures.add('negated request');
+  if (failures.size) {
+    const detail = [...failures].sort().join(', ');
+    throw new ExtractionValidationError(
+      `extraction returned values not grounded in the input: ${detail}`);
+  }
+  return arguments_;
+}
+
+module.exports = {
+  ExtractionValidationError,
+  sourceYears,
+  relativeCue,
+  licensedYears,
+  walkGrounding,
+  temporalGrounding,
+  groundedNumberPaths,
+  sourceNumbers,
+  numericPaths,
+  ungroundedPaths,
+  annotateUngrounded,
+  validateExtraction,
+};