@things-factory/ai-assistant 10.1.88 → 10.1.90

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

@@ -0,0 +1,442 @@
+/*
+ * Data entry from material - what an application declares so the assistant can enter its records
+ * (operato-application/design/ai/data-entry.md).
+ *
+ * A person hands the conversation what the records are made of - a bank export, a photo of a receipt,
+ * lines pasted from a mail - and the assistant turns it into rows of one of the application's records.
+ * Nothing is written by the model. It proposes the rows; the card shows them with what was wrong in
+ * each and where each came from; a correction is said in the conversation and the model proposes again;
+ * the person presses the button; the server enters each row **through the application's own GraphQL
+ * mutation**, run with the person's request state - the same door, directives and checks as entering by hand.
+ * There is no second way into the record.
+ *
+ * This file is pure - no framework, no database - so the rules a row passes are tested without a server.
+ */
+import { parse } from 'graphql'
+
+export type EntryFieldType = 'string' | 'text' | 'number' | 'integer' | 'date' | 'boolean' | 'enum'
+
+export interface EntryField {
+  name: string
+  type: EntryFieldType
+  required?: boolean
+  /** The allowed values of an `enum` field. */
+  values?: string[]
+  /** What the model reads about the field - English, like every tool description. */
+  description?: string
+  /** i18n key of the column heading on the card. Absent: the field name. */
+  labelKey?: string
+  /** A number field the card sums - and compares with the total the material prints (§ totals). */
+  total?: boolean
+}
+
+/** 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. */
+  where?: string
+}
+
+export interface EntryIssue {
+  /** The field it is about. Absent: the row as a whole. */
+  field?: string
+  /** A code the screen translates: `ai-assistant.entry.issue.<code>`, or the target's own `messageKey`. */
+  code: string
+  messageKey?: string
+  params?: Record<string, unknown>
+  /** A blocking issue keeps the row out when the person presses the button. */
+  blocking: boolean
+}
+
+export interface EntryRowInput {
+  values?: Record<string, unknown>
+  sources?: EntrySource[]
+}
+
+export interface EntryRow {
+  index: number
+  values: Record<string, unknown>
+  sources: EntrySource[]
+  issues: EntryIssue[]
+  /** The line of a text source where this row's numbers and dates were all found - the server's check, not the model's word. */
+  evidence?: { attachmentId: string; line: number }
+}
+
+export interface EntryContext {
+  /** The request state - domain, user, and when writing, `tx` and `afterCommit`. */
+  state: any
+}
+
+export interface EntryApplied {
+  /** The created record's id, when there is one. */
+  id?: string
+  /** A short name for the conversation line - "2026-09-12 · 택시 · ₩12,400". */
+  label?: string
+}
+
+/** What happened, for an application that writes down every assistant call (office's AI audit). */
+export interface EntryEvent {
+  phase: 'propose' | 'apply'
+  tool: string
+  rows: number
+  ok: boolean
+  applied?: number
+  missed?: number
+  error?: string
+  /** propose: the rows as the model gave them; apply: the proposal key and each row's result. */
+  detail?: unknown
+}
+
+export interface EntryTarget {
+  /** `<app>.<record>` - `office.expense-line`. */
+  key: string
+  /** i18n key of the record's name on the card. */
+  labelKey: string
+  /** What one row is, for the model. */
+  description: string
+  fields: EntryField[]
+  /**
+   * The application's own mutation that enters one record, as a GraphQL document with one root field -
+   * `mutation ($line: NewExpenseLine!) { addExpenseLine(line: $line) { id } }`. Its root field is the door:
+   * the propose tool is offered only to someone who passes it, and each row is entered by running it with
+   * the person's request state, so `@privilege`, `@transaction` and the door's own checks apply as they do
+   * to a person typing it in.
+   */
+  mutation: string
+  /** The mutation's variables for one row. */
+  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
+  /** At most this many rows in one proposal. Default 200. */
+  maxRows?: number
+  /**
+   * Read-only checks the application owns - a duplicate of what is already entered, a code that does not
+   * exist. Asked when the rows are proposed and again when they are entered: the records may have moved.
+   * Returns one list per row, in order.
+   */
+  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>
+}
+
+/**
+ * `Mutation.<root field>` of the target's mutation - the one declaration both the tool's gate and the
+ * 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)
+  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')
+  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}`
+}
+
+/** Tells the target, and never lets its record keeping stop the work. */
+export async function recordEntryEvent(target: EntryTarget, event: EntryEvent, context: EntryContext): Promise<void> {
+  if (!target.record) return
+  try {
+    await target.record(event, context)
+  } catch {
+    /* an audit that failed to write is the application's to report */
+  }
+}
+
+export const DEFAULT_MAX_ROWS = 200
+
+const targets = new Map<string, EntryTarget>()
+
+const KEY = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/
+
+/** Validates and keeps a target - `registerEntryTarget` (entry-tools.ts) also opens its tool. A malformed declaration is refused at boot, not in a conversation. */
+export function declareEntryTarget(target: EntryTarget): void {
+  if (!KEY.test(target?.key ?? '')) throw new Error(`[ai-assistant] entry target key '${target?.key}' is not '<app>.<record>'.`)
+  try {
+    entryDoorOf(target.mutation ?? '')
+  } 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 (!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 (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)
+      throw new Error(`[ai-assistant] entry target '${target.key}': enum field '${field.name}' lists no values.`)
+  }
+  targets.set(target.key, target)
+}
+
+export function entryTargetOf(key: string | undefined): EntryTarget | undefined {
+  return key ? targets.get(key) : undefined
+}
+
+export function entryTargets(): EntryTarget[] {
+  return [...targets.values()]
+}
+
+/** For tests. */
+export function clearEntryTargets(): void {
+  targets.clear()
+}
+
+/** `office.expense-line` → `proposeOfficeExpenseLineEntries` - one tool per target, so each has its own door. */
+export function entryToolName(key: string): string {
+  const pascal = key
+    .split(/[.-]/)
+    .filter(Boolean)
+    .map(part => part[0].toUpperCase() + part.slice(1))
+    .join('')
+  return `propose${pascal}Entries`
+}
+
+export function entryCategoryName(key: string): string {
+  return `data-entry:${key}`
+}
+
+const empty = (value: unknown) => value === undefined || value === null || (typeof value === 'string' && !value.trim())
+
+/** "12,400" · "₩12,400" · "12 400" → 12400. Only the separators people write; anything else is not a number. */
+function toNumber(value: unknown): number | undefined {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined
+  if (typeof value !== 'string') return undefined
+  const cleaned = value.trim().replace(/^[₩$€¥£]\s*/, '').replace(/[,\s]/g, '').replace(/원$/, '')
+  if (!/^-?\d+(\.\d+)?$/.test(cleaned)) return undefined
+  return Number(cleaned)
+}
+
+/** A calendar date as `YYYY-MM-DD` - "2026.9.12", "2026/09/12" too. A day that does not exist is not a date. */
+function toDate(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const match = value.trim().match(/^(\d{4})[-./](\d{1,2})[-./](\d{1,2})\.?$/)
+  if (!match) return undefined
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])]
+  const date = new Date(Date.UTC(year, month - 1, day))
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return undefined
+  return `${match[1]}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`
+}
+
+function toBoolean(value: unknown): boolean | undefined {
+  if (typeof value === 'boolean') return value
+  if (typeof value !== 'string') return undefined
+  const text = value.trim().toLowerCase()
+  if (['true', 'yes', 'y', '1'].includes(text)) return true
+  if (['false', 'no', 'n', '0'].includes(text)) return false
+  return undefined
+}
+
+/**
+ * The rows as the target reads them - each value in its field's type, and what was wrong said as an issue.
+ *
+ * A value that does not fit is **kept as it was written and marked**, never dropped or guessed: the card
+ * shows what the material said, and the person corrects it in the conversation.
+ */
+export function normalizeEntryRows(target: EntryTarget, input: unknown): { rows: EntryRow[]; cut: number } {
+  const list = Array.isArray(input) ? input : []
+  const max = target.maxRows ?? DEFAULT_MAX_ROWS
+  const fields = new Map(target.fields.map(field => [field.name, field]))
+
+  const rows = list.slice(0, max).map((raw: any, index): EntryRow => {
+    const given = raw && typeof raw.values === 'object' && raw.values ? raw.values : {}
+    const values: Record<string, unknown> = {}
+    const issues: EntryIssue[] = []
+
+    for (const name of Object.keys(given)) {
+      if (!fields.has(name)) issues.push({ field: name, code: 'unknown-field', blocking: false })
+    }
+
+    for (const field of target.fields) {
+      const value = given[field.name]
+      if (empty(value)) {
+        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()
+      }
+      if (read === undefined) {
+        values[field.name] = value
+        issues.push({ field: field.name, code, params: code === 'not-in-list' ? { values: field.values } : undefined, blocking: true })
+      } else {
+        values[field.name] = read
+      }
+    }
+
+    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) } : {})
+          }))
+      : []
+    if (!sources.length) issues.push({ code: 'no-source', blocking: false })
+
+    return { index, values, sources, issues }
+  })
+
+  return { rows, cut: Math.max(0, list.length - max) }
+}
+
+/** Adds the target's own findings to each row. A check that throws marks nothing and is reported by the caller. */
+export function withCheckedIssues(rows: EntryRow[], found: EntryIssue[][] | undefined): EntryRow[] {
+  if (!found) return rows
+  return rows.map((row, i) => (found[i]?.length ? { ...row, issues: [...row.issues, ...found[i]] } : row))
+}
+
+export function isBlocked(row: EntryRow): boolean {
+  return row.issues.some(issue => issue.blocking)
+}
+
+/* ── Checking the rows against the material (design/ai/data-entry.md §4-1) ─────────────────────────────
+ *
+ * A row cites where it came from; the model's word is not proof. For a text source the server looks: the
+ * row's numbers and dates must stand together on one line of the cited file. Found - the row carries that
+ * line as evidence. A value the file does not have is marked, unless the row also cites the person's
+ * message (a correction said in the conversation). A photo cannot be read here - the row says so.
+ * 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[] {
+  if (type === 'number' || type === 'integer') {
+    if (typeof value !== 'number' || !Number.isFinite(value)) return []
+    const negative = value < 0
+    const abs = Math.abs(value)
+    const fixed = Number.isInteger(abs) ? String(abs) : abs.toFixed(2).replace(/0+$/, '').replace(/\.$/, '')
+    const [int, frac] = fixed.split('.')
+    const grouped = int.replace(/\B(?=(\d{3})+(?!\d))/g, ',')
+    const forms = new Set<string>()
+    for (const whole of [int, grouped]) {
+      forms.add(frac ? `${whole}.${frac}` : whole)
+      if (!frac) forms.add(`${whole}.00`)
+    }
+    return [...forms].map(form => (negative ? `-${form}` : form))
+  }
+  if (type === 'date') {
+    const match = typeof value === 'string' ? value.match(/^(\d{4})-(\d{2})-(\d{2})$/) : null
+    if (!match) return []
+    const [, y, m, d] = match
+    const mm = String(Number(m))
+    const dd = String(Number(d))
+    return [`${y}-${m}-${d}`, `${y}.${m}.${d}`, `${y}/${m}/${d}`, `${y}${m}${d}`, `${y}.${mm}.${dd}`, `${y}/${mm}/${dd}`, `${y}-${mm}-${dd}`, `${y.slice(2)}.${m}.${d}`, `${y.slice(2)}/${m}/${d}`]
+  }
+  return []
+}
+
+/**
+ * A form found as a whole number - "12,400" is not found in "112,400", "12,4001", "12,400.50" or "12,400,000";
+ * "2026-09-12" not in "2026-09-120". A CSV's own commas are not part of the number.
+ */
+export function lineHas(line: string, forms: string[]): boolean {
+  const digit = (c: string | undefined) => !!c && c >= '0' && c <= '9'
+  return forms.some(form => {
+    for (let at = line.indexOf(form); at >= 0; at = line.indexOf(form, at + 1)) {
+      const before = line[at - 1]
+      const after = line[at + form.length]
+      /* A comma is also the column separator of a CSV: only a comma and three digits more continue the number. */
+      if (digit(before) || (before === '.' && digit(line[at - 2]))) continue
+      if (digit(after) || (after === '.' && digit(line[at + form.length + 1]))) continue
+      if (after === ',' && /^,\d{3}(?!\d)/.test(line.slice(at + form.length))) continue
+      return true
+    }
+    return false
+  })
+}
+
+/**
+ * Checks each row against the text of the files it cites. `texts` holds what could be read, by attachment id;
+ * an id that is not there was an image, or could not be opened.
+ */
+export function verifyRowsAgainstSources(rows: EntryRow[], fields: EntryField[], texts: Map<string, string>): EntryRow[] {
+  const checked = fields.filter(field => ['number', 'integer', 'date'].includes(field.type))
+  return rows.map(row => {
+    const files = row.sources.map(source => source.attachmentId).filter((id): id is string => !!id)
+    if (!files.length || !checked.length) return row
+    const readable = files.filter(id => texts.has(id))
+    if (!readable.length) return { ...row, issues: [...row.issues, { code: 'source-not-checked', blocking: false }] }
+
+    const forms = checked
+      .map(field => ({ field, forms: writtenForms(field.type, row.values[field.name]) }))
+      .filter(one => one.forms.length)
+    if (!forms.length) return row
+
+    for (const id of readable) {
+      const lines = texts.get(id)!.split(/\r?\n/)
+      const at = lines.findIndex(line => forms.every(one => lineHas(line, one.forms)))
+      if (at >= 0) return { ...row, evidence: { attachmentId: id, line: at + 1 } }
+    }
+
+    const saidByPerson = row.sources.some(source => !source.attachmentId && PERSON.test(source.where ?? ''))
+    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)))
+      if (!anywhere && !saidByPerson) issues.push({ field: one.field.name, code: 'not-in-source', blocking: false })
+    }
+    if (issues.length === row.issues.length) issues.push({ code: 'source-scattered', blocking: false })
+    return { ...row, issues }
+  })
+}
+
+export interface EntryTotal {
+  field: string
+  /** The sum over every row, and over the rows that will be entered. */
+  all: number
+  ready: number
+  /** The total the material prints, as the model read it - and whether the server found it in the file. */
+  declared?: number
+  declaredFound?: boolean
+  /** declared - all. */
+  difference?: number
+}
+
+/** The sums of the fields declared `total`, and how they stand against the total the material prints. */
+export function entryTotals(
+  rows: EntryRow[],
+  fields: EntryField[],
+  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'))
+    .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 (value !== undefined) {
+        total.declared = value
+        total.difference = Math.round((value - total.all) * 100) / 100
+        const text = declared!.attachmentId ? texts.get(declared!.attachmentId) : undefined
+        if (text !== undefined) total.declaredFound = text.split(/\r?\n/).some(line => lineHas(line, writtenForms(field.type, value)))
+      }
+      return total
+    })
+}
+

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

@@ -0,0 +1,174 @@
+/*
+ * The propose tool of each entry target (operato-application/design/ai/data-entry.md §3).
+ *
+ * One tool per target, so each carries its own door: the tool is offered only to a person who could enter
+ * those records by hand, and its card cannot be made for someone who could not press it.
+ *
+ * The tool writes nothing. It reads the rows the model made from the material, puts each value in its
+ * field's type, asks the target's own checks, and hands back a proposal - the card.
+ */
+import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
+
+import {
+  declareEntryTarget,
+  entryTotals,
+  verifyRowsAgainstSources,
+  entryCategoryName,
+  entryDoorOf,
+  entryToolName,
+  isBlocked,
+  normalizeEntryRows,
+  recordEntryEvent,
+  withCheckedIssues,
+  type EntryField,
+  type EntryRow,
+  type EntryTarget
+} from './entry-target.js'
+
+function fieldSchema(field: EntryField): any {
+  const type = field.type === 'number' || field.type === 'integer' ? ['number', 'string'] : field.type === 'boolean' ? ['boolean', 'string'] : 'string'
+  const said = [
+    field.description,
+    field.required ? 'required' : 'optional',
+    field.type === 'date' ? 'YYYY-MM-DD' : undefined,
+    field.type === 'enum' ? `one of: ${field.values!.join(', ')}` : undefined
+  ]
+    .filter(Boolean)
+    .join('. ')
+  return { type, description: said }
+}
+
+/** What the card needs besides the rows - the columns, in the target's order. */
+function columnsOf(target: EntryTarget) {
+  return target.fields.map(field => ({ name: field.name, type: field.type, required: !!field.required, ...(field.labelKey ? { labelKey: field.labelKey } : {}) }))
+}
+
+export type SourceTextLoader = (attachmentIds: string[], context: any) => Promise<Map<string, string>>
+
+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) {
+  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)
+  if (!normalized.length) {
+    await told({ rows: 0, ok: false, error: 'no-rows', detail: args })
+    return { rejected: true, error: 'no-rows', message: 'no rows were given. Read the material and pass every record as a row.' }
+  }
+
+  /* The server looks in the cited files itself - the model's citation is not proof (design/ai/data-entry.md §4-1). */
+  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)
+
+  let rows: EntryRow[] = read
+  let checkFailed: string | undefined
+  if (target.check) {
+    try {
+      rows = withCheckedIssues(read, await target.check(read, { state: context?.state }))
+    } catch (error: any) {
+      checkFailed = error?.message || 'check-failed'
+    }
+  }
+
+  const blocked = rows.filter(isBlocked).length
+  const totals = entryTotals(rows, target.fields, declared, texts)
+  const verified = rows.filter(row => row.evidence).length
+  const unmatched = rows.filter(row => row.issues.some(issue => issue.code === 'not-in-source')).length
+  await told({ rows: rows.length, ok: true, detail: args })
+  return {
+    proposed: true,
+    kind: 'entry',
+    target: target.key,
+    labelKey: target.labelKey,
+    label: `${rows.length} ${target.key} rows`,
+    icon: 'playlist_add',
+    columns: columnsOf(target),
+    rows,
+    counts: { rows: rows.length, ready: rows.length - blocked, blocked, cut, verified, unmatched },
+    ...(totals.length ? { totals } : {}),
+    ...(typeof args?.note === 'string' && args.note.trim() ? { reason: args.note.trim().slice(0, 300) } : {}),
+    ...(checkFailed ? { checkFailed } : {}),
+    /* For the model - the card is the answer; it says what the person must still decide. */
+    message:
+      `proposed ${rows.length} rows (${rows.length - blocked} ready, ${blocked} blocked${cut ? `, ${cut} cut over the limit` : ''}; ` +
+      `${verified} found line by line in their files, ${unmatched} with a value the file does not have). ` +
+      totals.filter(total => total.difference).map(total => `${total.field}: the material's total differs from the rows by ${total.difference}. `).join('') +
+      'nothing is written until the person presses the button on the card. Tell them which rows are blocked or do not match their file, and why, and ask for what is missing.'
+  }
+}
+
+export function entryCategoryOf(target: EntryTarget): ToolCategory {
+  const name = entryToolName(target.key)
+  const spec = {
+    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)],
+    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.',
+    schema: {
+      type: 'object',
+      properties: {
+        rows: {
+          type: 'array',
+          description: `At most ${target.maxRows ?? 200} rows.`,
+          items: {
+            type: 'object',
+            properties: {
+              values: {
+                type: 'object',
+                properties: Object.fromEntries(target.fields.map(field => [field.name, fieldSchema(field)]))
+              },
+              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' } } }
+              }
+            },
+            required: ['values', 'sources']
+          }
+        },
+        note: { type: 'string', description: 'One line for the card - what this set is ("September card statement").' },
+        declaredTotal: {
+          type: 'object',
+          description: 'The total the material itself prints, when it prints one - the card compares it with the sum of the rows. Never compute it yourself.',
+          properties: {
+            field: { type: 'string', description: `Which field it totals${target.fields.filter(field => field.total).length ? ` (${target.fields.filter(field => field.total).map(field => field.name).join(', ')})` : ''}.` },
+            value: { type: ['number', 'string'] },
+            attachmentId: { type: 'string' },
+            where: { type: 'string' }
+          }
+        }
+      },
+      required: ['rows']
+    },
+    builder: (args: any, context: any) => proposeEntries(target, args, context)
+  } as ToolSpec
+
+  return {
+    name: entryCategoryName(target.key),
+    description: `data entry: ${target.key}`,
+    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.',
+      `- ${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.`
+    ].join('\n'),
+    specs: [spec]
+  }
+}
+
+/**
+ * What an application calls at boot to let the assistant enter one of its records.
+ *
+ * A mode opens it by naming the key in `entryTargets` (the tool is not in every conversation of the app).
+ */
+export function registerEntryTarget(target: EntryTarget): void {
+  declareEntryTarget(target)
+  registerToolCategory(entryCategoryOf(target))
+}

package/server/service/index.ts

@@ -10,6 +10,7 @@ import { entities as ChatSessionParticipantEntities } from './chat-session-parti
 import './chat-session/attachment-tools.js'
 import './chat-session/session-purge.js'
 import './chat-session/attachment-route.js'
+import { EntryProposalResolver } from './data-entry/entry-resolver.js'
 
 export * from './types.js'
 export * from './chat-session-resolver.js'
@@ -23,6 +24,9 @@ export * from './assistant-capability-resolver.js'
  * 실린다. 시험은 경로로 가져온다: `…/service/testing/conversation-script.js`.
  */
 export * from './tool-access.js'
+/* Data entry from material - an app registers what it can enter; a mode names it (design/ai/data-entry.md). */
+export * from './data-entry/entry-target.js'
+export { registerEntryTarget, entryCategoryOf } from './data-entry/entry-tools.js'
 /* 무엇이 근거인가 — 도구 결과 밖의 셋(프롬프트 · 대화 · 화면 스냅숏). */
 export * from './grounding-sources.js'
 /* 앵커 순수 로직 — 호스트가 앵커 종류를 참조한다(리졸버는 데코레이터 때문에 무겁다). */
@@ -63,6 +67,8 @@ export const schema = {
     AssistantCapabilityResolver,
     ChatMessageSubscription,
     /* 내가 참여한 모든 세션의 활동 — 창을 닫아 둔 표면이 배지·목록을 갱신할 수 있게. */
-    MySessionActivitySubscription
+    MySessionActivitySubscription,
+    /* 사람이 누른 입력 제안을 쓰는 자리 — 행마다 앱의 코드로, 그 사람의 권한으로. */
+    EntryProposalResolver
   ]
 }