reploid 0.0.0-stage → 0.1.0

package/packages/reploid/src/retrieval/citations.js

@@ -0,0 +1,156 @@
+/** Mechanical citation checks for one answer against its retrieval record. Parsing and mapping are exact;
+ * whether a source supports a claim is delegated to a host support checker and is never inferred here. */
+import { sumMicroUsd } from './costs.js';
+import { abortable } from '../cancellation.js';
+
+export const CITATION_VERIFICATION_SCHEMA = 'reploid.citation-verification/v1';
+export const SUPPORT_VERDICTS = Object.freeze(['supported', 'unsupported', 'unverified']);
+
+const MARKER = /\[(\d{1,3}(?:\s*[,–-]\s*\d{1,3})*)\]/g;
+const MARKERS_ONLY = /^(?:\s*\[(\d{1,3}(?:\s*[,–-]\s*\d{1,3})*)\])+\s*[.,;:!?]?\s*$/;
+// A sentence ends at terminal punctuation followed by space or line end; markers after the period stay with it.
+const SENTENCE = /\S[^]*?(?:[.!?]+["'’”)\]]*(?:\s*\[\d{1,3}(?:\s*[,–-]\s*\d{1,3})*\])*(?=\s|$)|$)/g;
+const URL_TEXT = /\bhttps?:\/\/[^\s<>"'`\]\[)(]+/g;
+// "Sources:", "**References**" and similar labels open a source list; "Sources disagree" does not.
+const SOURCE_LABEL = /^\s*(?:\*\*|__)?(?:sources|references|citations)(?:\*\*|__)?\s*(?::(?:\*\*|__)?|$)/i;
+const MAX_RANGE = 20;
+
+function markerNumbers(group) {
+  return group.split(',').flatMap(part => {
+    const [from, to] = part.split(/[–-]/).map(value => Number(value.trim()));
+    if (to === undefined) return [from];
+    return to >= from && to - from <= MAX_RANGE ? Array.from({ length: to - from + 1 }, (_, index) => from + index) : [from, to];
+  });
+}
+const markersIn = text => [...new Set([...text.matchAll(MARKER)].flatMap(match => markerNumbers(match[1])))];
+const withoutMarkers = text => text.replace(MARKER, '').replace(/\s+([.,;:!?])/g, '$1').replace(/\s+/g, ' ').trim();
+const trimUrl = url => url.replace(/[.,;:!?]+$/, '');
+const sameUrl = (a, b) => a === b || a.replace(/\/$/, '') === b.replace(/\/$/, '');
+
+/**
+ * Splits an answer into claims (sentences outside code, headings and a trailing source list) with their
+ * citation markers, reference-list entries, and every URL the answer names.
+ */
+export function parseCitations(answer) {
+  const claims = [], references = [], urls = [];
+  let offset = 0, fenced = false, referenceList = false;
+  for (const raw of String(answer).split('\n')) {
+    const start = offset; offset += raw.length + 1;
+    if (/^\s*(```|~~~)/.test(raw)) { fenced = !fenced; continue; }
+    if (fenced) continue;
+    for (const match of raw.matchAll(URL_TEXT)) urls.push({ url: trimUrl(match[0]), start: start + match.index });
+    if (!raw.trim()) continue;
+    if (/^\s{0,3}#{1,6}\s/.test(raw)) { referenceList = /^\s{0,3}#{1,6}\s+(sources|references|citations)\b/i.test(raw); continue; }
+    const listed = raw.match(/^(\s*(?:[-*+•]|\d{1,3}[.)])\s+)/)?.[1] || '';
+    const body = raw.slice(listed.length), opensWithMarker = /^\s*\[\d{1,3}\]/.test(body);
+    // A "Sources:" line starts a source list that continues through list items and marker-led lines.
+    // A marker-led line naming a URL is a reference entry anywhere.
+    const label = !listed && SOURCE_LABEL.test(raw);
+    if (label) referenceList = true;
+    else if (referenceList && !(listed || opensWithMarker)) referenceList = false;
+    if (referenceList || opensWithMarker && /\bhttps?:\/\//.test(body)) {
+      const text = (label ? raw.replace(SOURCE_LABEL, '') : body).trim();
+      if (text) references.push({ start, end: start + raw.length, markers: markersIn(text), text });
+      continue;
+    }
+    for (const match of body.matchAll(SENTENCE)) {
+      const sentence = match[0].trimEnd(), text = withoutMarkers(sentence);
+      const at = start + listed.length + match.index;
+      if (MARKERS_ONLY.test(sentence) && claims.length) {
+        // A marker group separated from its sentence belongs to the preceding claim.
+        const previous = claims.at(-1);
+        previous.markers = [...new Set([...previous.markers, ...markersIn(sentence)])]; previous.end = at + sentence.length;
+        continue;
+      }
+      if (!/[\p{L}\p{N}]/u.test(text)) continue;
+      const markers = markersIn(sentence);
+      if (!markers.length && /:\s*$/.test(text)) continue; // A lead-in such as "The sources say:" asserts nothing.
+      claims.push({ index: claims.length, start: at, end: at + sentence.length, text, markers });
+    }
+  }
+  return { claims, references, urls };
+}
+
+const unverified = reason => ({ verdict: 'unverified', reason });
+const STOPPED = 'Support checking stopped before this citation.';
+/** A checker that ignores its signal cannot hold the attempt past it. */
+function untilStopped(operation, signal) {
+  if (!signal) return Promise.resolve().then(operation);
+  return abortable(operation, signal).catch(error => {
+    if (signal.aborted && error === signal.reason) return unverified(STOPPED);
+    throw error;
+  });
+}
+function judged(value) {
+  if (!value || !SUPPORT_VERDICTS.includes(value.verdict) || typeof value.reason !== 'string' || !value.reason.trim()) {
+    return unverified('The support checker returned an invalid result.');
+  }
+  return { verdict: value.verdict, reason: value.reason.trim().slice(0, 500) };
+}
+
+/**
+ * Maps every citation marker to the record's numbered sources, flags uncited claims, unresolved markers and URLs
+ * absent from the record, and asks the support checker about each resolved citation. Without a checker, or past
+ * the check limit, support is unverified. Nothing here grades the answer; flags are evidence for review.
+ */
+export async function verifyCitations({ answer, record, checker = null, signal = null, maxSupportChecks = 256 }) {
+  const parsed = parseCitations(answer), byNumber = new Map((record?.sources || []).map(source => [source.number, source]));
+  const known = (record?.sources || []).map(source => source.url);
+  let checks = 0;
+  // Each check's cost as the checker reports it; unreported, failed or stopped checks are unknown, not free.
+  const checkCosts = [];
+  const support = async (claim, source) => {
+    if (!checker) return unverified('No support checker is configured.');
+    if (signal?.aborted) return unverified(STOPPED);
+    if (checks >= maxSupportChecks) return unverified('The support check limit was reached.');
+    checks++;
+    try {
+      const value = await untilStopped(() => checker.check({ claim, signal, source: { number: source.number,
+        sourceId: source.sourceId, title: source.title, url: source.url, passage: source.passage } }), signal);
+      checkCosts.push(Number.isSafeInteger(value?.costMicroUsd) && value.costMicroUsd >= 0 ? value.costMicroUsd : null);
+      return judged(value);
+    } catch (error) {
+      checkCosts.push(null);
+      return unverified(`The support checker failed: ${String(error?.message || error).slice(0, 200)}`);
+    }
+  };
+  const claims = [], flags = [];
+  for (const claim of parsed.claims) {
+    const citations = [];
+    for (const marker of claim.markers) {
+      const source = byNumber.get(marker);
+      if (!source) { citations.push({ marker, sourceId: null, resolved: false, support: null }); continue; }
+      citations.push({ marker, sourceId: source.sourceId, resolved: true, support: await support(claim.text, source) });
+    }
+    claims.push({ ...claim, cited: citations.length > 0, citations });
+    if (!citations.length) flags.push({ kind: 'uncited-claim', claim: claim.index });
+    for (const citation of citations) {
+      if (!citation.resolved) flags.push({ kind: 'unresolved-citation', claim: claim.index, marker: citation.marker });
+      else if (citation.support.verdict === 'unsupported') flags.push({ kind: 'unsupported-citation', claim: claim.index,
+        marker: citation.marker, reason: citation.support.reason });
+      else if (citation.support.verdict === 'unverified') flags.push({ kind: 'unverified-support', claim: claim.index, marker: citation.marker });
+    }
+  }
+  const references = parsed.references.map(entry => ({ ...entry, unresolved: entry.markers.filter(marker => !byNumber.has(marker)) }));
+  for (const entry of references) {
+    for (const marker of entry.unresolved) flags.push({ kind: 'unresolved-reference', marker });
+    // "[2] https://..." must name source 2's own URL, not another retrieved source's.
+    const source = entry.markers.length === 1 ? byNumber.get(entry.markers[0]) : null;
+    for (const match of source ? entry.text.matchAll(URL_TEXT) : []) {
+      if (!sameUrl(source.url, trimUrl(match[0]))) flags.push({ kind: 'mismatched-reference', marker: source.number, url: trimUrl(match[0]) });
+    }
+  }
+  const unrecordedUrls = [...new Set(parsed.urls.map(item => item.url).filter(url => !known.some(source => sameUrl(source, url))))];
+  for (const url of unrecordedUrls) flags.push({ kind: 'unrecorded-url', url });
+  const all = claims.flatMap(claim => claim.citations), verdict = name => all.filter(item => item.support?.verdict === name).length;
+  return {
+    schema: CITATION_VERIFICATION_SCHEMA,
+    checker: checker ? { id: checker.id, version: checker.version } : null,
+    usage: { checks, costMicroUsd: sumMicroUsd(checkCosts) },
+    claims, references, unrecordedUrls, flags,
+    summary: { claims: claims.length, citedClaims: claims.filter(claim => claim.cited).length,
+      uncitedClaims: claims.filter(claim => !claim.cited).length, citations: all.length,
+      unresolvedCitations: all.filter(item => !item.resolved).length, supported: verdict('supported'),
+      unsupported: verdict('unsupported'), unverified: verdict('unverified'), unrecordedUrls: unrecordedUrls.length }
+  };
+}

package/packages/reploid/src/retrieval/claim-support.js

@@ -0,0 +1,113 @@
+/** Claim-to-span mapping and deterministic citation validity for one answer against its retrieval record.
+ * Everything here is mechanical: a valid citation names a fetched source whose retained passage still hashes to
+ * its record and contains the mapped span. Whether a span supports its claim is never decided here; only an
+ * independent reviewer (support-review.js) decides that, so every reviewable claim stays unverified until then. */
+import defaults from './policy.json' with { type: 'json' };
+import { parseCitations } from './citations.js';
+import { renderSourceContext } from './sources.js';
+import { SHA256, contentWords, sha256Text } from './text.js';
+
+export const CLAIM_SUPPORT_SCHEMA = 'reploid.claim-support/v1';
+export const SPAN_ALIGNMENT = 'reploid.lexical-span-alignment/v1';
+/** Why a citation is not deterministically valid. */
+export const CITATION_PROBLEMS = Object.freeze(['unresolved-marker', 'mismatched-reference', 'not-retrieved', 'passage-hash-mismatch',
+  'document-offsets-invalid', 'context-digest-mismatch', 'span-invalid']);
+
+const URL_TEXT = /\bhttps?:\/\/[^\s<>"'`\]\[)(]+/g;
+const trimUrl = url => url.replace(/[.,;:!?]+$/, '');
+const sameUrl = (a, b) => a === b || a.replace(/\/$/, '') === b.replace(/\/$/, '');
+const webUrl = value => { try { return ['http:', 'https:'].includes(new URL(value).protocol); } catch { return false; } };
+
+/** Sentence spans of a passage, as [start, end) offsets without surrounding whitespace. */
+export function passageSentences(passage) {
+  const spans = [];
+  // A period ends a sentence only before whitespace or the end (after any closing quote), so 3.5 stays inside.
+  for (const match of String(passage).matchAll(/(?:[^\n.!?]|[.!?](?!["'’”)\]]*(?:\s|$)))*(?:[.!?]+["'’”)\]]*|\n|$)/g)) {
+    const raw = match[0], lead = raw.length - raw.trimStart().length, text = raw.trim();
+    if (text && /[\p{L}\p{N}]/u.test(text)) spans.push({ start: match.index + lead, end: match.index + lead + text.length });
+    if (!raw) break;
+  }
+  return spans;
+}
+
+/** The passage sentence sharing the most content words with the claim (earliest on ties); the whole passage when none does.
+ * This only points the reviewer at evidence; overlap is not support. */
+export function alignClaimSpan(claim, passage) {
+  const words = new Set(contentWords(claim));
+  let best = null;
+  for (const span of passageSentences(passage)) {
+    const score = contentWords(passage.slice(span.start, span.end)).filter(word => words.has(word)).length;
+    if (score > (best?.score ?? 0)) best = { ...span, score };
+  }
+  return best ? { start: best.start, end: best.end, alignment: 'sentence' } : { start: 0, end: passage.length, alignment: 'whole-passage' };
+}
+
+/** A span is valid when it lies inside the passage, its text is exactly that slice and its hash is the slice's sha256. */
+export async function validSpan(passage, span) {
+  return !!span && Number.isSafeInteger(span.start) && Number.isSafeInteger(span.end) && span.start >= 0 && span.end > span.start
+    && span.end <= passage.length && span.text === passage.slice(span.start, span.end)
+    && SHA256.test(span.sha256) && span.sha256 === await sha256Text(span.text);
+}
+
+/** Integrity of one retrieved source, independent of any claim. */
+async function sourceProblems(record, source) {
+  const problems = [];
+  // The cited URL was fetched and extracted, not merely named by a search result.
+  if (record.outcome !== 'retrieved' || source.passageOrigin !== 'extract' || !webUrl(source.url)
+    || source.document && !webUrl(source.document.url)) problems.push('not-retrieved');
+  if (await sha256Text(source.passage) !== source.passageHash) problems.push('passage-hash-mismatch');
+  if (source.document && !(Number.isSafeInteger(source.document.start) && source.document.end - source.document.start === source.passage.length
+    && source.document.end <= source.document.characters)) problems.push('document-offsets-invalid');
+  return problems;
+}
+
+/**
+ * Maps every claim of `answer` to spans of the passages it cites and checks each citation deterministically:
+ * the marker resolves to a numbered source, any reference entry names that source's URL, the source was fetched,
+ * its passage still matches its hash and offsets, the numbered context still matches the digest that was sent, and
+ * the span is an exact, hashed slice of the passage. Uncited claims and claims citing only unknown markers are
+ * unsupported; claims with a valid citation await independent review; claims whose citations all fail integrity
+ * checks are unverified.
+ */
+export async function mapClaimSpans({ answer, record, policy = defaults }) {
+  const parsed = parseCitations(answer), sources = record?.sources || [];
+  const byNumber = new Map(sources.map(source => [source.number, source]));
+  const contextValid = !!record?.context && sources.length > 0
+    && await sha256Text(renderSourceContext(sources, policy)) === record.context.digest;
+  const integrity = new Map();
+  for (const source of sources) integrity.set(source.number, [...await sourceProblems(record, source), ...(contextValid ? [] : ['context-digest-mismatch'])]);
+  // "[2] https://..." in a source list must name source 2's own URL.
+  const mismatched = new Set();
+  for (const entry of parsed.references) {
+    const source = entry.markers.length === 1 ? byNumber.get(entry.markers[0]) : null;
+    for (const match of source ? entry.text.matchAll(URL_TEXT) : []) if (!sameUrl(source.url, trimUrl(match[0]))) mismatched.add(source.number);
+  }
+  const claims = [];
+  for (const claim of parsed.claims) {
+    const citations = [];
+    for (const marker of claim.markers) {
+      const source = byNumber.get(marker);
+      if (!source) { citations.push({ marker, sourceId: null, url: null, valid: false, problems: ['unresolved-marker'], span: null }); continue; }
+      const aligned = alignClaimSpan(claim.text, source.passage), text = source.passage.slice(aligned.start, aligned.end);
+      const span = { start: aligned.start, end: aligned.end, text, sha256: await sha256Text(text), alignment: aligned.alignment };
+      const problems = [...integrity.get(marker), ...(mismatched.has(marker) ? ['mismatched-reference'] : []),
+        ...(await validSpan(source.passage, span) ? [] : ['span-invalid'])];
+      citations.push({ marker, sourceId: source.sourceId, url: source.url, passageHash: source.passageHash,
+        ...(source.document ? { document: { sha256: source.document.sha256, start: source.document.start + span.start,
+          end: source.document.start + span.end } } : {}), valid: !problems.length, problems, span });
+    }
+    const valid = citations.filter(citation => citation.valid);
+    const [verdict, reason] = !citations.length ? ['unsupported', 'uncited']
+      : citations.every(citation => citation.problems.includes('unresolved-marker')) ? ['unsupported', 'unresolved-citation']
+        : valid.length ? ['unverified', 'awaiting-review'] : ['unverified', 'invalid-evidence'];
+    claims.push({ id: `claim-${claim.index + 1}`, index: claim.index, text: claim.text, start: claim.start, end: claim.end,
+      markers: claim.markers, citations, reviewable: valid.length > 0, verdict, reason });
+  }
+  const all = claims.flatMap(claim => claim.citations), tally = name => claims.filter(claim => claim.verdict === name).length;
+  return { schema: CLAIM_SUPPORT_SCHEMA, alignment: SPAN_ALIGNMENT, query: record?.query ?? null,
+    contextDigest: record?.context?.digest ?? null, contextValid, claims,
+    summary: { claims: claims.length, citedClaims: claims.filter(claim => claim.citations.length).length,
+      reviewableClaims: claims.filter(claim => claim.reviewable).length, citations: all.length,
+      validCitations: all.filter(citation => citation.valid).length, invalidCitations: all.filter(citation => !citation.valid).length,
+      supported: tally('supported'), unsupported: tally('unsupported'), unverified: tally('unverified') } };
+}

package/packages/reploid/src/retrieval/costs.js

@@ -0,0 +1,101 @@
+/** Per-answer costs of a search-backed answer, kept in its retrieval record and never in conversation text. Retrieval
+ * (search queries and page fetches), verification (support checks and entailment reviews) and fallback are separate
+ * entries so service economics can sum each one. Prices come only from explicit configuration reported by the
+ * providers and reviewers: an unpriced or unmeasured component is null, never zero, and a null makes every sum above
+ * it null. Zero means the work did not happen. Amounts are integer micro-USD. */
+
+export const RETRIEVAL_COSTS_SCHEMA = 'reploid.retrieval-costs/v1';
+/** Who pays a route's retrieval: the operator (a Reploid-paid provider) or the requester (their own device and tools). */
+export const COST_BEARERS = Object.freeze(['operator', 'requester']);
+/** No fallback route exists yet, so every record says so explicitly rather than omitting the entry. */
+export const NO_FALLBACK = Object.freeze({ path: 'none', costMicroUsd: 0 });
+
+const amount = value => Number.isSafeInteger(value) && value >= 0;
+const known = value => amount(value) ? value : null;
+/** The sum of the amounts, or null when any of them is unknown. */
+export const sumMicroUsd = values => values.every(amount) ? values.reduce((total, value) => total + value, 0) : null;
+
+/** A model's configured token prices, micro-USD per million tokens, or null when unpriced. */
+export function validTokenPrice(price) {
+  return price === null || !!price && typeof price === 'object' && Object.keys(price).length === 2
+    && amount(price.inputMicroUsdPerMillionTokens) && amount(price.outputMicroUsdPerMillionTokens);
+}
+/** One model call's cost; null unless both token counts and the price are known. Rounded to the nearest micro-USD. */
+export function tokenCostMicroUsd({ inputTokens, outputTokens, price }) {
+  if (!amount(inputTokens) || !amount(outputTokens) || !price || !validTokenPrice(price)) return null;
+  return Math.round((inputTokens * price.inputMicroUsdPerMillionTokens + outputTokens * price.outputMicroUsdPerMillionTokens) / 1e6);
+}
+
+const unknownSearch = service => ({ service, requests: null, costMicroUsd: null });
+const UNKNOWN_EXTRACTION = Object.freeze({ attempted: null, documents: null, failed: null, bytes: null, costMicroUsd: null });
+/** The retrieval entry of a record whose retrieval was not observed to completion (for example, interrupted by a reload). */
+export const unknownRetrievalCosts = (bearer = null) => ({ bearer, search: unknownSearch(null), extraction: { ...UNKNOWN_EXTRACTION }, costMicroUsd: null });
+
+/**
+ * The retrieval entry from what one retrieval observed. `meter`: whether the provider was called and the usage it
+ * reported; extraction attempts, failures, fetched bytes (null when an extractor did not report them) and each
+ * extracted passage's reported cost (null when unreported). A failed fetch may still have transferred bytes, so any
+ * failure leaves the extraction cost unknown.
+ */
+export function retrievalCostEntry({ bearer = null, service = null, meter }) {
+  const search = !meter.searched ? { service: null, requests: 0, costMicroUsd: 0 }
+    : meter.usage ? { service: meter.usage.provider, requests: meter.usage.requests, costMicroUsd: known(meter.usage.costMicroUsd) }
+      : unknownSearch(service);
+  const extraction = { attempted: meter.attempted, documents: meter.documents, failed: meter.failed, bytes: meter.bytes,
+    costMicroUsd: meter.attempted === 0 ? 0 : meter.failed > 0 ? null : sumMicroUsd(meter.costs) };
+  return { bearer: COST_BEARERS.includes(bearer) ? bearer : null, search, extraction,
+    costMicroUsd: sumMicroUsd([search.costMicroUsd, extraction.costMicroUsd]) };
+}
+
+/** One review's cost: a model review from its reported tokens and configured price; a human review unpriced unless declared. */
+export function reviewCostEntry(judgments) {
+  if (judgments?.schema !== 'reploid.claim-support-judgments/v1' || !judgments.reviewer) throw new Error('Invalid support judgments');
+  const base = { kind: judgments.reviewer.kind, packet: judgments.packet?.id ?? null, reviewer: judgments.reviewer.id };
+  if (judgments.reviewer.kind === 'model') {
+    const usage = judgments.usage ?? {}, price = validTokenPrice(usage.price ?? null) ? usage.price ?? null : null;
+    const inputTokens = known(usage.inputTokens), outputTokens = known(usage.outputTokens);
+    return { ...base, inputTokens, outputTokens, price: price && { ...price }, costMicroUsd: tokenCostMicroUsd({ inputTokens, outputTokens, price }) };
+  }
+  return amount(judgments.declaredCostMicroUsd) ? { ...base, pricing: 'declared', costMicroUsd: judgments.declaredCostMicroUsd }
+    : { ...base, pricing: 'unpriced', costMicroUsd: null };
+}
+
+/** The verification entry: the configured support checker's checks during verification, plus any entailment reviews. */
+function verificationEntry(verification, reviews = []) {
+  const checker = verification?.checker ? { id: verification.checker.id, version: verification.checker.version,
+    checks: verification.usage?.checks ?? null, costMicroUsd: verification.usage ? known(verification.usage.costMicroUsd) : null } : null;
+  return { checker, reviews: structuredClone(reviews),
+    costMicroUsd: sumMicroUsd([...(checker ? [checker.costMicroUsd] : []), ...reviews.map(review => review.costMicroUsd)]) };
+}
+const NO_VERIFICATION = Object.freeze({ checker: null, reviews: [], costMicroUsd: 0 });
+
+/** The complete cost record: three separate entries, their total, and the components whose cost is unknown. */
+export function retrievalCostRecord({ retrieval, verification = NO_VERIFICATION, fallback = NO_FALLBACK }) {
+  const unknown = [
+    ...(retrieval.search.costMicroUsd === null ? ['retrieval.search'] : []),
+    ...(retrieval.extraction.costMicroUsd === null ? ['retrieval.extraction'] : []),
+    ...(verification.checker?.costMicroUsd === null ? ['verification.checker'] : []),
+    ...verification.reviews.filter(review => review.costMicroUsd === null).map(review => `verification.review:${review.kind}:${review.reviewer}`),
+    ...(fallback.costMicroUsd === null ? ['fallback'] : [])];
+  return { schema: RETRIEVAL_COSTS_SCHEMA, unit: 'micro-usd', retrieval: structuredClone(retrieval), verification: structuredClone(verification),
+    fallback: { ...fallback }, totalMicroUsd: sumMicroUsd([retrieval.costMicroUsd, verification.costMicroUsd, fallback.costMicroUsd]), unknown };
+}
+
+/** The record with its citation verification attached and the verification cost entry updated from it. */
+export function withVerification(record, verification) {
+  const costs = record.costs;
+  return { ...record, verification, costs: retrievalCostRecord({ retrieval: costs?.retrieval ?? unknownRetrievalCosts(),
+    verification: verificationEntry(verification, costs?.verification?.reviews), fallback: costs?.fallback ?? NO_FALLBACK }) };
+}
+
+/** The record with entailment review costs added from judgment files; a reviewer's later file for the same packet replaces its earlier one. */
+export function withReviewCosts(record, judgmentFiles) {
+  if (!Array.isArray(judgmentFiles)) throw new Error('Review cost needs judgment files');
+  const reviews = [...(record.costs?.verification?.reviews ?? [])];
+  for (const entry of judgmentFiles.map(reviewCostEntry)) {
+    const index = reviews.findIndex(item => item.kind === entry.kind && item.reviewer === entry.reviewer && item.packet === entry.packet);
+    if (index >= 0) reviews[index] = entry; else reviews.push(entry);
+  }
+  return { ...record, costs: retrievalCostRecord({ retrieval: record.costs?.retrieval ?? unknownRetrievalCosts(),
+    verification: verificationEntry(record.verification, reviews), fallback: record.costs?.fallback ?? NO_FALLBACK }) };
+}

package/packages/reploid/src/retrieval/fixed-provider.js

@@ -0,0 +1,34 @@
+/** Deterministic search and extraction over fixed documents, for tests and harnesses. It makes no network
+ * request, needs no key and discloses the query to no one. It is not a search provider. */
+import { contentWords, sha256Text, wordTokens } from './text.js';
+
+const assert = (ok, message) => { if (!ok) throw new Error(message); };
+
+export function createFixedSearchProvider({ documents, now = Date.now, id = 'reploid.fixed-documents', version = '1' }) {
+  assert(Array.isArray(documents) && documents.every(doc => doc && ['id', 'url', 'title', 'text'].every(key => typeof doc[key] === 'string' && doc[key]))
+    && new Set(documents.map(doc => doc.id)).size === documents.length, 'Fixed documents need unique id, url, title and text');
+  const fixed = documents.map(doc => Object.freeze({ ...doc, words: new Set(wordTokens(`${doc.title} ${doc.text}`)) }));
+  const hashes = new Map();
+  const hash = doc => { if (!hashes.has(doc.id)) hashes.set(doc.id, sha256Text(doc.text)); return hashes.get(doc.id); };
+  // The paragraph naming the most query words, first on ties.
+  const passage = (doc, terms) => doc.text.split(/\n\s*\n/).map(part => part.trim()).filter(Boolean)
+    .map((part, index) => ({ part, index, score: (words => terms.filter(term => words.has(term)).length)(new Set(wordTokens(part))) }))
+    .sort((a, b) => b.score - a.score || a.index - b.index)[0].part;
+  return Object.freeze({
+    id, version,
+    async search(query, limits, signal) {
+      signal?.throwIfAborted();
+      const terms = contentWords(query);
+      const ranked = fixed.map(doc => ({ doc, score: terms.filter(term => doc.words.has(term)).length }))
+        .filter(row => row.score > 0).sort((a, b) => b.score - a.score || a.doc.id.localeCompare(b.doc.id)).slice(0, limits.maxResults);
+      return Promise.all(ranked.map(async ({ doc }) => ({ sourceId: doc.id, url: doc.url, title: doc.title,
+        excerpt: passage(doc, terms), retrievedAt: now(), contentHash: await hash(doc) })));
+    },
+    async extract({ source, query, signal }) {
+      signal?.throwIfAborted();
+      const doc = fixed.find(item => item.id === source.sourceId);
+      assert(doc, 'Unknown fixed document');
+      return { sourceId: doc.id, url: doc.url, text: passage(doc, contentWords(query)), retrievedAt: now(), contentHash: await hash(doc) };
+    }
+  });
+}

package/packages/reploid/src/retrieval/index.js

@@ -0,0 +1,20 @@
+export { createRetrieval } from './retrieval.js';
+export { RETRIEVAL_RECORD_SCHEMA, RETRIEVAL_OUTCOMES, normalizeRetrievalLimits, normalizeRetrievalRequest, retrieveSources,
+  renderSourceContext, withSourceContext, retrievalFailureMessage, interruptRetrievalRecord, RETRIEVAL_SUPPLIES } from './sources.js';
+export { CITATION_VERIFICATION_SCHEMA, SUPPORT_VERDICTS, parseCitations, verifyCitations } from './citations.js';
+export { createLexicalSupportChecker } from './lexical-support.js';
+export { createFixedSearchProvider } from './fixed-provider.js';
+export { CLAIM_SUPPORT_SCHEMA, SPAN_ALIGNMENT, CITATION_PROBLEMS, mapClaimSpans, alignClaimSpan, passageSentences, validSpan } from './claim-support.js';
+export { SUPPORT_REVIEW_PACKET_SCHEMA, SUPPORT_JUDGMENTS_SCHEMA, SUPPORT_RESULT_SCHEMA, REVIEW_VERDICTS, SUPPORT_REVIEW_INSTRUCTIONS,
+  createSupportReviewPacket, renderSupportReviewPacketMarkdown, applySupportJudgments, validateSupportJudgments,
+  assertIndependentReviewer, validateGenerator, supportPacketHash, canonicalJson } from './support-review.js';
+export { REVIEW_QUEUE_SCHEMA, createHumanReviewQueue } from './review-queue.js';
+export { MODEL_REVIEWER_SYSTEM, createModelSupportReviewer, renderModelReviewPrompt } from './model-reviewer.js';
+export { RETRIEVAL_COSTS_SCHEMA, COST_BEARERS, NO_FALLBACK, sumMicroUsd, validTokenPrice, tokenCostMicroUsd, reviewCostEntry,
+  retrievalCostRecord, withVerification, withReviewCosts } from './costs.js';
+export { decodeEntities, htmlFragmentText, detectCharset, extractDocumentText } from './page-text.js';
+export { selectPassage } from './passage.js';
+export { sha256Text } from './text.js';
+import pageFetchPolicy from './page-fetch.json' with { type: 'json' };
+/** Page fetch limits shared by the server fetcher and device-side extractors. */
+export const PAGE_FETCH_POLICY = pageFetchPolicy;

package/packages/reploid/src/retrieval/lexical-support.js

@@ -0,0 +1,27 @@
+/** Test-only support checker. It compares words, not meaning, and is not qualified to judge support.
+ * It misses paraphrase (false unsupported) and accepts reworded falsehoods that reuse the source's words
+ * (false supported); scope, attribution and most negation errors pass undetected. */
+import { contentWords, wordTokens } from './text.js';
+
+const NEGATIONS = new Set(['not', 'no', 'never', 'none', 'nor', 'without', "isn't", "aren't", "wasn't", "weren't", "doesn't",
+  "don't", "didn't", "cannot", "can't", "won't"]);
+const numeric = token => /^\p{N}/u.test(token);
+
+export function createLexicalSupportChecker({ supportedAt = 0.8, unsupportedBelow = 0.5 } = {}) {
+  if (!(unsupportedBelow > 0 && unsupportedBelow <= supportedAt && supportedAt <= 1)) throw new Error('Invalid lexical support thresholds');
+  return Object.freeze({
+    id: 'reploid.lexical-overlap-test', version: '1', qualified: false,
+    async check({ claim, source }) {
+      const words = contentWords(claim), passage = new Set(wordTokens(source.passage));
+      if (!words.length) return { verdict: 'unverified', reason: 'The claim has no checkable words.' };
+      const missingNumbers = words.filter(word => numeric(word) && !passage.has(word));
+      if (missingNumbers.length) return { verdict: 'unsupported', reason: `The source does not contain ${missingNumbers.join(', ')}.` };
+      const negation = words.find(word => NEGATIONS.has(word) && !passage.has(word));
+      if (negation) return { verdict: 'unverified', reason: `The claim says "${negation}" and the source does not.` };
+      const found = words.filter(word => passage.has(word)).length, share = found / words.length;
+      const reason = `${found} of ${words.length} claim words appear in the source.`;
+      if (share >= supportedAt) return { verdict: 'supported', reason };
+      return { verdict: share < unsupportedBelow ? 'unsupported' : 'unverified', reason };
+    }
+  });
+}

package/packages/reploid/src/retrieval/model-reviewer.js

@@ -0,0 +1,67 @@
+/** A stronger-model entailment reviewer. Off unless a host configures it: the host names the reviewer's provider and
+ * model, the generating models it is declared stronger than, and a `complete` port that reaches that model.
+ * Sending a packet to it discloses the question, the answer and the cited passages to that provider; this is a
+ * separate disclosure from search and from execution contributors, so hosts use it only for evaluation material
+ * they may send there. It never reviews an answer from its own model or from a model it is not declared stronger than. */
+import { SUPPORT_JUDGMENTS_SCHEMA, assertIndependentReviewer, supportPacketHash, validateGenerator } from './support-review.js';
+import { tokenCostMicroUsd, validTokenPrice } from './costs.js';
+
+const assert = (ok, message) => { if (!ok) throw new Error(message); };
+const named = value => typeof value === 'string' && value.trim() && value.length <= 256;
+const normalized = value => String(value).toLowerCase().replace(/[^a-z0-9]/g, '');
+
+export const MODEL_REVIEWER_SYSTEM = 'You review whether cited source passages support claims in an answer. You judge only against the recorded passages, never your own knowledge. You reply with JSON only.';
+
+export function renderModelReviewPrompt(packet) {
+  return [...packet.instructions, '',
+    'Reply with one JSON object: {"judgments":[{"claim":"<claim id>","verdict":"supported|unsupported|unverified","basis":"<one or two sentences>","spans":[{"source":<number>,"quote":"<exact text copied from that passage>"}]}]}.',
+    'Include every claim id once. For supported, quote the exact passage text you relied on; quotes must match the passage character for character.', '',
+    `Question:\n${packet.question}`, '', `Answer:\n${packet.answer}`, '',
+    'Sources:', ...packet.sources.map(source => `[${source.number}] ${source.title}\n${source.url}\n<<<\n${source.passage}\n>>>`), '',
+    'Claims:', ...packet.claims.map(claim => `${claim.id}: ${claim.text}\n  cites: ${claim.citations.map(citation =>
+      `[${citation.source}] suggested span "${citation.suggestedSpan.text}"`).join('; ')}`)].join('\n');
+}
+
+function parseJudgments(reply) {
+  const body = String(reply), start = body.indexOf('{'), end = body.lastIndexOf('}');
+  assert(start >= 0 && end > start, 'The reviewer model returned no JSON judgments');
+  const parsed = JSON.parse(body.slice(start, end + 1));
+  assert(Array.isArray(parsed?.judgments), 'The reviewer model returned no judgments list');
+  return parsed.judgments.map(item => ({ claim: item?.claim, verdict: item?.verdict, basis: item?.basis,
+    spans: Array.isArray(item?.spans) ? item.spans.map(span => ({ source: span?.source, quote: span?.quote })) : [] }));
+}
+
+const tokens = value => Number.isSafeInteger(value) && value >= 0 ? value : null;
+
+/**
+ * `identity`: `{ provider, model, version?, identity? }` of the reviewer. `strongerThan`: generating model ids or
+ * content identities this reviewer is explicitly declared stronger than. `complete({ system, prompt, signal })`
+ * returns the model's text reply, or `{ text, usage: { inputTokens, outputTokens } }` when the endpoint reports tokens.
+ * `price`: the configured `{ inputMicroUsdPerMillionTokens, outputMicroUsdPerMillionTokens }`, or null when unpriced.
+ * Each judgment file carries the review's token usage and cost (null when tokens or price are unknown).
+ */
+export function createModelSupportReviewer({ identity, strongerThan, complete, price = null, maxReplyCharacters = 200000 } = {}) {
+  assert(identity && named(identity.provider) && named(identity.model), 'A model reviewer is off unless its provider and model are configured');
+  assert(Array.isArray(strongerThan) && strongerThan.length && strongerThan.every(named),
+    'A model reviewer must name the generating models it is stronger than');
+  assert(typeof complete === 'function', 'A model reviewer needs a completion port');
+  assert(validTokenPrice(price), 'A model reviewer price is null or both token prices in micro-USD per million tokens');
+  const reviewer = Object.freeze({ kind: 'model', id: `${identity.provider}/${identity.model}`,
+    model: { provider: identity.provider, name: identity.model, version: identity.version ?? null, ...(identity.identity ? { identity: identity.identity } : {}) } });
+  return Object.freeze({
+    id: 'reploid.model-support-reviewer', version: '1', kind: 'model', reviewer,
+    async review(packet, { generator, signal = null } = {}) {
+      const made = validateGenerator(generator);
+      assertIndependentReviewer(reviewer, made);
+      assert(strongerThan.some(value => value === made.modelIdentity || normalized(value) === normalized(made.modelId)),
+        'This reviewer is not configured as stronger than the generating model');
+      const returned = await complete({ system: MODEL_REVIEWER_SYSTEM, prompt: renderModelReviewPrompt(packet), signal });
+      const reply = typeof returned === 'string' ? returned : returned?.text;
+      assert(typeof reply === 'string' && reply.length <= maxReplyCharacters, 'The reviewer model reply is missing or too long');
+      const inputTokens = tokens(returned?.usage?.inputTokens), outputTokens = tokens(returned?.usage?.outputTokens);
+      return { schema: SUPPORT_JUDGMENTS_SCHEMA, packet: { id: packet.id, sha256: await supportPacketHash(packet) },
+        reviewer: structuredClone(reviewer), judgments: parseJudgments(reply),
+        usage: { inputTokens, outputTokens, price: price && { ...price }, costMicroUsd: tokenCostMicroUsd({ inputTokens, outputTokens, price }) } };
+    }
+  });
+}

package/packages/reploid/src/retrieval/page-fetch.json

@@ -0,0 +1,10 @@
+{
+  "id": "reploid.page-fetch-policy",
+  "version": "1.0.0",
+  "maxBytes": 2000000,
+  "timeoutMs": 8000,
+  "maxRedirects": 3,
+  "maxUrlCharacters": 2048,
+  "contentTypes": ["text/html", "application/xhtml+xml", "text/plain"],
+  "unsupportedContentTypes": ["application/pdf"]
+}