@things-factory/figure-service 10.1.6 → 10.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.6",
+  "version": "10.1.8",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -23,14 +23,14 @@
     "migration:create": "node ../../node_modules/typeorm/cli.js migration:create ./server/migrations/migration"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.15",
+    "@hatiolab/figure-model": "file:../../../figure-model",
     "@operato/typeorm-history": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.6",
-    "@things-factory/auth-base": "^10.1.6",
+    "@things-factory/ai-client-base": "^10.1.8",
+    "@things-factory/auth-base": "^10.1.7",
     "@things-factory/env": "^10.1.3",
-    "@things-factory/shell": "^10.1.4",
+    "@things-factory/shell": "^10.1.7",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "963aeb9ac470be5aea05bb5842a0a92afcab6036"
+  "gitHead": "c402982e29aab3b49e56bea4e41948be6a749c7f"
 }

package/server/service/figure/catalog-db.test.ts

@@ -0,0 +1,162 @@
+/**
+ * 분류와 태그가 **정말 써지는가** — sqlite 를 실제로 들고 확인한다.
+ *
+ * ── 왜 순수 시험으로는 부족한가 ─────────────────────────────────────────────
+ * 이 저장 경로는 읽어 온 엔티티를 펼쳐 `save` 한다(`{ ...figure, ...patch }`). 그 모양은 칸이
+ * **조용히 안 써지는** 자리로 알려져 있다 — `save` 는 정상 반환하고 로그도 성공이라고 말한다.
+ * 다른 레인이 도메인 시각대를 그렇게 잃었고, `select` 를 해 보기 전에는 못 찾았다.
+ *
+ * 그래서 여기서는 반환값을 믿지 않고 **저장소에서 다시 읽는다.**
+ *
+ * ── 이 하네스로 볼 수 없는 것 ───────────────────────────────────────────────
+ * sqlite 다. 동시성·격리·컬럼 타입 방언은 여기서 초록이어도 근거가 아니다. `simple-json` 이
+ * 드라이버마다 어떻게 저장되는지도 postgres 에서 따로 봐야 한다 — 여기서 보는 것은 **왕복**이다.
+ */
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+/* Figure 가 creator·updater 로 User 를 가리킨다 — 그 엔티티가 없으면 메타데이터가 안 선다. */
+const authBase = require('@things-factory/auth-base')
+
+let dataSource: DataSource | null = null
+let Figure: any
+
+/*
+  엔티티는 컴파일된 산출물에서 든다.
+
+  `@Field({ nullable: true })` 처럼 명시 타입이 없는 type-graphql 데코레이터는
+  `emitDecoratorMetadata` 가 있어야 읽히는데 jest 의 변환기는 babel 이라 그것을 못 낸다.
+  소스에서 들면 import 시점에 죽는다. auth-base 가 같은 이유로 같은 길을 간다(tests/compiled.ts).
+*/
+function loadCompiled(modulePath: string): any {
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+  const resolved = join(__dirname, '..', '..', '..', 'dist-server', `${modulePath}.js`)
+
+  if (!existsSync(resolved)) {
+    throw new Error(
+      `figure-service 산출물이 없다: ${resolved}\n` +
+        `이 시험은 tsc 산출물을 든다. 먼저 빌드할 것:\n` +
+        `  yarn workspace @things-factory/figure-service build:server`
+    )
+  }
+
+  return require(resolved)
+}
+
+beforeAll(async () => {
+  Figure = loadCompiled('service/figure/figure').Figure
+
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, Figure],
+    logging: false
+  })
+
+  await dataSource.initialize()
+  shell.addDataSource('default', dataSource)
+  shell.addDataSource('tx', dataSource)
+})
+
+beforeEach(async () => {
+  await dataSource!.synchronize(true)
+})
+
+afterAll(async () => {
+  if (!dataSource) return
+  shell.removeDataSource('default')
+  shell.removeDataSource('tx')
+  await dataSource.destroy()
+  dataSource = null
+})
+
+/** 저장소에서 **다시 읽은** 것. 반환값이 아니라 이것이 근거다. */
+async function readBack(id: string) {
+  return await dataSource!.getRepository(Figure).findOne({ where: { id } })
+}
+
+async function seed(over: Record<string, unknown> = {}) {
+  const repository = dataSource!.getRepository(Figure)
+  return await repository.save({
+    type: 'CONVEYOR',
+    name: '컨베이어',
+    source: '{}',
+    state: 'draft',
+    ...over
+  })
+}
+
+describe('태그가 정말 써진다', () => {
+  it('여럿 붙고, 다시 읽어도 그대로다', async () => {
+    const saved = await seed({ tags: ['반출', '자동'] })
+    const read = await readBack(saved.id)
+
+    expect(read!.tags).toEqual(['반출', '자동'])
+  })
+
+  /*
+    이 저장 경로의 모양이다 — 읽어 온 것을 펼쳐 새 값을 얹는다. 여기서 칸이 조용히 빠지는 것이
+    기억에 남은 그 함정이다.
+  */
+  it('읽어 온 것을 펼쳐 얹어도 써진다 — save 가 그 칸을 흘리지 않는다', async () => {
+    const saved = await seed({ tags: ['반출'] })
+    const before = await readBack(saved.id)
+
+    await dataSource!.getRepository(Figure).save({ ...before, tags: ['반출', '2층'] })
+
+    expect((await readBack(saved.id))!.tags).toEqual(['반출', '2층'])
+  })
+
+  it('빈 배열은 전부 지운다 — 지울 방법이 있어야 한다', async () => {
+    const saved = await seed({ tags: ['반출'] })
+    const before = await readBack(saved.id)
+
+    await dataSource!.getRepository(Figure).save({ ...before, tags: [] })
+
+    expect((await readBack(saved.id))!.tags).toEqual([])
+  })
+
+  it('안 준 도형은 태그가 없다 — 빈 배열로 갈음하지 않는다', async () => {
+    const saved = await seed()
+
+    expect((await readBack(saved.id))!.tags).toBeNull()
+  })
+})
+
+describe('분류는 하나다', () => {
+  it('써지고 다시 읽힌다', async () => {
+    const saved = await seed({ category: '컨베이어' })
+
+    expect((await readBack(saved.id))!.category).toBe('컨베이어')
+  })
+
+  it('분류와 태그는 서로 손대지 않는다', async () => {
+    const saved = await seed({ category: '컨베이어', tags: ['반출'] })
+    const before = await readBack(saved.id)
+
+    await dataSource!.getRepository(Figure).save({ ...before, tags: ['반출', '자동'] })
+    const read = await readBack(saved.id)
+
+    expect(read!.category).toBe('컨베이어')
+    expect(read!.tags).toEqual(['반출', '자동'])
+  })
+})
+
+describe('★ 이 시험이 실제로 DB 를 읽고 있다', () => {
+  it('없는 것을 물으면 없다고 한다 — 늘 초록이 아니다', async () => {
+    expect(await readBack('없는-id')).toBeNull()
+  })
+
+  it('표가 실제로 서 있다', async () => {
+    const saved = await seed()
+    const rows = await dataSource!.query('select count(*) as n from figures')
+
+    expect(Number(rows[0].n)).toBe(1)
+    expect(saved.id).toBeTruthy()
+  })
+})

package/server/service/figure/figure-ai-flow.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Figure AI의 결정적 종단 흐름.
+ *
+ * 외부 공급자·DB를 띄우지 않되, 도크 host context → 도구 → 실제 후보 생성/검사 → 후보 카드라는
+ * 경계를 한 번에 지난다. 단위 시험만으로는 피드백이 도구 입력에서 끊기거나, 검증된 후보가 카드
+ * 표시를 잃는 연결 결함을 놓칠 수 있다.
+ */
+import { clearToolRegistry, getToolCategories, setDefaultAIClient } from '@things-factory/ai-client-base'
+import type { AIClient } from '@things-factory/ai-client-base'
+
+import { __setFigureToolDepsForTest, registerFigureToolCategories } from './figure-tools'
+import { proposeFigure } from './figure-propose'
+
+const DOMAIN = { id: 'domain-mine' }
+const SOURCE = {
+  type: 'MIXER', base: { x: 300, y: 500, z: 300 }, detailLevel: 'M',
+  parts: [{
+    name: 'body', primitive: 'cylinder', segments: 12,
+    transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 300, y: 400, z: 300 } },
+    material: { token: 'palette.primary' }
+  }]
+}
+const ROW = { id: 'fig-1', type: 'MIXER', name: '믹서', state: 'draft', domain: DOMAIN, source: JSON.stringify(SOURCE) }
+
+function client(): AIClient & { sent: any[][] } {
+  const fake = {
+    id: 'deterministic-figure-flow',
+    sent: [] as any[][],
+    async chat() { return '' },
+    async generateJSON(messages: any[]) {
+      fake.sent.push(JSON.parse(JSON.stringify(messages)))
+      return SOURCE
+    }
+  }
+  return fake as unknown as AIClient & { sent: any[][] }
+}
+
+beforeEach(() => {
+  clearToolRegistry()
+  const model = require('@hatiolab/figure-model')
+  __setFigureToolDepsForTest({
+    getRepository: () => ({
+      async findOne({ where }: any) { return where.id === ROW.id && where.domain?.id === DOMAIN.id ? ROW : null },
+      async find({ where }: any) { return where.domain?.id === DOMAIN.id ? [ROW] : [] }
+    }),
+    Figure: class {},
+    inspectSource: () => ({ blocked: false, findings: [] }),
+    proposeFigure,
+    compile: model.compile,
+    costOf: model.costOf,
+    scoreOf: model.scoreOf,
+    validate: model.validate
+  })
+  registerFigureToolCategories()
+})
+
+afterEach(() => {
+  clearToolRegistry()
+  setDefaultAIClient(undefined)
+})
+
+test('초안·세션 피드백을 반영한 후보가 검증·품질 근거와 카드 표시를 거쳐 돌아온다', async () => {
+  const fake = client()
+  setDefaultAIClient(fake)
+  const propose = getToolCategories()
+    .find((category: any) => category.name === 'figure-authoring')!
+    .specs.find((spec: any) => spec.name === 'proposeFigureCandidate') as any
+
+  const result = await propose.builder(
+    { prompt: '포트가 더 잘 읽히도록 고쳐줘' },
+    {
+      state: {
+        domain: DOMAIN,
+        host: {
+          figureId: 'fig-1',
+          palette: ['palette.primary'],
+          draftSource: SOURCE,
+          proposalFeedback: [{
+            outcome: 'discarded', selectedChanges: 0, totalChanges: 3,
+            note: '실루엣은 유지하고 포트의 대비를 높여줘',
+            quality: { status: 'review', findingCodes: ['top-view-readability'] }
+          }]
+        }
+      }
+    }
+  )
+
+  expect(fake.sent).toHaveLength(1)
+  expect(fake.sent[0]![0]!.content).toContain('Revise this existing figure')
+  expect(fake.sent[0]![0]!.content).toContain('실루엣은 유지하고 포트의 대비를 높여줘')
+  expect(result.proposed).toBe(true)
+  expect(result.source.type).toBe('MIXER')
+  expect(result.quality).toEqual(expect.objectContaining({ status: expect.stringMatching(/^(ready|review)$/) }))
+  expect(result.cost.triangles).toBeGreaterThan(0)
+})

package/server/service/figure/figure-gate.test.ts

@@ -0,0 +1,32 @@
+import { inspectSource } from './figure-gate'
+
+describe('release-gate repair candidates', () => {
+  it('returns data, not parsed prose, for a measured sizing split', () => {
+    const source = {
+      type: 'STACK',
+      base: { x: 100, y: 200, z: 100 },
+      detailLevel: 'M',
+      parts: [
+        {
+          name: 'foot', primitive: 'cube',
+          transform: { position: { x: 0, y: -50, z: 0 }, size: { x: 100, y: 100, z: 100 } },
+          material: { token: 'palette.primary' }, anchor: { y: 'min' }
+        },
+        {
+          name: 'lamp', primitive: 'cube',
+          transform: { position: { x: 0, y: 10, z: 0 }, size: { x: 60, y: 20, z: 60 } },
+          material: { token: 'palette.accent' }, anchor: { y: 'max' }
+        }
+      ]
+    }
+
+    const inspection = inspectSource(JSON.stringify(source))
+    const split = inspection.findings.find(finding => finding.code === 'sizing-splits')
+
+    expect(inspection.blocked).toBe(true)
+    expect(split?.fixes).toEqual(expect.arrayContaining([
+      expect.objectContaining({ part: expect.any(String), axis: 'y', to: expect.any(String), resolved: expect.any(Number), safe: expect.any(Boolean) })
+    ]))
+    expect(split?.fixes?.every(fix => fix.resolved > 0)).toBe(true)
+  })
+})

package/server/service/figure/figure-gate.ts

@@ -1,5 +1,17 @@
 import { compile, sizingReport, validate } from '@hatiolab/figure-model'
-import type { FigureSource } from '@hatiolab/figure-model'
+import type { Axis, FigureSource } from '@hatiolab/figure-model'
+
+/** Service transport shape. It deliberately contains only an explicit, reversible FigureSource edit. */
+export interface GateFix {
+  findingWay: string
+  part: string
+  axis: Axis
+  from?: string
+  to: 'min' | 'center' | 'max' | 'span'
+  resolved: number
+  /** True only when rechecking every sizing case leaves no release-blocking split. */
+  safe: boolean
+}
 
 /**
  * 발행해도 되나 — **서버가 판정한다.**
@@ -43,6 +55,12 @@ export interface GateFinding {
   how?: string
   /** 어디를 가리키나 — 갈라짐은 갈라진 부품 이름들, 형식 위반은 정본 안의 경로. */
   at?: string
+  /**
+   * 실제로 재 본, 되돌릴 수 있는 한 앵커 수정안들. 문장을 파싱해서 고치는 것이 아니라
+   * FigureSource 에 적용할 정확한 값만 내보낸다. 화면은 이것을 후보로만 보여 주고 저작자가
+   * 수락하기 전에는 정본을 바꾸지 않는다.
+   */
+  fixes?: GateFix[]
   blocking: boolean
 }
 
@@ -52,6 +70,54 @@ export interface Inspection {
   blocked: boolean
 }
 
+/**
+ * Figure model publishes the same capability for direct model consumers. Keep the service calculation
+ * here as well because this package is deployed independently and receives a compiled local model package.
+ * Each alternative is remeasured; prose from `how` is never parsed into an edit.
+ */
+function measuredFixes(source: FigureSource, factor: number): GateFix[] {
+  const baseline = sizingReport(compile(source), factor)
+  const baselineCount = baseline.findings.filter(finding => finding.code === 'sizing-splits').length
+  const seen = new Set<string>()
+  const fixes: GateFix[] = []
+
+  for (const finding of baseline.findings) {
+    if (finding.code !== 'sizing-splits' || !finding.way) continue
+    const axes = finding.way.split('-').filter((axis): axis is Axis => ['x', 'y', 'z'].includes(axis))
+    const names = new Set(finding.clumps.flat())
+
+    for (const part of source.parts) {
+      if (!names.has(part.name)) continue
+      for (const axis of axes) {
+        for (const to of ['min', 'center', 'max', 'span'] as const) {
+          if (part.anchor?.[axis] === to) continue
+          const changed: FigureSource = {
+            ...source,
+            parts: source.parts.map(one => one.name === part.name ? { ...one, anchor: { ...(one.anchor ?? {}), [axis]: to } } : one)
+          }
+          const afterCount = sizingReport(compile(changed), factor).findings.filter(one => one.code === 'sizing-splits').length
+          const resolved = baselineCount - afterCount
+          const key = `${finding.way}:${part.name}:${axis}:${to}`
+          if (resolved <= 0 || seen.has(key)) continue
+          seen.add(key)
+          fixes.push({
+            findingWay: finding.way,
+            part: part.name,
+            axis,
+            from: part.anchor?.[axis],
+            to,
+            resolved,
+            /* 한 finding만 없앤 것이 아니라 전수 검사에서 막는 split이 0일 때만 원클릭 후보가 된다. */
+            safe: afterCount === 0
+          })
+        }
+      }
+    }
+  }
+
+  return fixes.sort((a, b) => b.resolved - a.resolved || a.part.localeCompare(b.part)).slice(0, 12)
+}
+
 /**
  * 정본 하나를 판정한다.
  *
@@ -99,7 +165,9 @@ export function inspectSource(sourceJson?: string | null): Inspection {
   }
 
   if (result.errors.length === 0) {
-    const report = sizingReport(compile(parsed as FigureSource))
+    const source = parsed as FigureSource
+    const report = sizingReport(compile(source))
+    const fixes = measuredFixes(source, report.factor)
 
     for (const finding of report.findings) {
       findings.push({
@@ -110,6 +178,7 @@ export function inspectSource(sourceJson?: string | null): Inspection {
         how: finding.how,
         /* 숫자가 아니라 자리를 말한다 — 어느 부품들이 갈라져 나왔나. */
         at: finding.clumps.map(clump => [...clump].sort().join('+')).join(' | ') || undefined,
+        fixes: finding.code === 'sizing-splits' ? fixes.filter(fix => fix.findingWay === finding.way) : undefined,
         blocking: finding.code === 'sizing-splits'
       })
     }

package/server/service/figure/figure-llm-smoke.test.ts

@@ -0,0 +1,91 @@
+/**
+ * 실제 LLM Figure 후보 생성 smoke test (기본 비활성).
+ *
+ * 결정적 시험은 프롬프트·도구·검사 배선을 고정하지만, 실제 모델이 FigureSource JSON을 지키는지는
+ * 대신할 수 없다. 이 시험은 `RUN_FIGURE_LLM_SMOKE=1`과 공급자 API 키가 모두 있을 때만 실행한다.
+ * DB·GraphQL·Figure 저장을 건드리지 않고 후보 생성 함수만 호출하므로, 외부 영향은 API 비용뿐이다.
+ *
+ * 실행:
+ *   RUN_FIGURE_LLM_SMOKE=1 OPENAI_API_KEY=... yarn test:figure-llm-smoke
+ * 선택: FIGURE_LLM_PROVIDER=anthropic|gemini|openai, FIGURE_LLM_MODEL=<model id>
+ */
+import { createAIClient, setDefaultAIClient } from '@things-factory/ai-client-base'
+
+import { proposeFigure } from './figure-propose'
+
+// Provider modules register themselves on import. Keep this separate from the deterministic tests.
+import '@things-factory/ai-client-base'
+
+type Provider = 'anthropic' | 'gemini' | 'openai'
+
+function provider(): { provider: Provider; apiKey: string } | undefined {
+  const requested = process.env.FIGURE_LLM_PROVIDER as Provider | undefined
+  const candidates: Array<{ provider: Provider; keys: string[] }> = [
+    { provider: 'anthropic', keys: ['ANTHROPIC_API_KEY'] },
+    { provider: 'gemini', keys: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'] },
+    { provider: 'openai', keys: ['OPENAI_API_KEY'] }
+  ]
+  const usable = requested ? candidates.filter(candidate => candidate.provider === requested) : candidates
+  for (const candidate of usable) {
+    const apiKey = candidate.keys.map(key => process.env[key]).find(Boolean)
+    if (apiKey) return { provider: candidate.provider, apiKey }
+  }
+  return undefined
+}
+
+const picked = process.env.RUN_FIGURE_LLM_SMOKE === '1' ? provider() : undefined
+const describeIf = picked ? describe : describe.skip
+const PALETTE = ['palette.primary', 'palette.accent', 'palette.neutral']
+
+describeIf('Figure 실제 LLM smoke', () => {
+  beforeAll(() => {
+    setDefaultAIClient(createAIClient({ ...picked!, ...(process.env.FIGURE_LLM_MODEL ? { model: process.env.FIGURE_LLM_MODEL } : {}) }))
+    // eslint-disable-next-line no-console
+    console.log(`[figure-llm-smoke] provider=${picked!.provider} model=${process.env.FIGURE_LLM_MODEL ?? '(adapter default)'}`)
+  })
+
+  afterAll(() => setDefaultAIClient(undefined))
+
+  test(
+    '새 Figure 후보는 유효한 어휘·팔레트·품질 근거를 가진다',
+    async () => {
+      const result = await proposeFigure({
+        prompt: 'two cylindrical rollers inside a simple rectangular press frame; make the rollers visually distinct',
+        type: 'ROLL_PRESS_SMOKE',
+        palette: PALETTE,
+        refine: true
+      })
+
+      expect(result.source.type).toBe('ROLL_PRESS_SMOKE')
+      expect(result.source.parts.length).toBeGreaterThan(0)
+      expect(result.source.parts.every(part => PALETTE.includes(part.material.token))).toBe(true)
+      expect(result.quality.status).toMatch(/^(ready|review)$/)
+      expect(result.cost.triangles).toBeGreaterThan(0)
+    },
+    90_000
+  )
+
+  test(
+    '수정 후보는 type을 보존하고 명시적 세션 피드백을 참고한다',
+    async () => {
+      const result = await proposeFigure({
+        prompt: 'make the port more visible from above while keeping the body and port part names',
+        palette: PALETTE,
+        refine: true,
+        base: {
+          type: 'MIXER_SMOKE', base: { x: 300, y: 400, z: 300 }, detailLevel: 'M',
+          parts: [
+            { name: 'body', primitive: 'cylinder', segments: 12, transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 280, y: 320, z: 280 } }, material: { token: 'palette.primary' } },
+            { name: 'port', primitive: 'cube', transform: { position: { x: 0, y: 30, z: -155 }, size: { x: 80, y: 60, z: 30 } }, material: { token: 'palette.accent' } }
+          ]
+        },
+        feedback: [{ outcome: 'discarded', selectedChanges: 0, totalChanges: 2, note: 'the port must read clearly in top view' }]
+      })
+
+      expect(result.source.type).toBe('MIXER_SMOKE')
+      expect(result.source.parts.map(part => part.name)).toEqual(expect.arrayContaining(['body', 'port']))
+      expect(result.quality).toBeDefined()
+    },
+    90_000
+  )
+})

package/server/service/figure/figure-mutation.ts

@@ -318,6 +318,8 @@ export class FigureMutation {
         base: request.base ? JSON.parse(request.base) : undefined,
         type: request.type,
         palette: request.palette,
+        refine: request.refine,
+        feedback: request.feedback,
         image
       })
 
@@ -327,6 +329,12 @@ export class FigureMutation {
         grade: result.score.grade,
         triangles: result.cost.triangles,
         groups: result.cost.groups,
+        quality: {
+          ...result.quality,
+          visualRegions: result.quality.visual.regions,
+          visualCoverage: result.quality.visual.coverage,
+          visualReadability: result.quality.visual.readability
+        },
         violations: result.violations,
         attempts: result.attempts
       }

package/server/service/figure/figure-propose-type.ts

@@ -4,6 +4,72 @@ import { Field, InputType, Int, ObjectType } from 'type-graphql'
 
 import { FigureFinding } from './figure-type.js'
 
+@ObjectType({ description: 'One explainable consideration from the model-grounded candidate review.' })
+export class FigureQualityFinding {
+  @Field({ description: 'What the consideration concerns: identity, silhouette, palette, performance, or resilience.' })
+  dimension: string
+
+  @Field({ description: 'Stable machine-readable review code.' })
+  code: string
+
+  @Field({ description: 'Human-readable evidence and recommended review.' })
+  message: string
+}
+
+@ObjectType({ description: 'Explainable design review based on Figure-model evidence, not a visual aesthetic claim.' })
+export class FigureQualityReview {
+  @Field({ description: 'ready when measurable checks are clear; review when author attention is recommended.' })
+  status: string
+
+  @Field({ description: 'Compact explanation of this review.' })
+  summary: string
+
+  @Field(type => [FigureQualityFinding], { description: 'Measured considerations for the author and assistant.' })
+  findings: FigureQualityFinding[]
+
+  @Field(type => Int, { description: 'Visible material regions in the reproducible top-view evidence.' })
+  visualRegions: number
+
+  @Field({ description: 'Top-view footprint coverage from 0 to 1.' })
+  visualCoverage: number
+
+  @Field({ description: 'Normalized top-view readability evidence from 0 to 1.' })
+  visualReadability: number
+
+}
+
+/** 제한된 후보 품질 코드. 현재 요청의 참고 데이터이며 어떤 Figure에도 저장되지 않는다. */
+@InputType({ description: 'Measured review summary from an earlier candidate in this authoring session.' })
+export class ProposalFeedbackQualityInput {
+  @Field({ nullable: true })
+  status?: string
+
+  @Field(type => [String], { nullable: true })
+  findingCodes?: string[]
+}
+
+/** 사람이 명시적으로 수락하거나 거절한 후보의 제한된 세션 반응. */
+@InputType({ description: 'Explicit author feedback for the next candidate. Session-only; never persisted.' })
+export class ProposalFeedbackInput {
+  @Field()
+  outcome: string
+
+  @Field(type => Int)
+  selectedChanges: number
+
+  @Field(type => Int)
+  totalChanges: number
+
+  @Field({ nullable: true })
+  note?: string
+
+  @Field({ nullable: true })
+  grade?: string
+
+  @Field(type => ProposalFeedbackQualityInput, { nullable: true })
+  quality?: ProposalFeedbackQualityInput
+}
+
 /**
  * 저작 보조에 넘기는 것.
  *
@@ -39,6 +105,15 @@ export class ProposeRequest {
 
   @Field(type => [String], { description: 'Palette tokens the client can resolve. Anything else is rejected.' })
   palette: string[]
+
+  @Field({ nullable: true, description: 'Ask for one evidence-grounded refinement when the first valid candidate needs review.' })
+  refine?: boolean
+
+  @Field(type => [ProposalFeedbackInput], {
+    nullable: true,
+    description: 'Explicit session-only feedback on earlier candidates. It is constrained again before prompting and never stored.'
+  })
+  feedback?: ProposalFeedbackInput[]
 }
 
 /**
@@ -64,6 +139,11 @@ export class FigureProposal {
   @Field(type => Int, { description: 'Material groups — the draw calls one instance costs' })
   groups: number
 
+  @Field(type => FigureQualityReview, {
+    description: 'Explainable design review. It advises the author and never saves or rejects the candidate.'
+  })
+  quality: FigureQualityReview
+
   @Field(type => [FigureFinding], {
     description: 'Policy violations. These do not block the proposal — the author decides.'
   })