@tangle-network/agent-app 0.44.12 → 0.44.14

package/dist/work-product/index.d.ts

@@ -215,6 +215,12 @@ declare const EVIDENCE_COVERAGE_CHECK = "evidence_coverage";
  *  a reviewer reads the strength of the lineage off the row itself rather than
  *  trusting that a quote was checked. */
 declare const QUOTE_VERIFICATION_CHECK = "quote_verification";
+/** Platform check: how many quoted evidence entries anchor to text that
+ *  actually CARRIES the figure the entry claims. Distinct from
+ *  `quote_verification`, which only proves the text came from the document —
+ *  production row `7256ef49` passed that one on all four entries while
+ *  supporting none of them. */
+declare const CLAIM_SUPPORT_CHECK = "claim_support";
 /** Domain seams for the three work-product tools — every domain word is a
  *  parameter; the shell bakes none. */
 interface WorkProductToolConfig {
@@ -258,6 +264,17 @@ interface WorkProductToolConfig {
      *  document-derived targets, and coverage stops being satisfiable by
      *  assertion. */
     requireAnchoredEvidence?: boolean;
+    /** Verify that each anchored quote CARRIES the figure its entry claims.
+     *  ON by default — an anchor that does not support its claim is the one
+     *  failure mode every other gate here passes, and it reads to a reviewer as
+     *  the most authoritative citation on the row.
+     *
+     *  Only claims that assert a figure are checked, so a filing status, a name
+     *  or a date is unaffected; see `./claim-support` for exactly where the line
+     *  is drawn and why it is drawn to stay satisfiable. Set `false` only for a
+     *  product whose claims are figures the source states in a form no numeric
+     *  comparison can reach. */
+    verifyClaimSupport?: boolean;
     /** Per-turn provenance closure the ROUTE supplies (profileHash + runId are
      *  known at dispatch; trusted, never read from model args). */
     provenance: (ctx: AppToolContext) => WorkProductProvenanceBase;
@@ -386,6 +403,10 @@ type SourceFindFailure = {
 } | {
     reason: 'occurrence_out_of_range';
     found: number;
+} | {
+    reason: 'not_distinctive';
+    needle: string;
+    found: number;
 };
 type SourceFindResult = {
     ok: true;
@@ -408,6 +429,130 @@ declare function sliceSourceSpan(sourceText: string, span: {
     end: number;
 }): SourceSpanResult;
 
+/**
+ * Claim support — does the anchored text actually say what the entry claims?
+ *
+ * The two gates before this one answer different questions. `sourceContainsQuote`
+ * asks whether the quote is really in the document; `findSourceLine` /
+ * `sliceSourceSpan` make the platform produce the quote so it cannot be typed
+ * wrong. Both are about the TEXT's provenance. Neither one looks at `claim`.
+ *
+ * Production row `7256ef49` is what that gap costs. Four evidence entries, all
+ * `quoteBasis:'span'`, every quote a genuine slice of the document it named —
+ * and every one landing on the employer/payer line about 200 characters above
+ * the figure:
+ *
+ *     claim 128450.00  ->  "tics LLC   EIN 84-2213907\nEmployee: Dana"
+ *     claim 812.44     ->  "nt Savings Bank   TIN 22-5510983\nRecip"
+ *     claim 2204.18    ->  "ndex Fund Trust   TIN 47-3320115\nRec"
+ *     claim 1955.02    ->  "pient: Dana R. Whitfield\n------------"
+ *
+ * That is strictly worse than a fabricated quote. A fabricated quote fails the
+ * verbatim gate; this one passes every gate, is real text from the right
+ * document, and reads to a reviewer as an authoritative citation while
+ * supporting nothing. `locator.find` (the platform locating a value the model
+ * names) prevents the model from ADDRESSING the wrong line, and it is the right
+ * primary fix. This module is the independent check underneath it: whatever
+ * anchoring form produced the text, the text has to contain the figure.
+ *
+ * That also settles what a raw `locator.span` is worth. Hand-computed offsets
+ * stay accepted, but only when they independently verify — which is exactly
+ * "the slice contains the claimed value".
+ *
+ * ── The rule, and why it is drawn here ──────────────────────────────────────
+ *
+ * Strict on figures, silent on everything else. An unsatisfiable gate does not
+ * stop a bad submit, it SELECTS for one — that is the measured mechanism behind
+ * the 38 fabricated quotes on row `a68b1943`, where a coverage gate demanded
+ * document lineage for computed values and got thirteen invented citations
+ * forty seconds later. So the rule fires only where an honest citation can
+ * always satisfy it:
+ *
+ *  - The claim IS a value (`"128450.00"`, `"$30,000"`, `"3"`) — the anchored
+ *    text MUST contain that value. No latitude. This is the shape every tax
+ *    figure takes and the shape row `7256ef49` failed.
+ *  - The claim is prose naming figures (`"indemnity capped at $5,000,000"`) —
+ *    at least one of its currency-shaped figures must occur. Not all of them:
+ *    a claim may legitimately narrate a computation over several lines while
+ *    anchoring to the one line under discussion, and refusing that would make
+ *    an honest citation unrepresentable for the sake of a stricter-sounding
+ *    rule. One is enough to keep the anchor tethered to the claim's subject.
+ *  - The claim carries no figure at all (`"Married Filing Jointly"`,
+ *    `"Dana R. Whitfield"`, `"2025-04-15"`) — nothing to check, and the entry
+ *    passes. A filing status has no number to find, and inventing a
+ *    word-overlap score here would re-open the hole the verbatim gate closes.
+ *  - The entry has no anchored text at all — nothing to check. A computed
+ *    value cites its computation, not a document.
+ *
+ * A bare year, a form number and a box number are deliberately NOT figures:
+ * `2025`, `1040` and `Box 1` have no thousands separator, no cent pair and no
+ * currency symbol, so prose mentioning them does not trip the rule.
+ *
+ * ── Matching is value-wise, never substring ─────────────────────────────────
+ *
+ * `text.includes(claim)` would be the obvious implementation and it is wrong in
+ * the direction that matters: it passes `"450.00"` against `"128,450.00"`, so a
+ * claim citing the wrong figure survives whenever its digits happen to be a tail
+ * of a real one. Both sides are tokenized into numbers and compared as VALUES,
+ * so `450` and `128450` are simply different.
+ */
+/**
+ * Reduce a numeric token to the form both sides are compared in: no currency,
+ * no grouping, no trailing zeros in the fraction, no leading zeros.
+ *
+ * Sign and accounting parentheses are stripped rather than preserved, so
+ * `(1,234.00)`, `-1,234.00` and `1,234.00` all reduce to `1234`. A document
+ * renders the same deduction all three ways depending on the form and the
+ * extractor, and the sign is a property of the TARGET LINE's semantics, not of
+ * the document's typography. Comparing magnitudes keeps those honest citations
+ * working, and it concedes nothing to fabrication: the digits still have to be
+ * the document's digits.
+ *
+ * Returns `null` for anything that is not a plain number.
+ */
+declare function canonicalizeValue(token: string): string | null;
+/** Every distinct value appearing in `text`, canonicalized. */
+declare function valuesInText(text: string): string[];
+/**
+ * The values a claim asserts, canonicalized — empty when the claim asserts no
+ * figure, which is the "nothing to check" case.
+ *
+ * A claim that is ENTIRELY one value yields that value (strict path). Otherwise
+ * only currency-shaped figures inside the prose count, so an assertion that
+ * merely mentions a year or a form number yields nothing.
+ */
+declare function claimValues(claim: string): string[];
+type ClaimSupport = 
+/** No figure to check: a non-numeric claim, or no anchored text. */
+{
+    status: 'not_applicable';
+} | {
+    status: 'supported';
+    matched: string;
+} | {
+    status: 'unsupported';
+    claimed: string[];
+    present: string[];
+};
+/**
+ * Does `quote` carry the figure `claim` asserts?
+ *
+ * `supported` requires ONE claimed value to occur, which is exact for the
+ * single-value claim (there is only one) and deliberate latitude for prose (see
+ * the rule note at the top of the file).
+ */
+declare function verifyClaimSupport(quote: string, claim: string): ClaimSupport;
+/**
+ * The sentence a model can act on without re-reading the document: what it
+ * claimed, what the line it cited actually says, what figures that line does
+ * carry, and the two ways out — cite the value, or drop the locator because the
+ * figure was computed. Naming both keeps the gate satisfiable, which is the
+ * property that stops it manufacturing the citation it screens for.
+ */
+declare function claimSupportErrorDetail(failure: Extract<ClaimSupport, {
+    status: 'unsupported';
+}>, quote: string): string;
+
 /**
  * Framework-neutral work-product review endpoints — the
  * `createInteractionAnswerRoute` factory pattern: web-standard
@@ -497,4 +642,4 @@ interface WorkProductRoutes {
 /** Create the work-product review endpoints over the store port and product seams */
 declare function createWorkProductRoutes(options: WorkProductRoutesOptions): WorkProductRoutes;
 
-export { type CreateWorkProductInput, EVIDENCE_COVERAGE_CHECK, EvidenceEntry, ExceptionEntry, type FinalizeWorkProductProvenanceInput, type InMemoryWorkProductStore, MAX_WORK_PRODUCT_BATCH, QUOTE_VERIFICATION_CHECK, QualityCheck, type SourceFindFailure, type SourceFindResult, type SourceSpanFailure, type SourceSpanResult, type SubmitWorkProductInput, TrustItem, WorkProductArtifact, WorkProductAuditEvent, type WorkProductAuthorizeArgs, type WorkProductOutcome, WorkProductPersistedPart, WorkProductProvenance, type WorkProductProvenanceBase, WorkProductRecord, type WorkProductRouteAuthorization, type WorkProductRoutes, type WorkProductRoutesOptions, type WorkProductService, type WorkProductServiceOptions, WorkProductStatus, WorkProductStorePort, type WorkProductToolConfig, type WorkProductVerdictBody, type WorkProductVerdictInput, buildWorkProductTools, canTransitionWorkProduct, createInMemoryWorkProductStore, createWorkProductRoutes, createWorkProductService, finalizeWorkProductProvenance, findSourceLine, isWorkProductTerminal, normalizeQuoteText, sliceSourceSpan, sourceContainsQuote, stampProvenance, validateWorkProductVerdictBody, workProductTrustInputs };
+export { CLAIM_SUPPORT_CHECK, type ClaimSupport, type CreateWorkProductInput, EVIDENCE_COVERAGE_CHECK, EvidenceEntry, ExceptionEntry, type FinalizeWorkProductProvenanceInput, type InMemoryWorkProductStore, MAX_WORK_PRODUCT_BATCH, QUOTE_VERIFICATION_CHECK, QualityCheck, type SourceFindFailure, type SourceFindResult, type SourceSpanFailure, type SourceSpanResult, type SubmitWorkProductInput, TrustItem, WorkProductArtifact, WorkProductAuditEvent, type WorkProductAuthorizeArgs, type WorkProductOutcome, WorkProductPersistedPart, WorkProductProvenance, type WorkProductProvenanceBase, WorkProductRecord, type WorkProductRouteAuthorization, type WorkProductRoutes, type WorkProductRoutesOptions, type WorkProductService, type WorkProductServiceOptions, WorkProductStatus, WorkProductStorePort, type WorkProductToolConfig, type WorkProductVerdictBody, type WorkProductVerdictInput, buildWorkProductTools, canTransitionWorkProduct, canonicalizeValue, claimSupportErrorDetail, claimValues, createInMemoryWorkProductStore, createWorkProductRoutes, createWorkProductService, finalizeWorkProductProvenance, findSourceLine, isWorkProductTerminal, normalizeQuoteText, sliceSourceSpan, sourceContainsQuote, stampProvenance, validateWorkProductVerdictBody, valuesInText, verifyClaimSupport, workProductTrustInputs };

package/dist/work-product/index.js

@@ -387,6 +387,64 @@ function workProductTrustInputs(records, verdictsFor) {
   return items;
 }
 
+// src/work-product/claim-support.ts
+var CURRENCY = /[$€£¥₹]/gu;
+var NUMBER_IN_TEXT = /[$€£¥₹]?\s*\d{1,3}(?:,\d{3})+(?:\.\d+)?|[$€£¥₹]?\s*\d+(?:\.\d+)?/gu;
+var FIGURE_IN_PROSE = /[$€£¥₹]\s*[-+]?\d[\d,]*(?:\.\d+)?|[-+]?\d{1,3}(?:,\d{3})+(?:\.\d+)?|[-+]?\d+\.\d{2}(?!\d)/gu;
+var WHOLE_VALUE = /^[$€£¥₹]?\s*[-+]?\s*(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?\s*%?$/u;
+function canonicalizeValue(token) {
+  let text = token.trim();
+  if (text.length === 0) return null;
+  if (/^\(.*\)$/u.test(text)) text = text.slice(1, -1).trim();
+  text = text.replace(CURRENCY, "").trim();
+  text = text.replace(/^[-+]\s*/u, "").trim();
+  text = text.replace(/%$/u, "").trim();
+  if (!/^(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?$/u.test(text)) return null;
+  text = text.replace(/,/gu, "");
+  if (text.includes(".")) text = text.replace(/0+$/u, "").replace(/\.$/u, "");
+  text = text.replace(/^0+(?=\d)/u, "");
+  return text.length === 0 ? null : text;
+}
+function valuesInText(text) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const match of text.matchAll(NUMBER_IN_TEXT)) {
+    const canonical = canonicalizeValue(match[0]);
+    if (canonical !== null) seen.add(canonical);
+  }
+  return [...seen];
+}
+function claimValues(claim) {
+  const trimmed = claim.trim();
+  if (WHOLE_VALUE.test(trimmed)) {
+    const whole = canonicalizeValue(trimmed);
+    if (whole !== null) return [whole];
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const match of trimmed.matchAll(FIGURE_IN_PROSE)) {
+    const canonical = canonicalizeValue(match[0]);
+    if (canonical !== null) seen.add(canonical);
+  }
+  return [...seen];
+}
+function verifyClaimSupport(quote, claim) {
+  if (quote.trim().length === 0) return { status: "not_applicable" };
+  const claimed = claimValues(claim);
+  if (claimed.length === 0) return { status: "not_applicable" };
+  const present = valuesInText(quote);
+  const matched = claimed.find((value) => present.includes(value));
+  if (matched !== void 0) return { status: "supported", matched };
+  return { status: "unsupported", claimed, present };
+}
+function excerpt(quote, limit = 120) {
+  const flat = quote.replace(/\s+/gu, " ").trim();
+  return flat.length <= limit ? flat : `${flat.slice(0, limit)}\u2026`;
+}
+function claimSupportErrorDetail(failure, quote) {
+  const wanted = failure.claimed.length === 1 ? failure.claimed[0] : `any of ${failure.claimed.join(", ")}`;
+  const carries = failure.present.length === 0 ? "that line carries no figure at all" : `the only figures on it are ${failure.present.join(", ")}`;
+  return `the cited text does not contain ${wanted}. It reads "${excerpt(quote)}", and ${carries}. Cite locator.find with the value exactly as it appears in the document and the platform will locate the right line for you. If this figure was COMPUTED rather than read from the document, omit the locator entirely and state the computation in claim.`;
+}
+
 // src/work-product/quote.ts
 var WHITESPACE = /[\s\p{Zs}\u2028\u2029\u200b-\u200d\ufeff]+/gu;
 var DASHES = /[\u2010-\u2015\u2212\ufe58\ufe63\uff0d]/gu;
@@ -403,6 +461,8 @@ function sourceContainsQuote(sourceText, quote) {
   if (normalizedQuote.length === 0) return false;
   return normalizeQuoteText(sourceText).includes(normalizedQuote);
 }
+var MIN_NEEDLE_LENGTH = 3;
+var MAX_AMBIGUOUS_MATCHES = 8;
 function lineAround(text, index) {
   let start = text.lastIndexOf("\n", index);
   start = start < 0 ? 0 : start + 1;
@@ -414,26 +474,41 @@ function lineAround(text, index) {
 function findSourceLine(sourceText, needle, occurrence = 1) {
   const trimmed = needle.trim();
   if (trimmed.length === 0) return { ok: false, failure: { reason: "blank_needle" } };
-  const positions = [];
-  for (let at = sourceText.indexOf(trimmed); at >= 0; at = sourceText.indexOf(trimmed, at + 1)) {
-    positions.push(at);
+  if (trimmed.length < MIN_NEEDLE_LENGTH) {
+    return { ok: false, failure: { reason: "not_distinctive", needle: trimmed, found: 0 } };
   }
-  if (positions.length === 0) {
-    const wanted = normalizeQuoteText(trimmed);
-    if (wanted.length > 0) {
-      let cursor = 0;
-      while (cursor <= sourceText.length) {
-        const bound2 = lineAround(sourceText, cursor);
-        const line = sourceText.slice(bound2.start, bound2.end);
-        if (normalizeQuoteText(line).includes(wanted) || normalizeQuoteText(line.replace(/,/gu, "")).includes(wanted)) {
-          positions.push(bound2.start);
-        }
-        if (bound2.end >= sourceText.length) break;
-        cursor = bound2.end + 1;
+  const eachLine = (visit) => {
+    let cursor = 0;
+    while (cursor <= sourceText.length) {
+      const bound2 = lineAround(sourceText, cursor);
+      visit(bound2, sourceText.slice(bound2.start, bound2.end));
+      if (bound2.end >= sourceText.length) break;
+      cursor = bound2.end + 1;
+    }
+  };
+  const positions = [];
+  const wantedValue = canonicalizeValue(trimmed);
+  if (wantedValue !== null) {
+    eachLine((bound2, line) => {
+      if (valuesInText(line).includes(wantedValue)) positions.push(bound2.start);
+    });
+  } else {
+    for (let at = sourceText.indexOf(trimmed); at >= 0; at = sourceText.indexOf(trimmed, at + 1)) {
+      positions.push(at);
+    }
+    if (positions.length === 0) {
+      const wanted = normalizeQuoteText(trimmed);
+      if (wanted.length > 0) {
+        eachLine((bound2, line) => {
+          if (normalizeQuoteText(line).includes(wanted)) positions.push(bound2.start);
+        });
       }
     }
   }
   if (positions.length === 0) return { ok: false, failure: { reason: "not_found" } };
+  if (occurrence === 1 && positions.length > MAX_AMBIGUOUS_MATCHES) {
+    return { ok: false, failure: { reason: "not_distinctive", needle: trimmed, found: positions.length } };
+  }
   if (occurrence < 1 || occurrence > positions.length) {
     return { ok: false, failure: { reason: "occurrence_out_of_range", found: positions.length } };
   }
@@ -461,6 +536,7 @@ function sliceSourceSpan(sourceText, span) {
 var MAX_WORK_PRODUCT_BATCH = 50;
 var EVIDENCE_COVERAGE_CHECK = "evidence_coverage";
 var QUOTE_VERIFICATION_CHECK = "quote_verification";
+var CLAIM_SUPPORT_CHECK = "claim_support";
 async function unwrap(run, code) {
   let outcome = await run();
   if (!outcome.succeeded && outcome.conflict) outcome = await run();
@@ -527,6 +603,8 @@ function findErrorDetail(failure, needle) {
       return `${JSON.stringify(needle)} does not occur in that document. Read it again and cite a value it actually contains, or \u2014 if this figure is COMPUTED rather than read \u2014 omit the locator and state the computation in claim.`;
     case "occurrence_out_of_range":
       return `that value occurs ${failure.found} time(s) in the document; findOccurrence is out of range.`;
+    case "not_distinctive":
+      return failure.found === 0 ? `${JSON.stringify(failure.needle)} is too short to identify a place in the document \u2014 a digit or two matches somewhere in almost any text. Cite the labelled line instead (for example "Box 1   Wages, tips, other compensation ......... 128,450.00"). If the document does not state this value at all, omit the locator and say so in claim rather than pointing at an unrelated line.` : `${JSON.stringify(failure.needle)} occurs ${failure.found} times, so it names no particular place. Cite a longer stretch of the supporting line, or pass findOccurrence to say which one you mean.`;
   }
 }
 async function resolveEvidenceQuotes(config, entries, ctx) {
@@ -612,6 +690,20 @@ async function resolveEvidenceQuotes(config, entries, ctx) {
     entry.locator.quoteBasis = "model";
   }
 }
+function assertClaimsSupported(config, entries) {
+  if (config.verifyClaimSupport === false) return;
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    const quote = entry.locator.quote;
+    if (quote === void 0) continue;
+    const support = verifyClaimSupport(quote, entry.claim);
+    if (support.status !== "unsupported") continue;
+    throw new ToolInputError(
+      "claim_not_supported",
+      `entries[${index}].claim ${JSON.stringify(entry.claim)} is not supported by the text it cites in "${entry.sourceRef}": ${claimSupportErrorDetail(support, quote)}`
+    );
+  }
+}
 async function summarizeQuoteVerification(config, evidence, ctx) {
   const readSourceText = config.readSourceText;
   if (!readSourceText) return void 0;
@@ -646,6 +738,21 @@ async function summarizeQuoteVerification(config, evidence, ctx) {
   }
   return { verified, spanAnchored, withoutQuote, failed };
 }
+function summarizeClaimSupport(evidence) {
+  let supported = 0;
+  let checkable = 0;
+  const unsupported = [];
+  for (const entry of evidence) {
+    const quote = entry.locator.quote;
+    if (quote === void 0) continue;
+    const support = verifyClaimSupport(quote, entry.claim);
+    if (support.status === "not_applicable") continue;
+    checkable += 1;
+    if (support.status === "supported") supported += 1;
+    else unsupported.push(entry.id);
+  }
+  return { supported, checkable, unsupported };
+}
 function buildWorkProductTools(config) {
   const service = createWorkProductService({
     store: config.store,
@@ -726,6 +833,7 @@ function buildWorkProductTools(config) {
         }
       }
       await resolveEvidenceQuotes(config, entries, ctx);
+      assertClaimsSupported(config, entries);
       const draft = await resolveDraft(service, config, scopeKey, ctx);
       const record = await unwrap(() => service.upsertEvidence(draft.id, entries), "evidence_rejected");
       return {
@@ -885,6 +993,28 @@ function buildWorkProductTools(config) {
           );
         }
       }
+      if (config.verifyClaimSupport !== false) {
+        const support = summarizeClaimSupport(draft.evidence);
+        checks.unshift({
+          id: CLAIM_SUPPORT_CHECK,
+          name: CLAIM_SUPPORT_CHECK,
+          passed: support.unsupported.length === 0,
+          detail: support.unsupported.length > 0 ? `Cited text does not contain the claimed figure on: ${support.unsupported.join(", ")}` : support.checkable === 0 ? (
+            // Honest about a vacuous pass: no entry paired a quote with a
+            // figure, so nothing was checked. Reporting "0/0 verified"
+            // would read to a reviewer as assurance that was never earned.
+            "No citation pairs a quote with a claimed figure \u2014 nothing to check"
+          ) : `${support.supported}/${support.checkable} value-bearing citations anchor to text containing the claimed figure`,
+          source: "platform"
+        });
+        if (support.unsupported.length > 0) {
+          await unwrap(() => service.recordChecks(draft.id, checks), "checks_rejected");
+          throw new ToolInputError(
+            "claim_not_supported",
+            `Cannot submit: ${support.unsupported.length} evidence entr${support.unsupported.length === 1 ? "y cites" : "ies cite"} text that does not contain the figure claimed (${support.unsupported.join(", ")}). Re-emit each with locator.find set to the value exactly as it appears in the document, or without a locator if the figure was computed rather than read.`
+          );
+        }
+      }
       if (config.materialTargets) {
         const targets = config.materialTargets(artifact);
         const covered = new Set(draft.evidence.map((entry) => entry.target));
@@ -1031,11 +1161,15 @@ function createWorkProductRoutes(options) {
   return { list, detail, verdict };
 }
 export {
+  CLAIM_SUPPORT_CHECK,
   EVIDENCE_COVERAGE_CHECK,
   MAX_WORK_PRODUCT_BATCH,
   QUOTE_VERIFICATION_CHECK,
   buildWorkProductTools,
   canTransitionWorkProduct,
+  canonicalizeValue,
+  claimSupportErrorDetail,
+  claimValues,
   createInMemoryWorkProductStore,
   createWorkProductRoutes,
   createWorkProductService,
@@ -1056,6 +1190,8 @@ export {
   stampProvenance,
   unresolvedBlockingExceptions,
   validateWorkProductVerdictBody,
+  valuesInText,
+  verifyClaimSupport,
   workProductToPersistedPart,
   workProductTrustInputs
 };