@things-factory/ai-assistant 10.1.88 → 10.1.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.88",
+  "version": "10.1.90",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -51,5 +51,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "11ece44d38c469f73aa28f4789f4baa244545097"
+  "gitHead": "cc35c48a40020554ceed0b1801dc7955fe027e79"
 }

package/server/service/assistant-mode/registry.ts

@@ -11,6 +11,7 @@
  * registration: `getAssistantModeWarnings()` is the answer as of now, and the boot report reads it
  * after every module is in.
  */
+import { entryTargetOf } from '../data-entry/entry-target.js'
 import { getToolSpecsFor } from '@things-factory/ai-client-base'
 
 import type { AssistantModeSpec, AssistantModeWarning } from './types'
@@ -104,6 +105,18 @@ export function getAssistantModeWarnings(): ReadonlyArray<AssistantModeWarning>
     }
   }
 
+  for (const mode of modes.values()) {
+    /* A record the mode says it enters, which no app registered - the tool never appears and the person is told nothing. */
+    for (const key of mode.entryTargets ?? []) {
+      if (entryTargetOf(key)) continue
+      out.push({
+        code: 'assistant-mode-entry-target-unknown',
+        params: { kind: mode.kind, target: key },
+        message: `mode '${mode.kind}' enters '${key}', which no application registered with registerEntryTarget`
+      })
+    }
+  }
+
   for (const mode of modes.values()) {
     const exposed = new Set(getToolSpecsFor(mode.toolCategories ?? []).map(spec => spec.name))
     for (const slash of mode.slashTemplates ?? []) {

package/server/service/assistant-mode/resolve.ts

@@ -43,6 +43,18 @@ export interface ModeSettings {
   maxTokens?: number
 }
 
+/**
+ * The categories a mode opens: its own, the attachment reader when it takes files (design/ai/shared-dock.md
+ * §9-4), and one propose tool per record it may enter (design/ai/data-entry.md).
+ */
+export function modeToolCategories(mode: { toolCategories?: string[]; attachments?: { kinds?: string[] }; entryTargets?: string[] }): string[] | undefined {
+  const extra = [
+    ...(mode.attachments?.kinds?.length ? ['chat-attachments'] : []),
+    ...(mode.entryTargets ?? []).map(key => `data-entry:${key}`)
+  ]
+  return extra.length ? [...(mode.toolCategories ?? []), ...extra] : mode.toolCategories
+}
+
 /** The conversation's settings, from the server's declaration. */
 export function resolveModeSettings(ref: AssistantModeRef, t: Translate): ModeSettings {
   const kind = String(ref?.kind ?? '')
@@ -53,9 +65,7 @@ export function resolveModeSettings(ref: AssistantModeRef, t: Translate): ModeSe
   return {
     systemPrompt: mode.systemPrompt,
     /* A mode that takes attachments can open the files sent in earlier turns (design/ai/shared-dock.md §9-4). */
-    toolCategories: mode.attachments?.kinds?.length
-      ? [...(mode.toolCategories ?? []), 'chat-attachments']
-      : mode.toolCategories,
+    toolCategories: modeToolCategories(mode),
     requireToolOnFirstTurn: mode.requireToolOnFirstTurn,
     model: mode.model,
     temperature: mode.temperature,

package/server/service/assistant-mode/types.ts

@@ -100,6 +100,11 @@ export interface AssistantModeSpec {
    * screen offers no attach button, so no file is taken that the model would never see.
    */
   attachments?: AttachmentPolicy
+  /**
+   * Which records this conversation may enter from material (design/ai/data-entry.md) - keys registered
+   * with `registerEntryTarget`. Each opens that target's propose tool; its door still decides who gets it.
+   */
+  entryTargets?: string[]
   /** i18n key for the line under an empty conversation. */
   footerNoticeKey?: string
   /** i18n key for the line shown once the host reports a proposal staged. */
@@ -121,7 +126,8 @@ export interface AssistantModeWarning {
     | 'assistant-mode-subject-without-default'
     | 'assistant-mode-subject-default-twice'
     | 'assistant-mode-offered-without-label'
-  params: { kind: string; slash?: string; tool?: string; subject?: string; kinds?: string[] }
+    | 'assistant-mode-entry-target-unknown'
+  params: { kind: string; slash?: string; tool?: string; subject?: string; kinds?: string[]; target?: string }
   /** For a person reading the boot log; callers act on the code and params. */
   message: string
 }

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

@@ -0,0 +1,311 @@
+/*
+ * 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 { entryCategoryOf, proposeEntries } from './entry-tools'
+import { applyEntryProposal, entryProposalAnswered, findEntryProposal, type EntryApplyDeps } from './entry-apply'
+import { modeToolCategories } from '../assistant-mode/resolve'
+
+const written: any[] = []
+
+const expense: EntryTarget = {
+  key: 'office.expense-line',
+  labelKey: 'office.entry.expense-line',
+  description: 'one expense: when, what for, how much.',
+  mutation: 'mutation ($line: NewExpenseLine!) { addExpenseLine(line: $line) { id } }',
+  variables: row => ({ line: row.values }),
+  appliedOf: (data, row) => ({ id: data?.addExpenseLine?.id, label: String(row.values.amount) }),
+  fields: [
+    { name: 'spentOn', type: 'date', required: true },
+    { name: 'amount', type: 'number', required: true, total: true },
+    { name: 'category', type: 'enum', values: ['taxi', 'meal'] },
+    { name: 'memo', type: 'string' }
+  ],
+  check: rows => rows.map(row => (row.values.memo === 'dup' ? [{ code: 'duplicate', blocking: true }] : []))
+}
+
+/* The application's API, as a fake: it refuses a memo 'refuse' the way a door refuses - with a GraphQL error. */
+const api = async (mutation: string, variables: any) => {
+  asked.push({ mutation, variables })
+  if (variables.line.memo === 'refuse') return { errors: [{ message: 'closed period' }] }
+  written.push(variables.line)
+  return { data: { addExpenseLine: { id: `id-${written.length - 1}` } } }
+}
+const asked: any[] = []
+
+beforeEach(() => {
+  written.length = 0
+  asked.length = 0
+  clearEntryTargets()
+})
+
+describe('declaring a target', () => {
+  it('★ refuses a declaration that could not work - at boot, not in a conversation', () => {
+    expect(() => declareEntryTarget({ ...expense, key: 'expense' })).toThrow(/<app>\.<record>/)
+    expect(() => declareEntryTarget({ ...expense, mutation: 'query { expenseLines { id } }' })).toThrow(/is not one mutation/)
+    expect(() => declareEntryTarget({ ...expense, mutation: 'mutation { a { id } b { id } }' })).toThrow(/exactly one root field/)
+    expect(() => declareEntryTarget({ ...expense, mutation: 'mutation {' })).toThrow(/its mutation/)
+    expect(() => declareEntryTarget({ ...expense, fields: [] })).toThrow(/no fields/)
+    expect(() => declareEntryTarget({ ...expense, fields: [{ name: 'c', type: 'enum' }] })).toThrow(/lists no values/)
+  })
+
+  it('one tool per target, named for it', () => {
+    expect(entryToolName('office.expense-line')).toBe('proposeOfficeExpenseLineEntries')
+  })
+
+  it("★ the door is the mutation's own root field - one declaration, read by the tool's gate and by the entering", () => {
+    expect(entryDoorOf(expense.mutation)).toBe('Mutation.addExpenseLine')
+  })
+
+  it("★ the tool carries the target's door - it is offered only to someone who could enter the records by hand", () => {
+    const category = entryCategoryOf(expense)
+    expect(category.name).toBe('data-entry:office.expense-line')
+    expect((category.specs[0] as any).doors).toEqual(['Mutation.addExpenseLine'])
+    expect(category.guidance).toMatch(/never say the records were entered/)
+  })
+
+  it('a mode opens a target by naming it', () => {
+    expect(modeToolCategories({ toolCategories: ['office-ops'], entryTargets: ['office.expense-line'] })).toEqual(['office-ops', 'data-entry:office.expense-line'])
+    expect(modeToolCategories({ toolCategories: ['office-ops'] })).toEqual(['office-ops'])
+  })
+})
+
+describe('reading the rows', () => {
+  it('puts each value in its type - the separators people write are read', () => {
+    const { rows } = normalizeEntryRows(expense, [{ values: { spentOn: '2026.9.12', amount: '₩12,400', category: 'taxi' }, sources: [{ where: 'row 1' }] }])
+    expect(rows[0].values).toEqual({ spentOn: '2026-09-12', amount: 12400, category: 'taxi' })
+    expect(rows[0].issues).toEqual([])
+  })
+
+  it('★ a value that does not fit is kept as written and marked - never dropped or guessed', () => {
+    const { rows } = normalizeEntryRows(expense, [{ values: { spentOn: '2026-02-30', amount: 'twelve', category: 'hotel' }, sources: [{ where: 'row 2' }] }])
+    expect(rows[0].values).toEqual({ spentOn: '2026-02-30', amount: 'twelve', category: 'hotel' })
+    expect(rows[0].issues.map(issue => `${issue.field}:${issue.code}:${issue.blocking}`)).toEqual([
+      'spentOn:not-a-date:true',
+      'amount:not-a-number:true',
+      'category:not-in-list:true'
+    ])
+  })
+
+  it('★ a missing required value blocks the row; a missing source is only said', () => {
+    const { rows } = normalizeEntryRows(expense, [{ values: { amount: 1000 } }])
+    expect(rows[0].issues).toEqual([
+      { field: 'spentOn', code: 'required', blocking: true },
+      { code: 'no-source', blocking: false }
+    ])
+  })
+
+  it('cuts at the limit and says how many', () => {
+    const { rows, cut } = normalizeEntryRows({ ...expense, maxRows: 2 }, [{}, {}, {}, {}])
+    expect(rows).toHaveLength(2)
+    expect(cut).toBe(2)
+  })
+})
+
+describe('proposing', () => {
+  it("★ hands back a card, never a write - with the target's own findings on each row", async () => {
+    const result: any = await proposeEntries(
+      expense,
+      {
+        rows: [
+          { values: { spentOn: '2026-09-12', amount: 12400 }, sources: [{ attachmentId: 'a1', where: 'row 1' }] },
+          { values: { spentOn: '2026-09-13', amount: 9000, memo: 'dup' }, sources: [{ attachmentId: 'a1', where: 'row 2' }] }
+        ]
+      },
+      { state: {} },
+      async () => new Map()
+    )
+    expect(result.proposed).toBe(true)
+    expect(result.kind).toBe('entry')
+    expect(result.target).toBe('office.expense-line')
+    expect(result.counts).toMatchObject({ rows: 2, ready: 1, blocked: 1, cut: 0 })
+    expect(result.rows[1].issues).toEqual([{ code: 'source-not-checked', blocking: false }, { code: 'duplicate', blocking: true }])
+    expect(written).toEqual([])
+  })
+
+  it('no rows is refused, with what to do', async () => {
+    const result: any = await proposeEntries(expense, { rows: [] }, { state: {} })
+    expect(result).toMatchObject({ rejected: true, error: 'no-rows' })
+  })
+})
+
+describe('entering what the person pressed', () => {
+  const proposal = (key: string, rows: any[]) => ({ key, kind: 'entry', target: 'office.expense-line', rows })
+  const row = (values: any) => ({ values, sources: [{ where: 'row' }] })
+  const deps = (messages: any[], over: Partial<EntryApplyDeps> = {}): EntryApplyDeps => ({
+    messages,
+    answered: false,
+    passesDoor: async () => true,
+    execute: api,
+    state: {},
+    ...over
+  })
+
+  beforeEach(() => declareEntryTarget(expense))
+
+  it("★ enters each row through the application's own mutation - a refused row keeps the others, and each is reported by its place", async () => {
+    const messages = [{ id: 'm1', proposals: [proposal('k1', [row({ spentOn: '2026-09-12', amount: 1 }), row({ spentOn: '2026-09-12', amount: 2, memo: 'refuse' }), row({ spentOn: '2026-09-12', amount: 3 })])] }]
+    const outcome = await applyEntryProposal('k1', deps(messages))
+    expect(outcome).toMatchObject({ verdict: 'accepted', applied: 2, missed: 1 })
+    expect(outcome.rows).toEqual([
+      { index: 0, ok: true, id: 'id-0', label: '1' },
+      { index: 1, ok: false, error: 'closed period' },
+      { index: 2, ok: true, id: 'id-1', label: '3' }
+    ])
+    expect(asked.map(one => one.mutation)).toEqual([expense.mutation, expense.mutation, expense.mutation])
+    expect(asked[0].variables).toEqual({ line: { spentOn: '2026-09-12', amount: 1 } })
+  })
+
+  it('★ asks the checks again - a record entered since the card was made keeps its row out', async () => {
+    const messages = [{ id: 'm1', proposals: [proposal('k1', [row({ spentOn: '2026-09-12', amount: 1, memo: 'dup' })])] }]
+    const outcome = await applyEntryProposal('k1', deps(messages))
+    expect(outcome).toMatchObject({ verdict: 'refused', errorCode: 'no-row-entered', applied: 0, missed: 1 })
+    expect(outcome.rows[0]).toEqual({ index: 0, ok: false, error: 'duplicate' })
+    expect(written).toEqual([])
+  })
+
+  it('★ a newer card for the same record replaces this one', async () => {
+    const messages = [
+      { id: 'm1', proposals: [proposal('k1', [row({ spentOn: '2026-09-12', amount: 1 })])] },
+      { id: 'm2', proposals: [proposal('k2', [row({ spentOn: '2026-09-12', amount: 10 })])] }
+    ]
+    expect(findEntryProposal(messages, 'k1').superseded).toBe(true)
+    expect(await applyEntryProposal('k1', deps(messages))).toMatchObject({ verdict: 'refused', errorCode: 'superseded' })
+    expect(await applyEntryProposal('k2', deps(messages))).toMatchObject({ verdict: 'accepted', applied: 1 })
+  })
+
+  it('★ the door is asked again at the moment of writing', async () => {
+    const messages = [{ id: 'm1', proposals: [proposal('k1', [row({ spentOn: '2026-09-12', amount: 1 })])] }]
+    expect(await applyEntryProposal('k1', deps(messages, { passesDoor: async () => false }))).toMatchObject({ verdict: 'refused', errorCode: 'door-closed' })
+    expect(written).toEqual([])
+  })
+
+  it('★ an answered card is not entered twice', async () => {
+    const messages = [{ id: 'm1', proposals: [proposal('k1', [row({ spentOn: '2026-09-12', amount: 1 })])] }]
+    expect(await applyEntryProposal('k1', deps(messages, { answered: true }))).toMatchObject({ verdict: 'refused', errorCode: 'already-answered' })
+    expect(written).toEqual([])
+  })
+
+  it("'requested' alone is not an answer - the dock writes it just before pressing", () => {
+    expect(entryProposalAnswered('k1', ['proposal k1: requested'])).toBe(false)
+    expect(entryProposalAnswered('k1', ['proposal k1: requested', 'proposal k1: accepted 2/3'])).toBe(true)
+    expect(entryProposalAnswered('k1', ['proposal k10: accepted'])).toBe(false)
+  })
+
+  it('a target no longer registered is unavailable; a key nobody proposed is refused', async () => {
+    const messages = [{ id: 'm1', proposals: [{ ...proposal('k1', []), target: 'office.gone' }] }]
+    expect(await applyEntryProposal('k1', deps(messages))).toMatchObject({ verdict: 'unavailable', errorCode: 'unknown-entry-target' })
+    expect(await applyEntryProposal('nope', deps(messages))).toMatchObject({ verdict: 'refused', errorCode: 'proposal-not-found' })
+  })
+})
+
+describe('checking the rows against the material', () => {
+  const csv = ['date,shop,amount', '2026-09-12,Kakao T,"12,400"', '2026.09.13,Starbucks,9000', '2026-09-14,Hotel,112400', '', 'total,,"21,400"'].join('\n')
+  const texts = new Map([['a1', csv]])
+  const rowsOf = (list: any[]) => normalizeEntryRows(expense, list).rows
+
+  it('writes a number and a date the ways a file does', () => {
+    expect(writtenForms('number', 12400)).toEqual(expect.arrayContaining(['12400', '12,400', '12,400.00']))
+    expect(writtenForms('date', '2026-09-03')).toEqual(expect.arrayContaining(['2026-09-03', '2026.09.03', '2026.9.3', '20260903']))
+  })
+
+  it("★ finds a number only as a whole - not inside a longer one, and a CSV's commas are not part of it", () => {
+    expect(lineHas('2026-09-12,Kakao T,12400', ['12400'])).toBe(true)
+    expect(lineHas('2026-09-12,Hotel,112400', ['12400'])).toBe(false)
+    expect(lineHas('12,400,000', ['12,400'])).toBe(false)
+    expect(lineHas('12,400.50', ['12,400'])).toBe(false)
+    expect(lineHas('9000,2026-09-13', ['9000'])).toBe(true)
+  })
+
+  it('★ a row whose numbers and dates stand together on one line of its file carries that line as evidence', () => {
+    const [row] = verifyRowsAgainstSources(rowsOf([{ values: { spentOn: '2026-09-13', amount: 9000 }, sources: [{ attachmentId: 'a1', where: 'row 3' }] }]), expense.fields, texts)
+    expect(row.evidence).toEqual({ attachmentId: 'a1', line: 3 })
+    expect(row.issues).toEqual([])
+  })
+
+  it('★ a value the file does not have is marked - the model misread 12,400 as 12,800', () => {
+    const [row] = verifyRowsAgainstSources(rowsOf([{ values: { spentOn: '2026-09-12', amount: 12800 }, sources: [{ attachmentId: 'a1', where: 'row 2' }] }]), expense.fields, texts)
+    expect(row.evidence).toBeUndefined()
+    expect(row.issues).toEqual([{ field: 'amount', code: 'not-in-source', blocking: false }])
+  })
+
+  it('a value the person corrected in the conversation is not marked against the file', () => {
+    const [row] = verifyRowsAgainstSources(
+      rowsOf([{ values: { spentOn: '2026-09-12', amount: 12000 }, sources: [{ attachmentId: 'a1', where: 'row 2' }, { where: "the person's message" }] }]),
+      expense.fields,
+      texts
+    )
+    expect(row.issues).toEqual([{ code: 'source-scattered', blocking: false }])
+  })
+
+  it('a photo cannot be read here - the row says it was not checked', () => {
+    const [row] = verifyRowsAgainstSources(rowsOf([{ values: { spentOn: '2026-09-12', amount: 1 }, sources: [{ attachmentId: 'photo' }] }]), expense.fields, texts)
+    expect(row.issues).toEqual([{ code: 'source-not-checked', blocking: false }])
+  })
+
+  it("★ the sum of the rows against the total the material prints - and whether that total is in the file", () => {
+    const rows = rowsOf([
+      { values: { spentOn: '2026-09-12', amount: 12400 }, sources: [{ where: 'x' }] },
+      { values: { spentOn: '2026-09-13', amount: 9000 }, sources: [{ where: 'x' }] },
+      { 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 }
+    ])
+    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 }])
+  })
+
+  it('the tool reads the cited files and puts the check and the totals on the card', async () => {
+    const asked: string[][] = []
+    const result: any = await proposeEntries(
+      expense,
+      {
+        rows: [
+          { values: { spentOn: '2026-09-12', amount: '12,400' }, sources: [{ attachmentId: 'a1', where: 'row 2' }] },
+          { values: { spentOn: '2026-09-13', amount: 9500 }, sources: [{ attachmentId: 'a1', where: 'row 3' }] }
+        ],
+        declaredTotal: { field: 'amount', value: 21400, attachmentId: 'a1' }
+      },
+      { state: {} },
+      async ids => (asked.push(ids), texts)
+    )
+    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.message).toMatch(/differs from the rows by -500/)
+  })
+})
+
+describe('telling the application', () => {
+  it('★ every proposal and every entering is told - an application that audits its assistant writes both down', async () => {
+    const events: any[] = []
+    const audited: EntryTarget = { ...expense, record: event => void events.push(event) }
+    declareEntryTarget(audited)
+    const proposed: any = await proposeEntries(audited, { rows: [{ values: { spentOn: '2026-09-12', amount: 1 }, sources: [{ where: 'x' }] }] }, { state: {} }, async () => new Map())
+    await applyEntryProposal('k1', {
+      messages: [{ id: 'm1', proposals: [{ ...proposed, key: 'k1' }] }],
+      answered: false,
+      passesDoor: async () => true,
+      execute: api,
+      state: {}
+    })
+    await applyEntryProposal('k1', {
+      messages: [{ id: 'm1', proposals: [{ ...proposed, key: 'k1' }] }],
+      answered: false,
+      passesDoor: async () => false,
+      execute: api,
+      state: {}
+    })
+    expect(events.map(event => `${event.phase}:${event.ok}:${event.applied ?? ''}:${event.error ?? ''}`)).toEqual(['propose:true::', 'apply:true:1:', 'apply:false::door-closed'])
+    expect(events[0].tool).toBe('proposeOfficeExpenseLineEntries')
+  })
+
+  it('a record keeping that throws does not stop the work', async () => {
+    const loud: EntryTarget = { ...expense, record: () => { throw new Error('audit down') } }
+    const result: any = await proposeEntries(loud, { rows: [{ values: { spentOn: '2026-09-12', amount: 1 }, sources: [{ where: 'x' }] }] }, { state: {} }, async () => new Map())
+    expect(result.proposed).toBe(true)
+  })
+})

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

@@ -0,0 +1,134 @@
+/*
+ * Writing a proposal the person pressed (operato-application/design/ai/data-entry.md §4).
+ *
+ * The rows written are the **stored** proposal's, never rows the screen sends: what the person reviewed
+ * on the card is what goes in. The server asks everything again - the door, whether a newer card replaced
+ * this one, whether it was already answered, the target's checks (records move between proposing and
+ * pressing) - and enters each row by running the application's own mutation with the person's request
+ * state. Each call is its own request (the door's `@transaction`), so one refused row does not undo the
+ * others and each is reported by its place.
+ *
+ * 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'
+
+export interface StoredProposalMessage {
+  id: string
+  proposals: any[]
+}
+
+export interface EntryRowResult {
+  index: number
+  ok: boolean
+  id?: string
+  label?: string
+  /** A blocking issue kept it out, or the target refused it. */
+  error?: string
+}
+
+export interface EntryApplyOutcome {
+  verdict: 'accepted' | 'refused' | 'unavailable'
+  errorCode?: string
+  applied: number
+  missed: number
+  rows: EntryRowResult[]
+}
+
+export interface EntryApplyDeps {
+  /** The conversation's messages that carry proposals, oldest first. */
+  messages: StoredProposalMessage[]
+  /** Whether an outcome line already answers this key. */
+  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.
+   */
+  execute(mutation: string, variables: Record<string, unknown>): Promise<{ data?: any; errors?: readonly { message: string }[] }>
+  state: any
+  report?(message: string, error: unknown): void
+}
+
+const nothing = (verdict: EntryApplyOutcome['verdict'], errorCode: string): EntryApplyOutcome => ({ verdict, errorCode, applied: 0, missed: 0, rows: [] })
+
+export function findEntryProposal(messages: StoredProposalMessage[], key: string): { proposal?: any; superseded: boolean } {
+  let at = -1
+  let proposal: any
+  messages.forEach((message, i) => {
+    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))
+  return { proposal, superseded }
+}
+
+export async function applyEntryProposal(key: string, deps: EntryApplyDeps, targetOf: (key: string) => EntryTarget | undefined = entryTargetOf): Promise<EntryApplyOutcome> {
+  const { proposal, superseded } = findEntryProposal(deps.messages, key)
+  if (!proposal) return nothing('refused', 'proposal-not-found')
+  if (proposal.kind !== 'entry') return nothing('refused', 'not-an-entry-proposal')
+  if (superseded) return nothing('refused', 'superseded')
+  if (deps.answered) return nothing('refused', 'already-answered')
+
+  const target = targetOf(proposal.target)
+  if (!target) return nothing('unavailable', 'unknown-entry-target')
+  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 })
+    return nothing('refused', 'door-closed')
+  }
+
+  /* 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 })))
+  if (target.check) {
+    try {
+      rows = withCheckedIssues(rows, await target.check(rows, { state: deps.state }))
+    } catch (error) {
+      deps.report?.(`[ai-assistant] entry check of '${target.key}' failed`, error)
+      return nothing('refused', 'check-failed')
+    }
+  }
+
+  const results: EntryRowResult[] = []
+  for (const row of 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))
+      if (answer.errors?.length) {
+        results.push({ index: row.index, ok: false, error: answer.errors.map(one => one.message).join('; ') || 'refused' })
+        continue
+      }
+      const applied = target.appliedOf?.(answer.data, row)
+      results.push({ index: row.index, ok: true, ...(applied?.id ? { id: applied.id } : {}), ...(applied?.label ? { label: applied.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: entryToolName(target.key), rows: results.length, ok: applied > 0, applied, missed, ...(applied ? {} : { error: 'no-row-entered' }), detail: { proposalKey: key, rows: results } },
+    { state: deps.state }
+  )
+  return applied
+    ? { verdict: 'accepted', applied, missed, rows: results }
+    : { verdict: 'refused', errorCode: 'no-row-entered', applied, missed, rows: results }
+}
+
+/** An outcome line already answers this key - `requested` alone does not: the dock writes it just before calling here. */
+export function entryProposalAnswered(key: string, lines: readonly (string | null | undefined)[]): boolean {
+  const answered = `${PROPOSAL_OUTCOME_PREFIX}${key}: `
+  return lines.some(line => {
+    const text = (line ?? '').trim()
+    if (!text.startsWith(answered)) return false
+    const rest = text.slice(answered.length)
+    return PROPOSAL_VERDICTS.some(verdict => rest === verdict || rest.startsWith(`${verdict} `))
+  })
+}

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

@@ -0,0 +1,74 @@
+import { Resolver, Mutation, Arg, Ctx, Directive } from 'type-graphql'
+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 { ChatSession } from '../chat-session/chat-session.js'
+import { ChatMessage } from '../chat-message/chat-message.js'
+import { assertMayWriteSession } from '../chat-session/session-write-gate.js'
+import { isSessionParticipant } from '../chat-session-participant/participant-lookup.js'
+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'
+
+@Resolver()
+export class EntryProposalResolver {
+  /*
+   * Not `@transaction`: each row is its own call of the application's mutation (entry-apply.ts), so one
+   * refused row keeps the others. The dock reports the outcome afterwards through `reportProposalOutcome`.
+   */
+  @Mutation(() => GraphQLJSON, {
+    description:
+      'Enter the rows of a data entry proposal the person pressed. The rows are the stored proposal\'s; the door, a newer proposal and the target\'s checks are asked again, and each row is written in its own transaction.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "mutation", domainOwnerGranted: true)')
+  async applyEntryProposal(
+    @Arg('sessionId') sessionId: string,
+    @Arg('proposalKey') proposalKey: string,
+    @Ctx() context: ResolverContext
+  ): Promise<EntryApplyOutcome> {
+    const { domain, user } = context.state
+    const session = await getRepository(ChatSession).findOneBy({ id: sessionId, domain: { id: domain.id } } as any)
+    if (!session) throw new Error(`ChatSession ${sessionId} not found`)
+    await assertMayWriteSession({
+      session,
+      userId: user?.id,
+      isParticipant: () => isSessionParticipant(domain.id, session.id, user?.id),
+      t: (key, options) => (context.t ? context.t(key, options) : String(options?.defaultValue ?? key))
+    })
+
+    const key = (proposalKey ?? '').trim()
+    const carrying = await getRepository(ChatMessage).find({
+      select: ['id', 'proposals', 'createdAt'] as any,
+      where: { session: { id: session.id } as any, proposals: Not(IsNull()) } as any,
+      order: { createdAt: 'ASC' } as any
+    })
+    const lines = await getRepository(ChatMessage).find({
+      select: ['content'] as any,
+      where: { session: { id: session.id } as any, role: 'system', content: Like(`${PROPOSAL_OUTCOME_PREFIX}${key}:%`) } as any
+    })
+
+    const passes = toolAccessFor(context)
+    return await applyEntryProposal(key, {
+      messages: carrying.map((message: any) => ({ id: message.id, proposals: message.proposalsJson ?? [] })),
+      answered: entryProposalAnswered(key, lines.map((line: any) => line.content)),
+      passesDoor: door => passes(door),
+      state: context.state,
+      /*
+       * 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.
+       */
+      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 }
+      },
+      report: (message, error) => logger.error(message, error)
+    })
+  }
+}

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

@@ -0,0 +1,35 @@
+/*
+ * The text of the files a proposal cites - read through the conversation's own gate, as readChatAttachment
+ * reads them (chat-session/attachment-tools.ts). A file of another conversation, or of a private one the
+ * caller does not sit in, is not read: it is left out, and the rows citing it say they were not checked.
+ */
+import { Attachment, STORAGE } from '@things-factory/attachment-base'
+import { getRepository } from '@things-factory/shell'
+
+import { ChatSession } from '../chat-session/chat-session.js'
+import { mayReadSession } from '../chat-session/session-visibility.js'
+import { isSessionParticipant } from '../chat-session-participant/participant-lookup.js'
+import { CHAT_ATTACHMENT_REF } from '../chat-session/session-attachments.js'
+import { attachmentKindOf } from '../chat-session/attachment-policy.js'
+
+/** The whole text is read - the check must see every line, not the part the model was shown. */
+const MAX_CHARS = 2_000_000
+
+export async function loadSourceTexts(ids: string[], context: any): Promise<Map<string, string>> {
+  const { domain, user } = context?.state ?? {}
+  const texts = new Map<string, string>()
+  if (!domain?.id) return texts
+  for (const id of [...new Set(ids)].slice(0, 20)) {
+    const row: any = await getRepository(Attachment).findOne({ where: { id, domain: { id: domain.id }, refType: CHAT_ATTACHMENT_REF } as any })
+    const session: any = row && (await getRepository(ChatSession).findOne({ where: { id: row.refBy, domain: { id: domain.id } } as any }))
+    if (!row || !session) continue
+    if (!mayReadSession(session.visibility, await isSessionParticipant(domain.id, session.id, user?.id))) continue
+    if (attachmentKindOf({ type: row.mimetype, name: row.name }) !== 'text') continue
+    try {
+      texts.set(id, String(await STORAGE.readFile(row.path, 'utf8')).slice(0, MAX_CHARS))
+    } catch {
+      /* gone from storage - the rows citing it say they were not checked */
+    }
+  }
+  return texts
+}