@things-factory/figure-service 10.1.64 → 10.1.65

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

@@ -1,14 +1,14 @@
 /**
  * 저작 도구의 **배선**을 못박는다.
  *
- * 도구가 무엇을 계산하는지는 각 진입점의 시험이 이미 잠근다(`figure-propose.test` ·
+ * 도구가 무엇을 계산하는지는 각 진입점의 시험이 이미 잠근다(`figure-propose-v3.test` ·
  * figure-model 의 게이트 시험). 비어 있던 것은 **그 사이를 잇는 줄들**이고, 그 줄이 끊어질 때
  * 나타나는 증상이 실제로 겪은 실패와 1:1 로 대응한다.
  *
  *   · guidance → 도구 호출          끊기면 → 「후보를 만들었습니다」라고만 쓰고 화면에는 아무것도 없다
  *   · hostContext.figureId → 대상    끊기면 → 화면에 도형이 떠 있는데 「어느 도형입니까」를 되묻는다
  *   · 도메인 확인 → 대상            끊기면 → 모델이 넘긴 id 로 남의 테넌트를 읽는다
- *   · hostContext.palette → 후보     끊기면 → 모델이 색을 지어내고 그리는 시점에 죽는다
+ *   · hostContext.context·revision → 제안   끊기면 → 모델러가 모델이 본 판이 아닌 판에 명령을 적용한다
  *
  * 실제 모델은 부르지 않는다. 여기서 볼 것은 모델의 솜씨가 아니라 **우리 배선**이다.
  */
@@ -64,14 +64,13 @@ function install() {
     Figure: class {},
     inspectSource: (json?: string | null) =>
       json ? { blocked: false, findings: [] } : { blocked: true, findings: [{ code: 'no-source', message: '정본이 없다', blocking: true }] },
-    proposeFigure: async (input: any) => {
+    proposeFigureV3: async (input: any) => {
       proposed.push(input)
       return {
-        source: SOURCE,
+        steps: [{ kind: 'rename', name: 'Mixer' }],
+        source: { ...model.createV3Asset(input.base?.name ?? input.name ?? 'Figure') },
         score: { grade: 'B' },
-        cost: { triangles: 12, at: { drawCalls: 100 } },
-        quality: { status: 'ready', summary: 'clear', findings: [] },
-        violations: [],
+        cost: { triangles: 12 },
         attempts: 1
       }
     },
@@ -304,16 +303,6 @@ describe('대화면 문맥에서 대상을 해소한다', () => {
     expect(result.source.parts).toHaveLength(2)
   })
 
-  it('후보 수정도 저장 전 초안을 base로 쓴다 — 도크가 옛 판을 고치지 않게', async () => {
-    const draft = { ...SOURCE, base: { x: 400, y: 500, z: 300 } }
-    await toolNamed('proposeFigureCandidate').builder(
-      { prompt: '폭을 더 살려줘' },
-      ctx({ figureId: 'fig-1', palette: ['palette.primary'], draftSource: draft })
-    )
-
-    expect(proposed[0].base.base.x).toBe(400)
-  })
-
   it('다른 type의 초안은 거절한다 — 브라우저 문맥으로 저장 식별자를 바꾸지 않는다', async () => {
     await expect(
       toolNamed('getFigureSource').builder(
@@ -373,154 +362,125 @@ describe('모델이 넘긴 id 를 믿지 않는다', () => {
   })
 })
 
-describe('후보를 요청할 때', () => {
-  it('저장 전 새 모델도 현재 초안을 읽고 수정 후보의 기반으로 사용한다', async () => {
-    const host = { editorMode: 'new', draftSource: SOURCE, palette: ['palette.primary'] }
-    const read = await toolNamed('getFigureSource').builder({}, ctx(host))
-    expect(read.source).toEqual(SOURCE)
-    expect(read.draft).toBe(true)
-    const result = await toolNamed('proposeFigureCandidate').builder({ prompt: '몸체를 키워줘' }, ctx(host))
-    expect(proposed[0].base).toEqual(SOURCE)
-    expect(result.args.draftType).toBe('MIXER')
-    expect(result.args.figureId).toBeUndefined()
+/*
+  제안은 모델러의 명령 목록이다(ADR-0094). 고치는 제안은 모델러가 모델이 본 판 위에 한 단계로 적용하므로, 고칠 수
+  있는 것은 모델러에 열린 V3 도형뿐이고 그 판(context · revision)을 문맥이 싣고 와야 한다.
+*/
+const v3Draft = () => {
+  const model = require('@hatiolab/figure-model')
+  let asset = model.createV3Asset('Probe')
+  asset = model.addV3Box(asset, { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  return asset
+}
+const modeller = (over: any = {}) => ({ figureId: 'fig-1', draftSource: v3Draft(), context: 'ctx-7', revision: 4, ...over })
+
+describe('제안을 요청할 때', () => {
+  it('열린 도형을 고치면 그 V3 초안이 제안기에 가고, 모델러가 적용할 판이 함께 돌아온다', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '다리를 길게' }, ctx(modeller()))
+    expect(proposed[0].base.name).toBe('Probe')
+    expect(proposed[0].base.version).toBe('figure-v3-asset-1')
+    expect(out.context).toBe('ctx-7')
+    expect(out.revision).toBe(4)
+    expect(out.figureId).toBe('fig-1')
+    expect(out.create).toBe(false)
+  })
+
+  it('판을 모르는 문맥에서는 고치는 제안을 내지 않는다 — 다른 판에 적용되지 않게', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '다리를 길게' }, ctx(modeller({ revision: undefined })))
+    expect(out.error).toBe('FIGURE_NOT_OPEN')
+    expect(proposed).toHaveLength(0)
   })
 
-  it('목록에 남은 새 모델 초안은 현재 모델로 사용하지 않는다', async () => {
-    const result = await toolNamed('getFigureSource').builder({}, ctx({ editorMode: 'catalog', draftSource: SOURCE }))
-    expect(result.error).toBe('FIGURE_TARGET_REQUIRED')
+  it('모델러에 열리지 않은 도형은 고치지 않고, 열라고 말한다', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '고쳐줘', figureId: 'fig-blank' }, ctx(modeller()))
+    expect(out.error).toBe('FIGURE_NOT_OPEN')
+    expect(proposed).toHaveLength(0)
   })
 
-  it('목록에서 새 제작은 기존 도형을 요구하지 않는다', async () => {
-    const result = await toolNamed('proposeFigureCandidate').builder(
-      { prompt: '믹서를 새로 만들어줘', create: true }, ctx({ palette: ['palette.primary'] })
-    )
-    expect(result.proposed).toBe(true)
-    expect(proposed[0].base).toBeUndefined()
+  it('V3 가 아닌 원본은 고치지 않는다 — V2 를 제안기에 건네지 않는다', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '고쳐줘' }, ctx({ figureId: 'fig-1', context: 'c', revision: 1 }))
+    expect(out.error).toBe('FIGURE_NOT_OPEN')
+    expect(proposed).toHaveLength(0)
   })
 
-  it('figureId null은 도구 설명대로 새 제작을 의미한다', async () => {
-    await toolNamed('proposeFigureCandidate').builder({ prompt: '새로 만들어줘', figureId: null }, ctx())
+  it('목록에서 새 제작은 열린 도형을 요구하지 않는다', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '믹서를 새로 만들어줘', create: true, name: 'Mixer' }, ctx({}))
+    expect(out.proposed).toBe(true)
     expect(proposed[0].base).toBeUndefined()
+    expect(proposed[0].name).toBe('Mixer')
+    expect(out.create).toBe(true)
+    expect(out.context).toBeUndefined()
   })
 
-  it('다른 도형을 지정하면 열린 도형의 미저장 초안을 섞지 않는다', async () => {
-    const result = await toolNamed('getFigureSource').builder(
-      { figureId: 'fig-blank' }, ctx({ figureId: 'fig-1', draftSource: SOURCE })
-    )
-    expect(result.id).toBe('fig-blank')
-    expect(result.source).toBeNull()
-  })
-
-  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())
-
+  it('figureId null 은 도구 설명대로 새 제작이다', async () => {
+    await toolNamed('proposeFigureCandidate').builder({ prompt: '새로 만들어줘', figureId: null }, ctx(modeller()))
     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('create 를 켜면 열린 도형이 있어도 새로 만든다 — 열린 것을 덮어쓰는 제안이 오지 않게', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '새 컨베이어', create: true }, ctx(modeller()))
+    expect(proposed[0].base).toBeUndefined()
+    expect(out.revision).toBeUndefined()
   })
 
   it('빈 요청은 거절한다', async () => {
-    await expect(toolNamed('proposeFigureCandidate').builder({ prompt: '   ' }, ctx())).rejects.toThrow(
-      /prompt is required/
-    )
+    await expect(toolNamed('proposeFigureCandidate').builder({ prompt: '   ' }, ctx(modeller()))).rejects.toThrow(/prompt is required/)
   })
 
   it('남의 도형을 고치라고 하면 못 찾았다고 한다', async () => {
     await expect(
-      toolNamed('proposeFigureCandidate').builder({ prompt: '고쳐줘', figureId: 'fig-other' }, ctx())
+      toolNamed('proposeFigureCandidate').builder({ prompt: '고쳐줘', figureId: 'fig-other' }, ctx(modeller()))
     ).rejects.toThrow(/not found in this tenant/)
   })
+
+  it('세 번 거절된 끝의 사유가 도구 경계를 넘어간다 — 「만들지 못했습니다」만 남지 않게', async () => {
+    const { ProposeV3Failure } = require('./figure-propose-v3')
+    const model = require('@hatiolab/figure-model')
+    __setFigureToolDepsForTest({
+      getRepository: () => stubRepository(ROWS),
+      Figure: class {},
+      parseAnySource: require('./figure-format').parseAnySource,
+      proposeFigureV3: async () => {
+        throw new ProposeV3Failure('만들지 못했습니다.', ['ATTACH_FACE: steps[4]: attach: faces along x'], 3)
+      },
+      v3CostOf: model.v3CostOf,
+      v3ScoreOf: model.v3ScoreOf
+    })
+    await expect(toolNamed('proposeFigureCandidate').builder({ prompt: '고쳐줘' }, ctx(modeller()))).rejects.toThrow(
+      /만들지 못했습니다\.\nATTACH_FACE: steps\[4\]/
+    )
+  })
 })
 
 /*
-  후보가 화면에 닿는 길은 하나다 — 도구 결과의 `proposed: true` 가 카드를 만들고, 카드의 단추가
-  호스트에게 실행을 넘긴다. 이 표시가 빠지면 후보는 도구 추적 안에 묻히고 화면에는 아무것도 생기지
-  않는다. 그때 모델이 「후보를 만들었습니다」라고 쓴 것이 거짓이 된다. twin 이 이 자리에서 사용자에게
-  없는 단추를 누르라고 안내했다.
+  제안이 화면에 닿는 길은 하나다 — 도구 결과의 `proposed: true` 가 카드를 만들고, 카드의 실행 단추가
+  figure-ui 의 처리기에 넘긴다. 이 표시가 빠지면 제안은 도구 추적 안에 묻히고 화면에는 아무것도 생기지
+  않는다. 그때 모델이 「후보를 만들었습니다」라고 쓴 것이 거짓이 된다.
 */
-describe('후보가 카드가 된다', () => {
-  it('proposed 표시가 붙어 온다 — 없으면 화면에 아무것도 생기지 않는다', async () => {
-    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '교반기', create: true }, ctx())
-
+describe('제안이 카드가 된다', () => {
+  it('proposed 표시와 명령 목록이 함께 온다', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '교반기', create: true }, ctx({}))
     expect(out.proposed).toBe(true)
+    expect(out.steps).toEqual([{ kind: 'rename', name: 'Mixer' }])
   })
 
-  it('카드에 그릴 두 줄이 함께 온다', async () => {
-    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '교반기', create: true }, ctx())
-
-    expect(out.label).toContain('MIXER')
-    // 잰 값을 그대로 적는다 — 「좋아졌다」로 요약하면 저작자가 판단할 근거가 없다.
+  it('카드에 그릴 두 줄이 잰 값으로 온다', async () => {
+    const out = await toolNamed('proposeFigureCandidate').builder({ prompt: '교반기', create: true, name: 'Mixer' }, ctx({}))
+    expect(out.label).toBe('Mixer 만들기')
+    expect(out.reason).toMatch(/명령 1개/)
     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())
-
+    const revise = await toolNamed('proposeFigureCandidate').builder({ prompt: '고쳐줘' }, ctx(modeller()))
+    const create = await toolNamed('proposeFigureCandidate').builder({ prompt: '만들어줘', create: true }, ctx({}))
     expect(revise.label).toMatch(/고치기/)
     expect(create.label).toMatch(/만들기/)
   })
-
-  it('현재 Figure의 세션 피드백만 후보 개선 입력으로 전달한다', async () => {
-    const feedback = [{ outcome: 'discarded', selectedChanges: 0, totalChanges: 2, note: '포트를 더 분명히' }]
-    await toolNamed('proposeFigureCandidate').builder(
-      { prompt: '다시 고쳐줘' },
-      ctx({ figureId: 'fig-1', palette: ['palette.primary'], proposalFeedback: feedback })
-    )
-
-    expect(proposed[0].feedback).toEqual(feedback)
-    expect(proposed[0].refine).toBe(true)
-  })
-
-  it('새 Figure 생성에는 열려 있던 Figure의 세션 피드백을 섞지 않는다', async () => {
-    await toolNamed('proposeFigureCandidate').builder(
-      { prompt: '새로 만들어줘', create: true, type: 'NEW_FIGURE' },
-      ctx({ figureId: 'fig-1', palette: ['palette.primary'], proposalFeedback: [{ outcome: 'discarded' }] })
-    )
-
-    expect(proposed[0].feedback).toBeUndefined()
-    expect(proposed[0].refine).toBe(false)
-  })
 })
 
-/*
-  V3 도형이 열려 있을 때(사용자 2026-09-24: 도크가 V3 초안에 「type 이 없다 · base 가 없다」 로 답했다). 읽기는 V3 로 읽고
-  잰다. 후보 제안은 아직 V2 만 쓰므로 지어내지 않고 그렇다고 말한다.
-*/
 describe('V3 도형이 열려 있을 때', () => {
-  const v3Draft = () => {
-    const model = require('@hatiolab/figure-model')
-    let asset = model.createV3Asset('Probe')
-    asset = model.addV3Box(asset, { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
-    return asset
-  }
-
   it('저장 전 V3 초안을 V3 로 읽고, V3 셈으로 잰다', async () => {
     const draft = v3Draft()
     const got = await toolNamed('getFigureSource').builder({}, ctx({ figureId: 'fig-1', draftSource: draft, palette: ['palette.primary'] }))
@@ -535,11 +495,4 @@ describe('V3 도형이 열려 있을 때', () => {
     await expect(toolNamed('getFigureSource').builder({}, ctx({ figureId: 'fig-1', draftSource: broken, palette: ['palette.primary'] }))).rejects.toThrow(/V3 draft/)
     await expect(toolNamed('getFigureSource').builder({}, ctx({ figureId: 'fig-1', draftSource: broken, palette: ['palette.primary'] }))).rejects.not.toThrow(/base 가 없다/)
   })
-
-  it('후보 제안은 V3 도형에 V2 후보를 지어내지 않고, 아직 못 한다고 말한다', async () => {
-    const got = await toolNamed('proposeFigureCandidate').builder({ prompt: '다리를 길게' }, ctx({ figureId: 'fig-1', draftSource: v3Draft(), palette: ['palette.primary'] }))
-    expect(got.error).toBe('V3_PROPOSAL_UNAVAILABLE')
-    expect(proposed).toHaveLength(0)
-  })
 })
-

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

@@ -6,12 +6,12 @@
  * 하려면 어시스턴트가 **지금 무엇이 있는지 읽을 수 있어야** 한다. 읽지 못하면 매번 사람이 정본을
  * 붙여 넣어야 하고, 그러면 대화가 아니다.
  *
- * 능력을 복제하지 않는다. figure-service 가 이미 가진 진입점(`inspectSource` · `proposeFigure` ·
+ * 능력을 복제하지 않는다. figure-service 가 이미 가진 진입점(`inspectSource` · `proposeFigureV3` ·
  * 조회)을 레지스트리에 투영한다.
  *
  * ── 전부 조회·제안 전용이다 ─────────────────────────────────────────────────
  * 정본을 고치는 도구를 넣지 않는다. 형식의 설계가 그렇게 정해져 있다 — 어시스턴트는 **후보**를
- * 내고, 받을지 버릴지는 저작자가 정한다(`figure-propose.ts`). 되돌릴 수 없는 조작이 대화면으로
+ * 내고, 받을지 버릴지는 저작자가 정한다(`figure-propose-v3.ts`, ADR-0094). 되돌릴 수 없는 조작이 대화면으로
  * 새지 않으므로 전부 `kind: 'read'` 다.
  *
  * 저장은 저작면이 `updateFigure` 로 한다. 그 mutation 은 `figure:mutation` 이 지키고, 대화는
@@ -53,7 +53,7 @@ function getDeps(): any {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const format = require('./figure-format.js')
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const propose = require('./figure-propose.js')
+    const proposeV3 = require('./figure-propose-v3.js')
     _deps = {
       getRepository: shell.getRepository,
       Figure: entity.Figure,
@@ -65,7 +65,7 @@ function getDeps(): any {
       parseAnySource: format.parseAnySource,
       v3CostOf: model.v3CostOf,
       v3ScoreOf: model.v3ScoreOf,
-      proposeFigure: propose.proposeFigure,
+      proposeFigureV3: proposeV3.proposeFigureV3,
       compile: model.compile,
       costOf: model.costOf,
       scoreOf: model.scoreOf,
@@ -160,16 +160,15 @@ async function resolveFigureTarget(figureId: string | undefined, domainId: strin
 const isV3 = (source: any) => source?.version === 'figure-v3-asset-1'
 
 /**
- * The V2 proposer writes V2 figures; a V3 figure open in the modeller is not something it can revise or add to. Said as
- * what is true, with what the assistant can do instead -- not a V2 parser's complaint about a V3 asset (user,
- * 2026-09-24: the dock answered 「type 이 없다 · base 가 없다」 for a V3 draft).
+ * A revision is applied by the modeller on the version the model saw (ADR-0094), so only the figure open there can be
+ * revised. Said as what is true, with what the assistant can do instead.
  */
-function v3ProposalUnavailable() {
+function figureNotOpen() {
   return {
-    error: 'V3_PROPOSAL_UNAVAILABLE',
-    message: '이 도형은 V3 형식입니다. AI 후보 제안은 아직 V2 도형만 만들 수 있어 이 도형을 고치는 후보를 낼 수 없습니다.',
+    error: 'FIGURE_NOT_OPEN',
+    message: '고치는 제안은 모델러에 열려 있는 도형에만 낼 수 있습니다.',
     nextStep:
-      'Tell the person plainly that candidate proposals do not support V3 figures yet. You can still read the figure (getFigureSource) and explain whether it may be released and why (inspectFigure). Do not produce a V2 candidate for a V3 figure.'
+      'Tell the person to open the figure in the modeller and ask again there. A new figure needs no open one: call proposeFigureCandidate with create: true.'
   }
 }
 
@@ -221,23 +220,6 @@ function sourceForTool(row: any, host: any): { source: any; draft: boolean } {
   return { source: normalizedDraft, draft: true }
 }
 
-/**
- * 후보를 냈던 바로 그 Figure의 세션 반응만 후보 생성기에 넘긴다.
- *
- * 도크의 host context는 브라우저 값이므로 이 함수는 접근 권한을 판단하지 않는다. 이미 현재
- * 도메인에서 Figure를 찾은 뒤, `proposeFigure`가 다시 길이·형식을 정리할 참고 데이터만 건넨다.
- */
-function feedbackForTool(host: any, figureId?: string): unknown[] | undefined {
-  if (!Array.isArray(host?.proposalFeedback)) return undefined
-  if (figureId && host?.figureId === figureId) {
-    return host.proposalFeedback.slice(-5)
-  }
-  if (host?.editorMode === 'new' || !host?.figureId) {
-    return host.proposalFeedback.slice(-5)
-  }
-  return undefined
-}
-
 /**
  * 무엇을 고치라는 것인지 대화면 문맥에서 해소한다.
  *
@@ -395,9 +377,9 @@ function figureToolSpecs(): ToolSpec[] {
       /* 후보 생성 — 저장은 하지 않지만 같은 문의 권한을 쓴다. */
       doors: ['Mutation.proposeFigure'],
       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.',
+        'Asks for a proposal: the modeller commands that make a new figure or revise the one open in the modeller. ' +
+        'Returns the commands with the score and cost of the figure they make. NOTHING IS SAVED — the author applies ' +
+        'the proposal in the modeller as one step, or leaves it. This is the only way a proposal reaches the screen.',
       schema: {
         type: 'object',
         properties: {
@@ -407,11 +389,11 @@ function figureToolSpecs(): ToolSpec[] {
           },
           figureId: {
             type: 'string',
-            description: 'Revise this figure. Omit to revise the one open in the editor; pass null to create anew.'
+            description: 'Revise this figure; it must be the one open in the modeller. Omit to revise the open one; pass null to create anew.'
           },
-          type: {
+          name: {
             type: 'string',
-            description: 'Type name for a new figure. Check listFigures first — it is a stored identifier.'
+            description: 'The name a person reads for a new figure.'
           },
           create: {
             type: 'boolean',
@@ -429,54 +411,52 @@ function figureToolSpecs(): ToolSpec[] {
           고치는 것인지 만드는 것인지를 **문맥에서 정한다.** 열린 도형이 있으면 고치는 것이 기본이고,
           모델이 `create` 를 켜면 만드는 것이다. 이것을 모델의 짐작에 맡기면 열려 있는 도형을 덮어쓰는
           후보가 온다.
+
+          고치는 제안은 모델러가 **요청 당시의 판(context · revision)** 위에 한 단계로 적용한다(ADR-0094).
+          그래서 고칠 수 있는 것은 모델러에 열린 도형뿐이고, 그 판을 문맥이 함께 실어 와야 한다.
         */
+        const host = ctx?.host
+        const create = args?.create === true || args?.figureId === null
         let base: unknown
-        if (!args?.create && args?.figureId !== null) {
-          const open = typeof args?.figureId === 'string' ? args.figureId : ctx?.host?.figureId
-          const row = await resolveFigureTarget(open ? open.trim() : undefined, domainId, ctx?.host)
-          if (row) {
-            base = sourceForTool(row, ctx?.host).source ?? undefined
+        let figureId: string | undefined
+        if (!create) {
+          const said = typeof args?.figureId === 'string' ? args.figureId.trim() : ''
+          const open = typeof host?.figureId === 'string' ? host.figureId.trim() : ''
+          if (said && said !== open) {
+            await figureInDomain(said, domainId)
+            return figureNotOpen()
           }
-        }
-        if (isV3(base) || (args?.create !== true && isV3(ctx?.host?.draftSource))) return v3ProposalUnavailable()
-
-        const palette = Array.isArray(ctx?.host?.palette) ? ctx.host.palette : []
-        if (palette.length === 0) {
-          /*
-            팔레트를 모르면 모델이 색을 지어내고, 그 후보는 그리는 시점에 `resolveToken` 이 던진다 —
-            저장까지 되고 나서 화면에서 죽는다. 빈 목록으로 진행하지 않는다.
-          */
-          throw new Error('the palette is missing from the host context — the candidate would invent colours')
+          if (!open) return missingFigureTarget()
+          const row = await resolveFigureTarget(open, domainId, host)
+          if (!row) return missingFigureTarget()
+          base = sourceForTool(row, host).source ?? undefined
+          if (!isV3(base)) return figureNotOpen()
+          if (typeof host?.context !== 'string' || !Number.isInteger(host?.revision)) return figureNotOpen()
+          figureId = open
         }
 
-        const { proposeFigure } = getDeps()
-        const feedback = feedbackForTool(ctx?.host, base ? figureIdFrom(args, ctx?.host) : undefined)
-
         let hostImage: { data: Buffer; mediaType: any } | undefined
-        const rawImage = ctx?.host?.image || (Array.isArray(ctx?.host?.attachments) ? ctx.host.attachments.find((a: any) => a?.mediaType?.startsWith('image/')) : undefined)
+        const rawImage = host?.image || (Array.isArray(host?.attachments) ? host.attachments.find((a: any) => a?.mediaType?.startsWith('image/')) : undefined)
         if (rawImage?.data) {
           const rawData = typeof rawImage.data === 'string' ? rawImage.data.replace(/^data:image\/[a-zA-Z]+;base64,/, '') : rawImage.data
           const buf = typeof rawData === 'string' ? Buffer.from(rawData, 'base64') : Buffer.from(rawData)
           hostImage = { data: buf, mediaType: rawImage.mediaType || 'image/png' }
         }
 
+        const { proposeFigureV3 } = getDeps()
         let result: any
         try {
-          result = await proposeFigure({
+          result = await proposeFigureV3({
             prompt,
-            palette,
             base,
-            type: typeof args?.type === 'string' ? args.type : undefined,
-            feedback,
-            refine: !!feedback?.length,
+            name: typeof args?.name === 'string' && args.name.trim() ? args.name.trim() : undefined,
             image: hostImage
           })
         } catch (error) {
           /*
-           * 후보 생성은 세 번의 JSON·형식 검사 끝에 실패할 수 있다. 그 마지막 검사 사유를
-           * ProposeFailure.reasons 에만 두면 agentic-loop은 "만들지 못했습니다"만 받아
-           * 사용자 화면에는 "응답이 비어있습니다"가 된다. 재시도할 수 있는 말로 경계를
-           * 넘긴다. 다른 예외(권한·통신)는 원문을 보존한다.
+           * 세 번 거절된 끝의 사유를 ProposeV3Failure.reasons 에만 두면 agentic-loop 은 「만들지 못했습니다」만
+           * 받아 화면에는 「응답이 비어있습니다」가 된다. 다시 시도할 수 있는 말로 경계를 넘긴다.
+           * 다른 예외(권한·통신)는 원문을 보존한다.
            */
           const reasons = Array.isArray((error as any)?.reasons) ? (error as any).reasons : []
           if (reasons.length > 0) throw new Error([(error as Error).message, ...reasons].join('\n'))
@@ -484,37 +464,26 @@ function figureToolSpecs(): ToolSpec[] {
         }
 
         /*
-          **`proposed: true` 가 카드를 만든다.** 이 표시가 없으면 후보는 도구 추적 안에 묻히고,
-          화면에는 아무것도 생기지 않는다 — 그러면 모델이 「후보를 만들었습니다」라고 쓴 것이
-          거짓말이 된다(사용자가 없는 단추를 찾는다).
-
-          `label`·`reason` 이 카드에 그려지는 두 줄이고, `args` 는 같은 제안을 두 번 세지 않기
-          위한 열쇠의 일부다 — 같은 요청을 두 번 내면 카드가 하나로 접힌다.
+          **`proposed: true` 가 카드를 만든다.** 이 표시가 없으면 제안은 도구 추적 안에 묻히고 화면에는
+          아무것도 생기지 않는다. 카드의 실행 단추가 figure-ui 의 처리기에 넘기고, 처리기가 모델러에 명령
+          목록을 한 단계로 적용한다. `args` 는 같은 제안을 두 번 세지 않기 위한 열쇠의 일부다.
         */
+        const name = result.source.name || 'Figure'
         return {
           proposed: true,
-          label: base ? `${result.source.type} 고치기` : `${result.source.type} 만들기`,
+          icon: 'view_in_ar',
+          label: create ? `${name} 만들기` : `${name} 고치기`,
           reason:
-            `등급 ${result.score.grade} · 삼각형 ${result.cost.triangles} · ` +
-            `한 도면 ${result.cost.at.drawCalls}회 · ${result.attempts}번에 만들었다`,
-          choices: [
-            { id: 'save', action: 'save', label: '초안 저장', icon: 'save', primary: true },
-            { id: 'repropose', action: 'prompt', label: '다른 콘셉트 재제안', icon: 'refresh', prompt: '현재 제안과 완전히 다른 스타일과 콘셉트로 새로 제안해줘' },
-            { id: 'slim', action: 'prompt', label: '비율 슬림 조정', icon: 'aspect_ratio', prompt: '전체적인 가로세로 비율을 좀 더 슬림하고 날렵하게 조정해줘' },
-            { id: 'palette', action: 'prompt', label: '색상 테마 변경', icon: 'palette', prompt: '다른 팔레트 색상 테마로 부품 색상을 변경해줘' },
-            { id: 'detail', action: 'prompt', label: '디테일 보강', icon: 'extension', prompt: '주요 디테일과 센서 부품을 좀 더 풍부하게 보강해줘' }
-          ],
-          args: {
-            baseSource: base ? JSON.stringify(base) : undefined,
-            prompt, figureId: base ? figureIdFrom(args, ctx?.host) : undefined,
-            draftType: base && ctx?.host?.editorMode === 'new' && !figureIdFrom(args, ctx?.host)
-              ? (base as any).type : undefined
-          },
-          source: result.source,
+            `명령 ${result.steps.length}개 · 등급 ${result.score?.grade ?? '-'} · 삼각형 ${result.cost.triangles} · ` +
+            `${result.attempts}번에 만들었다`,
+          args: { prompt, figureId, create },
+          create,
+          figureId,
+          context: create ? undefined : host.context,
+          revision: create ? undefined : host.revision,
+          steps: result.steps,
           score: result.score,
           cost: result.cost,
-          quality: result.quality,
-          violations: result.violations,
           attempts: result.attempts
         }
       }
@@ -537,13 +506,13 @@ export function registerFigureToolCategories(): void {
       '- **도형을 만들거나 고쳐 달라는 요청에는 반드시 `proposeFigureCandidate` 를 호출한다.**',
       '  후보는 도구 호출 결과에서만 생긴다.',
       '  호출 없이 "후보를 만들었습니다" · "적용 버튼을 누르세요" 라고 쓰는 것은 **거짓이다** — 화면에 후보 칸이 생기지 않으므로 사용자는 존재하지 않는 버튼을 찾는다.',
-      '  도크에서는 후보 카드의 버튼을 눌러야 모델러 비교 화면이 열린다. 아직 열지 않은 비교 화면이 이미 보인다고 말하지 않는다.',
-      '  요청한 부품만 바뀌었다고 추측하지 않는다. 후보와 원본을 비교한 근거가 없으면 변경 범위는 비교 화면에서 확인하도록 안내한다.',
+      '  후보는 모델러 명령 목록이다. 도크 카드의 실행 단추를 눌러야 모델러에 한 단계로 적용되고, 되돌리기 한 번에 통째로 돌아간다. 적용 전에 이미 바뀌었다고 말하지 않는다.',
+      '  고치는 제안은 모델러에 열린 도형에만 낼 수 있다. 결과의 `steps` 가 무엇을 하는지 그대로 전한다 — 명령에 없는 변경을 지어내지 않는다.',
       '- 정본을 직접 저장하지 않는다. 후보만 내고, 받을지 버릴지는 저작자가 화면에서 정한다.',
       '- 좌표와 크기는 X/Y/Z 축 이름으로 정확하게 표시한다. 확인되지 않은 가로·세로·높이 의미를 임의로 붙이지 않는다.',
       '- **고치라는 요청이면 먼저 `getFigureSource` 를 부른다.** 읽지 않고 고치면 짐작을 상대로 후보를 내게 되고, 부품 이름이 갈려 이미 배치된 보드의 바인딩이 끊긴다.',
-      '- 목록 화면에는 열린 도형이 없다. 기존 도형을 조회·수정할 때는 `listFigures`에서 사용자가 말한 이름·타입의 id를 찾는다. 대상이 모호할 때만 어느 도형인지 묻는다. 새 제작 요청에는 기존 정본을 조회하지 않고 `proposeFigureCandidate`를 create: true로 호출한다.',
-      '- 타입 이름을 지어내지 않는다 — `listFigures` 로 확인한다. **타입 이름은 저장되는 식별자**이고 보드가 그 이름으로 도형을 찾는다.',
+      '- 목록 화면에는 열린 도형이 없다. 기존 도형을 조회할 때는 `listFigures`에서 사용자가 말한 이름·타입의 id를 찾는다. 대상이 모호할 때만 어느 도형인지 묻는다. 기존 도형을 고치려면 모델러에서 그 도형을 열고 거기서 요청하도록 안내한다. 새 제작 요청에는 기존 정본을 조회하지 않고 `proposeFigureCandidate`를 create: true로 호출한다.',
+      '- 타입 이름을 지어내지 않는다 — `listFigures` 로 확인한다. **타입 이름은 저장되는 식별자**이고 보드가 그 이름으로 도형을 찾는다. 새 도형의 타입은 첫 저장 때 사람이 정한다.',
       '- 발행이 안 되는 이유를 물으면 `inspectFigure` 를 부른다. 판정 없이 "발행할 수 있습니다"라고 말하지 않는다.',
       '  판정의 각 항목은 **왜 문제인지와 무엇을 바꾸면 되는지**를 함께 담고 있다. 그대로 전한다 — 요약하면 저작자가 어느 부품의 어느 축을 고칠지 다시 찾아야 한다.',
       '- 무게·삼각형 수를 물으면 `getFigureSource` 의 `cost` 를 쓴다. 눈대중으로 세지 않는다.'