@things-factory/ai-assistant 10.1.114 → 10.1.121

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.114",
+  "version": "10.1.121",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -34,11 +34,11 @@
     "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
     "@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/apptool-base": "^10.1.121",
+    "@things-factory/attachment-base": "^10.1.121",
+    "@things-factory/auth-base": "^10.1.121",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.106",
+    "@things-factory/shell": "^10.1.121",
     "dompurify": "^3.0.0",
     "exceljs": "4.2.0",
     "graphql-scalars": "^1.22.0",
@@ -52,5 +52,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "0d8f9bc0ff0cb50431f2c76cb166aaf3809d3cf7"
+  "gitHead": "23536a73b10f103048a2c893d3960b2a4e0f03dd"
 }

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/test/entry-proposal.test.ts

@@ -5,6 +5,9 @@
 import { readFileSync } from 'fs'
 import { join } from 'path'
 
+const mockNotify = jest.fn()
+jest.mock('@operato/layout', () => ({ notify: (...args: any[]) => mockNotify(...args) }))
+
 import { runProposal, setEntryProposalHandler } from '../client/utils/assistant-proposals'
 import {
   entryGroupOf,
@@ -78,6 +81,34 @@ describe('the entry card', () => {
     expect(outcome).toMatchObject({ verdict: 'accepted', applied: 1, missed: 0 })
   })
 
+  it('a closed door emits one generic notification and keeps its refused verdict', async () => {
+    const refusal = { message: 'required', extensions: { code: 'FORBIDDEN', because: 'role', operation: 'mutation', requires: { category: 'warehouse', privilege: 'mutation' } }, path: ['addExpenseLine'] }
+    const report = jest.fn()
+    const handler = entryProposalHandler(async () => ({ verdict: 'refused', errorCode: 'door-closed', applied: 0, missed: 0, refusal }), t, () => undefined, report)
+    const context = { sessionId: 's', confirm: async () => true, notify: () => {} }
+    expect(await handler(card('k'), context)).toMatchObject({ verdict: 'refused', errorCode: 'door-closed', applied: 0 })
+    expect(report.mock.calls).toEqual([[{ level: 'error', message: 'required', ex: [refusal] }]])
+    const broken = entryProposalHandler(async () => ({ verdict: 'refused', errorCode: 'door-closed', refusal }), t, () => undefined, () => { throw new Error('toast unavailable') })
+    expect(await broken(card('k'), context)).toMatchObject({ verdict: 'refused', errorCode: 'door-closed' })
+    const rejected = entryProposalHandler(async () => ({ verdict: 'refused', errorCode: 'door-closed', refusal }), t, () => undefined, async () => { throw new Error('async delivery unavailable') })
+    expect(await rejected(card('k'), context)).toMatchObject({ verdict: 'refused', errorCode: 'door-closed' })
+  })
+
+  it('successful and stale-review answers emit no refusal notification', async () => {
+    const report = jest.fn()
+    for (const answer of [{ verdict: 'accepted', applied: 1 }, { verdict: 'refused', errorCode: 'review-stale' }] as EntryApplyAnswer[]) {
+      await entryProposalHandler(async () => answer, t, () => undefined, report)(card('k'), { sessionId: 's', confirm: async () => true, notify: () => {} })
+    }
+    expect(report).not.toHaveBeenCalled()
+  })
+
+  it('the default transport passes the serialized refusal to layout, with no explicit action', async () => {
+    mockNotify.mockClear()
+    const refusal = { message: 'required', extensions: { code: 'FORBIDDEN' }, path: ['addExpenseLine'] }
+    await entryProposalHandler(async () => ({ verdict: 'refused', errorCode: 'door-closed', refusal }), t)(card('k'), { sessionId: 's', confirm: async () => true, notify: () => {} })
+    expect(mockNotify.mock.calls).toEqual([[{ level: 'error', message: 'required', ex: [refusal] }]])
+  })
+
   it('the chat draws the review and names the button by the rows it enters', () => {
     const chat = readFileSync(join(__dirname, '..', 'client', 'components', 'assistant-chat.ts'), 'utf8')
     expect(chat).toContain('<ox-assistant-entry-review .proposal=${p}>')
@@ -107,4 +138,3 @@ describe('the entry card', () => {
     expect(entryReadyCount(p)).toBe(2)
   })
 })
-