@things-factory/ai-assistant 10.1.99 → 10.1.101

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.99",
+  "version": "10.1.101",
   "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": "44abc5cac98642b8028b17bf3e019d083539ccab"
 }

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,109 @@ 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' })
+  })
+})
+
+describe('a record with lines', () => {
+  const advice: EntryTarget = {
+    key: 'warehouse.inbound-advice',
+    labelKey: 'x',
+    description: 'one inbound advice line.',
+    mutation: 'mutation ($advice: InboundAdviceInput!) { receiveInboundAdvice(advice: $advice) { name } }',
+    fields: [
+      { name: 'despatchAdvice', type: 'string', required: true },
+      { name: 'epcClass', type: 'string', required: true },
+      { name: 'quantity', type: 'number', required: true }
+    ],
+    group: {
+      by: 'despatchAdvice',
+      variables: rows => ({ advice: { name: rows[0].values.despatchAdvice, lines: rows.map(row => ({ epcClass: row.values.epcClass, quantity: row.values.quantity })) } }),
+      appliedOf: data => ({ id: data?.receiveInboundAdvice?.name })
+    }
+  }
+  const line = (despatchAdvice: string, epcClass: string, quantity: any) => ({ values: { despatchAdvice, epcClass, quantity }, sources: [{ where: 'x' }] })
+
+  it('★ the lines of one record go in by one call; a record with a line kept out stays out whole', async () => {
+    declareEntryTarget(advice)
+    const proposed: any = await proposeEntries(advice, { rows: [line('DA-1', 'A', 20), line('DA-1', 'B', 5), line('DA-2', 'C', 'many'), line('DA-2', 'D', 1)] }, { state: {} }, async () => new Map(), run)
+    expect(proposed.counts).toMatchObject({ rows: 4, groups: 2, groupsReady: 1 })
+    expect(proposed.groupBy).toBe('despatchAdvice')
+    const sent: any[] = []
+    const outcome = await applyEntryProposal('g1', {
+      messages: [{ id: 'm1', proposals: [{ ...proposed, key: 'g1' }] }],
+      answered: false,
+      passesDoor: async () => true,
+      execute: async (_document, variables) => (sent.push(variables), { data: { receiveInboundAdvice: { name: variables.advice.name } } }),
+      state: {}
+    })
+    expect(sent).toEqual([{ advice: { name: 'DA-1', lines: [{ epcClass: 'A', quantity: 20 }, { epcClass: 'B', quantity: 5 }] } }])
+    expect(outcome.rows).toEqual([
+      { index: 0, ok: true, id: 'DA-1' },
+      { index: 1, ok: true, id: 'DA-1' },
+      { index: 2, ok: false, error: 'quantity: not-a-number' },
+      { index: 3, ok: false, error: 'group-kept-out (row 3)' }
+    ])
+  })
+
+  it('a group by a field that is not declared is refused at boot', () => {
+    expect(() => declareEntryTarget({ ...advice, group: { ...advice.group!, by: 'order' } })).toThrow(/group by 'order'/)
+  })
+})
+

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,37 @@ 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' }])
+  })
+})
+
+describe('a moment', () => {
+  const shift: EntryTarget = { ...expense, fields: [{ name: 'startTime', type: 'datetime', required: true }] }
+  it('reads the ways a moment is written - without an offset it stays without one', () => {
+    const { rows } = normalizeEntryRows(shift, [
+      { values: { startTime: '2026-10-01 08:30' }, sources: [{ where: 'x' }] },
+      { values: { startTime: '2026.10.1 8:05:09' }, sources: [{ where: 'x' }] },
+      { values: { startTime: '2026-10-01T08:30:00+0900' }, sources: [{ where: 'x' }] },
+      { values: { startTime: '2026-10-01 25:00' }, sources: [{ where: 'x' }] }
+    ])
+    expect(rows.map(row => row.values.startTime)).toEqual(['2026-10-01T08:30:00', '2026-10-01T08:05:09', '2026-10-01T08:30:00+09:00', '2026-10-01 25:00'])
+    expect(rows[3].issues).toEqual([{ field: 'startTime', code: 'not-a-datetime', blocking: true }])
+  })
+})
+

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, entryGroups, 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 }))
@@ -95,14 +97,35 @@ export async function applyEntryProposal(key: string, deps: EntryApplyDeps, targ
   }
 
   const results: EntryRowResult[] = []
-  for (const row of rows) {
+  if (target.group) {
+    /* One call per group; a group with a row kept out stays out whole - an order missing a line is not entered. */
+    for (const [, members] of entryGroups(rows, target.group.by)) {
+      const blocked = members.find(isBlocked)
+      if (blocked) {
+        const issue = blocked.issues.find(one => one.blocking)!
+        for (const row of members)
+          results.push({ index: row.index, ok: false, error: row === blocked ? (issue.field ? `${issue.field}: ${issue.code}` : issue.code) : `group-kept-out (row ${blocked.index + 1})` })
+        continue
+      }
+      try {
+        const answer = await deps.execute(target.mutation, target.group.variables(members))
+        const error = answer.errors?.length ? answer.errors.map(one => one.message).join('; ') || 'refused' : undefined
+        const applied = error ? undefined : target.group.appliedOf?.(answer.data, members)
+        for (const row of members) results.push(error ? { index: row.index, ok: false, error } : { index: row.index, ok: true, ...(applied?.id ? { id: applied.id } : {}), ...(applied?.label ? { label: applied.label } : {}) })
+      } catch (error: any) {
+        for (const row of members) results.push({ index: row.index, ok: false, error: error?.message || 'refused' })
+      }
+    }
+    results.sort((a, b) => a.index - b.index)
+  }
+  for (const row of target.group ? [] : rows) {
     if (isBlocked(row)) {
       const issue = row.issues.find(one => one.blocking)!
       results.push({ index: row.index, ok: false, error: issue.field ? `${issue.field}: ${issue.code}` : issue.code })
       continue
     }
     try {
-      const answer = await deps.execute(target.mutation, target.variables(row))
+      const answer = await deps.execute(target.mutation, target.variables!(row))
       if (answer.errors?.length) {
         results.push({ index: row.index, ok: false, error: answer.errors.map(one => one.message).join('; ') || 'refused' })
         continue

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' | 'datetime' | '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 {
@@ -105,10 +127,20 @@ export interface EntryTarget {
    * to a person typing it in.
    */
   mutation: string
-  /** The mutation's variables for one row. */
-  variables(row: EntryRow): Record<string, unknown>
+  /** The mutation's variables for one row. Absent when the target enters rows by group (below). */
+  variables?(row: EntryRow): Record<string, unknown>
   /** What the conversation says of an entered row - its id and a short name. */
   appliedOf?(data: any, row: EntryRow): EntryApplied | undefined
+  /**
+   * A record with lines - one order, several item lines. Rows that share the value of `by` (the order number) are one
+   * record, entered by one call of the mutation with `variables(rows)`. If any row of a group is kept out, the whole
+   * group is: an order missing a line must not go in unseen.
+   */
+  group?: {
+    by: string
+    variables(rows: EntryRow[]): Record<string, unknown>
+    appliedOf?(data: any, rows: EntryRow[]): EntryApplied | undefined
+  }
   /** At most this many rows in one proposal. Default 200. */
   maxRows?: number
   /**
@@ -135,9 +167,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 +209,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-]*$/
@@ -189,7 +224,10 @@ export function declareEntryTarget(target: EntryTarget): void {
   } catch (error: any) {
     throw new Error(`[ai-assistant] entry target '${target.key}': its mutation ${error?.message ?? 'does not parse'}.`)
   }
-  if (typeof target.variables !== 'function') throw new Error(`[ai-assistant] entry target '${target.key}' has no variables.`)
+  if (typeof target.variables !== 'function' && typeof target.group?.variables !== 'function')
+    throw new Error(`[ai-assistant] entry target '${target.key}' has no variables (per row, or per group).`)
+  if (target.group && !target.fields.some(field => field.name === target.group!.by))
+    throw new Error(`[ai-assistant] entry target '${target.key}': group by '${target.group.by}' is not a declared field.`)
   if (target.update) {
     for (const [what, document, operation] of [
       ['update.read', target.update.read?.query, 'query'],
@@ -208,6 +246,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)
@@ -276,6 +321,22 @@ function toDate(value: unknown): string | undefined {
   return `${match[1]}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`
 }
 
+/**
+ * A moment as `YYYY-MM-DDTHH:mm:ss`, with the offset when it was written - "2026-10-01 08:30", "2026.10.1 8:30",
+ * an ISO string. Without an offset it stays without one: the application reads it in its own time zone, as it
+ * reads a time typed into its own screen.
+ */
+function toDateTime(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const match = value.trim().match(/^(\d{4})[-./](\d{1,2})[-./](\d{1,2})[ T](\d{1,2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?\s*(Z|[+-]\d{2}:?\d{2})?$/)
+  if (!match) return undefined
+  const day = toDate(`${match[1]}-${match[2]}-${match[3]}`)
+  const [hour, minute, second] = [Number(match[4]), Number(match[5]), Number(match[6] ?? 0)]
+  if (!day || hour > 23 || minute > 59 || second > 59) return undefined
+  const offset = match[7] ? (match[7] === 'Z' ? 'Z' : match[7].replace(/^([+-]\d{2})(\d{2})$/, '$1:$2')) : ''
+  return `${day}T${String(hour).padStart(2, '0')}:${match[5]}:${String(second).padStart(2, '0')}${offset}`
+}
+
 function toBoolean(value: unknown): boolean | undefined {
   if (typeof value === 'boolean') return value
   if (typeof value !== 'string') return undefined
@@ -300,12 +361,21 @@ export function readFieldValue(field: EntryField, value: unknown): { read?: unkn
       const read = toDate(value)
       return read === undefined ? { code: 'not-a-date' } : { read }
     }
+    case 'datetime': {
+      const read = toDateTime(value)
+      return read === undefined ? { code: 'not-a-datetime' } : { read }
+    }
     case 'boolean': {
       const read = toBoolean(value)
       return read === undefined ? { code: 'not-a-boolean' } : { read }
     }
     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 +385,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 +431,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 +468,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[] {
@@ -408,6 +485,12 @@ export function writtenForms(type: EntryFieldType, value: unknown): string[] {
     }
     return [...forms].map(form => (negative ? `-${form}` : form))
   }
+  if (type === 'datetime') {
+    /* A moment is found by its day and its hh:mm - the file writes seconds and zones its own way. */
+    const match = typeof value === 'string' ? value.match(/^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})/) : null
+    if (!match) return []
+    return writtenForms('date', match[1])
+  }
   if (type === 'date') {
     const match = typeof value === 'string' ? value.match(/^(\d{4})-(\d{2})-(\d{2})$/) : null
     if (!match) return []
@@ -462,7 +545,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 +556,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 +580,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 +591,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 +622,62 @@ 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
+}
+
+/** The rows by group, in the order groups first appear - `[key, rows]`. A row without the key is a group of its own. */
+export function entryGroups<T extends { index: number; values: Record<string, unknown> }>(rows: T[], by: string): [string, T[]][] {
+  const groups = new Map<string, T[]>()
+  for (const row of rows) {
+    const value = row.values[by]
+    const key = value === undefined || value === null || value === '' ? `\u0000row-${row.index}` : String(typeof value === 'object' ? (value as any).id ?? (value as any).text : value)
+    groups.set(key, [...(groups.get(key) ?? []), row])
+  }
+  return [...groups.entries()]
+}
+