@things-factory/ai-assistant 10.1.99 → 10.1.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.99",
+  "version": "10.1.100",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -51,5 +51,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "15e86d38824d6d2af94043eb14a928232a8924a3"
+  "gitHead": "e3c2444ded42290fdc77b189f5befa419f575f9b"
 }

package/server/service/data-entry/data-entry-update.test.ts

@@ -3,7 +3,7 @@
  * and what is asked again before a record is changed.
  */
 import { clearEntryTargets, declareEntryTarget, changeToolName, findToolName, type EntryTarget } from './entry-target'
-import { entryCategoryOf } from './entry-tools'
+import { entryCategoryOf, proposeEntries } from './entry-tools'
 import { changeRows, findRecords, proposeChanges, resolveChangeRefs, stillAsProposed } from './entry-update'
 import { applyEntryProposal, type EntryApplyDeps } from './entry-apply'
 
@@ -205,3 +205,63 @@ describe('the tool schemas', () => {
     for (const spec of entryCategoryOf(expense, () => run).specs as any[]) expect(typesOf(spec.schema)).toEqual([])
   })
 })
+
+describe('a field that points at another record', () => {
+  const loans: Record<string, any> = { a: { id: 'loan-a', name: '기업은행 운전자금' }, b: { id: 'loan-b', name: '중진공 시설자금' }, c: { id: 'loan-c', name: '기업은행 시설자금' } }
+  const lookup = async (document: string, variables: any) => {
+    calls.push({ document, variables })
+    if (document.includes('loans(')) return { data: { loans: Object.values(loans).filter(one => one.name.includes(variables.text)) } }
+    return run(document, variables)
+  }
+  const repayment: EntryTarget = {
+    key: 'office.loan-repayment',
+    labelKey: 'x',
+    description: 'one repayment.',
+    mutation: 'mutation ($r: NewLoanRepayment!) { createLoanRepayment(loanRepayment: $r) { id } }',
+    variables: row => ({ r: { ...row.values, loan: { id: (row.values.loan as any).id } } }),
+    fields: [
+      { name: 'loan', type: 'reference', required: true, reference: { query: 'query ($text: String) { loans(text: $text) { id name } }', variables: text => ({ text }), recordsOf: (data, text) => data.loans.filter((one: any) => one.name.includes(text)).map((one: any) => ({ id: one.id, label: one.name })) } },
+      { name: 'dueDate', type: 'date', required: true },
+      { name: 'principal', type: 'number' }
+    ]
+  }
+
+  it('★ one match keeps its id and name; none or several keep the row out, several with their names - the server never picks', async () => {
+    const result: any = await proposeEntries(
+      repayment,
+      { rows: [{ values: { loan: '중진공', dueDate: '2026-10-25', principal: 1 }, sources: [{ where: 'x' }] }, { values: { loan: '기업은행', dueDate: '2026-10-25' }, sources: [{ where: 'x' }] }, { values: { loan: '신한', dueDate: '2026-10-25' }, sources: [{ where: 'x' }] }] },
+      { state: {} },
+      async () => new Map(),
+      lookup
+    )
+    expect(result.rows[0].values.loan).toEqual({ id: 'loan-b', label: '중진공 시설자금' })
+    expect(result.rows[0].issues).toEqual([])
+    expect(result.rows[1].issues).toEqual([{ field: 'loan', code: 'reference-ambiguous', params: { text: '기업은행', candidates: '기업은행 운전자금, 기업은행 시설자금' }, blocking: true }])
+    expect(result.rows[2].issues).toEqual([{ field: 'loan', code: 'reference-not-found', params: { text: '신한' }, blocking: true }])
+    expect(result.counts).toMatchObject({ ready: 1, blocked: 2 })
+  })
+
+  it("★ the tool carries the reference query's door too - reading the names is the person's privilege", () => {
+    expect((entryCategoryOf(repayment, () => lookup).specs[0] as any).doors).toEqual(['Mutation.createLoanRepayment', 'Query.loans'])
+  })
+
+  it('a declaration whose reference has no query is refused at boot', () => {
+    expect(() => declareEntryTarget({ ...repayment, fields: [{ name: 'loan', type: 'reference' }] as any })).toThrow(/reference field 'loan'/)
+  })
+
+  it('the entering passes the resolved id, never the name', async () => {
+    declareEntryTarget(repayment)
+    const proposed: any = await proposeEntries(repayment, { rows: [{ values: { loan: '중진공', dueDate: '2026-10-25' }, sources: [{ where: 'x' }] }] }, { state: {} }, async () => new Map(), lookup)
+    const sent: any[] = []
+    const outcome = await applyEntryProposal('r1', {
+      messages: [{ id: 'm1', proposals: [{ ...proposed, key: 'r1' }] }],
+      answered: false,
+      passesDoor: async () => true,
+      execute: async (document, variables) => (document.includes('createLoanRepayment') ? (sent.push(variables), { data: { createLoanRepayment: { id: 'x' } } }) : lookup(document, variables)),
+      state: {}
+    })
+    expect(outcome).toMatchObject({ verdict: 'accepted', applied: 1 })
+    expect(sent[0].r.loan).toEqual({ id: 'loan-b' })
+  })
+})
+

package/server/service/data-entry/data-entry.test.ts

@@ -2,7 +2,7 @@
  * Data entry from material (design/ai/data-entry.md) - the rules a row passes, what the tool hands back,
  * and what the server asks again before it writes.
  */
-import { clearEntryTargets, declareEntryTarget, entryDoorOf, entryToolName, entryTotals, lineHas, normalizeEntryRows, verifyRowsAgainstSources, writtenForms, type EntryTarget } from './entry-target'
+import { clearEntryTargets, declareEntryTarget, entryDoorOf, entryToolName, entryTotals, lineHas, normalizeEntryRows, printedTotalOf, verifyRowsAgainstSources, writtenForms, type EntryTarget } from './entry-target'
 import { entryCategoryOf, proposeEntries } from './entry-tools'
 import { applyEntryProposal, entryProposalAnswered, findEntryProposal, type EntryApplyDeps } from './entry-apply'
 import { modeToolCategories } from '../assistant-mode/resolve'
@@ -237,6 +237,7 @@ describe('checking the rows against the material', () => {
       texts
     )
     expect(row.issues).toEqual([{ code: 'source-scattered', blocking: false }])
+    expect(row.sources).toEqual([{ attachmentId: 'a1', where: 'row 2' }, { person: true }])
   })
 
   it('a photo cannot be read here - the row says it was not checked', () => {
@@ -251,10 +252,12 @@ describe('checking the rows against the material', () => {
       { values: { amount: 500 }, sources: [{ where: 'x' }] }
     ])
     expect(entryTotals(rows, expense.fields, { field: 'amount', value: '21,400', attachmentId: 'a1' }, texts)).toEqual([
-      { field: 'amount', all: 21900, ready: 21400, declared: 21400, declaredFound: true, difference: -500 }
+      { field: 'amount', all: 21900, ready: 21400, declared: 21400, declaredFound: true, difference: -500, declaredBy: 'model' }
     ])
     expect(entryTotals(rows, expense.fields, { value: 30000, attachmentId: 'a1' }, texts)[0]).toMatchObject({ declared: 30000, declaredFound: false, difference: 8100 })
-    expect(entryTotals(rows, expense.fields, undefined, texts)).toEqual([{ field: 'amount', all: 21900, ready: 21400 }])
+    /* No total from the model: the server reads the file's own total line. */
+    expect(entryTotals(rows, expense.fields, undefined, texts)).toEqual([{ field: 'amount', all: 21900, ready: 21400, declared: 21400, declaredFound: true, declaredBy: 'file', difference: -500 }])
+    expect(entryTotals(rows, expense.fields, undefined, new Map())).toEqual([{ field: 'amount', all: 21900, ready: 21400 }])
   })
 
   it('the tool reads the cited files and puts the check and the totals on the card', async () => {
@@ -274,7 +277,7 @@ describe('checking the rows against the material', () => {
     expect(asked[0]).toEqual(['a1', 'a1', 'a1'])
     expect(result.counts).toMatchObject({ verified: 1, unmatched: 1 })
     expect(result.rows[0].evidence).toEqual({ attachmentId: 'a1', line: 2 })
-    expect(result.totals).toEqual([{ field: 'amount', all: 21900, ready: 21900, declared: 21400, declaredFound: true, difference: -500 }])
+    expect(result.totals).toEqual([{ field: 'amount', all: 21900, ready: 21900, declared: 21400, declaredFound: true, difference: -500, declaredBy: 'model' }])
     expect(result.message).toMatch(/differs from the rows by -500/)
   })
 })
@@ -318,3 +321,23 @@ describe('the card speaks the person\'s words', () => {
   })
 })
 
+describe('what the screen says for the model', () => {
+  it("★ the model's \"the person's message\" becomes the person flag - the screen words it, the model's English never shows", () => {
+    const { rows } = normalizeEntryRows(expense, [{ values: { spentOn: '2026-09-12', amount: 1 }, sources: [{ where: "the person's message" }, { person: true }, { attachmentId: 'a1', where: '3번째 줄' }] }])
+    expect(rows[0].sources).toEqual([{ person: true }, { person: true }, { attachmentId: 'a1', where: '3번째 줄' }])
+  })
+
+  it('reads a printed total line - the last amount on a line named 합계 or total', () => {
+    expect(printedTotalOf('a,1\n합계,,"50,900"')).toEqual({ value: 50900, line: 2 })
+    expect(printedTotalOf('Total amount: 1,234.50 KRW')).toEqual({ value: 1234.5, line: 1 })
+    expect(printedTotalOf('nothing like it here, 100')).toBeUndefined()
+  })
+})
+
+describe('the model names the total its own way', () => {
+  it("★ with one totalled field, the model's total counts whatever field name it wrote - 이용금액 is amount", () => {
+    const { rows } = normalizeEntryRows(expense, [{ values: { spentOn: '2026-09-12', amount: 100 }, sources: [{ where: 'x' }] }])
+    expect(entryTotals(rows, expense.fields, { field: '이용금액', value: '100' }, new Map())).toEqual([{ field: 'amount', all: 100, ready: 100, declared: 100, difference: 0, declaredBy: 'model' }])
+  })
+})
+

package/server/service/data-entry/entry-apply.ts

@@ -12,7 +12,7 @@
  */
 import { PROPOSAL_OUTCOME_PREFIX, PROPOSAL_VERDICTS } from '../chat-message/proposal-outcome.js'
 import { readRecords, stillAsProposed, type ChangeRow } from './entry-update.js'
-import { changeToolName, entryDoorOf, entryTargetOf, entryToolName, rootFieldOf, isBlocked, recordEntryEvent, normalizeEntryRows, withCheckedIssues, type EntryRow, type EntryTarget } from './entry-target.js'
+import { changeToolName, resolveReferences, entryDoorOf, entryTargetOf, entryToolName, rootFieldOf, isBlocked, recordEntryEvent, normalizeEntryRows, withCheckedIssues, type EntryRow, type EntryTarget } from './entry-target.js'
 
 export interface StoredProposalMessage {
   id: string
@@ -85,6 +85,8 @@ export async function applyEntryProposal(key: string, deps: EntryApplyDeps, targ
 
   /* Read again from the stored values - the same rules, and today's records for the target's checks. */
   let { rows } = normalizeEntryRows(target, (proposal.rows ?? []).map((row: EntryRow) => ({ values: row.values, sources: row.sources })))
+  /* A reference that was not settled on the card is asked again - never entered as a name. */
+  rows = await resolveReferences(target.fields, rows, deps.execute)
   if (target.check) {
     try {
       rows = withCheckedIssues(rows, await target.check(rows, { state: deps.state }))

package/server/service/data-entry/entry-target.ts

@@ -14,7 +14,7 @@
  */
 import { parse } from 'graphql'
 
-export type EntryFieldType = 'string' | 'text' | 'number' | 'integer' | 'date' | 'boolean' | 'enum'
+export type EntryFieldType = 'string' | 'text' | 'number' | 'integer' | 'date' | 'boolean' | 'enum' | 'reference'
 
 export interface EntryField {
   name: string
@@ -30,13 +30,35 @@ export interface EntryField {
   total?: boolean
   /** An enum's values on the card: `<prefix><value in lowercase>` - `text.expense-payment-` shows PERSONAL_CARD as 개인카드. */
   valueKeyPrefix?: string
+  /**
+   * A `reference` field points at another record - a loan, an item, a location. The model knows it by a name or
+   * a code; the server finds it through the application's query, as the person, and keeps its id. One match is
+   * taken; none or several keep the row out and say so - the server never picks among several.
+   */
+  reference?: EntryReference
+}
+
+export interface EntryReference {
+  query: string
+  /** The query's variables for what the model wrote - "기업은행", "A-100". */
+  variables(text: string): Record<string, unknown>
+  /** The records the answer holds that the text names - the application filters, the server does not guess. */
+  recordsOf(data: any, text: string): { id: string; label?: string }[]
+}
+
+/** A resolved reference, as a row keeps it. */
+export interface ReferenceValue {
+  id: string
+  label?: string
 }
 
 /** Where a row came from - which file, and where in it. Shown on the card beside the row. */
 export interface EntrySource {
   attachmentId?: string
-  /** "row 3", "the receipt photo", "the person's message" - the model's words. */
+  /** "row 3", "the receipt photo" - the model's words, in the person's language. */
   where?: string
+  /** The value came from what the person said in the conversation - shown in the screen's own words, never the model's. */
+  person?: boolean
 }
 
 export interface EntryIssue {
@@ -135,9 +157,9 @@ export type EntryRecord = { id: string } & Record<string, unknown>
  */
 export interface EntryUpdate {
   /** Reads the records by id, as the person - one they may not see is not found. */
-  read: { query: string; variables(ids: string[]): Record<string, unknown>; recordsOf(data: any): EntryRecord[] }
+  read: { query: string; variables(ids: string[]): Record<string, unknown>; recordsOf(data: any, ids: string[]): EntryRecord[] }
   /** Finds candidates from what the person said - "last week's 12,400 taxi". */
-  find?: { query: string; variables(criteria: Record<string, unknown>): Record<string, unknown>; recordsOf(data: any): EntryRecord[]; criteria: EntryField[] }
+  find?: { query: string; variables(criteria: Record<string, unknown>): Record<string, unknown>; recordsOf(data: any, criteria: Record<string, unknown>): EntryRecord[]; criteria: EntryField[] }
   /** The application's own mutation that changes one record. */
   mutation: string
   variables(change: { id: string; record: EntryRecord; values: Record<string, unknown> }): Record<string, unknown>
@@ -177,6 +199,9 @@ export async function recordEntryEvent(target: EntryTarget, event: EntryEvent, c
 
 export const DEFAULT_MAX_ROWS = 200
 
+/* The model's way of saying a value came from the person - kept only to read older rows and loose words. */
+const PERSON = /person|message|user|사용자|말/i
+
 const targets = new Map<string, EntryTarget>()
 
 const KEY = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/
@@ -208,6 +233,13 @@ export function declareEntryTarget(target: EntryTarget): void {
   if (!target.fields?.length) throw new Error(`[ai-assistant] entry target '${target.key}' declares no fields.`)
   const names = new Set<string>()
   for (const field of target.fields) {
+    if (field.type === 'reference') {
+      try {
+        rootFieldOf(field.reference?.query ?? '', 'query')
+      } catch (error: any) {
+        throw new Error(`[ai-assistant] entry target '${target.key}': reference field '${field.name}' ${error?.message ?? 'has no query'}.`)
+      }
+    }
     if (names.has(field.name)) throw new Error(`[ai-assistant] entry target '${target.key}' declares '${field.name}' twice.`)
     names.add(field.name)
     if (field.type === 'enum' && !field.values?.length)
@@ -306,6 +338,11 @@ export function readFieldValue(field: EntryField, value: unknown): { read?: unkn
     }
     case 'enum':
       return field.values!.includes(String(value).trim()) ? { read: String(value).trim() } : { code: 'not-in-list' }
+    case 'reference':
+      /* Resolved already ({ id }), or a name to look up ({ text }) - resolveReferences settles the second. */
+      if (value && typeof value === 'object' && typeof (value as any).id === 'string') return { read: { id: (value as any).id, ...((value as any).label ? { label: String((value as any).label) } : {}) } }
+      if (value && typeof value === 'object' && typeof (value as any).text === 'string') return { read: { text: (value as any).text } }
+      return typeof value === 'string' || typeof value === 'number' ? { read: { text: String(value).trim() } } : { code: 'not-a-reference' }
     default:
       return { read: String(value).trim() }
   }
@@ -315,6 +352,10 @@ export function readFieldValue(field: EntryField, value: unknown): { read?: unkn
 export function sameFieldValue(field: EntryField, a: unknown, b: unknown): boolean {
   if (empty(a) && empty(b)) return true
   if (empty(a) || empty(b)) return false
+  if (field.type === 'reference') {
+    const idOf = (v: any) => (v && typeof v === 'object' ? v.id ?? v.text : String(v))
+    return idOf(a) === idOf(b)
+  }
   const x = readFieldValue(field, a)
   const y = readFieldValue(field, b)
   return x.read !== undefined && y.read !== undefined ? x.read === y.read : String(a) === String(b)
@@ -357,11 +398,15 @@ export function normalizeEntryRows(target: EntryTarget, input: unknown): { rows:
 
     const sources: EntrySource[] = Array.isArray(raw?.sources)
       ? raw.sources
-          .filter((one: any) => one && (one.attachmentId || one.where))
-          .map((one: any) => ({
-            ...(typeof one.attachmentId === 'string' ? { attachmentId: one.attachmentId } : {}),
-            ...(typeof one.where === 'string' ? { where: one.where.slice(0, 120) } : {})
-          }))
+          .filter((one: any) => one && (one.attachmentId || one.where || one.person === true))
+          .map((one: any): EntrySource => {
+            /* "the person's message" written by the model is the person flag - the screen says it in its own words. */
+            if (one.person === true || (!one.attachmentId && typeof one.where === 'string' && PERSON.test(one.where))) return { person: true }
+            return {
+              ...(typeof one.attachmentId === 'string' ? { attachmentId: one.attachmentId } : {}),
+              ...(typeof one.where === 'string' ? { where: one.where.slice(0, 120) } : {})
+            }
+          })
       : []
     if (!sources.length) issues.push({ code: 'no-source', blocking: false })
 
@@ -390,7 +435,6 @@ export function isBlocked(row: EntryRow): boolean {
  * Names and descriptions are not looked for: the model tidies them, and a tidied name is not a wrong one.
  */
 
-const PERSON = /person|message|user|사용자|말/i
 
 /** The ways a number or a date is written in a file. */
 export function writtenForms(type: EntryFieldType, value: unknown): string[] {
@@ -462,7 +506,7 @@ export function verifyRowsAgainstSources(rows: EntryRow[], fields: EntryField[],
       if (at >= 0) return { ...row, evidence: { attachmentId: id, line: at + 1 } }
     }
 
-    const saidByPerson = row.sources.some(source => !source.attachmentId && PERSON.test(source.where ?? ''))
+    const saidByPerson = row.sources.some(source => source.person)
     const issues = [...row.issues]
     for (const one of forms) {
       const anywhere = readable.some(id => texts.get(id)!.split(/\r?\n/).some(line => lineHas(line, one.forms)))
@@ -473,6 +517,20 @@ export function verifyRowsAgainstSources(rows: EntryRow[], fields: EntryField[],
   })
 }
 
+/**
+ * The total a file prints - a line named 합계 · 총계 · 총액 · total · sum, and the last amount on it. The server
+ * reads it itself, so the card can compare even when the model did not say it (2026-10-01: once it did, once not).
+ */
+export function printedTotalOf(text: string): { value: number; line: number } | undefined {
+  const lines = text.split(/\r?\n/)
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!/(합\s*계|총\s*계|총\s*액|total|sum)/i.test(lines[i])) continue
+    const amounts = [...lines[i].matchAll(/-?\d{1,3}(?:,\d{3})+(?:\.\d+)?|-?\d+(?:\.\d+)?/g)].map(match => Number(match[0].replace(/,/g, '')))
+    if (amounts.length) return { value: amounts[amounts.length - 1], line: i + 1 }
+  }
+  return undefined
+}
+
 export interface EntryTotal {
   field: string
   /** The sum over every row, and over the rows that will be entered. */
@@ -483,6 +541,8 @@ export interface EntryTotal {
   declaredFound?: boolean
   /** declared - all. */
   difference?: number
+  /** Where the declared total came from - the model's reading, or the server's own from a file's total line. */
+  declaredBy?: 'model' | 'file'
 }
 
 /** The sums of the fields declared `total`, and how they stand against the total the material prints. */
@@ -492,13 +552,28 @@ export function entryTotals(
   declared: { field?: string; value?: unknown; attachmentId?: string } | undefined,
   texts: Map<string, string>
 ): EntryTotal[] {
-  return fields
-    .filter(field => field.total && (field.type === 'number' || field.type === 'integer'))
+  const totalled = fields.filter(field => field.total && (field.type === 'number' || field.type === 'integer'))
+  /* With one totalled field and no total from the model, the server looks for the file's own total line. */
+  const printed = !declared && totalled.length === 1 ? [...texts.values()].map(printedTotalOf).find(Boolean) : undefined
+  return totalled
     .map(field => {
       const sum = (list: EntryRow[]) => Math.round(list.reduce((acc, row) => acc + (typeof row.values[field.name] === 'number' ? (row.values[field.name] as number) : 0), 0) * 100) / 100
       const total: EntryTotal = { field: field.name, all: sum(rows), ready: sum(rows.filter(row => !isBlocked(row))) }
-      const value = declared && (declared.field ?? field.name) === field.name ? toNumber(declared.value) : undefined
+      if (printed) {
+        total.declared = printed.value
+        total.declaredFound = true
+        total.declaredBy = 'file'
+        total.difference = Math.round((printed.value - total.all) * 100) / 100
+        return total
+      }
+      /*
+       * With one totalled field the model's total is that field's, whatever it named it - on office's second card it
+       * wrote the file's column name (이용금액) for amount, and the total was dropped (2026-10-01).
+       */
+      const mine = declared && (totalled.length === 1 || (declared.field ?? field.name) === field.name)
+      const value = mine ? toNumber(declared!.value) : undefined
       if (value !== undefined) {
+        total.declaredBy = 'model'
         total.declared = value
         total.difference = Math.round((value - total.all) * 100) / 100
         const text = declared!.attachmentId ? texts.get(declared!.attachmentId) : undefined
@@ -508,3 +583,51 @@ export function entryTotals(
     })
 }
 
+/** The doors of the queries a target's reference fields reach - the person must pass them too. */
+export function referenceDoorsOf(fields: EntryField[]): string[] {
+  return [...new Set(fields.filter(field => field.type === 'reference' && field.reference).map(field => rootFieldOf(field.reference!.query, 'query')))]
+}
+
+/**
+ * Settles each reference a row names by text, through the application's query as the person. One match keeps its
+ * id and name; none or several keep the row out - several with their names, so the person can say which.
+ */
+export async function resolveReferences<T extends { values: Record<string, unknown>; issues: EntryIssue[] }>(
+  fields: EntryField[],
+  rows: T[],
+  run: (document: string, variables: Record<string, unknown>) => Promise<{ data?: any; errors?: readonly { message: string }[] }>
+): Promise<T[]> {
+  const references = fields.filter(field => field.type === 'reference' && field.reference)
+  if (!references.length) return rows
+  const asked = new Map<string, { id: string; label?: string }[] | Error>()
+  for (const row of rows) {
+    for (const field of references) {
+      const value: any = row.values[field.name]
+      if (!value || typeof value !== 'object' || typeof value.text !== 'string') continue
+      const key = `${field.name}\u0000${value.text}`
+      if (!asked.has(key)) {
+        try {
+          const answer = await run(field.reference!.query, field.reference!.variables(value.text))
+          asked.set(key, answer.errors?.length ? new Error(answer.errors[0].message) : field.reference!.recordsOf(answer.data, value.text) ?? [])
+        } catch (error: any) {
+          asked.set(key, error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+      const found = asked.get(key)!
+      if (found instanceof Error) {
+        row.issues.push({ field: field.name, code: 'reference-unreadable', params: { text: value.text }, blocking: true })
+      } else if (found.length === 1) {
+        row.values[field.name] = { id: found[0].id, ...(found[0].label ? { label: found[0].label } : {}) }
+      } else {
+        row.issues.push({
+          field: field.name,
+          code: found.length ? 'reference-ambiguous' : 'reference-not-found',
+          params: { text: value.text, ...(found.length ? { candidates: found.slice(0, 5).map(one => one.label || one.id).join(', ') } : {}) },
+          blocking: true
+        })
+      }
+    }
+  }
+  return rows
+}
+

package/server/service/data-entry/entry-tools.ts

@@ -22,6 +22,8 @@ import {
   entryToolName,
   isBlocked,
   normalizeEntryRows,
+  referenceDoorsOf,
+  resolveReferences,
   recordEntryEvent,
   withCheckedIssues,
   type EntryField,
@@ -35,6 +37,7 @@ function fieldSchema(field: EntryField): any {
    * whole request with it: "12,400" or "₩12,400" is the model's to write as 12400 (2026-10-01, office).
    */
   const type = field.type === 'number' ? 'number' : field.type === 'integer' ? 'integer' : field.type === 'boolean' ? 'boolean' : 'string'
+  if (field.type === 'reference') return { type: 'string', description: [field.description, field.required ? 'required' : 'optional', 'the name or code as the material or the person gives it - the server finds the record'].filter(Boolean).join('. ') }
   const said = [
     field.description,
     field.required ? 'required' : 'optional',
@@ -61,7 +64,7 @@ export type SourceTextLoader = (attachmentIds: string[], context: any) => Promis
 
 const readSources: SourceTextLoader = async (ids, context) => (await import('./entry-sources.js')).loadSourceTexts(ids, context)
 
-export async function proposeEntries(target: EntryTarget, args: any, context: any, loadTexts: SourceTextLoader = readSources) {
+export async function proposeEntries(target: EntryTarget, args: any, context: any, loadTexts: SourceTextLoader = readSources, run?: GraphqlRunner) {
   const tool = entryToolName(target.key)
   const told = (event: Omit<Parameters<typeof recordEntryEvent>[1], 'phase' | 'tool'>) => recordEntryEvent(target, { phase: 'propose', tool, ...event }, { state: context?.state })
   const { rows: normalized, cut } = normalizeEntryRows(target, args?.rows)
@@ -74,7 +77,9 @@ export async function proposeEntries(target: EntryTarget, args: any, context: an
   const declared = args?.declaredTotal && typeof args.declaredTotal === 'object' ? args.declaredTotal : undefined
   const cited = [...normalized.flatMap(row => row.sources.map(source => source.attachmentId)), declared?.attachmentId].filter((id): id is string => typeof id === 'string' && !!id)
   const texts = cited.length ? await loadTexts(cited, context).catch(() => new Map<string, string>()) : new Map<string, string>()
-  const read = verifyRowsAgainstSources(normalized, target.fields, texts)
+  /* A name the model wrote for another record is settled to its id by the application's query, as the person. */
+  const resolved = await resolveReferences(target.fields, normalized, run ?? runAsCaller(context))
+  const read = verifyRowsAgainstSources(resolved, target.fields, texts)
 
   let rows: EntryRow[] = read
   let checkFailed: string | undefined
@@ -138,7 +143,7 @@ function changeSpecs(target: EntryTarget, run: (context: any) => GraphqlRunner):
       kind: 'read',
       name: changeToolName(target.key),
       /* The person must be able to read the records and change them by hand. */
-      doors: [rootFieldOf(update.mutation, 'mutation'), readDoor],
+      doors: [...new Set([rootFieldOf(update.mutation, 'mutation'), readDoor, ...referenceDoorsOf(changeableFields(target))])],
       description:
         `Propose changes to existing records: ${target.description} ` +
         'Name each record by ref: "current" (the one on screen), "selected" (every row selected on screen) or an id a find tool returned. ' +
@@ -183,7 +188,7 @@ export function entryCategoryOf(target: EntryTarget, run: (context: any) => Grap
     kind: 'read',
     name,
     /* The person must be able to enter these records themselves - the tool is not a second way in. */
-    doors: [entryDoorOf(target.mutation)],
+    doors: [entryDoorOf(target.mutation), ...referenceDoorsOf(target.fields)],
     description:
       `Propose records to enter: ${target.description} ` +
       'Pass every record found in the material as one row. The rows are shown to the person as a card; nothing is written until they press it.',
@@ -202,8 +207,15 @@ export function entryCategoryOf(target: EntryTarget, run: (context: any) => Grap
               },
               sources: {
                 type: 'array',
-                description: 'Where this row came from: the attachment id and where in it ("row 3", "the receipt photo"), or where: "the person\'s message".',
-                items: { type: 'object', properties: { attachmentId: { type: 'string' }, where: { type: 'string' } } }
+                description: 'Where this row came from: the attachment id and where in it, and { person: true } for a value the person said.',
+                items: {
+                  type: 'object',
+                  properties: {
+                    attachmentId: { type: 'string' },
+                    where: { type: 'string', description: 'Where in the attachment, in the person\'s language ("3번째 줄", "영수증 사진").' },
+                    person: { type: 'boolean', description: 'true when the value came from what the person said in the conversation.' }
+                  }
+                }
               }
             },
             required: ['values', 'sources']
@@ -223,7 +235,7 @@ export function entryCategoryOf(target: EntryTarget, run: (context: any) => Grap
       },
       required: ['rows']
     },
-    builder: (args: any, context: any) => proposeEntries(target, args, context)
+    builder: (args: any, context: any) => proposeEntries(target, args, context, readSources, run(context))
   } as ToolSpec
 
   return {
@@ -232,8 +244,8 @@ export function entryCategoryOf(target: EntryTarget, run: (context: any) => Grap
     guidance: [
       `- When the person gives material to enter as records (files, photos, pasted text), read all of it first - call readChatAttachment for a file sent in an earlier turn - then call ${name} once with every record as a row.`,
       '- Never invent a value. Leave a field out when the material does not say it; the card marks it, and you ask the person for it.',
-      '- Give each row its sources: which attachment and where in it. A value the person gave or corrected in the conversation adds the source where: "the person\'s message". The server looks for each row\'s numbers and dates in the cited file and marks what it does not find.',
-      '- When the material prints a total, pass it as declaredTotal exactly as printed - do not add it up yourself.',
+      '- Give each row its sources: which attachment and where in it, written in the person\'s language. A value the person gave or corrected in the conversation adds the source { person: true }. The server looks for each row\'s numbers and dates in the cited file and marks what it does not find.',
+      '- When the material prints a total, always pass it as declaredTotal exactly as printed - do not add it up yourself. The server also reads a total line of a text file itself.',
       `- ${name} only proposes. Nothing is entered until the person presses the button on the card - never say the records were entered.`,
       `- When the person corrects or drops rows, call ${name} again with the whole corrected set. The newest card replaces the earlier ones; an earlier card can no longer be entered.`,
       ...(target.update

package/server/service/data-entry/entry-update.ts

@@ -13,6 +13,7 @@ import {
   changeToolName,
   findToolName,
   readFieldValue,
+  resolveReferences,
   sameFieldValue,
   type EntryField,
   type EntryIssue,
@@ -85,7 +86,7 @@ export async function readRecords(target: EntryTarget, ids: string[], run: Graph
   const update = target.update!
   const answer = await run(update.read.query, update.read.variables([...new Set(ids)]))
   if (answer.errors?.length) throw new Error(answer.errors.map(one => one.message).join('; '))
-  return new Map((update.read.recordsOf(answer.data) ?? []).filter(record => record && typeof record.id === 'string').map(record => [record.id, record]))
+  return new Map((update.read.recordsOf(answer.data, [...new Set(ids)]) ?? []).filter(record => record && typeof record.id === 'string').map(record => [record.id, record]))
 }
 
 /** The change rows against what the records hold now. */
@@ -146,7 +147,7 @@ export async function proposeChanges(target: EntryTarget, args: any, context: an
   } catch (error: any) {
     return { rejected: true, error: 'read-failed', message: `could not read the records: ${error?.message ?? error}` }
   }
-  const rows = changeRows(target, picked, records)
+  const rows = await resolveReferences(changeableFields(target), changeRows(target, picked, records), run)
   const blocked = rows.filter(blockedChange).length
   return {
     proposed: true,
@@ -181,7 +182,7 @@ export async function findRecords(target: EntryTarget, args: any, run: GraphqlRu
   }
   const answer = await run(find.query, find.variables(criteria))
   if (answer.errors?.length) return { rejected: true, error: 'find-failed', message: answer.errors.map(one => one.message).join('; ') }
-  const found = (find.recordsOf(answer.data) ?? []).filter(record => record && typeof record.id === 'string')
+  const found = (find.recordsOf(answer.data, criteria) ?? []).filter(record => record && typeof record.id === 'string')
   return {
     total: found.length,
     candidates: found.slice(0, MAX_CANDIDATES).map(record => ({ id: record.id, ...(target.update?.labelOf ? { label: target.update.labelOf(record) } : {}), record })),

package/translations/en.json

@@ -267,5 +267,11 @@
   "ai-assistant.entry.issue.changed-since": "changed since the card was made",
   "ai-assistant.entry.issue.no-change": "already that value",
   "ai-assistant.entry.issue.nothing-to-change": "nothing to change",
-  "ai-assistant.entry.issue.not-changeable": "this field cannot be changed - left out"
+  "ai-assistant.entry.issue.not-changeable": "this field cannot be changed - left out",
+  "ai-assistant.entry.source-person": "said in the conversation",
+  "ai-assistant.entry.total-declared-file": "the file's total line {sum}",
+  "ai-assistant.entry.issue.reference-not-found": "\"{text}\" - not found",
+  "ai-assistant.entry.issue.reference-ambiguous": "\"{text}\" - matches several: {candidates}",
+  "ai-assistant.entry.issue.reference-unreadable": "\"{text}\" - could not be looked up",
+  "ai-assistant.entry.issue.not-a-reference": "not a record it can point to"
 }

package/translations/ja.json

@@ -267,5 +267,11 @@
   "ai-assistant.entry.issue.changed-since": "その間に変更されました",
   "ai-assistant.entry.issue.no-change": "すでにその値です",
   "ai-assistant.entry.issue.nothing-to-change": "修正する項目がありません",
-  "ai-assistant.entry.issue.not-changeable": "修正できない項目のため除外しました"
+  "ai-assistant.entry.issue.not-changeable": "修正できない項目のため除外しました",
+  "ai-assistant.entry.source-person": "会話で伝えた値",
+  "ai-assistant.entry.total-declared-file": "資料の合計行 {sum}",
+  "ai-assistant.entry.issue.reference-not-found": "「{text}」— 見つかりません",
+  "ai-assistant.entry.issue.reference-ambiguous": "「{text}」— 複数に一致: {candidates}",
+  "ai-assistant.entry.issue.reference-unreadable": "「{text}」— 検索できませんでした",
+  "ai-assistant.entry.issue.not-a-reference": "参照先の記録が分かりません"
 }

package/translations/ko.json

@@ -267,5 +267,11 @@
   "ai-assistant.entry.issue.changed-since": "그사이 바뀌었습니다",
   "ai-assistant.entry.issue.no-change": "이미 그 값입니다",
   "ai-assistant.entry.issue.nothing-to-change": "고칠 칸이 없습니다",
-  "ai-assistant.entry.issue.not-changeable": "고칠 수 없는 칸이라 뺐습니다"
+  "ai-assistant.entry.issue.not-changeable": "고칠 수 없는 칸이라 뺐습니다",
+  "ai-assistant.entry.source-person": "대화에서 말한 값",
+  "ai-assistant.entry.total-declared-file": "자료의 합계 줄 {sum}",
+  "ai-assistant.entry.issue.reference-not-found": "\"{text}\" — 찾지 못했습니다",
+  "ai-assistant.entry.issue.reference-ambiguous": "\"{text}\" — 여럿과 맞습니다: {candidates}",
+  "ai-assistant.entry.issue.reference-unreadable": "\"{text}\" — 찾아보지 못했습니다",
+  "ai-assistant.entry.issue.not-a-reference": "가리키는 기록을 알 수 없습니다"
 }

package/translations/ms.json

@@ -267,5 +267,11 @@
   "ai-assistant.entry.issue.changed-since": "telah berubah sejak kad dibuat",
   "ai-assistant.entry.issue.no-change": "sudah nilai itu",
   "ai-assistant.entry.issue.nothing-to-change": "tiada yang perlu diubah",
-  "ai-assistant.entry.issue.not-changeable": "medan ini tidak boleh diubah - ditinggalkan"
+  "ai-assistant.entry.issue.not-changeable": "medan ini tidak boleh diubah - ditinggalkan",
+  "ai-assistant.entry.source-person": "dinyatakan dalam perbualan",
+  "ai-assistant.entry.total-declared-file": "baris jumlah fail {sum}",
+  "ai-assistant.entry.issue.reference-not-found": "\"{text}\" - tidak ditemui",
+  "ai-assistant.entry.issue.reference-ambiguous": "\"{text}\" - sepadan dengan beberapa: {candidates}",
+  "ai-assistant.entry.issue.reference-unreadable": "\"{text}\" - tidak dapat dicari",
+  "ai-assistant.entry.issue.not-a-reference": "bukan rekod yang boleh dirujuk"
 }

package/translations/zh.json

@@ -267,5 +267,11 @@
   "ai-assistant.entry.issue.changed-since": "在此期间已被修改",
   "ai-assistant.entry.issue.no-change": "已是该值",
   "ai-assistant.entry.issue.nothing-to-change": "没有要修改的字段",
-  "ai-assistant.entry.issue.not-changeable": "此字段不可修改，已忽略"
+  "ai-assistant.entry.issue.not-changeable": "此字段不可修改，已忽略",
+  "ai-assistant.entry.source-person": "对话中提供的值",
+  "ai-assistant.entry.total-declared-file": "资料合计行 {sum}",
+  "ai-assistant.entry.issue.reference-not-found": "\"{text}\" — 未找到",
+  "ai-assistant.entry.issue.reference-ambiguous": "\"{text}\" — 匹配多个：{candidates}",
+  "ai-assistant.entry.issue.reference-unreadable": "\"{text}\" — 无法查找",
+  "ai-assistant.entry.issue.not-a-reference": "无法确定所指记录"
 }