@things-factory/figure-service 10.1.3

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

@@ -0,0 +1,163 @@
+import { In } from 'typeorm'
+import { Arg, Ctx, Directive, Mutation, Resolver } from 'type-graphql'
+
+import { getRepository } from '@things-factory/shell'
+
+import { Figure } from './figure.js'
+import { FigurePatch, FigureSaveResult, NewFigure } from './figure-type.js'
+import { FigureProposal, ProposeRequest } from './figure-propose-type.js'
+import { parseSource } from './figure-source.js'
+import { ProposeFailure, proposeFigure } from './figure-propose.js'
+
+@Resolver(Figure)
+export class FigureMutation {
+  @Directive('@transaction')
+  @Directive('@privilege(category: "figure", privilege: "mutation", domainOwnerGranted: true)')
+  @Mutation(returns => FigureSaveResult, { description: 'Creates a figure. Rejects when the source violates the format.' })
+  async createFigure(
+    @Arg('figure') figure: NewFigure,
+    @Ctx() context: ResolverContext
+  ): Promise<FigureSaveResult> {
+    const { domain, user, tx } = context.state
+    const repository = tx.getRepository(Figure)
+
+    // 타입 이름은 도메인 안에서 유일하다. 유니크 인덱스가 있지만 여기서 먼저 본다 —
+    // DB 오류 문구는 저작자에게 아무 말도 해 주지 못한다.
+    const taken = await repository.findOne({ where: { domain: { id: domain.id }, type: figure.type } })
+    if (taken) {
+      throw new Error(`타입 이름 '${figure.type}' 은 이미 쓰이고 있다. 만든 뒤에는 고칠 수 없으므로 다른 이름을 고른다`)
+    }
+
+    // 형식을 어기면 여기서 던진다. 파생값은 서버가 계산한다.
+    const { source, derived, violations } = parseSource(figure.source)
+
+    const saved = await repository.save({
+      ...figure,
+      source,
+      ...derived,
+      state: figure.state ?? 'draft',
+      thumbnailUpdatedAt: figure.thumbnail ? new Date() : undefined,
+      domain,
+      creator: user,
+      updater: user
+    })
+
+    return { figure: saved, violations }
+  }
+
+  @Directive('@transaction')
+  @Directive('@privilege(category: "figure", privilege: "mutation", domainOwnerGranted: true)')
+  @Mutation(returns => FigureSaveResult, { description: 'Updates a figure. The `type` field cannot be changed.' })
+  async updateFigure(
+    @Arg('id') id: string,
+    @Arg('patch') patch: FigurePatch,
+    @Ctx() context: ResolverContext
+  ): Promise<FigureSaveResult> {
+    const { domain, user, tx } = context.state
+    const repository = tx.getRepository(Figure)
+
+    const figure = await repository.findOne({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, id }
+    })
+    if (!figure) {
+      throw new Error(`Figure ${id} 를 찾을 수 없다`)
+    }
+
+    // 정본이 바뀌면 파생값도 다시 계산한다. 안 바뀌었으면 손대지 않는다 —
+    // 이름만 고쳤는데 점수가 흔들리면 읽는 사람이 원인을 못 찾는다.
+    let derived: { score: number; triangles: number; groups: number } | undefined
+    let violations = []
+    let source = figure.source
+
+    if (patch.source !== undefined && patch.source !== figure.source) {
+      const parsed = parseSource(patch.source)
+      source = parsed.source
+      derived = parsed.derived
+      violations = parsed.violations
+    }
+
+    const saved = await repository.save({
+      ...figure,
+      ...patch,
+      source,
+      ...(derived ?? {}),
+      // 썸네일이 **썸네일로서** 바뀐 때만 시각을 갱신한다. 이름·설명 변경에는 안 건드린다.
+      thumbnailUpdatedAt:
+        patch.thumbnail !== undefined && patch.thumbnail !== figure.thumbnail
+          ? new Date()
+          : figure.thumbnailUpdatedAt,
+      version: (figure.version ?? 1) + 1,
+      updater: user
+    })
+
+    return { figure: saved, violations }
+  }
+
+  @Directive('@transaction')
+  @Directive('@privilege(category: "figure", privilege: "mutation", domainOwnerGranted: true)')
+  @Mutation(returns => Boolean, { description: 'Soft-deletes a figure.' })
+  async deleteFigure(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<boolean> {
+    const { domain, tx } = context.state
+
+    // 소프트 삭제다 — 이미 배치된 보드가 이 타입을 참조할 수 있으므로 행을 지우지
+    // 않는다. 되살릴 길을 남긴다.
+    await tx.getRepository(Figure).softDelete({ domain: { id: domain.id }, id })
+
+    return true
+  }
+
+  /**
+   * 저작 보조에게 후보를 시킨다.
+   *
+   * **저장하지 않는다.** 후보를 돌려줄 뿐이고, 정본이 되는 것은 저작자가 보고 받은
+   * 뒤다. AI 가 정본에 직접 쓰면 저작자가 무엇이 자기 것이고 무엇이 기계 것인지
+   * 모르게 된다.
+   *
+   * 형식을 어긴 후보는 여기까지 오지 않는다 — `proposeFigure` 가 사유를 모델에
+   * 돌려주고 다시 시킨다. 끝내 못 만들면 **사유와 함께 던진다.** 반쯤 만든 것을
+   * 돌려주지 않는다.
+   */
+  @Directive('@privilege(category: "figure", privilege: "mutation", domainOwnerGranted: true)')
+  @Mutation(returns => FigureProposal, {
+    description: 'Asks the authoring assistant for a figure. Returns a candidate — nothing is saved.'
+  })
+  async proposeFigure(@Arg('request') request: ProposeRequest): Promise<FigureProposal> {
+    // 그림은 메모리로 받는다. 참고용이라 저장하지 않는다 — 남기면 지울 사람이 없다.
+    let image
+    if (request.image) {
+      const file = await request.image
+      const chunks: Buffer[] = []
+      for await (const chunk of file.createReadStream()) {
+        chunks.push(chunk as Buffer)
+      }
+      image = { data: Buffer.concat(chunks), mediaType: file.mimetype as never }
+    }
+
+    try {
+      const result = await proposeFigure({
+        prompt: request.prompt,
+        base: request.base ? JSON.parse(request.base) : undefined,
+        type: request.type,
+        palette: request.palette,
+        image
+      })
+
+      return {
+        source: JSON.stringify(result.source),
+        score: Math.round(result.score.score),
+        grade: result.score.grade,
+        triangles: result.cost.triangles,
+        groups: result.cost.groups,
+        violations: result.violations,
+        attempts: result.attempts
+      }
+    } catch (e) {
+      if (e instanceof ProposeFailure) {
+        // 사유를 삼키지 않는다. 저작자가 무엇이 막혔는지 알아야 말을 고쳐 다시 시킨다.
+        throw new Error([e.message, ...e.reasons].join('\n'))
+      }
+      throw e
+    }
+  }
+
+}

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

@@ -0,0 +1,74 @@
+import type { FileUpload } from 'graphql-upload/GraphQLUpload.js'
+import GraphQLUpload from 'graphql-upload/GraphQLUpload.js'
+import { Field, InputType, Int, ObjectType } from 'type-graphql'
+
+import { FigureFinding } from './figure-type.js'
+
+/**
+ * 저작 보조에 넘기는 것.
+ *
+ * ## 팔레트를 클라이언트가 보낸다
+ *
+ * 서버가 팔레트를 알 수 없다. 팔레트는 things-scene 이 갖고 있는데, 그 패키지의
+ * node 조건은 transfer 번들로 가고 거기에는 `activePalette` 이 없다 [확인함].
+ * 그리는 쪽이 어떤 토큰을 풀 수 있는지 아는 유일한 자리이므로 그쪽이 보낸다.
+ *
+ * **그래서 저장 문(`parseSource`)은 토큰을 검사하지 못한다.** `validate()` 도
+ * 못 한다 — figure-model 이 형식은 갖고 있지만 색 어휘는 things-scene 에 있다.
+ * 색 어휘가 형식의 일부라면 figure-model 이 갖는 것이 맞다. **figure-model 에 올릴 것.**
+ */
+@InputType({ description: 'What to ask the authoring assistant for' })
+export class ProposeRequest {
+  @Field({ description: 'What the author asked for, in their own words' })
+  prompt: string
+
+  @Field({ nullable: true, description: 'The figure source to revise, as JSON. Omit to create a new one.' })
+  base?: string
+
+  @Field({ nullable: true, description: 'Type name for a new figure. Ignored when base is given.' })
+  type?: string
+
+  /**
+   * 그림.
+   *
+   * 비율과 덩어리를 읽는 데 쓴다. 표면 무늬를 옮기는 데 쓰지 않는다 — 로우폴리는
+   * 텍스처가 0 인 것이 목표다.
+   */
+  @Field(type => GraphQLUpload, { nullable: true, description: 'Reference photo or render' })
+  image?: FileUpload
+
+  @Field(type => [String], { description: 'Palette tokens the client can resolve. Anything else is rejected.' })
+  palette: string[]
+}
+
+/**
+ * 후보 하나.
+ *
+ * **정본이 아니다.** 저작자가 보고 받아야 정본이 된다. 그래서 서버는 저장하지 않고
+ * 돌려주기만 한다.
+ */
+@ObjectType({ description: 'A figure the assistant proposes. Not saved — the author accepts or discards it.' })
+export class FigureProposal {
+  @Field({ description: 'The proposed figure source, as JSON' })
+  source: string
+
+  @Field(type => Int, { description: 'Reuse score out of 100' })
+  score: number
+
+  @Field({ description: 'Grade from the score — A, B, C or D' })
+  grade: string
+
+  @Field(type => Int, { description: 'Triangles in one instance' })
+  triangles: number
+
+  @Field(type => Int, { description: 'Material groups — the draw calls one instance costs' })
+  groups: number
+
+  @Field(type => [FigureFinding], {
+    description: 'Policy violations. These do not block the proposal — the author decides.'
+  })
+  violations: FigureFinding[]
+
+  @Field(type => Int, { description: 'How many attempts the assistant needed. Diagnostic.' })
+  attempts: number
+}

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

@@ -0,0 +1,164 @@
+/**
+ * figure-propose — AI 가 낸 것을 무엇으로 거르나.
+ *
+ * 이 파일이 지키는 것은 하나다. **형식을 어긴 후보는 사람에게 가지 않는다.**
+ *
+ * AI 생성이 3D 에서 대개 잘 안 되는 이유는 「틀렸는지 기계가 판정할 수 없어서」인데,
+ * 여기는 판정기가 있다. 그 판정기를 실제로 통과시키는지, 틀렸을 때 사유를 모델에
+ * 돌려주고 다시 시키는지, 끝내 못 만들면 **못 만들었다고 말하는지**를 본다.
+ *
+ * 모델은 부르지 않는다. 부르면 시험이 느리고 답이 매번 다르다 — 여기서 볼 것은
+ * 모델의 솜씨가 아니라 **우리 거름망**이다.
+ */
+import { LIMITS, PART_LIMIT, PRIMITIVE_KINDS, SEGMENT_PRESETS } from '@hatiolab/figure-model'
+import { setDefaultAIClient } from '@things-factory/ai-client-base'
+import type { AIClient } from '@things-factory/ai-client-base'
+
+import { ProposeFailure, inspect, proposeFigure, rulesPrompt } from './figure-propose'
+
+const PALETTE = ['palette.primary', 'palette.accent', 'palette.neutral']
+
+/** 온전한 후보. 시험할 곳만 덮어쓴다. */
+function candidate(over: Record<string, unknown> = {}) {
+  return {
+    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' }
+      }
+    ],
+    ...over
+  }
+}
+
+/** 정해 둔 답을 차례로 내놓는 가짜 모델. */
+function stubClient(answers: unknown[]): AIClient & { calls: number } {
+  const client = {
+    id: 'stub',
+    calls: 0,
+    async chat() {
+      return ''
+    },
+    async generateJSON() {
+      const answer = answers[client.calls]
+      client.calls++
+      if (answer instanceof Error) throw answer
+      return answer
+    }
+  }
+  return client as unknown as AIClient & { calls: number }
+}
+
+afterEach(() => setDefaultAIClient(undefined))
+
+describe('규칙을 프롬프트로 옮길 때', () => {
+  it('값을 손으로 적지 않고 figure-model 에서 가져온다', () => {
+    const prompt = rulesPrompt(PALETTE)
+
+    for (const kind of PRIMITIVE_KINDS) {
+      expect(prompt).toContain(kind)
+    }
+    for (const preset of SEGMENT_PRESETS) {
+      expect(prompt).toContain(String(preset))
+    }
+    expect(prompt).toContain(`<= ${LIMITS.materialGroups}`)
+    expect(prompt).toContain(`M=${PART_LIMIT.M}`)
+  })
+
+  it('쓸 수 있는 팔레트 토큰만 알려 준다', () => {
+    const prompt = rulesPrompt(PALETTE)
+
+    expect(prompt).toContain('palette.primary | palette.accent | palette.neutral')
+  })
+})
+
+describe('후보를 받아 볼 때', () => {
+  it('온전하면 통과시킨다', () => {
+    const looked = inspect(candidate(), PALETTE)
+
+    expect(looked.source).toBeDefined()
+    expect(looked.reasons).toEqual([])
+  })
+
+  it('형식을 어기면 어디가 왜 틀렸는지 말한다', () => {
+    const looked = inspect(candidate({ parts: [] }), PALETTE)
+
+    expect(looked.source).toBeUndefined()
+    expect(looked.reasons.length).toBeGreaterThan(0)
+    expect(looked.reasons[0]).toContain('parts')
+  })
+
+  it('JSON 이 아니면 통과시키지 않는다', () => {
+    const looked = inspect('그럼요, 만들어 드릴게요', PALETTE)
+
+    expect(looked.source).toBeUndefined()
+    expect(looked.reasons.length).toBeGreaterThan(0)
+  })
+
+  /*
+    토큰은 형식상 자유 문자열이라 validate 를 지난다. 막지 않으면 저장까지 되고
+    화면에서 resolveToken 이 던진다 — 가장 늦게 드러나는 자리다.
+  */
+  it('팔레트에 없는 색을 지어내면 막는다', () => {
+    const bad = candidate()
+    bad.parts[0].material = { token: 'palette.brand' }
+
+    const looked = inspect(bad, PALETTE)
+
+    expect(looked.source).toBeUndefined()
+    expect(looked.reasons[0]).toContain('palette.brand')
+    expect(looked.reasons[0]).toContain('palette.primary')
+  })
+})
+
+describe('후보를 만들 때', () => {
+  it('한 번에 되면 점수와 무게를 함께 낸다', async () => {
+    setDefaultAIClient(stubClient([candidate()]))
+
+    const result = await proposeFigure({ prompt: '교반기', palette: PALETTE, type: 'MIXER' })
+
+    expect(result.attempts).toBe(1)
+    expect(result.source.parts).toHaveLength(1)
+    expect(result.score.grade).toMatch(/^[ABCD]$/)
+    expect(result.cost.triangles).toBeGreaterThan(0)
+  })
+
+  it('틀리면 사유를 돌려주고 다시 시킨다', async () => {
+    const client = stubClient([candidate({ parts: [] }), candidate()])
+    setDefaultAIClient(client)
+
+    const result = await proposeFigure({ prompt: '교반기', palette: PALETTE, type: 'MIXER' })
+
+    expect(result.attempts).toBe(2)
+    expect(client.calls).toBe(2)
+  })
+
+  it('끝내 못 만들면 못 만들었다고 말한다 — 반쯤 만든 것을 내밀지 않는다', async () => {
+    setDefaultAIClient(stubClient([candidate({ parts: [] }), candidate({ parts: [] }), candidate({ parts: [] })]))
+
+    await expect(proposeFigure({ prompt: '교반기', palette: PALETTE, type: 'MIXER' })).rejects.toThrow(ProposeFailure)
+  })
+
+  it('못 만들었을 때 마지막 사유를 함께 낸다', async () => {
+    setDefaultAIClient(stubClient([candidate({ parts: [] }), candidate({ parts: [] }), candidate({ parts: [] })]))
+
+    await proposeFigure({ prompt: '교반기', palette: PALETTE, type: 'MIXER' }).catch((e: ProposeFailure) => {
+      expect(e.reasons.length).toBeGreaterThan(0)
+      expect(e.attempts).toBe(3)
+    })
+  })
+
+  it('모델이 없으면 있는 척하지 않는다', async () => {
+    setDefaultAIClient(undefined)
+
+    await expect(proposeFigure({ prompt: '교반기', palette: PALETTE, type: 'MIXER' })).rejects.toThrow(
+      /설정돼 있지 않습니다/
+    )
+  })
+})

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

@@ -0,0 +1,271 @@
+import {
+  CHANNEL_PATHS,
+  DETAIL_LEVELS,
+  LIMITS,
+  MATERIAL_PRESETS,
+  PART_LIMIT,
+  PRIMITIVE_KINDS,
+  SEGMENT_PRESETS,
+  SIZING_RULES,
+  compile,
+  costOf,
+  scoreOf,
+  validate
+} from '@hatiolab/figure-model'
+import type { FigureSource } from '@hatiolab/figure-model'
+import { getDefaultAIClient } from '@things-factory/ai-client-base'
+import type { AIImageMediaType, AIMessage } from '@things-factory/ai-client-base'
+
+/**
+ * 저작 보조 — 말이나 그림으로 Figure 후보를 만든다.
+ *
+ * ## 왜 이 문제에 AI 가 맞나
+ *
+ * 3D 생성에 AI 를 붙이는 시도는 대개 잘 안 된다. 출력이 메시라서 **틀렸는지 기계가
+ * 판정할 수 없기** 때문이다. 여기는 다르다 — 출력이 닫힌 어휘로 된 JSON 하나이고,
+ * `validate()` 와 `scoreOf()` 가 **객관적인 채점기**다.
+ *
+ * ## 정본에 직접 쓰지 않는다
+ *
+ * 이 함수는 **후보**를 낸다. 형식을 어긴 후보는 사람에게 보이지 않는다 — 사유를
+ * 모델에 돌려주고 다시 시킨다. 정해진 횟수 안에 못 만들면 **못 만들었다고 말한다.**
+ * 반쯤 만든 것을 내밀면 저작자가 그것을 고치느라 처음부터 만드는 것보다 오래 걸린다.
+ *
+ * ## 어휘를 프롬프트에서 지어내지 않는다
+ *
+ * 도형·프리셋·한도는 전부 `@hatiolab/figure-model` 이 내보내는 상수에서 만든다.
+ * 프롬프트에 손으로 적으면 모델이 바뀔 때 프롬프트만 옛말을 하게 된다.
+ */
+
+/*
+  `slot` 은 시키지 않는다.
+
+  형식에는 있지만 그리는 쪽이 읽지 않아 **아무 일도 하지 않는다.** 죽은 필드를 채우게
+  시키면 저작자가 「상태 색이 되는구나」로 읽는다. 속성·바인딩 설계가 서면(figure-model#2)
+  그때 다시 넣는다.
+
+  강제 규칙과 취향 규칙을 갈라 적는다.
+
+  `validate()` 가 막는 것만 「hard」다. 한때 「부품은 기준 상자 안에 있어야 한다」를
+  강제 규칙으로 적었는데 **그런 규칙이 없다** — `base` 는 경계 상자가 아니라 배치
+  크기가 나오는 비율 기준이고, 밖으로 나가도 오류가 아니다 [확인함]. 없는 규칙을
+  강제라고 적으면 모델이 그것 때문에 좋은 답을 버린다.
+*/
+
+/** 몇 번까지 다시 시키나. 이보다 늘려도 대개 같은 자리에서 막힌다. */
+const MAX_ATTEMPTS = 3
+
+export interface ProposeInput {
+  /** 사람이 시킨 말. */
+  prompt: string
+  /** 고쳐 달라는 것이면 지금 정본. 없으면 새로 만든다. */
+  base?: FigureSource
+  /** 참고 그림. 설비 사진·렌더. */
+  image?: { data: Buffer; mediaType: AIImageMediaType }
+  /** 만들 타입 이름. 새로 만들 때 필요하다. */
+  type?: string
+  /** 쓸 수 있는 팔레트 토큰. 여기 없는 토큰은 거절한다. */
+  palette: string[]
+}
+
+export interface ProposeResult {
+  source: FigureSource
+  /** 재활용 점수와 한도 여유. */
+  score: ReturnType<typeof scoreOf>
+  /** 무게. */
+  cost: ReturnType<typeof costOf>
+  /** 형식은 맞으나 정책을 넘은 것. 막지 않고 알린다. */
+  violations: { code: string; message: string }[]
+  /** 몇 번 만에 됐나. 저작자에게 보여 줄 값은 아니지만 진단에 쓴다. */
+  attempts: number
+}
+
+/** 못 만들었을 때. 조용히 빈 것을 돌려주지 않는다. */
+export class ProposeFailure extends Error {
+  constructor(
+    message: string,
+    /** 마지막 시도가 낸 사유들. 저작자에게 그대로 보여 준다. */
+    readonly reasons: string[],
+    readonly attempts: number
+  ) {
+    super(message)
+    this.name = 'ProposeFailure'
+  }
+}
+
+/**
+ * 규칙을 프롬프트로 옮긴다.
+ *
+ * 값을 손으로 적지 않는다 — figure-model 의 상수에서 만든다. 그래야 한도가 바뀌면
+ * 프롬프트도 같이 바뀐다.
+ */
+export function rulesPrompt(palette: string[]): string {
+  const partLimits = DETAIL_LEVELS.map(level => `${level}=${PART_LIMIT[level]}`).join(' · ')
+
+  return [
+    'You compose low-poly 3D figures for a factory digital twin.',
+    'Answer with a single JSON object and nothing else — no prose, no code fence.',
+    '',
+    'The JSON is a FigureSource:',
+    '  { type, base: {x,y,z}, detailLevel, parts: [...] }',
+    '',
+    'A part is:',
+    '  { name, primitive, transform: { position: {x,y,z}, size: {x,y,z}, rotation?: {x,y,z} },',
+    '    material: {token, preset?}, segments?, shape?, sizing? }',
+    '',
+    'Hard vocabulary — anything outside these is rejected:',
+    `  primitive   ${PRIMITIVE_KINDS.join(' | ')}`,
+    `  segments    ${SEGMENT_PRESETS.join(' | ')} (only for cylinder and sphere)`,
+    `  material.token  ${palette.join(' | ')}`,
+    `  material.preset ${MATERIAL_PRESETS.join(' | ')}`,
+    `  sizing      ${SIZING_RULES.join(' | ')}`,
+    `  animation.path  ${CHANNEL_PATHS.join(' | ')}`,
+    `  detailLevel ${DETAIL_LEVELS.join(' | ')}`,
+    '',
+    'Hard limits — exceeding these makes the figure unusable at scale:',
+    `  parts        by detailLevel: ${partLimits}`,
+    `  material groups (distinct token+preset+slot combinations)  <= ${LIMITS.materialGroups}`,
+    `  animated parts  <= ${LIMITS.animatedParts}`,
+    `  transparent materials  <= ${LIMITS.transparentMaterials}`,
+    '',
+    'Geometry rules:',
+    '  Axes are the usual 3D ones: x right, y UP, z towards the viewer — same as glTF and three.js.',
+    '  transform.position is the CENTRE of the part, not a corner.',
+    '  The origin (0,0,0) is the centre of the base box, so the floor is at y = -base.y / 2.',
+    '  base and transform.size are extents along each axis: size.y is the height.',
+    '  part names are stored identifiers — lowercase, hyphenated, unique, and descriptive',
+    '  of the real thing (body, lid, motor, leg-front-left), never part-1.',
+    '',
+    'Taste rules — this is what makes it low-poly rather than a pile of boxes:',
+    '  Few colours. Reuse one token for the mass and reserve accents for what must stand out.',
+    '  Recognisable silhouette from directly above — that is how it is seen on a board.',
+    '  Prefer fewer, larger parts. A detail smaller than a twentieth of the base is not visible.',
+    '  Use the coarsest segment count that keeps the silhouette right.',
+    '  Keep parts within the base box unless the real thing overhangs. The base is the reference',
+    '  the instance is scaled from, so a part far outside it grows in a way nobody intended.'
+  ].join('\n')
+}
+
+/** 무엇을 만들라는 것인지 한 덩어리로. */
+function taskPrompt(input: ProposeInput): string {
+  const lines = [`Request: ${input.prompt}`]
+
+  if (input.base) {
+    lines.push(
+      '',
+      'Revise this existing figure. Keep the part names that still mean the same thing —',
+      'renaming a part breaks bindings on instances already placed.',
+      JSON.stringify(input.base)
+    )
+  } else {
+    lines.push('', `Create a new figure with type "${input.type ?? 'FIGURE'}".`)
+  }
+
+  if (input.image) {
+    lines.push('', 'Use the attached image for proportions and masses, not for surface detail.')
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * 후보 하나를 받아 본다.
+ *
+ * 던지는 것이 아니라 **사유를 모아 돌려준다** — 사유가 다음 시도의 입력이 되기
+ * 때문이다. 사람에게 보여 줄 것과 모델에 돌려줄 것이 같은 글이다.
+ */
+export function inspect(parsed: unknown, palette: string[]): { source?: FigureSource; reasons: string[] } {
+  const result = validate(parsed as FigureSource)
+  if (result.errors.length > 0) {
+    return { reasons: result.errors.map(error => `${error.path}: ${error.message}`) }
+  }
+
+  const source = parsed as FigureSource
+
+  /*
+    토큰은 형식상 자유 문자열이라 validate 를 지난다. 그런데 팔레트에 없는 토큰은
+    그리는 시점에 `resolveToken` 이 던진다 — 저장까지 되고 나서 화면에서 죽는다.
+    그래서 여기서 막는다.
+  */
+  const unknown = [
+    ...new Set(source.parts.map(part => part.material?.token).filter(token => token && !palette.includes(token)))
+  ]
+  if (unknown.length > 0) {
+    return {
+      reasons: [`Unknown palette tokens: ${unknown.join(', ')}. Use only: ${palette.join(', ')}.`]
+    }
+  }
+
+  return { source, reasons: [] }
+}
+
+/**
+ * 말과 그림으로 후보를 만든다.
+ *
+ * 생성-검사 루프다. 도구 루프가 아니다 — 첫 조각에 도구는 필요 없다.
+ *
+ * 도구가 필요해지면 `@things-factory/ai-client-base` 의 `runAgenticLoop` 을 부른다.
+ * 전에는 그것이 board-ai 안에만 있어 밖에서 쓸 수 없었는데, 공용으로 옮겨졌다.
+ */
+export async function proposeFigure(input: ProposeInput): Promise<ProposeResult> {
+  const client = getDefaultAIClient()
+  if (!client) {
+    // 없는 것을 있는 척하지 않는다. 부르는 쪽이 사람에게 그대로 옮길 수 있는 말로.
+    throw new ProposeFailure('AI 모델이 설정돼 있지 않습니다.', [], 0)
+  }
+
+  const system = rulesPrompt(input.palette)
+  const messages: AIMessage[] = [
+    {
+      role: 'user',
+      content: input.image
+        ? [
+            { type: 'text', text: taskPrompt(input) },
+            { type: 'image', source: { kind: 'base64', data: input.image.data, mediaType: input.image.mediaType } }
+          ]
+        : taskPrompt(input)
+    }
+  ]
+
+  let reasons: string[] = []
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    // `generateJSON` 을 쓴다 — 어댑터가 JSON 출력을 강제하고 파싱까지 해 준다.
+    // 코드 울타리나 앞뒤 설명을 우리가 걷어내지 않아도 된다.
+    let answer: unknown
+    try {
+      answer = await client.generateJSON(messages, { systemPrompt: system })
+    } catch (e) {
+      // 모델이 JSON 을 못 냈다. 그것도 사유이므로 돌려주고 다시 시킨다.
+      reasons = [`The answer was not valid JSON: ${(e as Error).message}`]
+      messages.push({
+        role: 'user',
+        content: ['That was rejected. Answer with the JSON object only:', ...reasons].join('\n')
+      })
+      continue
+    }
+
+    const looked = inspect(answer, input.palette)
+    if (looked.source) {
+      const blueprint = compile(looked.source)
+      return {
+        source: looked.source,
+        score: scoreOf(blueprint),
+        cost: costOf(blueprint, 100),
+        violations: blueprint.violations.map(v => ({ code: v.code, message: v.message })),
+        attempts: attempt
+      }
+    }
+
+    reasons = looked.reasons
+
+    // 사유를 그대로 돌려준다. 요약하면 모델이 무엇을 고쳐야 하는지 모른다.
+    messages.push({ role: 'assistant', content: JSON.stringify(answer) })
+    messages.push({
+      role: 'user',
+      content: ['That was rejected. Fix these and answer again with the JSON only:', ...reasons].join('\n')
+    })
+  }
+
+  throw new ProposeFailure('만들지 못했습니다.', reasons, MAX_ATTEMPTS)
+}