@things-factory/ai-assistant 10.1.91 → 10.1.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.91",
+  "version": "10.1.97",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -51,5 +51,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "e9a052f7faaeb5884db1ff8b862b8f05567a31f9"
+  "gitHead": "79bebdf2ce31c5e82134757678be2cc1bb6e4dec"
 }

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

@@ -0,0 +1,192 @@
+/*
+ * The 수정안 (design/ai/data-entry.md §5-1) - which record is meant is settled by the server, what the card shows,
+ * 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 { changeRows, findRecords, proposeChanges, resolveChangeRefs, stillAsProposed } from './entry-update'
+import { applyEntryProposal, type EntryApplyDeps } from './entry-apply'
+
+/* The application, as a fake: its records, its read query, its find query, its change mutation. */
+let records: Record<string, any>
+const calls: { document: string; variables: any }[] = []
+const run = async (document: string, variables: any) => {
+  calls.push({ document, variables })
+  if (document.includes('myExpenseLines')) {
+    const list = Object.values(records).filter(
+      (one: any) => (!variables.ids || variables.ids.includes(one.id)) && (!variables.merchant || one.merchant.includes(variables.merchant)) && (variables.amount === undefined || one.amount === variables.amount)
+    )
+    return { data: { myExpenseLines: list } }
+  }
+  if (variables.id === 'closed') return { errors: [{ message: 'a submitted claim cannot be changed' }] }
+  records[variables.id] = { ...records[variables.id], ...variables.patch }
+  return { data: { changeExpenseLine: { id: variables.id } } }
+}
+
+const expense: EntryTarget = {
+  key: 'office.expense-line',
+  labelKey: 'office.entry.expense-line',
+  description: 'one expense.',
+  mutation: 'mutation ($line: NewExpenseLine!) { addExpenseLine(line: $line) { id } }',
+  variables: row => ({ line: row.values }),
+  fields: [
+    { name: 'spentDate', type: 'date', required: true },
+    { name: 'merchant', type: 'string' },
+    { name: 'amount', type: 'number', required: true },
+    { name: 'category', type: 'enum', values: ['교통비', '회의비'] }
+  ],
+  update: {
+    read: { query: 'query ($ids: [String!]) { myExpenseLines(ids: $ids) { id spentDate merchant amount category } }', variables: ids => ({ ids }), recordsOf: data => data.myExpenseLines },
+    find: {
+      query: 'query ($merchant: String, $amount: Float) { myExpenseLines(merchant: $merchant, amount: $amount) { id spentDate merchant amount category } }',
+      variables: criteria => criteria,
+      recordsOf: data => data.myExpenseLines,
+      criteria: [
+        { name: 'merchant', type: 'string' },
+        { name: 'amount', type: 'number' }
+      ]
+    },
+    mutation: 'mutation ($id: String!, $patch: ExpenseLinePatch!) { changeExpenseLine(id: $id, patch: $patch) { id } }',
+    variables: change => ({ id: change.id, patch: change.values }),
+    labelOf: record => `${record.spentDate} · ${record.merchant}`,
+    fields: ['amount', 'category', 'merchant']
+  }
+}
+
+beforeEach(() => {
+  clearEntryTargets()
+  calls.length = 0
+  records = {
+    l1: { id: 'l1', spentDate: '2026-09-12', merchant: '카카오T', amount: '12400.00', category: '교통비' },
+    l2: { id: 'l2', spentDate: '2026-09-13', merchant: '카카오T', amount: 12400, category: '교통비' },
+    closed: { id: 'closed', spentDate: '2026-08-01', merchant: '스타벅스', amount: 5000, category: '회의비' }
+  }
+})
+
+describe('which record is meant', () => {
+  it('★ "current" and "selected" come from the screen, but only for this kind of record', () => {
+    const host = { record: { target: 'office.expense-line', id: 'l1' }, selection: { target: 'office.expense-line', ids: ['l1', 'l2'] } }
+    expect(resolveChangeRefs('office.expense-line', [{ ref: 'current', values: { amount: 1 } }, { ref: 'selected', values: { category: '회의비' } }], host).picked.map(one => `${one.via}:${one.id}`)).toEqual([
+      'current:l1',
+      'selected:l1',
+      'selected:l2'
+    ])
+    expect(resolveChangeRefs('office.expense-line', [{ ref: 'current', values: {} }], { record: { target: 'office.contract', id: 'c1' } }).unresolved).toEqual(['current'])
+  })
+
+  it('★ an id from the screen is only a candidate - a record the person cannot read is not found, and nothing is shown of it', async () => {
+    const result: any = await proposeChanges(expense, { changes: [{ ref: 'current', values: { amount: 13000 } }] }, { host: { record: { id: 'someone-elses' } } }, run)
+    expect(result.rows[0].issues).toEqual([{ code: 'record-not-found', blocking: true }])
+    expect(result.rows[0].before).toEqual({})
+    expect(calls[0].document).toContain('myExpenseLines(ids: $ids)')
+  })
+
+  it('no ref at all is refused, with the way to name one', async () => {
+    const result: any = await proposeChanges(expense, { changes: [{ values: { amount: 1 } }] }, { host: {} }, run)
+    expect(result).toMatchObject({ rejected: true, error: 'unresolved-no-ref' })
+    expect(result.message).toMatch(/never guess an id/i)
+  })
+
+  it('★ finding says how many match and asks the model to list them - it never picks one', async () => {
+    const two: any = await findRecords(expense, { merchant: '카카오', amount: '12,400' }, run)
+    expect(two.total).toBe(1)
+    const many: any = await findRecords(expense, { merchant: '카카오' }, run)
+    expect(many.total).toBe(2)
+    expect(many.message).toMatch(/ask which - never pick one yourself/)
+    expect(many.candidates.map((one: any) => one.label)).toEqual(['2026-09-12 · 카카오T', '2026-09-13 · 카카오T'])
+  })
+})
+
+describe('the card', () => {
+  it('★ shows what each record holds now and what it becomes - read by the server, "12400.00" is 12400', async () => {
+    const result: any = await proposeChanges(expense, { changes: [{ ref: 'l1', values: { amount: '13,000', category: '회의비' } }] }, { host: {} }, run)
+    expect(result).toMatchObject({ proposed: true, kind: 'entry', op: 'update', counts: { rows: 1, ready: 1, blocked: 0 } })
+    expect(result.rows[0]).toMatchObject({ id: 'l1', via: 'id', label: '2026-09-12 · 카카오T', before: { amount: '12400.00', category: '교통비' }, values: { amount: 13000, category: '회의비' }, issues: [] })
+    expect(result.columns.map((one: any) => one.name)).toEqual(['amount', 'category'])
+  })
+
+  it('a change to what it already is, a field that may not change, a value that does not fit - each said', () => {
+    const rows = changeRows(expense, [{ id: 'l1', via: 'id', values: { amount: 12400, spentDate: '2026-09-01' } }, { id: 'l2', via: 'id', values: { category: '식대' } }], new Map(Object.entries(records)) as any)
+    expect(rows[0].issues).toEqual([{ field: 'spentDate', code: 'not-changeable', blocking: false }, { code: 'no-change', blocking: true }])
+    expect(rows[1].issues).toEqual([{ field: 'category', code: 'not-in-list', params: { values: ['교통비', '회의비'] }, blocking: true }])
+  })
+})
+
+describe('changing what the person pressed', () => {
+  const card = async (changes: any[]) => ({ ...(await proposeChanges(expense, { changes }, { host: {} }, run)), key: 'u1' })
+  const deps = (proposal: any, over: Partial<EntryApplyDeps> = {}): EntryApplyDeps => ({
+    messages: [{ id: 'm1', proposals: [proposal] }],
+    answered: false,
+    passesDoor: async () => true,
+    execute: run,
+    state: {},
+    ...over
+  })
+
+  beforeEach(() => declareEntryTarget(expense))
+
+  it("★ reads each record again and changes it through the application's own mutation", async () => {
+    const proposal = await card([{ ref: 'l1', values: { amount: 13000 } }])
+    calls.length = 0
+    const outcome = await applyEntryProposal('u1', deps(proposal))
+    expect(outcome).toMatchObject({ verdict: 'accepted', applied: 1, missed: 0 })
+    expect(calls.map(one => one.document.match(/(myExpenseLines|changeExpenseLine)/)![1])).toEqual(['myExpenseLines', 'changeExpenseLine'])
+    expect(records.l1.amount).toBe(13000)
+  })
+
+  it('★ a record changed by someone else since the card was made is not overwritten unseen', async () => {
+    const proposal = await card([{ ref: 'l1', values: { amount: 13000 } }, { ref: 'l2', values: { amount: 9000 } }])
+    records.l1.amount = 15000
+    const outcome = await applyEntryProposal('u1', deps(proposal))
+    expect(outcome).toMatchObject({ verdict: 'accepted', applied: 1, missed: 1 })
+    expect(outcome.rows[0]).toEqual({ index: 0, ok: false, error: 'amount: changed-since' })
+    expect(records.l1.amount).toBe(15000)
+    expect(records.l2.amount).toBe(9000)
+  })
+
+  it("the application's own refusal is said by its place, and the others still change", async () => {
+    const proposal = await card([{ ref: 'closed', values: { amount: 6000 } }, { ref: 'l2', values: { amount: 9000 } }])
+    const outcome = await applyEntryProposal('u1', deps(proposal))
+    expect(outcome.rows[0]).toEqual({ index: 0, ok: false, error: 'a submitted claim cannot be changed' })
+    expect(outcome.rows[1]).toMatchObject({ ok: true, id: 'l2' })
+  })
+
+  it('★ both doors are asked again - the change mutation and the read query', async () => {
+    const proposal = await card([{ ref: 'l1', values: { amount: 13000 } }])
+    const asked: string[] = []
+    const outcome = await applyEntryProposal('u1', deps(proposal, { passesDoor: async door => (asked.push(door), door !== 'Query.myExpenseLines') }))
+    expect(outcome).toMatchObject({ verdict: 'refused', errorCode: 'door-closed' })
+    expect(asked).toEqual(['Mutation.changeExpenseLine', 'Query.myExpenseLines'])
+    expect(records.l1.amount).toBe('12400.00')
+  })
+
+  it('★ a newer 수정안 replaces an older one - an 입력안 of the same record does not', async () => {
+    const older = await card([{ ref: 'l1', values: { amount: 13000 } }])
+    const entry = { key: 'e1', kind: 'entry', target: 'office.expense-line', rows: [] }
+    const newer = { ...(await card([{ ref: 'l1', values: { amount: 14000 } }])), key: 'u2' }
+    expect(await applyEntryProposal('u1', deps(older, { messages: [{ id: 'm1', proposals: [older] }, { id: 'm2', proposals: [entry] }] }))).toMatchObject({ verdict: 'accepted' })
+    records.l1.amount = '12400.00'
+    expect(await applyEntryProposal('u1', deps(older, { messages: [{ id: 'm1', proposals: [older] }, { id: 'm2', proposals: [newer] }] }))).toMatchObject({ verdict: 'refused', errorCode: 'superseded' })
+  })
+})
+
+describe('declaring and offering', () => {
+  it('refuses an update whose documents could not work', () => {
+    expect(() => declareEntryTarget({ ...expense, update: { ...expense.update!, mutation: 'query { x { id } }' } })).toThrow(/update.mutation is not one mutation/)
+    expect(() => declareEntryTarget({ ...expense, update: { ...expense.update!, fields: ['nope'] } })).toThrow(/update field 'nope' is not declared/)
+  })
+
+  it("★ each tool carries the doors of what it reaches - changing needs both the change and the read", () => {
+    const specs = entryCategoryOf(expense, () => run).specs as any[]
+    expect(specs.map(spec => `${spec.name}:${spec.doors.join('+')}`)).toEqual([
+      'proposeOfficeExpenseLineEntries:Mutation.addExpenseLine',
+      `${changeToolName('office.expense-line')}:Mutation.changeExpenseLine+Query.myExpenseLines`,
+      `${findToolName('office.expense-line')}:Query.myExpenseLines`
+    ])
+  })
+
+  it('stillAsProposed marks a record gone since as not found', () => {
+    const rows = stillAsProposed(expense, [{ index: 0, id: 'gone', via: 'id', before: { amount: 1 }, values: { amount: 2 }, issues: [] }], new Map())
+    expect(rows[0].issues).toEqual([{ code: 'record-not-found', blocking: true }])
+  })
+})

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

@@ -11,7 +11,8 @@
  * Dependencies come in as arguments so the rules are tested without a database.
  */
 import { PROPOSAL_OUTCOME_PREFIX, PROPOSAL_VERDICTS } from '../chat-message/proposal-outcome.js'
-import { entryDoorOf, entryTargetOf, entryToolName, isBlocked, recordEntryEvent, normalizeEntryRows, withCheckedIssues, type EntryRow, type EntryTarget } from './entry-target.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'
 
 export interface StoredProposalMessage {
   id: string
@@ -42,10 +43,10 @@ export interface EntryApplyDeps {
   answered: boolean
   passesDoor(door: string): Promise<boolean>
   /**
-   * Runs the target's mutation for one row with the person's request state - the application's API, its
-   * directives and its own checks. Answers what GraphQL answers.
+   * Runs one of the application's queries or mutations with the person's request state - its API, its directives
+   * and its own checks. Answers what GraphQL answers.
    */
-  execute(mutation: string, variables: Record<string, unknown>): Promise<{ data?: any; errors?: readonly { message: string }[] }>
+  execute(document: string, variables: Record<string, unknown>): Promise<{ data?: any; errors?: readonly { message: string }[] }>
   state: any
   report?(message: string, error: unknown): void
 }
@@ -59,8 +60,10 @@ export function findEntryProposal(messages: StoredProposalMessage[], key: string
     for (const one of message.proposals ?? []) if (one?.key === key) (at = i), (proposal = one)
   })
   if (!proposal) return { superseded: false }
-  /* A later card for the same record replaces this one - entering both would enter the corrected rows twice. */
-  const superseded = messages.slice(at + 1).some(message => (message.proposals ?? []).some(one => one?.kind === 'entry' && one?.target === proposal.target))
+  /* A later card of the same record and the same work replaces this one - pressing both would do the corrected work twice. */
+  const superseded = messages
+    .slice(at + 1)
+    .some(message => (message.proposals ?? []).some(one => one?.kind === 'entry' && one?.target === proposal.target && (one?.op ?? 'create') === (proposal.op ?? 'create')))
   return { proposal, superseded }
 }
 
@@ -73,6 +76,7 @@ export async function applyEntryProposal(key: string, deps: EntryApplyDeps, targ
 
   const target = targetOf(proposal.target)
   if (!target) return nothing('unavailable', 'unknown-entry-target')
+  if (proposal.op === 'update') return applyChanges(key, proposal, target, deps)
   const door = entryDoorOf(target.mutation)
   if (!(await deps.passesDoor(door))) {
     await recordEntryEvent(target, { phase: 'apply', tool: entryToolName(target.key), rows: 0, ok: false, error: 'door-closed', detail: { proposalKey: key } }, { state: deps.state })
@@ -132,3 +136,56 @@ export function entryProposalAnswered(key: string, lines: readonly (string | nul
     return PROPOSAL_VERDICTS.some(verdict => rest === verdict || rest.startsWith(`${verdict} `))
   })
 }
+
+/**
+ * A pressed 수정안: the doors again, each record read again as the person, a field that moved since the card was
+ * made keeps its row out (`changed-since`), and each record is changed by the application's own mutation.
+ */
+async function applyChanges(key: string, proposal: any, target: EntryTarget, deps: EntryApplyDeps): Promise<EntryApplyOutcome> {
+  const tool = changeToolName(target.key)
+  const update = target.update
+  if (!update) return nothing('unavailable', 'target-does-not-change')
+  for (const door of [rootFieldOf(update.mutation, 'mutation'), rootFieldOf(update.read.query, 'query')]) {
+    if (!(await deps.passesDoor(door))) {
+      await recordEntryEvent(target, { phase: 'apply', tool, rows: 0, ok: false, error: 'door-closed', detail: { proposalKey: key } }, { state: deps.state })
+      return nothing('refused', 'door-closed')
+    }
+  }
+
+  const stored: ChangeRow[] = proposal.rows ?? []
+  let now
+  try {
+    now = await readRecords(target, stored.map(row => row.id), deps.execute)
+  } catch (error) {
+    deps.report?.(`[ai-assistant] reading '${target.key}' again failed`, error)
+    return nothing('refused', 'read-failed')
+  }
+
+  const results: EntryRowResult[] = []
+  for (const row of stillAsProposed(target, stored, now)) {
+    if (row.issues.some(one => one.blocking)) {
+      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(update.mutation, update.variables({ id: row.id, record: row.now!, values: row.values }))
+      if (answer.errors?.length) {
+        results.push({ index: row.index, ok: false, error: answer.errors.map(one => one.message).join('; ') || 'refused' })
+        continue
+      }
+      results.push({ index: row.index, ok: true, id: row.id, ...(row.label ? { label: row.label } : {}) })
+    } catch (error: any) {
+      results.push({ index: row.index, ok: false, error: error?.message || 'refused' })
+    }
+  }
+
+  const applied = results.filter(one => one.ok).length
+  const missed = results.length - applied
+  await recordEntryEvent(
+    target,
+    { phase: 'apply', tool, rows: results.length, ok: applied > 0, applied, missed, ...(applied ? {} : { error: 'no-row-changed' }), detail: { proposalKey: key, op: 'update', rows: results } },
+    { state: deps.state }
+  )
+  return applied ? { verdict: 'accepted', applied, missed, rows: results } : { verdict: 'refused', errorCode: 'no-row-changed', applied, missed, rows: results }
+}

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

@@ -3,9 +3,7 @@ import { GraphQLJSON } from 'graphql-scalars'
 import { Like, Not, IsNull } from 'typeorm'
 
 import { logger } from '@things-factory/env'
-import gql from 'graphql-tag'
-
-import { getRepository, GraphqlLocalClient } from '@things-factory/shell'
+import { getRepository } from '@things-factory/shell'
 
 import { ChatSession } from '../chat-session/chat-session.js'
 import { ChatMessage } from '../chat-message/chat-message.js'
@@ -14,6 +12,7 @@ import { isSessionParticipant } from '../chat-session-participant/participant-lo
 import { PROPOSAL_OUTCOME_PREFIX } from '../chat-message/proposal-outcome.js'
 import { toolAccessFor } from '../tool-access.js'
 import { applyEntryProposal, entryProposalAnswered, type EntryApplyOutcome } from './entry-apply.js'
+import { runAsCaller } from './entry-tools.js'
 
 @Resolver()
 export class EntryProposalResolver {
@@ -61,13 +60,9 @@ export class EntryProposalResolver {
       /*
        * The application's API, as the person - the same request state the door would have seen had they typed
        * the row in: domain, user, and what their address and prohibitions say. No `tx` is handed on, so the
-       * door opens its own transaction per row.
+       * door opens its own transaction per row (entry-tools.ts `runAsCaller`).
        */
-      execute: async (mutation, variables) => {
-        const { tx: _tx, afterCommit: _after, ...state } = context.state as any
-        const result: any = await GraphqlLocalClient.client.mutate({ mutation: gql(mutation), variables, context: { state, t: context.t } })
-        return { data: result.data, errors: result.errors }
-      },
+      execute: runAsCaller(context),
       report: (message, error) => logger.error(message, error)
     })
   }

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

@@ -117,6 +117,32 @@ export interface EntryTarget {
   check?(rows: EntryRow[], context: EntryContext): EntryIssue[][] | Promise<EntryIssue[][]>
   /** Told of every proposal and every entering - an application that audits its assistant writes it down. A throw is ignored. */
   record?(event: EntryEvent, context: EntryContext): void | Promise<void>
+  /** Changing records that exist (design/ai/data-entry.md §5-1). Absent: this target only enters new ones. */
+  update?: EntryUpdate
+}
+
+/** One record as the application's read query answers it - an `id` and the fields. */
+export type EntryRecord = { id: string } & Record<string, unknown>
+
+/**
+ * How records of a target are changed - every step through the application's API, as the person.
+ *
+ * Which record is meant is the server's to settle, never the model's memory: whichever way it was picked
+ * (on screen, selected, described), the server reads it with `read` before a card is made and again before
+ * it is written.
+ */
+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[] }
+  /** 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[] }
+  /** The application's own mutation that changes one record. */
+  mutation: string
+  variables(change: { id: string; record: EntryRecord; values: Record<string, unknown> }): Record<string, unknown>
+  /** How a record is named on the card - "2026-09-12 · 카카오T". */
+  labelOf?(record: EntryRecord): string
+  /** The fields that may change. Default: every declared field. */
+  fields?: string[]
 }
 
 /**
@@ -124,12 +150,17 @@ export interface EntryTarget {
  * entering read. A document that is not one mutation with one root field is refused at boot.
  */
 export function entryDoorOf(mutation: string): string {
-  const doc = parse(mutation)
+  return rootFieldOf(mutation, 'mutation')
+}
+
+/** `Query.<field>` or `Mutation.<field>` of a document with one operation and one root field. */
+export function rootFieldOf(document: string, operation: 'query' | 'mutation'): string {
+  const doc = parse(document)
   const operations = doc.definitions.filter((one: any) => one.kind === 'OperationDefinition') as any[]
-  if (operations.length !== 1 || operations[0].operation !== 'mutation') throw new Error('is not one mutation')
+  if (operations.length !== 1 || operations[0].operation !== operation) throw new Error(`is not one ${operation}`)
   const fields = operations[0].selectionSet.selections.filter((one: any) => one.kind === 'Field')
   if (fields.length !== 1) throw new Error('must have exactly one root field')
-  return `Mutation.${fields[0].name.value}`
+  return `${operation === 'query' ? 'Query' : 'Mutation'}.${fields[0].name.value}`
 }
 
 /** Tells the target, and never lets its record keeping stop the work. */
@@ -157,6 +188,21 @@ export function declareEntryTarget(target: EntryTarget): void {
     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 (target.update) {
+    for (const [what, document, operation] of [
+      ['update.read', target.update.read?.query, 'query'],
+      ['update.mutation', target.update.mutation, 'mutation'],
+      ...(target.update.find ? [['update.find', target.update.find.query, 'query']] : [])
+    ] as [string, string, 'query' | 'mutation'][]) {
+      try {
+        rootFieldOf(document ?? '', operation)
+      } catch (error: any) {
+        throw new Error(`[ai-assistant] entry target '${target.key}': ${what} ${error?.message ?? 'does not parse'}.`)
+      }
+    }
+    const known = new Set(target.fields.map(field => field.name))
+    for (const name of target.update.fields ?? []) if (!known.has(name)) throw new Error(`[ai-assistant] entry target '${target.key}': update field '${name}' is not declared.`)
+  }
   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) {
@@ -181,6 +227,17 @@ export function clearEntryTargets(): void {
   targets.clear()
 }
 
+const pascalOf = (key: string) =>
+  key
+    .split(/[.-]/)
+    .filter(Boolean)
+    .map(part => part[0].toUpperCase() + part.slice(1))
+    .join('')
+
+/** `office.expense-line` → `proposeOfficeExpenseLineChanges` / `findOfficeExpenseLine` - the tools of changing. */
+export const changeToolName = (key: string) => `propose${pascalOf(key)}Changes`
+export const findToolName = (key: string) => `find${pascalOf(key)}`
+
 /** `office.expense-line` → `proposeOfficeExpenseLineEntries` - one tool per target, so each has its own door. */
 export function entryToolName(key: string): string {
   const pascal = key
@@ -226,6 +283,41 @@ function toBoolean(value: unknown): boolean | undefined {
   return undefined
 }
 
+/** One value in its field's type - or the code of why it is not. An empty value is the caller's to judge. */
+export function readFieldValue(field: EntryField, value: unknown): { read?: unknown; code?: string } {
+  switch (field.type) {
+    case 'number': {
+      const read = toNumber(value)
+      return read === undefined ? { code: 'not-a-number' } : { read }
+    }
+    case 'integer': {
+      const read = toNumber(value)
+      return read === undefined || !Number.isInteger(read) ? { code: 'not-an-integer' } : { read }
+    }
+    case 'date': {
+      const read = toDate(value)
+      return read === undefined ? { code: 'not-a-date' } : { 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' }
+    default:
+      return { read: String(value).trim() }
+  }
+}
+
+/** Two values of one field the same - "12400.00" read from the database is 12400. */
+export function sameFieldValue(field: EntryField, a: unknown, b: unknown): boolean {
+  if (empty(a) && empty(b)) return true
+  if (empty(a) || empty(b)) return false
+  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)
+}
+
 /**
  * The rows as the target reads them - each value in its field's type, and what was wrong said as an issue.
  *
@@ -252,36 +344,10 @@ export function normalizeEntryRows(target: EntryTarget, input: unknown): { rows:
         if (field.required) issues.push({ field: field.name, code: 'required', blocking: true })
         continue
       }
-      let read: unknown
-      let code = ''
-      switch (field.type) {
-        case 'number':
-          read = toNumber(value)
-          code = 'not-a-number'
-          break
-        case 'integer':
-          read = toNumber(value)
-          if (read !== undefined && !Number.isInteger(read)) read = undefined
-          code = 'not-an-integer'
-          break
-        case 'date':
-          read = toDate(value)
-          code = 'not-a-date'
-          break
-        case 'boolean':
-          read = toBoolean(value)
-          code = 'not-a-boolean'
-          break
-        case 'enum':
-          read = field.values!.includes(String(value).trim()) ? String(value).trim() : undefined
-          code = 'not-in-list'
-          break
-        default:
-          read = String(value).trim()
-      }
+      const { read, code } = readFieldValue(field, value)
       if (read === undefined) {
         values[field.name] = value
-        issues.push({ field: field.name, code, params: code === 'not-in-list' ? { values: field.values } : undefined, blocking: true })
+        issues.push({ field: field.name, code: code!, params: code === 'not-in-list' ? { values: field.values } : undefined, blocking: true })
       } else {
         values[field.name] = read
       }

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

@@ -9,7 +9,11 @@
  */
 import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
 
+import { findRecords, proposeChanges, changeableFields, type GraphqlRunner } from './entry-update.js'
 import {
+  changeToolName,
+  findToolName,
+  rootFieldOf,
   declareEntryTarget,
   entryTotals,
   verifyRowsAgainstSources,
@@ -99,7 +103,71 @@ export async function proposeEntries(target: EntryTarget, args: any, context: an
   }
 }
 
-export function entryCategoryOf(target: EntryTarget): ToolCategory {
+/**
+ * The application's API as the person who asked - the tool's own request state, no transaction handed on.
+ * Loaded late so the rules are tested without the shell.
+ */
+export const runAsCaller = (context: any): GraphqlRunner => async (document, variables) => {
+  const [{ GraphqlLocalClient }, { default: gql }] = await Promise.all([import('@things-factory/shell'), import('graphql-tag')])
+  const { tx: _tx, afterCommit: _after, ...state } = context?.state ?? {}
+  const operation = /^\s*mutation\b/.test(document) ? 'mutate' : 'query'
+  const result: any =
+    operation === 'mutate'
+      ? await GraphqlLocalClient.client.mutate({ mutation: gql(document), variables, context: { state, t: context?.t } })
+      : await GraphqlLocalClient.client.query({ query: gql(document), variables, context: { state, t: context?.t }, fetchPolicy: 'no-cache' })
+  return { data: result.data, errors: result.errors }
+}
+
+/** The two tools of changing records - finding candidates, and the 수정안 (design/ai/data-entry.md §5-1). */
+function changeSpecs(target: EntryTarget, run: (context: any) => GraphqlRunner): ToolSpec[] {
+  const update = target.update
+  if (!update) return []
+  const readDoor = rootFieldOf(update.read.query, 'query')
+  const specs: ToolSpec[] = [
+    {
+      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],
+      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. ' +
+        'The server reads each record, and the card shows what it holds now and what it becomes; nothing changes until the person presses it.',
+      schema: {
+        type: 'object',
+        properties: {
+          changes: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                ref: { type: 'string', description: '"current", "selected", or a record id from a find tool - never a guessed id.' },
+                values: { type: 'object', description: 'Only the fields that change, with their new values.', properties: Object.fromEntries(changeableFields(target).map(field => [field.name, fieldSchema(field)])) }
+              },
+              required: ['ref', 'values']
+            }
+          },
+          note: { type: 'string', description: 'One line for the card.' }
+        },
+        required: ['changes']
+      },
+      builder: (args: any, context: any) => proposeChanges(target, args, context, run(context))
+    } as ToolSpec
+  ]
+  if (update.find) {
+    specs.push({
+      kind: 'read',
+      name: findToolName(target.key),
+      doors: [rootFieldOf(update.find.query, 'query')],
+      description: `Find existing records to change from what the person described: ${target.description} Returns candidates with their ids.`,
+      schema: { type: 'object', properties: Object.fromEntries(update.find.criteria.map(field => [field.name, fieldSchema(field)])) },
+      builder: (args: any, context: any) => findRecords(target, args, run(context))
+    } as ToolSpec)
+  }
+  return specs
+}
+
+export function entryCategoryOf(target: EntryTarget, run: (context: any) => GraphqlRunner = runAsCaller): ToolCategory {
   const name = entryToolName(target.key)
   const spec = {
     kind: 'read',
@@ -157,9 +225,15 @@ export function entryCategoryOf(target: EntryTarget): ToolCategory {
       '- 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.',
       `- ${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.`
+      `- 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
+        ? [
+            `- To change records that exist, call ${changeToolName(target.key)}. Use ref "current" for the record on screen and "selected" for the rows selected there.${target.update.find ? ` Otherwise call ${findToolName(target.key)} first with what the person said; if more than one record matches, list them and ask which - never pick one yourself.` : ' Otherwise ask the person to open or select the record.'}`,
+            `- ${changeToolName(target.key)} only proposes; the card shows each record's value now and after. Never say a record was changed.`
+          ]
+        : [])
     ].join('\n'),
-    specs: [spec]
+    specs: [spec, ...changeSpecs(target, run)]
   }
 }