@things-factory/ai-assistant 10.1.113 → 10.1.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.113",
+  "version": "10.1.116",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -33,10 +33,10 @@
     "@operato/popup": "^10.16.0",
     "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.81",
+    "@things-factory/ai-client-base": "^10.1.114",
     "@things-factory/apptool-base": "^10.1.106",
-    "@things-factory/attachment-base": "^10.1.113",
-    "@things-factory/auth-base": "^10.1.113",
+    "@things-factory/attachment-base": "^10.1.116",
+    "@things-factory/auth-base": "^10.1.116",
     "@things-factory/env": "^10.1.20",
     "@things-factory/shell": "^10.1.106",
     "dompurify": "^3.0.0",
@@ -52,5 +52,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "9da1e467ddce23e600e64f08454289cb3b806212"
+  "gitHead": "49fa935cc703be70200eef4d29f473de98f871ce"
 }

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

@@ -47,12 +47,13 @@ export interface ModeSettings {
  * The categories a mode opens: its own, the AI 작업판 (design/ai/workspace.md), 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 {
+export function modeToolCategories(mode: { toolCategories?: string[]; attachments?: { kinds?: string[] }; entryTargets?: string[]; readTargets?: string[] }): string[] | undefined {
   const extra = [
     /* Every conversation may put a large result on the AI 작업판 (design/ai/workspace.md). */
     'assistant-workspace',
     ...(mode.attachments?.kinds?.length ? ['chat-attachments'] : []),
-    ...(mode.entryTargets ?? []).map(key => `data-entry:${key}`)
+    ...(mode.entryTargets ?? []).map(key => `data-entry:${key}`),
+    ...(mode.readTargets ?? []).map(key => `data-read:${key}`)
   ]
   return [...new Set([...(mode.toolCategories ?? []), ...extra])]
 }

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

@@ -105,6 +105,8 @@ export interface AssistantModeSpec {
    * with `registerEntryTarget`. Each opens that target's propose tool; its door still decides who gets it.
    */
   entryTargets?: string[]
+  /** The lists of the application the conversation may read - read targets by key (design/ai/read-targets.md). */
+  readTargets?: 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. */

package/server/service/chat-session/attachment-tool-result.test.ts

@@ -0,0 +1,26 @@
+/*
+ * readChatAttachment's answer (design/ai/shared-dock.md §9-4) - a picture of an earlier turn comes back as the picture.
+ */
+/* The source, not the built package - the two land together and the test must see the change before a build. */
+import { takeToolImages } from '../../../../ai-client-base/server/service/agentic-loop/agentic-loop'
+
+import { attachmentToolResult } from './attachment-tool-result'
+
+describe('a file opened again in a later turn', () => {
+  const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 9])
+
+  it('★ a picture comes back as the picture - not as a request to send it again', () => {
+    const answer: any = attachmentToolResult('a1', { type: 'image', data: png, mediaType: 'image/png', name: '영수증.png' })
+    expect(answer.images).toEqual([{ data: png, mediaType: 'image/png' }])
+    expect(answer.note).not.toMatch(/send it again/)
+    /* What the loop makes of it: the picture as an image part, the rest as the JSON the model reads. */
+    const { value, images } = takeToolImages(answer)
+    expect(images).toHaveLength(1)
+    expect(value).toEqual({ attachmentId: 'a1', name: '영수증.png', type: 'image', note: answer.note, imagesAttached: 1 })
+  })
+
+  it('a text file comes back as its text, and a cut one says so', () => {
+    expect(attachmentToolResult('t1', { type: 'text', text: 'a,b', name: 'x.csv', truncated: false })).toEqual({ attachmentId: 't1', name: 'x.csv', type: 'text', text: 'a,b' })
+    expect(attachmentToolResult('t1', { type: 'text', text: 'a', name: 'x.csv', truncated: true })).toMatchObject({ note: 'the file is longer; this is its beginning.' })
+  })
+})

package/server/service/chat-session/attachment-tool-result.ts

@@ -0,0 +1,18 @@
+/*
+ * What readChatAttachment answers for a file of the conversation (design/ai/shared-dock.md §9-4).
+ *
+ * A text file comes back as its text. A picture comes back as the picture: the reserved `images` field is taken out
+ * of the JSON by the loop (ai-client-base takeToolImages) and sent as an image part of the same turn - so a receipt
+ * sent three turns ago can be read again without asking the person to send it again.
+ *
+ * Pure, so it is tested without storage or the shell.
+ */
+export type FileForModel =
+  | { type: 'image'; data: Buffer; mediaType: string; name: string }
+  | { type: 'text'; text: string; name: string; truncated: boolean }
+
+export function attachmentToolResult(attachmentId: string, file: FileForModel) {
+  return file.type === 'image'
+    ? { attachmentId, name: file.name, type: 'image', images: [{ data: file.data, mediaType: file.mediaType }], note: 'the picture is attached right after this result - look at it.' }
+    : { attachmentId, name: file.name, type: 'text', text: file.text, ...(file.truncated ? { note: 'the file is longer; this is its beginning.' } : {}) }
+}

package/server/service/chat-session/attachment-tools.ts

@@ -2,7 +2,7 @@
  * readChatAttachment - the model opens a file sent in an earlier turn (design/ai/shared-dock.md §9-4).
  *
  * A file reaches the model in full only in the turn it was sent; later turns carry one line naming it.
- * When the model needs it again it asks here. The caller must be able to read the conversation the file
+ * When the model needs it again it asks here - a text file comes back as its text, a picture as the picture itself. The caller must be able to read the conversation the file
  * belongs to - the same gate as reading its messages (ADR-0073 decision 1) - so a file id from elsewhere
  * opens nothing.
  *
@@ -18,6 +18,7 @@ import { isSessionParticipant } from '../chat-session-participant/participant-lo
 import { attachmentForModel, CHAT_ATTACHMENT_REF } from './session-attachments.js'
 import { textCharsOf } from './attachment-policy.js'
 import { getAssistantMode } from '../assistant-mode/registry.js'
+import { attachmentToolResult } from './attachment-tool-result.js'
 
 export const CHAT_ATTACHMENT_CATEGORY = 'chat-attachments'
 
@@ -27,7 +28,7 @@ const readChatAttachment: ToolSpec = {
   doors: ['Query.chatMessages'],
   description:
     'Open a file that was sent earlier in this conversation. History names such files as "[attachment <id>: <name> ...]"; ' +
-    'pass that id. An image comes back as a description request, a text file as its text (cut when long - the answer says so).',
+    'pass that id. An image comes back as the picture itself, a text file as its text (cut when long - the answer says so).',
   schema: {
     type: 'object',
     properties: { attachmentId: { type: 'string', description: 'The id from the "[attachment <id>: ...]" line.' } },
@@ -49,9 +50,7 @@ const readChatAttachment: ToolSpec = {
     }
 
     const file = await attachmentForModel(row, textCharsOf(getAssistantMode(session.kind || '')?.attachments))
-    return file.type === 'image'
-      ? { attachmentId: id, name: file.name, type: 'image', note: 'images are shown to you only in the turn they were sent; ask the person to send it again to look at it.' }
-      : { attachmentId: id, name: file.name, type: 'text', text: file.text, ...(file.truncated ? { note: 'the file is longer; this is its beginning.' } : {}) }
+    return attachmentToolResult(id, file)
   }
 } as ToolSpec
 

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

@@ -167,6 +167,16 @@ describe('changing what the person pressed', () => {
     expect(records.l1.amount).toBe('12400.00')
   })
 
+  it.each(['Mutation.changeExpenseLine', 'Query.myExpenseLines'])('enriches only the failed update door: %s', async door => {
+    const proposal = await card([{ ref: 'l1', values: { amount: 13000 } }])
+    const refusal = { message: 'required', extensions: { operation: door.startsWith('Query.') ? 'query' : 'mutation' }, path: [door.split('.')[1]] }
+    const refusalFor = jest.fn().mockResolvedValue(refusal)
+    const outcome = await applyEntryProposal('u1', deps(proposal, { passesDoor: async asked => asked !== door, refusalFor }))
+    expect(outcome).toMatchObject({ verdict: 'refused', errorCode: 'door-closed', applied: 0, missed: 0, refusal })
+    expect(refusalFor.mock.calls).toEqual([[door]])
+    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: [] }
@@ -347,4 +357,3 @@ describe('a check that cannot run', () => {
     expect(proposal.rows[0].issues).toEqual([{ code: 'check-failed', blocking: true }])
   })
 })
-

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

@@ -157,6 +157,35 @@ describe('entering what the person pressed', () => {
     expect(asked[0].variables).toEqual({ line: { spentOn: '2026-09-12', amount: 1 } })
   })
 
+  it('a closed mutation carries its authoritative refusal without entering any rows', async () => {
+    const refusal = { message: 'requires warehouse:mutation', extensions: { code: 'FORBIDDEN', because: 'role', operation: 'mutation', requires: { category: 'warehouse', privilege: 'mutation' } }, path: ['addExpenseLine'] }
+    const refusalFor = jest.fn().mockResolvedValue(refusal)
+    const messages = [{ id: 'm1', proposals: [proposal('k1', [row({ amount: 1 })])] }]
+    expect(await applyEntryProposal('k1', deps(messages, { passesDoor: async () => false, refusalFor }))).toEqual({ verdict: 'refused', errorCode: 'door-closed', applied: 0, missed: 0, rows: [], refusal })
+    expect(refusalFor).toHaveBeenCalledWith('Mutation.addExpenseLine')
+    expect(asked).toEqual([])
+  })
+
+  it('failed refusal enrichment keeps the original refusal and no writes', async () => {
+    const messages = [{ id: 'm1', proposals: [proposal('k1', [row({ amount: 1 })])] }]
+    expect(await applyEntryProposal('k1', deps(messages, { passesDoor: async () => false, refusalFor: async () => { throw new Error('lookup unavailable') } }))).toEqual({ verdict: 'refused', errorCode: 'door-closed', applied: 0, missed: 0, rows: [] })
+    expect(asked).toEqual([])
+  })
+
+  it('audits the closed door before best-effort enrichment and tolerates a broken diagnostic sink', async () => {
+    const order: string[] = []
+    const target = { ...expense, record: async () => { order.push('audit') } }
+    const messages = [{ id: 'm1', proposals: [proposal('k1', [row({ amount: 1 })])] }]
+    const outcome = await applyEntryProposal('k1', deps(messages, {
+      passesDoor: async () => false,
+      refusalFor: async () => { order.push('explain'); throw new Error('unavailable') },
+      report: () => { throw new Error('diagnostic unavailable') }
+    }), () => target)
+    expect(order).toEqual(['audit', 'explain'])
+    expect(outcome).toMatchObject({ verdict: 'refused', errorCode: 'door-closed', applied: 0 })
+    expect(asked).toEqual([])
+  })
+
   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))
@@ -381,4 +410,3 @@ describe("a moment is the domain's wall time", () => {
     expect(result.rows[0].values.startTime).toBe('2026-10-01T08:30:00+09:00')
   })
 })
-

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

@@ -29,12 +29,20 @@ export interface EntryRowResult {
   error?: string
 }
 
+export interface EntryRefusal {
+  message: string
+  extensions: Record<string, unknown>
+  path: string[]
+}
+
 export interface EntryApplyOutcome {
   verdict: 'accepted' | 'refused' | 'unavailable'
   errorCode?: string
   applied: number
   missed: number
   rows: EntryRowResult[]
+  /** AUTH's serialized refusal, only when the closed door could be identified. */
+  refusal?: EntryRefusal
 }
 
 export interface EntryApplyDeps {
@@ -43,6 +51,7 @@ export interface EntryApplyDeps {
   /** Whether an outcome line already answers this key. */
   answered: boolean
   passesDoor(door: string): Promise<boolean>
+  refusalFor?(door: string): Promise<EntryRefusal | undefined>
   /**
    * 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.
@@ -56,6 +65,22 @@ export interface EntryApplyDeps {
 
 const nothing = (verdict: EntryApplyOutcome['verdict'], errorCode: string): EntryApplyOutcome => ({ verdict, errorCode, applied: 0, missed: 0, rows: [] })
 
+/** Called after the existing audit. An unavailable explanation must not change the refusal. */
+async function closedDoor(door: string, deps: EntryApplyDeps): Promise<EntryApplyOutcome> {
+  const outcome = nothing('refused', 'door-closed')
+  try {
+    const refusal = await deps.refusalFor?.(door)
+    return refusal ? { ...outcome, refusal } : outcome
+  } catch (error) {
+    try {
+      deps.report?.('[ai-assistant] entry refusal explanation unavailable', error)
+    } catch {
+      /* A diagnostic sink cannot turn a closed door into a failed proposal request. */
+    }
+    return outcome
+  }
+}
+
 export function findEntryProposal(messages: StoredProposalMessage[], key: string): { proposal?: any; superseded: boolean } {
   let at = -1
   let proposal: any
@@ -85,7 +110,7 @@ export async function applyEntryProposal(key: string, deps: EntryApplyDeps, targ
   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')
+    return closedDoor(door, deps)
   }
 
   /* Read again from the stored values - the same rules, and today's records for the target's checks. */
@@ -176,7 +201,7 @@ async function applyChanges(key: string, proposal: any, target: EntryTarget, dep
   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')
+      return closedDoor(door, deps)
     }
   }
 

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

@@ -0,0 +1,73 @@
+const mockJudge = jest.fn()
+const mockLookup = jest.fn()
+jest.mock('@things-factory/auth-base', () => ({
+  judgePermission: (...args: any[]) => mockJudge(...args),
+  privilegeOfField: (...args: any[]) => mockLookup(...args),
+  privilegeRejection: jest.requireActual('../../../../auth-base/server/service/privilege/privilege-rejection').privilegeRejection
+}))
+
+import { entryRefusalFor } from './entry-refusal'
+import { requestableFrom } from '../../../../auth-ui/client/utils/access-request'
+
+const gate = { category: 'warehouse', privilege: 'mutation', owner: true, super: true }
+const state = { domain: { id: 'd' }, user: { id: 'u' }, unsafeIP: true, prohibitedPrivileges: [{ category: 'warehouse', privilege: 'mutation', by: 'license' }] }
+
+beforeEach(() => {
+  mockJudge.mockReset().mockResolvedValue({ permitted: false, because: 'role' })
+  mockLookup.mockReset().mockReturnValue({ known: true, gate })
+})
+
+it('uses AUTH\'s full judgement and declaration, not a guess from a closed boolean', async () => {
+  const refusal = await entryRefusalFor({ state })('Mutation.updateInboundPlan')
+  expect(mockLookup).toHaveBeenCalledWith('Mutation', 'updateInboundPlan')
+  expect(mockJudge).toHaveBeenCalledWith(gate, state.user, state.domain, true, state.prohibitedPrivileges)
+  expect(refusal).toEqual({
+    message: 'unauthorized! warehouse:mutation privilege required',
+    extensions: { code: 'FORBIDDEN', requires: { category: 'warehouse', privilege: 'mutation' }, because: 'role', operation: 'mutation' },
+    path: ['updateInboundPlan']
+  })
+  expect(requestableFrom(refusal?.extensions, refusal?.path[0])).toEqual({ category: 'warehouse', privilege: 'mutation', operationName: 'updateInboundPlan' })
+})
+
+it.each(['address', 'license', 'ownership', 'unknown'])('carries %s without offering a role request', async because => {
+  mockJudge.mockResolvedValue({ permitted: false, because })
+  const refusal = await entryRefusalFor({ state })('Mutation.updateInboundPlan')
+  expect(refusal?.extensions.because).toBe(because)
+  expect(requestableFrom(refusal?.extensions)).toBeNull()
+})
+
+it('a failed read stays a query even when applyEntryProposal is a mutation', async () => {
+  const refusal = await entryRefusalFor({ state })('Query.inboundPlans')
+  expect(refusal?.extensions.operation).toBe('query')
+  expect(refusal?.path).toEqual(['inboundPlans'])
+  expect(requestableFrom(refusal?.extensions)).toBeNull()
+})
+
+it('ownership-only carries no named requirement', async () => {
+  mockLookup.mockReturnValue({ known: true, gate: { owner: true } })
+  mockJudge.mockResolvedValue({ permitted: false, because: 'ownership' })
+  expect((await entryRefusalFor({ state })('Mutation.reset'))?.extensions.requires).toBe('ownership')
+})
+
+it('unknown, malformed and open doors supply no invented refusal', async () => {
+  expect(await entryRefusalFor({ state })('not-a-door')).toBeUndefined()
+  expect(mockLookup).not.toHaveBeenCalled()
+  for (const lookup of [{ known: false }, { known: true, gate: null }]) {
+    mockLookup.mockReturnValue(lookup)
+    expect(await entryRefusalFor({ state })('Mutation.updateInboundPlan')).toBeUndefined()
+  }
+  expect(mockJudge).not.toHaveBeenCalled()
+})
+
+it('missing caller and a newly permitted judgement supply no refusal', async () => {
+  for (const context of [undefined, { state: { user: state.user } }, { state: { domain: state.domain } }])
+    expect(await entryRefusalFor(context)('Mutation.updateInboundPlan')).toBeUndefined()
+  expect(mockJudge).not.toHaveBeenCalled()
+  mockJudge.mockResolvedValue({ permitted: true })
+  expect(await entryRefusalFor({ state })('Mutation.updateInboundPlan')).toBeUndefined()
+})
+
+it('uses the request translator for the refusal sentence', async () => {
+  const refusal = await entryRefusalFor({ state, t: () => '권한이 필요합니다.' })('Mutation.updateInboundPlan')
+  expect(refusal?.message).toBe('권한이 필요합니다.')
+})

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

@@ -0,0 +1,20 @@
+import { judgePermission, privilegeOfField, privilegeRejection } from '@things-factory/auth-base'
+import { doorField } from '../chat-message/door-access.js'
+import type { EntryRefusal } from './entry-apply.js'
+
+/** Presentation only: AUTH still guards the application's mutation when it is executed. */
+export function entryRefusalFor(context: { state?: any; t?: any } | undefined): (door: string) => Promise<EntryRefusal | undefined> {
+  return async door => {
+    const { domain, user, unsafeIP, prohibitedPrivileges } = context?.state ?? {}
+    const field = doorField(door)
+    if (!domain || !user || !field) return undefined
+    const asked = privilegeOfField(field.typeName, field.fieldName)
+    if (!asked.known || !asked.gate) return undefined
+    const judgement = await judgePermission(asked.gate as any, user, domain, unsafeIP, prohibitedPrivileges)
+    /* The gate may have opened since the preflight: never invent a refusal to explain that race. */
+    if (judgement.permitted !== false) return undefined
+    const operation = field.typeName === 'Mutation' ? 'mutation' : field.typeName === 'Query' ? 'query' : 'subscription'
+    const error = privilegeRejection(context, asked.gate.category, asked.gate.privilege, judgement.because, operation)
+    return { message: error.message, extensions: error.extensions, path: [field.fieldName] }
+  }
+}

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

@@ -13,6 +13,7 @@ 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'
+import { entryRefusalFor } from './entry-refusal.js'
 
 @Resolver()
 export class EntryProposalResolver {
@@ -57,6 +58,7 @@ export class EntryProposalResolver {
       messages: carrying.map((message: any) => ({ id: message.id, proposals: message.proposalsJson ?? [] })),
       answered: entryProposalAnswered(key, lines.map((line: any) => line.content)),
       passesDoor: door => passes(door),
+      refusalFor: entryRefusalFor(context),
       state: context.state,
       /*
        * The application's API, as the person - the same request state the door would have seen had they typed

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

@@ -0,0 +1,229 @@
+/*
+ * AI 조회 (design/ai/read-targets.md) - the conditions become the application's filters, the rows are read through
+ * its query page by page, the server counts and sums, a long result goes on the workspace as read, and the screen
+ * card says which conditions it does not take.
+ */
+import { modeToolCategories } from '../assistant-mode/resolve'
+import { clearReadTargets, declareReadTarget, groupsOf, MAX_READ_ROWS, queryToolName, readCategoryName, screenAddress, screenToolName, type ReadTarget } from './read-target'
+import { openScreen, queryRecords, readCategoryOf } from './read-tools'
+
+/* The application, as a fake: a bank ledger behind a list query that pages and filters like ListParam. */
+let ledger: any[]
+const calls: any[] = []
+const run = async (_document: string, variables: any) => {
+  calls.push(variables)
+  const keep = (row: any) =>
+    variables.filters.every((f: any) =>
+      f.operator === 'gte' ? row[f.name] >= f.value : f.operator === 'lte' ? row[f.name] <= f.value : f.operator === 'eq' ? row[f.name] === f.value : String(row[f.name] ?? '').includes(f.value)
+    )
+  const all = ledger.filter(keep)
+  const { page, limit } = variables.pagination
+  return { data: { cashTransactions: { items: all.slice((page - 1) * limit, page * limit), total: all.length } } }
+}
+
+const target: ReadTarget = {
+  key: 'office.cash-transaction',
+  labelKey: 'label.office-read-cash-transaction',
+  description: 'bank transactions.',
+  query: 'query ($filters: [Filter!], $pagination: Pagination, $sortings: [Sorting!]) { cashTransactions(filters: $filters, pagination: $pagination, sortings: $sortings) { items { id transactionDate type amount customerName account { name } } total } }',
+  criteria: [
+    { name: 'from', type: 'date', filter: v => ({ name: 'transactionDate', operator: 'gte', value: v }) },
+    { name: 'to', type: 'date', filter: v => ({ name: 'transactionDate', operator: 'lte', value: v }) },
+    { name: 'flow', type: 'enum', values: ['INCOME', 'EXPENSE'], filter: v => ({ name: 'type', operator: 'eq', value: v }) },
+    { name: 'text', type: 'string', filter: v => ({ name: 'customerName', operator: 'search', value: v }) }
+  ],
+  columns: [
+    { name: 'transactionDate', type: 'date' },
+    { name: 'account', path: 'account.name', type: 'string' },
+    { name: 'type', type: 'string' },
+    { name: 'amount', type: 'number', total: true },
+    { name: 'customerName', type: 'string' }
+  ],
+  rowsOf: data => ({ rows: data.cashTransactions.items, total: data.cashTransactions.total }),
+  screen: { route: 'cash-transaction-list', takes: ['flow', 'text'], params: c => ({ flow: c.flow as string, search: c.text as string }) }
+}
+
+const tx = (i: number, date: string, type: string, amount: number, customerName: string) => ({ id: `t${i}`, transactionDate: date, type, amount, customerName, account: { name: '우리은행' } })
+
+beforeEach(() => {
+  clearReadTargets()
+  calls.length = 0
+  ledger = [
+    tx(1, '2026-04-03', 'EXPENSE', 1_000_000, '외주A'),
+    tx(2, '2026-05-10', 'EXPENSE', 250_000, '카카오T'),
+    tx(3, '2026-05-20', 'INCOME', 9_000_000, '고객사'),
+    tx(4, '2026-09-30', 'EXPENSE', 2_000_000, '외주A'),
+    tx(5, '2026-10-01', 'EXPENSE', 70_000, '스타벅스')
+  ]
+})
+
+describe('reading a list', () => {
+  it('★ the conditions become the application\'s filters - the model never names the query\'s columns', async () => {
+    const result: any = await queryRecords(target, { from: '2026-04-01', to: '2026-09-30', flow: 'EXPENSE' }, {}, run)
+    expect(calls[0].filters).toEqual([
+      { name: 'transactionDate', operator: 'gte', value: '2026-04-01' },
+      { name: 'transactionDate', operator: 'lte', value: '2026-09-30' },
+      { name: 'type', operator: 'eq', value: 'EXPENSE' }
+    ])
+    expect(result).toMatchObject({ total: 3, read: 3, complete: true, sums: { amount: 3_250_000 } })
+    expect(result.rows[0]).toEqual({ id: 't1', transactionDate: '2026-04-03', account: '우리은행', type: 'EXPENSE', amount: 1_000_000, customerName: '외주A' })
+    expect(result.proposed).toBeUndefined()
+  })
+
+  it('★ the server groups and sums - by a column largest first, by a date column per month', async () => {
+    const byName: any = await queryRecords(target, { flow: 'EXPENSE', groupBy: 'customerName' }, {}, run)
+    expect(byName.groups[0]).toEqual({ key: '외주A', count: 2, sums: { amount: 3_000_000 } })
+    const byMonth: any = await queryRecords(target, { flow: 'EXPENSE', groupBy: 'transactionDate' }, {}, run)
+    expect(byMonth.groups.map((group: any) => group.key)).toEqual(['2026-04', '2026-05', '2026-09', '2026-10'])
+    expect(groupsOf(target, [], 'nothing')).toBeUndefined()
+  })
+
+  it('a condition that does not fit its type is refused, not guessed at', async () => {
+    const result: any = await queryRecords(target, { from: '지난달', flow: 'OUT' }, {}, run)
+    expect(result).toMatchObject({ rejected: true, error: 'condition-unreadable' })
+    expect(result.refused.map((one: any) => one.name)).toEqual(['from', 'flow'])
+    expect(calls).toHaveLength(0)
+  })
+
+  it('★ a long result goes on the workspace as read - the model gets 20 rows, the card every row', async () => {
+    ledger = Array.from({ length: 450 }, (_, i) => tx(i, `2026-06-${String((i % 28) + 1).padStart(2, '0')}`, 'EXPENSE', 1000 + i, `거래처${i % 7}`))
+    const result: any = await queryRecords(target, { flow: 'EXPENSE', groupBy: 'customerName' }, { t: (key: string) => (key === 'label.office-read-cash-transaction' ? '은행 입출금' : key) }, run)
+    expect(calls.map(one => one.pagination.page)).toEqual([1, 2, 3])
+    expect(result).toMatchObject({ proposed: true, kind: 'workspace', total: 450, read: 450, complete: true, rowsNotShown: 430 })
+    expect(result.rows).toHaveLength(20)
+    const tables = result.forScreen.workspace.blocks.filter((block: any) => block.kind === 'table')
+    expect(tables.map((table: any) => table.rows.length)).toEqual([7, 450])
+    expect(result.forScreen.workspace.title).toBe('은행 입출금 · 450')
+    expect(result.forScreen.workspace.name).toBe('office-cash-transaction')
+  })
+
+  it('★ more than the read limit is said - the sums are of the rows read, never called the total', async () => {
+    ledger = Array.from({ length: MAX_READ_ROWS + 30 }, (_, i) => tx(i, '2026-06-01', 'EXPENSE', 1, 'x'))
+    const result: any = await queryRecords(target, {}, {}, run)
+    expect(result).toMatchObject({ total: MAX_READ_ROWS + 30, read: MAX_READ_ROWS, complete: false, sums: { amount: MAX_READ_ROWS } })
+    expect(result.message).toMatch(/Only 1000 of 1030 rows were read/)
+  })
+
+  it('a query the person may not run is said as it failed', async () => {
+    const result: any = await queryRecords(target, {}, {}, async () => ({ errors: [{ message: 'unauthorized! office:query privilege required' }] }))
+    expect(result).toMatchObject({ rejected: true, error: 'query-failed' })
+  })
+})
+
+describe('the screen card', () => {
+  it('★ the address carries what the screen takes, and the card names what it does not', () => {
+    expect(screenAddress(target, { flow: 'EXPENSE', from: '2026-04-01', text: '외주' })).toEqual({
+      href: 'cash-transaction-list?flow=EXPENSE&search=%EC%99%B8%EC%A3%BC',
+      applied: ['flow', 'text'],
+      notApplied: ['from']
+    })
+    const card: any = openScreen(target, { flow: 'EXPENSE', from: '2026-04-01' }, {})
+    expect(card).toMatchObject({ proposed: true, kind: 'open-page', href: 'cash-transaction-list?flow=EXPENSE', notApplied: ['from'] })
+    expect(card.message).toMatch(/does not take from/)
+  })
+})
+
+describe('declaring and offering', () => {
+  it('★ the tools are locked by the list query\'s door, and a mode opens them by key', () => {
+    const category = readCategoryOf(target, () => run)
+    expect(category.name).toBe(readCategoryName(target.key))
+    expect(category.specs.map(spec => spec.name)).toEqual([queryToolName(target.key), screenToolName(target.key)])
+    expect(category.specs.map(spec => (spec as any).doors)).toEqual([['Query.cashTransactions'], ['Query.cashTransactions']])
+    expect(modeToolCategories({ readTargets: [target.key] })).toContain('data-read:office.cash-transaction')
+  })
+
+  it('a declaration that would mislead is refused at boot', () => {
+    declareReadTarget(target)
+    expect(() => declareReadTarget(target)).toThrow(/declared twice/)
+    expect(() => declareReadTarget({ ...target, key: 'office.x', screen: { ...target.screen!, takes: ['amount'] } })).toThrow(/takes 'amount', which is no condition/)
+    expect(() => declareReadTarget({ ...target, key: 'office.y', columns: [] })).toThrow(/shows no column/)
+  })
+
+  it('every condition has one schema type - Gemini refuses a list of types', () => {
+    const [query] = readCategoryOf(target, () => run).specs as any[]
+    for (const [name, schema] of Object.entries<any>(query.schema.properties)) expect(typeof schema.type).toBe('string')
+  })
+})
+
+describe('one record', () => {
+  it('★ one record by its id - every target takes it, and its every column comes back', async () => {
+    const result: any = await queryRecords(target, { id: 't3' }, {}, run)
+    expect(calls[0].filters).toEqual([{ name: 'id', operator: 'eq', value: 't3' }])
+    expect(result.record).toEqual({ id: 't3', transactionDate: '2026-05-20', account: '우리은행', type: 'INCOME', amount: 9_000_000, customerName: '고객사' })
+    expect(result.message).toMatch(/one record/)
+  })
+
+  it('a list answer names each row by its id - the next question can ask for one', async () => {
+    const result: any = await queryRecords(target, { flow: 'INCOME', text: '고객' }, {}, run)
+    expect(result.record?.id).toBe('t3')
+    const list: any = await queryRecords(target, { flow: 'EXPENSE' }, {}, run)
+    expect(list.rows.every((row: any) => typeof row.id === 'string')).toBe(true)
+  })
+
+  it('a target may not declare id itself', () => {
+    expect(() => declareReadTarget({ ...target, key: 'office.z', criteria: [{ name: 'id', type: 'string', filter: v => ({ name: 'id', operator: 'eq', value: v }) }] })).toThrow(/every target takes it/)
+  })
+})
+
+describe('the text condition', () => {
+  it('★ a target that takes ListParam search sends the words as search - the resolver finds them in its own fields', async () => {
+    const searching: ReadTarget = { ...target, key: 'office.searching', criteria: target.criteria.filter(one => one.name !== 'text'), search: { description: 'the memo and the counterparty' } }
+    const seen: any[] = []
+    await queryRecords(searching, { text: '외주', flow: 'EXPENSE' }, {}, async (_d, variables) => (seen.push(variables), { data: { cashTransactions: { items: [], total: 0 } } }))
+    expect(seen[0].search).toBe('외주')
+    expect(seen[0].filters).toEqual([{ name: 'type', operator: 'eq', value: 'EXPENSE' }])
+    const [query] = readCategoryOf(searching, () => run).specs as any[]
+    expect(query.schema.properties.text.description).toMatch(/the memo and the counterparty/)
+    expect(() => declareReadTarget({ ...target, key: 'office.both', search: { description: 'x' } })).toThrow(/search is the text condition/)
+  })
+})
+
+describe('a list declared in one line', () => {
+  const { listReadTarget } = require('./list-read')
+  const line = {
+    key: 'office.cash-transaction',
+    title: 'menu.cash-transaction-list',
+    name: '자금 입출금 관리',
+    listQuery: 'cashTransactions',
+    selection: 'id transactionDate type amount balance customerName',
+    columns: [
+      { name: 'transactionDate', type: 'date' },
+      { name: 'type', type: 'string' },
+      { name: 'amount', type: 'number', total: true },
+      { name: 'balance', type: 'number' }
+    ],
+    dateField: 'transactionDate',
+    narrowing: { year: 'year', month: 'month', flow: 'type' },
+    search: 'memo and counterparty',
+    route: 'cash-transaction-list',
+    screenTakes: ['year', 'month', 'flow', 'text']
+  }
+
+  it('★ becomes a target with the conditions its fields allow - and only those', async () => {
+    const made: ReadTarget = listReadTarget(line)
+    declareReadTarget(made)
+    expect(made.criteria.map(one => one.name)).toEqual(['from', 'to', 'year', 'month', 'flow', 'minAmount', 'maxAmount'])
+    expect(made.query).toContain('cashTransactions(filters: $filters, pagination: $pagination, sortings: $sortings, search: $search) { items { id transactionDate type amount balance customerName } total }')
+    const bare: ReadTarget = listReadTarget({ ...line, key: 'office.bare', narrowing: undefined, dateField: undefined, search: undefined, columns: [{ name: 'name', type: 'string' }] })
+    expect(bare.criteria).toEqual([])
+    expect(bare.query).not.toContain('$search')
+    expect(bare.screen!.takes).toEqual([])
+  })
+
+  it('★ the to day takes the whole day of a date-time, and the screen gets only what it reads', () => {
+    const made: ReadTarget = listReadTarget(line)
+    const to = made.criteria.find(one => one.name === 'to')!
+    expect(to.filter('2026-09-30')).toEqual({ name: 'transactionDate', operator: 'lte', value: '2026-09-30T23:59:59.999' })
+    expect(made.screen!.params({ year: 2026, month: 9, flow: 'EXPENSE', text: '외주', from: '2026-01-01' })).toEqual({ year: 2026, month: 9, flow: 'EXPENSE', search: '외주' })
+    expect(made.screen!.params({ month: 9 })).toEqual({})
+    const plain: ReadTarget = listReadTarget({ ...line, key: 'plant.x', screenTakes: undefined })
+    expect(plain.screen!.takes).toEqual([])
+    expect(plain.screen!.params({ year: 2026 })).toEqual({})
+  })
+
+  it('a minimum or maximum amount means the amount column, else the first summed one', () => {
+    const made: ReadTarget = listReadTarget({ ...line, key: 'office.claims', columns: [{ name: 'totalAmount', type: 'number', total: true }] })
+    expect(made.criteria.find(one => one.name === 'minAmount')!.filter(5)).toEqual({ name: 'totalAmount', operator: 'gte', value: 5 })
+  })
+})
+