@things-factory/figure-service 10.1.3 → 10.1.6

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

@@ -0,0 +1,284 @@
+/**
+ * 저작 도구의 **배선**을 못박는다.
+ *
+ * 도구가 무엇을 계산하는지는 각 진입점의 시험이 이미 잠근다(`figure-propose.test` ·
+ * figure-model 의 게이트 시험). 비어 있던 것은 **그 사이를 잇는 줄들**이고, 그 줄이 끊어질 때
+ * 나타나는 증상이 실제로 겪은 실패와 1:1 로 대응한다.
+ *
+ *   · guidance → 도구 호출          끊기면 → 「후보를 만들었습니다」라고만 쓰고 화면에는 아무것도 없다
+ *   · hostContext.figureId → 대상    끊기면 → 화면에 도형이 떠 있는데 「어느 도형입니까」를 되묻는다
+ *   · 도메인 확인 → 대상            끊기면 → 모델이 넘긴 id 로 남의 테넌트를 읽는다
+ *   · hostContext.palette → 후보     끊기면 → 모델이 색을 지어내고 그리는 시점에 죽는다
+ *
+ * 실제 모델은 부르지 않는다. 여기서 볼 것은 모델의 솜씨가 아니라 **우리 배선**이다.
+ */
+import { clearToolRegistry, getToolCategories } from '@things-factory/ai-client-base'
+
+import { __setFigureToolDepsForTest, registerFigureToolCategories } from './figure-tools'
+
+/** 도메인 소속을 흉내내는 저장소. 넘긴 id 와 도메인이 맞을 때만 돌려준다. */
+function stubRepository(rows: any[]) {
+  return {
+    async findOne({ where }: any) {
+      return (
+        rows.find(row => row.id === where.id && row.domain?.id === where.domain?.id) ?? null
+      )
+    },
+    async find({ where }: any) {
+      return rows.filter(row => row.domain?.id === where.domain?.id)
+    }
+  }
+}
+
+const MINE = { id: 'domain-mine' }
+const THEIRS = { id: 'domain-theirs' }
+
+const SOURCE = {
+  type: 'MIXER',
+  base: { x: 300, y: 500, z: 300 },
+  detailLevel: 'M',
+  parts: [
+    {
+      name: 'body',
+      primitive: 'cube',
+      transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 300, y: 400, z: 300 } },
+      material: { token: 'palette.primary' }
+    }
+  ]
+}
+
+const ROWS = [
+  { id: 'fig-1', type: 'MIXER', name: '믹서', state: 'draft', domain: MINE, source: JSON.stringify(SOURCE) },
+  { id: 'fig-blank', type: 'EMPTY', name: '빈 것', state: 'draft', domain: MINE, source: null },
+  { id: 'fig-other', type: 'SECRET', name: '남의 것', state: 'draft', domain: THEIRS, source: JSON.stringify(SOURCE) }
+]
+
+/** 부른 것을 적어 두는 가짜 제안기. */
+const proposed: any[] = []
+
+function install() {
+  const model = require('@hatiolab/figure-model')
+  __setFigureToolDepsForTest({
+    getRepository: () => stubRepository(ROWS),
+    Figure: class {},
+    inspectSource: (json?: string | null) =>
+      json ? { blocked: false, findings: [] } : { blocked: true, findings: [{ code: 'no-source', message: '정본이 없다', blocking: true }] },
+    proposeFigure: async (input: any) => {
+      proposed.push(input)
+      return {
+        source: SOURCE,
+        score: { grade: 'B' },
+        cost: { triangles: 12, at: { drawCalls: 100 } },
+        violations: [],
+        attempts: 1
+      }
+    },
+    compile: model.compile,
+    costOf: model.costOf,
+    scoreOf: model.scoreOf
+  })
+}
+
+/** 등록된 범주에서 도구 하나를 꺼낸다. */
+function toolNamed(name: string) {
+  const category = getToolCategories().find((one: any) => one.name === 'figure-authoring')
+  if (!category) throw new Error('figure-authoring 범주가 등록되지 않았다')
+  const spec = category.specs.find((one: any) => one.name === name)
+  if (!spec) throw new Error(`도구 ${name} 이 없다`)
+  return spec as any
+}
+
+const ctx = (host: any = { figureId: 'fig-1', palette: ['palette.primary'] }) => ({
+  state: { domain: MINE, host }
+})
+
+beforeEach(() => {
+  clearToolRegistry()
+  proposed.length = 0
+  install()
+  registerFigureToolCategories()
+})
+
+afterEach(() => clearToolRegistry())
+
+describe('범주가 등록된다', () => {
+  it('figure-authoring 이 도구 넷과 함께 올라온다', () => {
+    const category = getToolCategories().find((one: any) => one.name === 'figure-authoring')!
+
+    expect(category.specs.map((one: any) => one.name).sort()).toEqual([
+      'getFigureSource',
+      'inspectFigure',
+      'listFigures',
+      'proposeFigureCandidate'
+    ])
+  })
+
+  it('전부 조회 전용이다 — 되돌릴 수 없는 조작이 대화면으로 새지 않는다', () => {
+    const category = getToolCategories().find((one: any) => one.name === 'figure-authoring')!
+
+    expect(category.specs.map((one: any) => one.kind)).toEqual(['read', 'read', 'read', 'read'])
+  })
+})
+
+/*
+  twin 이 이 자리에서 사고를 냈다. 조치 요청에 도구를 부르지 않고 「제안해 두었습니다」라고만 답해
+  사용자에게 없는 버튼을 누르라고 안내했다. figure 도 같은 구조다 — 후보 칸은 도구 호출 결과에서만
+  만들어진다. 그래서 규율을 도구와 함께 보내고, 그 규율이 실려 있는지를 여기서 못박는다.
+*/
+describe('규율이 도구와 함께 나간다', () => {
+  it('후보는 도구 호출로만 생긴다는 것을 규율이 말한다', () => {
+    const category = getToolCategories().find((one: any) => one.name === 'figure-authoring')!
+
+    expect(category.guidance).toBeTruthy()
+    expect(category.guidance).toContain('proposeFigureCandidate')
+    expect(category.guidance).toMatch(/거짓/)
+    expect(category.guidance).toMatch(/도구 호출 결과에서만/)
+  })
+
+  it('고치기 전에 정본을 읽으라고 말한다 — 이름이 갈리면 배치된 보드가 끊긴다', () => {
+    const category = getToolCategories().find((one: any) => one.name === 'figure-authoring')!
+
+    expect(category.guidance).toContain('getFigureSource')
+    expect(category.guidance).toMatch(/바인딩이 끊긴다/)
+  })
+
+  it('타입 이름을 지어내지 말라고 말한다 — 저장되는 식별자다', () => {
+    const category = getToolCategories().find((one: any) => one.name === 'figure-authoring')!
+
+    expect(category.guidance).toContain('listFigures')
+    expect(category.guidance).toMatch(/저장되는 식별자/)
+  })
+})
+
+describe('대화면 문맥에서 대상을 해소한다', () => {
+  it('id 를 안 주면 열려 있는 도형을 읽는다 — 사용자에게 되묻지 않는다', async () => {
+    const result = await toolNamed('getFigureSource').builder({}, ctx())
+
+    expect(result.id).toBe('fig-1')
+    expect(result.source.type).toBe('MIXER')
+  })
+
+  it('열린 도형도 없고 id 도 없으면 명시 실패한다 — 아무 도형이나 고르지 않는다', async () => {
+    await expect(toolNamed('getFigureSource').builder({}, ctx({}))).rejects.toThrow(/figureId is required/)
+  })
+
+  it('정본이 없는 도형은 없다고 말한다 — 지어내지 않는다', async () => {
+    const result = await toolNamed('getFigureSource').builder({ figureId: 'fig-blank' }, ctx())
+
+    expect(result.source).toBeNull()
+    expect(result.cost).toBeNull()
+  })
+
+  it('측정한 비용이 함께 온다 — 눈대중으로 세지 않게', async () => {
+    const result = await toolNamed('getFigureSource').builder({ figureId: 'fig-1' }, ctx())
+
+    expect(result.cost.triangles).toBeGreaterThan(0)
+    expect(result.cost.drawCalls).toBeGreaterThan(0)
+  })
+})
+
+/*
+  사람이 목록에서 고르는 길에서는 드러나지 않는다. 모델은 대화 내용에 이끌려 임의의 id 를 넘길 수
+  있고, 그것을 그대로 믿으면 남의 테넌트를 읽는다.
+*/
+describe('모델이 넘긴 id 를 믿지 않는다', () => {
+  it('다른 도메인의 도형은 못 찾았다고 한다', async () => {
+    await expect(toolNamed('getFigureSource').builder({ figureId: 'fig-other' }, ctx())).rejects.toThrow(
+      /not found in this tenant/
+    )
+  })
+
+  it('발행 판정도 같은 확인을 지난다', async () => {
+    await expect(toolNamed('inspectFigure').builder({ figureId: 'fig-other' }, ctx())).rejects.toThrow(
+      /not found in this tenant/
+    )
+  })
+
+  it('목록은 자기 도메인만 낸다', async () => {
+    const result = await toolNamed('listFigures').builder({}, ctx())
+
+    expect(result.figures.map((one: any) => one.id)).toEqual(['fig-1', 'fig-blank'])
+  })
+
+  it('도메인 문맥이 없으면 아무것도 읽지 않는다', async () => {
+    await expect(toolNamed('listFigures').builder({}, { state: {} })).rejects.toThrow(/domain context is missing/)
+  })
+})
+
+describe('후보를 요청할 때', () => {
+  it('열린 도형이 있으면 고치는 것으로 본다 — 그 정본이 함께 나간다', async () => {
+    await toolNamed('proposeFigureCandidate').builder({ prompt: '재질을 줄여줘' }, ctx())
+
+    expect(proposed).toHaveLength(1)
+    expect(proposed[0].base.type).toBe('MIXER')
+  })
+
+  it('create 를 켜면 열린 도형이 있어도 새로 만든다 — 열린 것을 덮어쓰는 후보가 오지 않게', async () => {
+    await toolNamed('proposeFigureCandidate').builder({ prompt: '새 컨베이어', create: true, type: 'CONVEYOR' }, ctx())
+
+    expect(proposed[0].base).toBeUndefined()
+    expect(proposed[0].type).toBe('CONVEYOR')
+  })
+
+  /*
+    팔레트를 모르면 모델이 색을 지어낸다. 그 후보는 형식 검증을 지나가고 **그리는 시점에**
+    `resolveToken` 이 던진다 — 저장까지 되고 나서 화면에서 죽는다. 빈 목록으로 진행하지 않는다.
+  */
+  it('팔레트가 문맥에 없으면 후보를 요청하지 않는다', async () => {
+    await expect(
+      toolNamed('proposeFigureCandidate').builder({ prompt: '무언가' }, ctx({ figureId: 'fig-1' }))
+    ).rejects.toThrow(/palette is missing/)
+  })
+
+  it('빈 요청은 거절한다', async () => {
+    await expect(toolNamed('proposeFigureCandidate').builder({ prompt: '   ' }, ctx())).rejects.toThrow(
+      /prompt is required/
+    )
+  })
+
+  it('남의 도형을 고치라고 하면 못 찾았다고 한다', async () => {
+    await expect(
+      toolNamed('proposeFigureCandidate').builder({ prompt: '고쳐줘', figureId: 'fig-other' }, ctx())
+    ).rejects.toThrow(/not found in this tenant/)
+  })
+})
+
+/*
+  후보가 화면에 닿는 길은 하나다 — 도구 결과의 `proposed: true` 가 카드를 만들고, 카드의 단추가
+  호스트에게 실행을 넘긴다. 이 표시가 빠지면 후보는 도구 추적 안에 묻히고 화면에는 아무것도 생기지
+  않는다. 그때 모델이 「후보를 만들었습니다」라고 쓴 것이 거짓이 된다. twin 이 이 자리에서 사용자에게
+  없는 단추를 누르라고 안내했다.
+*/
+describe('후보가 카드가 된다', () => {
+  it('proposed 표시가 붙어 온다 — 없으면 화면에 아무것도 생기지 않는다', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '교반기', create: true }, ctx())
+
+    expect(out.proposed).toBe(true)
+  })
+
+  it('카드에 그릴 두 줄이 함께 온다', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '교반기', create: true }, ctx())
+
+    expect(out.label).toContain('MIXER')
+    // 잰 값을 그대로 적는다 — 「좋아졌다」로 요약하면 저작자가 판단할 근거가 없다.
+    expect(out.reason).toMatch(/등급 B/)
+    expect(out.reason).toMatch(/삼각형 12/)
+  })
+
+  it('후보 자체와 측정값이 함께 온다 — 호스트가 두 칸을 그릴 수 있게', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '교반기', create: true }, ctx())
+
+    expect(out.source.type).toBe('MIXER')
+    expect(out.score.grade).toBe('B')
+    expect(out.cost.triangles).toBe(12)
+    expect(out.attempts).toBe(1)
+  })
+
+  it('고치는 것과 만드는 것을 이름으로 가른다', async () => {
+    const revise = await toolNamed('proposeFigureCandidate').builder({ prompt: '고쳐줘' }, ctx())
+    const create = await toolNamed('proposeFigureCandidate').builder({ prompt: '만들어줘', create: true }, ctx())
+
+    expect(revise.label).toMatch(/고치기/)
+    expect(create.label).toMatch(/만들기/)
+  })
+})

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

@@ -0,0 +1,320 @@
+/*
+ * figure 저작 도구를 어시스턴트 도구 레지스트리에 등록 — **대화면(도크)에서 저작을 돕기 위함.**
+ *
+ * 왜 필요한가: `proposeFigure` 는 한 번 시키고 한 번 받는다. 그것으로 되는 일이 있지만, 저작은
+ * 대개 「이걸 이렇게 고쳐 봐 → 무게가 얼마나 되나 → 발행은 되나」처럼 여러 차례 오간다. 그 대화를
+ * 하려면 어시스턴트가 **지금 무엇이 있는지 읽을 수 있어야** 한다. 읽지 못하면 매번 사람이 정본을
+ * 붙여 넣어야 하고, 그러면 대화가 아니다.
+ *
+ * 능력을 복제하지 않는다. figure-service 가 이미 가진 진입점(`inspectSource` · `proposeFigure` ·
+ * 조회)을 레지스트리에 투영한다.
+ *
+ * ── 전부 조회·제안 전용이다 ─────────────────────────────────────────────────
+ * 정본을 고치는 도구를 넣지 않는다. 형식의 설계가 그렇게 정해져 있다 — 어시스턴트는 **후보**를
+ * 내고, 받을지 버릴지는 저작자가 정한다(`figure-propose.ts`). 되돌릴 수 없는 조작이 대화면으로
+ * 새지 않으므로 전부 `kind: 'read'` 다.
+ *
+ * 저장은 저작면이 `updateFigure` 로 한다. 그 mutation 은 `figure:mutation` 이 지키고, 대화는
+ * `ai-assistant:mutation` 이 지킨다 — 서로 다른 질문이라 서로 다른 권한이 지킨다. figure 가 board
+ * 의 권한을 빌리지 않는다.
+ *
+ * ── 규율을 도구와 함께 보낸다 ───────────────────────────────────────────────
+ * 도구 목록만으로는 「언제 반드시 불러야 하는지」를 모른다. twin 이 그 공백에서 사고를 냈다 —
+ * 조치 요청에 도구를 부르지 않고 「제안해 두었습니다」라고만 답해, 사용자에게 **없는 버튼을 누르라고
+ * 안내했다.** figure 도 똑같은 자리가 있다: 후보 화면(「지금 / 후보」 두 칸)은 **도구 호출 결과에서만**
+ * 만들어진다. 문장으로는 아무 일도 일어나지 않는다.
+ *
+ * ── LLM 이 넘긴 id 를 믿지 않는다 ───────────────────────────────────────────
+ * 사람이 목록에서 고르는 길에서는 드러나지 않지만, 모델은 대화 내용에 이끌려 임의의 id 를 넘길 수
+ * 있다. 그래서 호출자 도메인 소속을 먼저 확인한다.
+ */
+import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
+
+/*
+  서버 의존성은 lazy require 다. 등록은 부팅 초반에 평가되고 그때 typeorm DataSource 가 준비되지
+  않았을 수 있다(board-import · twin-ai 와 같은 정책).
+*/
+let _deps: any | undefined
+
+function getDeps(): any {
+  if (!_deps) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const shell = require('@things-factory/shell')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const model = require('@hatiolab/figure-model')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const entity = require('./figure.js')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const gate = require('./figure-gate.js')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const propose = require('./figure-propose.js')
+    _deps = {
+      getRepository: shell.getRepository,
+      Figure: entity.Figure,
+      inspectSource: gate.inspectSource,
+      proposeFigure: propose.proposeFigure,
+      compile: model.compile,
+      costOf: model.costOf,
+      scoreOf: model.scoreOf
+    }
+  }
+  return _deps
+}
+
+/** 시험·검증 하네스 전용 주입 시임. 운영 경로에서 호출 금지. */
+export function __setFigureToolDepsForTest(deps: any): void {
+  _deps = deps
+}
+
+function requireDomainId(state: any): string {
+  const id = state?.domain?.id
+  if (!id) {
+    // 도메인을 모르면 무엇을 읽어도 남의 것일 수 있다. 조용히 넘기지 않는다.
+    throw new Error('domain context is missing — the figure tools cannot resolve tenant scope')
+  }
+  return id
+}
+
+/**
+ * 이 도형이 호출자 도메인 것인가.
+ *
+ * 모델이 넘긴 id 를 그대로 쓰지 않는다. 없으면 못 찾았다고 말한다 — 「권한이 없다」와 구별해
+ * 알려 줄 것이 없다(다른 테넌트에 그 id 가 있다는 사실 자체가 알려 줄 것이 아니다).
+ */
+async function figureInDomain(figureId: string, domainId: string): Promise<any> {
+  const { getRepository, Figure } = getDeps()
+  const found = await getRepository(Figure).findOne({
+    where: { id: figureId, domain: { id: domainId } }
+  })
+  if (!found) {
+    throw new Error(`figure not found in this tenant: ${figureId}`)
+  }
+  return found
+}
+
+/**
+ * 무엇을 고치라는 것인지 대화면 문맥에서 해소한다.
+ *
+ * 모델이 대상을 안 줬으면 **저작면이 지금 열고 있는 도형**이다. 사용자에게 식별자를 되묻지
+ * 않는다 — 화면에 그 도형이 떠 있는데 「어느 도형입니까」를 묻는 것은 문맥을 안 읽은 것이다.
+ */
+function figureIdFrom(args: any, host: any): string {
+  const said = typeof args?.figureId === 'string' ? args.figureId.trim() : ''
+  if (said) return said
+
+  const open = typeof host?.figureId === 'string' ? host.figureId.trim() : ''
+  if (open) return open
+
+  throw new Error('figureId is required: this surface has no figure open to resolve it from')
+}
+
+const FIGURE_ID_ARG = {
+  figureId: {
+    type: 'string',
+    description: 'The figure to read. Omit to use the one open in the editor.'
+  }
+} as const
+
+/**
+ * 도구 넷.
+ *
+ * 목록 · 정본 · 발행 판정 · 후보. 저작 대화에서 실제로 묻는 것이 그 넷이다 — 「무엇이 있나」
+ * 「지금 어떻게 생겼나」 「발행이 왜 안 되나」 「이렇게 고쳐 봐」.
+ */
+function figureToolSpecs(): ToolSpec[] {
+  return [
+    {
+      kind: 'read',
+      name: 'listFigures',
+      description:
+        'Lists the figures in this tenant with their type names, states and part counts. ' +
+        'Call it before naming a type — type names are stored identifiers and must not be invented.',
+      schema: { type: 'object', properties: {} },
+      builder: async (_args: any, ctx: any) => {
+        const domainId = requireDomainId(ctx?.state)
+        const { getRepository, Figure } = getDeps()
+        const rows = await getRepository(Figure).find({
+          where: { domain: { id: domainId } },
+          order: { updatedAt: 'DESC' },
+          take: 200
+        })
+        return {
+          figures: rows.map((row: any) => ({
+            id: row.id,
+            type: row.type,
+            name: row.name,
+            state: row.state,
+            score: row.score,
+            triangles: row.triangles
+          }))
+        }
+      }
+    },
+    {
+      kind: 'read',
+      name: 'getFigureSource',
+      description:
+        'Returns the canonical FigureSource of one figure, with its measured cost ' +
+        '(triangles, draw calls, how many fit on one board). Call it before proposing a revision — ' +
+        'revising without reading it means proposing against a guess.',
+      schema: { type: 'object', properties: { ...FIGURE_ID_ARG } },
+      builder: async (args: any, ctx: any) => {
+        const domainId = requireDomainId(ctx?.state)
+        const figureId = figureIdFrom(args, ctx?.state?.host)
+        const row = await figureInDomain(figureId, domainId)
+
+        if (!row.source) {
+          // 저장된 정본이 없는 상태가 실제로 있다(새로 만들고 저장 안 한 것). 지어내지 않는다.
+          return { id: row.id, type: row.type, name: row.name, source: null, cost: null }
+        }
+
+        const { compile, costOf, scoreOf } = getDeps()
+        const source = JSON.parse(row.source)
+        const blueprint = compile(source)
+
+        return {
+          id: row.id,
+          type: row.type,
+          name: row.name,
+          state: row.state,
+          source,
+          cost: costOf(blueprint, 100),
+          score: scoreOf(blueprint)
+        }
+      }
+    },
+    {
+      kind: 'read',
+      name: 'inspectFigure',
+      description:
+        'Says whether a figure may be released and, when it may not, what is wrong — each finding ' +
+        'carries why it is a problem and what to change. Call it when asked about releasing, or ' +
+        'when asked to fix a figure that will not release.',
+      schema: { type: 'object', properties: { ...FIGURE_ID_ARG } },
+      builder: async (args: any, ctx: any) => {
+        const domainId = requireDomainId(ctx?.state)
+        const figureId = figureIdFrom(args, ctx?.state?.host)
+        const row = await figureInDomain(figureId, domainId)
+
+        const { inspectSource } = getDeps()
+        return inspectSource(row.source)
+      }
+    },
+    {
+      kind: 'read',
+      name: 'proposeFigureCandidate',
+      description:
+        'Asks for a figure candidate from a description, optionally revising an existing one. ' +
+        'Returns the candidate with its score and cost. NOTHING IS SAVED — the author accepts or ' +
+        'discards it on screen. This is the only way a candidate reaches the screen.',
+      schema: {
+        type: 'object',
+        properties: {
+          prompt: {
+            type: 'string',
+            description: 'What to make or change, in the words the author used.'
+          },
+          figureId: {
+            type: 'string',
+            description: 'Revise this figure. Omit to revise the one open in the editor; pass null to create anew.'
+          },
+          type: {
+            type: 'string',
+            description: 'Type name for a new figure. Check listFigures first — it is a stored identifier.'
+          },
+          create: {
+            type: 'boolean',
+            description: 'True to create rather than revise, even with a figure open.'
+          }
+        },
+        required: ['prompt']
+      },
+      builder: async (args: any, ctx: any) => {
+        const domainId = requireDomainId(ctx?.state)
+        const prompt = typeof args?.prompt === 'string' ? args.prompt.trim() : ''
+        if (!prompt) throw new Error('prompt is required: there is nothing to ask for')
+
+        /*
+          고치는 것인지 만드는 것인지를 **문맥에서 정한다.** 열린 도형이 있으면 고치는 것이 기본이고,
+          모델이 `create` 를 켜면 만드는 것이다. 이것을 모델의 짐작에 맡기면 열려 있는 도형을 덮어쓰는
+          후보가 온다.
+        */
+        let base: unknown
+        if (!args?.create) {
+          const open = typeof args?.figureId === 'string' ? args.figureId : ctx?.state?.host?.figureId
+          if (typeof open === 'string' && open.trim()) {
+            const row = await figureInDomain(open.trim(), domainId)
+            if (row.source) base = JSON.parse(row.source)
+          }
+        }
+
+        const palette = Array.isArray(ctx?.state?.host?.palette) ? ctx.state.host.palette : []
+        if (palette.length === 0) {
+          /*
+            팔레트를 모르면 모델이 색을 지어내고, 그 후보는 그리는 시점에 `resolveToken` 이 던진다 —
+            저장까지 되고 나서 화면에서 죽는다. 빈 목록으로 진행하지 않는다.
+          */
+          throw new Error('the palette is missing from the host context — the candidate would invent colours')
+        }
+
+        const { proposeFigure } = getDeps()
+        const result = await proposeFigure({
+          prompt,
+          palette,
+          base,
+          type: typeof args?.type === 'string' ? args.type : undefined
+        })
+
+        /*
+          **`proposed: true` 가 카드를 만든다.** 이 표시가 없으면 후보는 도구 추적 안에 묻히고,
+          화면에는 아무것도 생기지 않는다 — 그러면 모델이 「후보를 만들었습니다」라고 쓴 것이
+          거짓말이 된다(사용자가 없는 단추를 찾는다).
+
+          `label`·`reason` 이 카드에 그려지는 두 줄이고, `args` 는 같은 제안을 두 번 세지 않기
+          위한 열쇠의 일부다 — 같은 요청을 두 번 내면 카드가 하나로 접힌다.
+        */
+        return {
+          proposed: true,
+          label: base ? `${result.source.type} 고치기` : `${result.source.type} 만들기`,
+          reason:
+            `등급 ${result.score.grade} · 삼각형 ${result.cost.triangles} · ` +
+            `한 도면 ${result.cost.at.drawCalls}회 · ${result.attempts}번에 만들었다`,
+          args: { prompt, figureId: base ? figureIdFrom(args, ctx?.state?.host) : undefined },
+          source: result.source,
+          score: result.score,
+          cost: result.cost,
+          violations: result.violations,
+          attempts: result.attempts
+        }
+      }
+    }
+  ] as ToolSpec[]
+}
+
+/**
+ * 등록 — 부팅 시 1회.
+ *
+ * 범주가 하나다. twin 은 관찰과 생성을 둘로 갈랐는데(운영 협의에 생성 도구가 들려 있으면 대화의
+ * 성격이 흐려진다), figure 의 대화면은 저작면 하나뿐이고 그 자리에서 읽기와 후보 요청이 함께 필요하다.
+ * 대화면이 늘면 그때 가른다.
+ */
+export function registerFigureToolCategories(): void {
+  const authoring: ToolCategory = {
+    name: 'figure-authoring',
+    description: '저작 중인 Figure 의 정본·비용·발행 판정 조회와 후보 제안(저장 아님).',
+    guidance: [
+      '- **도형을 만들거나 고쳐 달라는 요청에는 반드시 `proposeFigureCandidate` 를 호출한다.**',
+      '  호출 없이 "후보를 만들었습니다" · "적용 버튼을 누르세요" 라고 쓰는 것은 **거짓이다** — 화면에 후보 칸이 생기지 않으므로 사용자는 존재하지 않는 버튼을 찾는다.',
+      '  후보 화면(「지금 / 후보」 두 칸)은 **도구 호출 결과에서만** 만들어진다. 문장으로는 아무 일도 일어나지 않는다.',
+      '- 정본을 직접 저장하지 않는다. 후보만 내고, 받을지 버릴지는 저작자가 화면에서 정한다.',
+      '- **고치라는 요청이면 먼저 `getFigureSource` 를 부른다.** 읽지 않고 고치면 짐작을 상대로 후보를 내게 되고, 부품 이름이 갈려 이미 배치된 보드의 바인딩이 끊긴다.',
+      '- 타입 이름을 지어내지 않는다 — `listFigures` 로 확인한다. **타입 이름은 저장되는 식별자**이고 보드가 그 이름으로 도형을 찾는다.',
+      '- 발행이 안 되는 이유를 물으면 `inspectFigure` 를 부른다. 판정 없이 "발행할 수 있습니다"라고 말하지 않는다.',
+      '  판정의 각 항목은 **왜 문제인지와 무엇을 바꾸면 되는지**를 함께 담고 있다. 그대로 전한다 — 요약하면 저작자가 어느 부품의 어느 축을 고칠지 다시 찾아야 한다.',
+      '- 무게·삼각형 수를 물으면 `getFigureSource` 의 `cost` 를 쓴다. 눈대중으로 세지 않는다.'
+    ].join('\n'),
+    specs: figureToolSpecs()
+  }
+
+  registerToolCategory(authoring)
+}

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

@@ -58,8 +58,12 @@ export class FigurePatch {
   @Field({ nullable: true, description: 'The new master-data field definition.' })
   properties?: string
 
-  @Field({ nullable: true, description: 'The new lifecycle state.' })
-  state?: 'draft' | 'released'
+  /*
+    `state` 는 여기 없다 — **상태는 저장이 정하지 않는다.**
+
+    발행은 `releaseFigure` 가 한다. 저장으로 상태를 바꿀 수 있게 두면 발행된 판을 덮어쓰면서 같은
+    판 번호로 판본을 또 뜨게 되고(유니크 충돌), 무엇이 약속된 판인지도 흐려진다. board 도 같다.
+  */
 
   @Field({ nullable: true, description: 'A base64 encoded thumbnail image.' })
   thumbnail?: string
@@ -106,3 +110,46 @@ export class FigureSaveResult {
   @Field(type => [FigureFinding], { description: 'Non-blocking findings. The save succeeded despite these.' })
   violations: FigureFinding[]
 }
+
+/**
+ * 발행 판정 한 줄.
+ *
+ * `FigureFinding` 과 칸이 겹치지만 **`blocking` 이 하나 더 있다.** 저장 쪽 발견은 정의상 막지 않는
+ * 것들이라 그 칸이 필요 없었다. 발행 판정은 막는 것과 알리는 것을 함께 내므로, 어느 쪽인지를 값이
+ * 스스로 말해야 한다 — 코드를 보고 화면이 다시 분류하면 규칙이 두 벌이 된다.
+ */
+@ObjectType({ description: 'One finding from the release gate.' })
+export class FigureGateFinding {
+  @Field({ description: 'Stable code — figure-model validation codes, or sizing-splits / sizing-loose.' })
+  code: string
+
+  @Field({ description: 'Human-readable message.' })
+  message: string
+
+  @Field({ nullable: true, description: 'Why this is a problem — what a person sees when it happens.' })
+  why?: string
+
+  @Field({ nullable: true, description: 'What to change, naming the part and the value.' })
+  how?: string
+
+  @Field({ nullable: true, description: 'Where it points: part names that came apart, or a path in the source.' })
+  at?: string
+
+  @Field({ description: 'True when this finding blocks the release.' })
+  blocking: boolean
+}
+
+/**
+ * 발행 판정.
+ *
+ * 화면이 **발행을 누르기 전에** 물어보는 자리다. 눌러 보고 거절당하는 것으로 알게 되면, 무엇을
+ * 고쳐야 하는지 모른 채 단추만 두드리게 된다.
+ */
+@ObjectType({ description: 'Whether a figure may be released, and why not.' })
+export class FigureInspection {
+  @Field({ description: 'True when at least one finding blocks the release.' })
+  blocked: boolean
+
+  @Field(type => [FigureGateFinding], { description: 'Findings, blocking and advisory together.' })
+  findings: FigureGateFinding[]
+}