@things-factory/figure-service 10.1.36 → 10.1.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.36",
+  "version": "10.1.38",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -23,15 +23,15 @@
     "migration:create": "node ../../node_modules/typeorm/cli.js migration:create ./server/migrations/migration"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.35",
+    "@hatiolab/figure-model": "^0.1.38",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.31",
-    "@things-factory/auth-base": "^10.1.34",
+    "@things-factory/auth-base": "^10.1.38",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.34",
+    "@things-factory/shell": "^10.1.38",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "3942ac0aa4f004b4700e739889e12ffc35d78794"
+  "gitHead": "b947349fe1c27d11038b592ceadaba336f14785b"
 }

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

@@ -0,0 +1,264 @@
+/**
+ * figure-format — 한 문이 두 판을 읽는다.
+ *
+ * 전환 중에는 `source` 칸에 V2 정본과 V3 자산이 섞여 있다(ADR-0087). 저장·발행·되돌리기·소비처가
+ * 저마다 판을 따지면 네 자리에서 답이 갈린다. 여기서 한 번 묻는다.
+ *
+ * 이 파일이 지키는 것:
+ *   - 판은 자산이 적은 `version` 으로 안다. 생김새로 짐작하지 않는다.
+ *   - 판을 모르는 정본은 거절한다 — 알아보지 못하는 것을 저장하면 안 된다.
+ *   - V3 자산도 저장·발행·되돌리기·소비처를 지난다. 이 넷은 전에 V2 만 지날 수 있었다.
+ *   - 예산 칸(`triangles`·`groups`)은 두 판에서 같은 뜻이다.
+ */
+import { createV3Asset, addV3Box, addV3Primitive, serializeV3Asset, applyV3Authoring, proposeV3Occupancy } from '@hatiolab/figure-model'
+import type { V3Asset } from '@hatiolab/figure-model'
+
+import { consumablePayloadOf, formatOf, inspectAnySource, parseAnySource } from './figure-format'
+import { FigureSourceError } from './figure-source'
+
+/** 온전한 V2 정본 하나. 바닥에 선 상자 한 부품. */
+const v2Source = (over: Record<string, unknown> = {}) =>
+  JSON.stringify({
+    version: 2,
+    type: 'MIXER',
+    base: { x: 300, y: 800, z: 300 },
+    detailLevel: 'M',
+    parts: [
+      {
+        name: 'body',
+        primitive: 'cube',
+        transform: { position: { x: 0, y: 50, z: 0 }, size: { x: 100, y: 100, z: 100 } },
+        material: { token: 'palette.primary' }
+      }
+    ],
+    ...over
+  })
+
+/** 온전한 V3 자산 하나: 바닥에 선 상자와, 부품에서 제안받아 확정한 점유 부피. */
+function v3Asset(): V3Asset {
+  let asset = createV3Asset('Mixer')
+  asset = addV3Box(asset, { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  asset = applyV3Authoring(asset, { kind: 'attach', part: 'body', face: 'bottom', to: { plane: 'mounting-plane' } })
+  asset = applyV3Authoring(asset, {
+    kind: 'declare-occupancy',
+    proposal: proposeV3Occupancy(asset, { over: 'range' }),
+    placement: 'floor'
+  })
+  return asset
+}
+const v3Source = () => serializeV3Asset(v3Asset())
+
+describe('figure-format — 판을 알아보는 문', () => {
+  describe('판은 자산이 적는다', () => {
+    it('숫자 version 은 V2, figure-v3-asset-1 은 V3 다', () => {
+      expect(formatOf(v2Source())).toBe('v2')
+      expect(formatOf(v3Source())).toBe('v3')
+    })
+
+    it('판을 안 적은 정본은 거절한다 — 생김새로 짐작하지 않는다', () => {
+      expect(() => formatOf(JSON.stringify({ type: 'MIXER', parts: [] }))).toThrow(FigureSourceError)
+      try {
+        formatOf(JSON.stringify({ type: 'MIXER' }))
+      } catch (e) {
+        expect((e as FigureSourceError).findings[0].code).toBe('source-format-unknown')
+      }
+    })
+
+    it('JSON 이 아니면 그 말로 거절한다', () => {
+      try {
+        formatOf('{')
+      } catch (e) {
+        expect((e as FigureSourceError).findings[0].code).toBe('source-not-json')
+      }
+    })
+  })
+
+  describe('저장 — 두 판 다 지난다', () => {
+    it('V2 정본은 전과 같이 점수·삼각형·묶음을 받는다', () => {
+      const parsed = parseAnySource(v2Source())
+      expect(parsed.format).toBe('v2')
+      expect(parsed.derived.triangles).toBe(12)
+      expect(parsed.derived.groups).toBeGreaterThan(0)
+      expect(typeof parsed.derived.score).toBe('number')
+    })
+
+    it('V3 자산은 같은 예산 칸을 받는다 — 상자 하나는 두 판에서 다 삼각형 12 다', () => {
+      const parsed = parseAnySource(v3Source())
+      expect(parsed.format).toBe('v3')
+      expect(parsed.derived.triangles).toBe(12)
+      expect(parsed.derived.groups).toBe(1)
+    })
+
+    it('V3 의 점수 칸은 비운다 — V2 점수는 V2 재사용의 잣대이고 V3 를 잰 적이 없다', () => {
+      expect(parseAnySource(v3Source()).derived.score).toBeNull()
+    })
+
+    it('형식을 어긴 V3 자산은 거절한다', () => {
+      const broken = JSON.parse(v3Source())
+      broken.appearance = []
+      expect(() => parseAnySource(JSON.stringify(broken))).toThrow(FigureSourceError)
+    })
+  })
+
+  describe('발행 판정 — 두 판 다 지난다', () => {
+    it('제 부피 안에 든 V3 자산은 막지 않는다', () => {
+      const inspection = inspectAnySource(v3Source())
+      expect(inspection.blocked).toBe(false)
+    })
+
+    it('선언한 부피 밖으로 나간 부품은 이름과 함께 막는다', () => {
+      let asset = v3Asset()
+      asset = addV3Box(asset, { id: 'arm', size: { x: 100, y: 100, z: 100 }, position: { x: 900, y: 50, z: 0 } })
+      const inspection = inspectAnySource(serializeV3Asset(asset))
+      expect(inspection.blocked).toBe(true)
+      expect(inspection.findings.some(f => f.code === 'part-outside-occupancy' && f.at === 'arm')).toBe(true)
+    })
+
+    it('부피를 선언하지 않은 V3 자산은 막는다', () => {
+      let asset = createV3Asset('Bare')
+      asset = addV3Box(asset, { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+      const inspection = inspectAnySource(serializeV3Asset(asset))
+      expect(inspection.blocked).toBe(true)
+      expect(inspection.findings.some(f => f.code === 'occupancy-undeclared')).toBe(true)
+    })
+
+    it('전 범위를 증명하지 못한 판정은 막지 않고 그 사실을 말한다', () => {
+      /* 상태에 따라 도는 부품은 모서리만으로 증명되지 않는다 — 표본 검사였음을 발행 화면이 읽는다. */
+      let asset = v3Asset()
+      asset = addV3Primitive(asset, { id: 'wheel', kind: 'cylinder', dimensions: { radius: 20, length: 20 }, position: { x: 0, y: 20, z: 0 } })
+      const m = asset.document.model as any
+      m.inputs.push({ id: 'spin', unit: 'deg', min: -180, max: 180, role: 'state' })
+      asset.stateDefaults['spin'] = 0
+      m.constants.push({ id: 'axisY0', unit: 'ratio', value: 0 }, { id: 'axisY1', unit: 'ratio', value: 1 })
+      m.nodes.push({
+        id: 'wheel.turn',
+        op: 'axis-turn@1',
+        args: ['axisY0', 'axisY1', 'axisY0', 'spin'],
+        outputs: { pose: 'wheel.turn.p' },
+        params: { from: 'wheel.spun', to: 'asset' }
+      })
+      const pose = m.nodes.find((n: any) => n.id === 'wheel.pose')
+      pose.params = { ...pose.params, to: 'wheel.spun' }
+      m.nodes.push({ id: 'wheel.world', op: 'compose@1', args: ['wheel.turn.p', pose.outputs.pose], outputs: { pose: 'wheel.wp' } })
+      m.nodes.find((n: any) => n.id === 'wheel').args = [m.nodes.find((n: any) => n.id === 'wheel.shape').outputs.shape, 'wheel.wp']
+      asset = applyV3Authoring(asset, {
+        kind: 'declare-occupancy',
+        proposal: proposeV3Occupancy(asset, { over: 'range' }),
+        placement: 'floor'
+      })
+
+      const inspection = inspectAnySource(serializeV3Asset(asset))
+      const sampled = inspection.findings.find(f => f.code === 'state-range-sampled')
+      expect(sampled).toBeDefined()
+      expect(sampled!.blocking).toBe(false)
+      /* 증명을 막은 연산은 기술 목록이라 문장이 아니라 자리 칸에 간다. */
+      expect(sampled!.at).toContain('axis-turn@1')
+      expect(sampled!.why).not.toContain('axis-turn@1')
+    })
+
+    it('정본이 없으면 전과 같이 그 말로 막는다', () => {
+      expect(inspectAnySource(null).findings[0].code).toBe('no-source')
+    })
+
+    it('직전 발행판이 있는 V3 재발행은 견주지 못했다고 말한다 — 막지는 않는다', () => {
+      /* V2 는 지난 발행과 견주어 놓인 인스턴스를 깨는 변경을 잡는다. V3 는 그 비교가 아직 없으니 그 사실을 적는다. */
+      const again = inspectAnySource(v3Source(), v3Source())
+      const warning = again.findings.find(f => f.code === 'released-unreadable')
+      expect(warning).toBeDefined()
+      expect(warning!.blocking).toBe(false)
+      expect(again.blocked).toBe(false)
+
+      /* 첫 발행에는 견줄 것이 없으니 그 말도 없다. */
+      expect(inspectAnySource(v3Source()).findings.some(f => f.code === 'released-unreadable')).toBe(false)
+    })
+  })
+
+  /*
+    ADR-0087 5단계에서 V3 판정이 저작자가 보는 유일한 발행 판정이 된다. 그때까지 이 판정은 발행 패널에 영어 문장
+    (`detail`)을 그대로 냈고 왜 · 어떻게가 없었다 — 사용자가 2026-09-19 에 「가장 큰 문제」로 짚고 V2 에서 고친 바로
+    그 모양이다. 문장은 요청의 언어를 아는 서버가 코드와 값에서 만든다(ADR-0054).
+  */
+  describe('V3 판정의 문장 — 발행 패널의 말로', () => {
+    const KO = require('../../../translations/ko.json') as Record<string, string>
+    const EN = require('../../../translations/en.json') as Record<string, string>
+
+    /** i18next 처럼 — 키가 있으면 `{이름}` 을 채우고, 없으면 defaultValue. */
+    const translatorOf = (dict: Record<string, string>, asked: string[] = []) =>
+      (key: string, options: Record<string, unknown> = {}) => {
+        asked.push(key)
+        const text = dict[key] ?? (options.defaultValue as string)
+        return text.replace(/\{(\w+)\}/g, (_, name) => String(options[name] ?? `{${name}}`))
+      }
+
+    const outside = () => {
+      let asset = v3Asset()
+      asset = addV3Box(asset, { id: 'arm', size: { x: 100, y: 100, z: 100 }, position: { x: 900, y: 50, z: 0 } })
+      return serializeV3Asset(asset)
+    }
+    const bare = () => {
+      let asset = createV3Asset('Bare')
+      asset = addV3Box(asset, { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+      return serializeV3Asset(asset)
+    }
+
+    it('넘은 부품은 이름 · 축 · 넘은 양을 화면 말투로 말하고, 왜와 어떻게를 함께 낸다', () => {
+      const finding = inspectAnySource(outside(), null, translatorOf(KO)).findings.find(f => f.code === 'part-outside-occupancy')!
+
+      expect(finding.message).toMatch(/^'arm' 부품이 공간 선언을 X 로 [\d.]+mm 넘습니다\.$/)
+      expect(finding.why).toMatch(/니다\.$/)
+      expect(finding.how).toContain('부품에 맞추기')
+      expect(finding.how).toMatch(/세요\.$/)
+      /* 영어 로그 문장이 화면으로 새지 않는다. */
+      expect(`${finding.message}${finding.why}${finding.how}`).not.toMatch(/declared volume|leaves/)
+    })
+
+    it('공간을 선언하지 않은 도형은 무엇을 누르면 되는지 말한다', () => {
+      const finding = inspectAnySource(bare(), null, translatorOf(KO)).findings.find(f => f.code === 'occupancy-undeclared')!
+
+      expect(finding.message).toBe('이 도형은 차지하는 공간을 아직 선언하지 않았습니다.')
+      expect(finding.how).toContain('부품에 맞추기')
+    })
+
+    it('번역이 없으면 영어로 답한다 — 키를 찍지 않는다', () => {
+      const finding = inspectAnySource(outside()).findings.find(f => f.code === 'part-outside-occupancy')!
+
+      expect(finding.message).toMatch(/^'arm' goes [\d.]+ mm past the declared space on X\.$/)
+      expect(finding.message).not.toContain('figure.gate.')
+    })
+
+    /* 코드가 묻는 키가 두 언어에 다 있어야 한다 — 없으면 그 언어의 화면에 영어가 섞인다. */
+    it('판정이 묻는 키는 ko · en 에 다 있다', () => {
+      const asked: string[] = []
+      const t = translatorOf(KO, asked)
+      inspectAnySource(outside(), null, t)
+      inspectAnySource(bare(), null, t)
+      inspectAnySource(v3Source(), v3Source(), t)
+
+      const keys = [...new Set(asked)]
+      expect(keys.length).toBeGreaterThan(5)
+      expect(keys.filter(k => !(k in KO))).toEqual([])
+      expect(keys.filter(k => !(k in EN))).toEqual([])
+    })
+  })
+
+  describe('소비처 — 판마다 받을 것이 다르다', () => {
+    it('V2 는 전과 같이 청사진을 받는다', () => {
+      const payload = consumablePayloadOf(v2Source())
+      expect(payload.format).toBe('v2')
+      expect((payload.blueprint as { groups?: unknown[] }).groups!.length).toBeGreaterThan(0)
+      expect((payload.blueprint as Record<string, unknown>).format).toBeUndefined()
+    })
+
+    it('V3 는 자산을 그대로 받는다 — 그리는 쪽이 커널로 컴파일한다', () => {
+      const payload = consumablePayloadOf(v3Source())
+      expect(payload.format).toBe('v3')
+      expect((payload.asset as V3Asset).version).toBe('figure-v3-asset-1')
+    })
+
+    it('컴파일되지 않는 V3 자산은 소비처에 넘기지 않고 던진다', () => {
+      const broken = JSON.parse(v3Source())
+      broken.designInputs = {}
+      expect(() => consumablePayloadOf(JSON.stringify(broken))).toThrow()
+    })
+  })
+})

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

@@ -0,0 +1,235 @@
+/*
+ * Which format a stored source is written in, and one door per job that reads either.
+ *
+ * ## Why this exists
+ *
+ * The cutover (ADR-0087) converts assets to V3 and the `source` column holds one or the other while that
+ * happens. Every server path that reads a source — saving, publishing, restoring a version, handing a
+ * blueprint to a board — had exactly one implementation, the V2 one, so a V3 asset saved through
+ * `saveFigureV3` could not be published, restored or drawn. Branching at each of those four places would put
+ * the same question in four voices; it is asked once, here.
+ *
+ * ## How the format is known
+ *
+ * The asset says so. A V2 source carries `version: 2`; a V3 asset carries `version: 'figure-v3-asset-1'`.
+ * Nothing is guessed from the shape of the object: a source that says neither is refused by name, because a
+ * source the server cannot identify is one it must not save.
+ *
+ * ## What is not here
+ *
+ * No conversion. This door reads what is stored; turning a V2 asset into a V3 one is `convertV2ToV3`, run
+ * deliberately against a recoverable copy (the designer's step 3), never as a side effect of a save.
+ */
+import { compile, compileV3Asset, inspectV3Asset, parseV3Asset, serializeV3Asset, v3CostOf } from '@hatiolab/figure-model'
+import type { V3ContractError, V3Violation } from '@hatiolab/figure-model'
+
+import type { GateFinding, Inspection } from './figure-gate.js'
+import { inspectSource } from './figure-gate.js'
+import { FigureSourceError, parseSource } from './figure-source.js'
+import type { ParsedSource } from './figure-source.js'
+
+export type FigureFormat = 'v2' | 'v3'
+
+/** The version each format stamps on its own source. */
+const V3_ASSET_VERSION = 'figure-v3-asset-1'
+
+/**
+ * Which format this source is written in, read from the `version` the asset carries.
+ *
+ * @throws {FigureSourceError} when the text is not JSON, or carries no version this server knows.
+ */
+export function formatOf(sourceJson: string): FigureFormat {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(sourceJson)
+  } catch (e) {
+    throw new FigureSourceError([
+      { code: 'source-not-json', message: `정본이 JSON 이 아니다: ${(e as Error).message}`, at: 'source' }
+    ])
+  }
+  const version = (parsed as { version?: unknown } | null)?.version
+  if (version === V3_ASSET_VERSION) return 'v3'
+  if (typeof version === 'number') return 'v2'
+  throw new FigureSourceError([
+    {
+      code: 'source-format-unknown',
+      message: `정본의 판을 알 수 없다 — V2 는 숫자 version 을, V3 자산은 '${V3_ASSET_VERSION}' 을 적는다`,
+      at: 'version'
+    }
+  ])
+}
+
+/**
+ * Validates a source of either format and computes what the catalogue shows.
+ *
+ * A V3 asset is measured with `v3CostOf`, which charges the same per-shape estimate V2 charges, so the
+ * budget columns mean one thing across the two formats. `score` is left null for V3: the V2 score is a
+ * measure of V2 reuse and carrying it over would put a number in the column that nothing computed.
+ *
+ * @throws {FigureSourceError} when the source breaks its own format.
+ */
+export function parseAnySource(sourceJson: string): ParsedSource & { format: FigureFormat } {
+  if (formatOf(sourceJson) === 'v2') return { ...parseSource(sourceJson), format: 'v2' }
+
+  let asset
+  try {
+    asset = parseV3Asset(sourceJson)
+    compileV3Asset(asset)
+  } catch (e) {
+    const error = e as V3ContractError & { path?: string }
+    throw new FigureSourceError([
+      { code: error.code ?? 'v3-asset-invalid', message: error.message ?? String(e), at: error.path }
+    ])
+  }
+  const cost = v3CostOf(asset)
+  return {
+    format: 'v3',
+    source: serializeV3Asset(asset),
+    derived: { score: null as unknown as number, triangles: cost.triangles, groups: cost.groups },
+    violations: []
+  }
+}
+
+/**
+ * Whether this source may be published, and why not.
+ *
+ * For V3 the judgement is `inspectV3Asset`: every part inside the volume the asset declares, over the whole
+ * state range, and the face it says it is mounted on lying in that plane. A verdict reached by sampling is
+ * reported as a finding of its own rather than hidden — an author releasing a figure the gate could only
+ * sample should be told so, because nothing proved it holds between the states that were checked.
+ */
+/** The request's translator. Always called with params — `t(key, undefined)` loses the locale. */
+export type Translate = (key: string, options?: Record<string, unknown>) => string
+
+/**
+ * A V3 finding in the words of the release panel.
+ *
+ * The gate says what it measured as a code and values (`part`, `axis`, `mm`, `degrees`) and an English `detail`
+ * for logs. The sentence an author reads is made here, where the request's language is known (ADR-0054) — not in
+ * figure-model, which knows no locale, and not on the screen, which would then have a second account of the same
+ * refusal. The English line is the fallback when a key is missing, so a missing translation reads as English
+ * rather than as the key printed raw.
+ *
+ * The words are the modeller's: 「공간 선언」 for the volume a figure takes up and 「장착면」 for the face it stands on
+ * (`figure.text.mounting-face-explained`). The same register as the V2 blockers since 2026-09-19 — a fact, then
+ * the way out — because at ADR-0087 step 5 these become the only findings an author sees.
+ */
+function v3Wording(violation: V3Violation, say: Say): Pick<GateFinding, 'message' | 'why' | 'how'> {
+  const part = violation.part ?? ''
+  const axis = (violation.axis ?? '').toUpperCase()
+  const mm = violation.mm ?? 0
+  const degrees = violation.degrees ?? 0
+  const key = (field: string) => `figure.gate.${violation.code.toLowerCase().replace(/_/g, '-')}.${field}`
+
+  switch (violation.code) {
+    case 'PART_OUTSIDE_OCCUPANCY':
+      return {
+        message: say(key('message'), { part, axis, mm }, `'${part}' goes ${mm} mm past the declared space on ${axis}.`),
+        why: say(key('why'), {}, 'The declared space sets the scale a figure is placed at. What lies past it is left out of that scale, so on a board this part lands outside the place given to the figure.'),
+        how: say(key('how'), { part, axis, mm }, `Use "fit to parts" to declare the space from the parts again, or move '${part}' ${mm} mm inward on ${axis}.`)
+      }
+    case 'OCCUPANCY_UNDECLARED':
+      return violation.axis
+        ? {
+            message: say(`figure.gate.occupancy-empty-axis.message`, { axis }, `The declared space is empty on ${axis}.`),
+            why: say(key('why'), {}, 'Without a declared space the scale a figure is placed at cannot be set.'),
+            how: say(key('how'), {}, 'Use "fit to parts" to declare the space from the parts as they are now.')
+          }
+        : {
+            message: say(key('message'), {}, 'This figure has not declared the space it takes up.'),
+            why: say(key('why'), {}, 'Without a declared space the scale a figure is placed at cannot be set.'),
+            how: say(key('how'), {}, 'Use "fit to parts" to declare the space from the parts as they are now.')
+          }
+    case 'PARTS_OFF_PLACEMENT_FACE':
+      return {
+        message: say(key('message'), { part, mm }, `The mounting face of '${part}' is ${mm} mm off the plane the figure stands on.`),
+        why: say(key('why'), {}, 'The figure is declared to stand on that face. If the face does not reach the plane, the figure floats on the board by that much, and whatever is placed on it floats too.'),
+        how: say(key('how'), { part, mm }, `Move '${part}' ${mm} mm on Y so the face meets the plane, or choose a different mounting face.`)
+      }
+    case 'PLACEMENT_FACE_TILTED':
+      return {
+        message: say(key('message'), { part, degrees }, `The mounting face of '${part}' is tilted ${degrees}° from the plane the figure stands on.`),
+        why: say(key('why'), {}, 'A tilted face cannot lie on the plane, so how the figure stands is not settled.'),
+        how: say(key('how'), { part }, `Choose a mounting face parallel to the plane, or turn '${part}' upright.`)
+      }
+  }
+}
+
+type Say = (key: string, params: Record<string, string | number>, english: string) => string
+
+function sayerOf(t?: Translate): Say {
+  return (key, params, english) => (t ? t(key, { ...params, defaultValue: english }) : english)
+}
+
+export function inspectAnySource(sourceJson?: string | null, releasedJson?: string | null, t?: Translate): Inspection {
+  if (!sourceJson) return inspectSource(sourceJson, releasedJson)
+
+  let format: FigureFormat
+  try {
+    format = formatOf(sourceJson)
+  } catch (e) {
+    const findings = (e as FigureSourceError).findings ?? [{ code: 'source-unreadable', message: String(e) }]
+    return { blocked: true, findings: findings.map(f => ({ ...f, blocking: true })) }
+  }
+  if (format === 'v2') return inspectSource(sourceJson, releasedJson)
+
+  let inspection
+  try {
+    inspection = inspectV3Asset(parseV3Asset(sourceJson))
+  } catch (e) {
+    const error = e as V3ContractError & { path?: string }
+    return {
+      blocked: true,
+      findings: [{ code: error.code ?? 'v3-asset-invalid', message: error.message ?? String(e), at: error.path, blocking: true }]
+    }
+  }
+
+  const say = sayerOf(t)
+  const findings: GateFinding[] = inspection.violations.map(violation => ({
+    code: violation.code.toLowerCase().replace(/_/g, '-'),
+    ...v3Wording(violation, say),
+    at: violation.part,
+    blocking: true
+  }))
+  if (inspection.coverage.method === 'sampled') {
+    const states = inspection.coverage.states
+    findings.push({
+      code: 'state-range-sampled',
+      message: say('figure.gate.state-range-sampled.message', { states }, `The whole range of motion could not be proven, so ${states} poses were checked.`),
+      why: say('figure.gate.state-range-sampled.why', {}, 'Between the poses that were checked, a part may still go past the declared space.'),
+      how: say('figure.gate.state-range-sampled.how', {}, 'Re-author the motion that could not be proven, and the whole range can be proven.'),
+      /* Which operations stopped the proof — a technical list, so it goes where the panel shows a location. */
+      at: inspection.coverage.unprovable?.join(' · ') || undefined,
+      blocking: false
+    })
+  }
+  /*
+    V2 compares a release with the one before it and names the changes that break placed instances (ADR-0063
+    decision 3). Nothing does that for a V3 asset yet, and a V2→V3 conversion has no V3 release to compare with.
+    The gate says so with the finding V2 uses when it cannot compare, rather than passing in silence — a
+    release that was not checked against the last one is a different fact from one that was and was found safe.
+  */
+  if (releasedJson) {
+    findings.push({
+      code: 'released-unreadable',
+      message: say('figure.gate.v3-released-not-compared.message', {}, 'Not compared with the last release — V3 figures have no comparison between releases yet.'),
+      why: say('figure.gate.v3-released-not-compared.why', {}, 'Whether this release breaks the instances already placed has not been checked.'),
+      blocking: false
+    })
+  }
+  return { blocked: findings.some(finding => finding.blocking), findings }
+}
+
+/**
+ * What a consumer is handed for a released figure.
+ *
+ * V2 hands over a compiled blueprint; V3 hands over the asset itself, because the thing that draws a V3 asset
+ * — `registerFigureV3` in things-scene — takes the asset and compiles it with the kernel. The format travels
+ * with it so the consumer calls the right registration rather than sniffing the payload a second time.
+ */
+export function consumablePayloadOf(sourceJson: string): { format: FigureFormat; blueprint?: unknown; asset?: unknown } {
+  if (formatOf(sourceJson) === 'v2') return { format: 'v2', blueprint: compile(JSON.parse(sourceJson)) }
+  const asset = parseV3Asset(sourceJson)
+  compileV3Asset(asset)
+  return { format: 'v3', asset }
+}

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

@@ -7,11 +7,11 @@ import { Figure } from './figure.js'
 import { FigureHistory } from './figure-history.js'
 import { FigurePatch, FigureSaveResult, NewFigure } from './figure-type.js'
 import { FigureProposal, ProposeRequest } from './figure-propose-type.js'
-import { inspectSource } from './figure-gate.js'
+import { inspectAnySource } from './figure-format.js'
 import { renameDraftType, renameFacts } from './figure-rename.js'
-import { parseSource } from './figure-source.js'
+import { parseAnySource } from './figure-format.js'
 import { ProposeFailure, proposeFigure } from './figure-propose.js'
-import { prepareV3Write, compareAndSwapV3 } from './figure-v3-write.js'
+import { prepareV3Write, compareAndSwapV3, pictureOf } from './figure-v3-write.js'
 
 @Resolver(Figure)
 export class FigureMutation {
@@ -23,14 +23,15 @@ export class FigureMutation {
     @Ctx() context: ResolverContext,
     @Arg('id', { nullable: true }) id?: string,
     @Arg('expectedSource', { nullable: true }) expectedSource?: string,
-    @Arg('creationId', { nullable: true }) creationId?: string
+    @Arg('creationId', { nullable: true }) creationId?: string,
+    @Arg('thumbnail', { nullable: true }) thumbnail?: string
   ): Promise<Figure> {
     const { domain, user, tx } = context.state
     const repository = tx.getRepository(Figure)
     if (!id) {
       if (!creationId || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(creationId))
         throw Error('새 모델 저장에는 생성 요청 식별자가 필요합니다.')
-      const prepared = prepareV3Write(source)
+      const prepared = { ...prepareV3Write(source), ...pictureOf(thumbnail) }
       const previous = await repository.findOne({ where: { id: creationId, domain: { id: domain.id } } })
       if (previous) {
         if (previous.source !== prepared.source) throw Error('이 생성 요청은 이미 다른 내용으로 저장되었습니다. 저장된 모델을 다시 열어 주세요.')
@@ -44,7 +45,7 @@ export class FigureMutation {
     // Exact tenant ownership: an inherited catalog entry is not writable in the child domain.
     const figure = await repository.findOne({ where: { id, domain: { id: domain.id } } })
     if (!figure) throw Error('편집할 Figure를 찾을 수 없습니다.')
-    const prepared = prepareV3Write(source, figure, expectedSource)
+    const prepared = { ...prepareV3Write(source, figure, expectedSource), ...pictureOf(thumbnail, figure) }
     // Compare-and-swap in the UPDATE itself: supported by SQLite as well as PostgreSQL.
     // A pessimistic row lock is not supported by the product's SQLite deployment.
     await compareAndSwapV3(criteria => repository.update(criteria, { ...prepared, updater: user }),
@@ -70,7 +71,7 @@ export class FigureMutation {
     }
 
     // 형식을 어기면 여기서 던진다. 파생값은 서버가 계산한다.
-    const { source, derived, violations } = parseSource(figure.source)
+    const { source, derived, violations } = parseAnySource(figure.source)
 
     const saved = await repository.save({
       ...figure,
@@ -111,7 +112,7 @@ export class FigureMutation {
     let source = figure.source
 
     if (patch.source !== undefined && patch.source !== figure.source) {
-      const parsed = parseSource(patch.source)
+      const parsed = parseAnySource(patch.source)
       source = parsed.source
       derived = parsed.derived
       violations = parsed.violations
@@ -262,7 +263,7 @@ export class FigureMutation {
       .limit(1)
       .getOne()
 
-    const inspection = inspectSource(figure.source, released?.source)
+    const inspection = inspectAnySource(figure.source, released?.source, context.t)
     if (inspection.blocked) {
       const reasons = inspection.findings
         .filter(finding => finding.blocking)
@@ -336,7 +337,7 @@ export class FigureMutation {
     }
 
     /* 형식 검사도 다시 받는다 — 옛 판이 오늘의 형식을 어길 수 있고, 그것을 조용히 들이지 않는다. */
-    const { source, derived, violations } = parseSource(history.source)
+    const { source, derived, violations } = parseAnySource(history.source)
 
     const saved = await repository.save({
       /*

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

@@ -169,7 +169,14 @@ describe('프롬프트는 형식을 따라간다 — 손으로 적은 목록이
     VIOLATION_CODES: '같다',
     RELEASE_BLOCKING_VIOLATIONS: '위반 코드의 부분집합이다 — 어느 것이 발행을 막나는 관문이 알 일이지 저작자가 적는 값이 아니다',
     AXES: "'x'·'y'·'z' 는 축 이름이고 값이 아니다 — 쓰는 자리에서 anchor.<axis> 로 가르친다",
-    SURFACE_KINDS: 'material.surface 는 things-scene 에 소비처가 0건이다 — 그릴 수 없는 것을 시키지 않는다'
+    SURFACE_KINDS: 'material.surface 는 things-scene 에 소비처가 0건이다 — 그릴 수 없는 것을 시키지 않는다',
+    /*
+      V3 커널의 연산자 이름이다. 제안기는 아직 V2 FigureSource 를 쓰므로 저작자가 적는 값이 아니다.
+      제안기가 V3 자산을 쓰게 되는 날 이 세 줄을 지우고 프롬프트가 연산자를 가르쳐야 한다(ADR-0087).
+    */
+    V3_OPERATORS: 'V3 커널 연산자 이름이다 — 제안기가 V2 정본을 쓰는 동안은 저작자가 적는 값이 아니다',
+    V3_NON_AFFINE_OPERATORS: '위 목록의 부분집합이다 — 어느 연산이 다중선형을 안 나르나는 관문이 알 일이다',
+    V3_STATE_NON_AFFINE_OPERATORS: '같다'
   }
 
   it('저작에 쓰이는 열거는 값 하나도 빠짐없이 프롬프트에 있다', () => {

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

@@ -14,7 +14,7 @@ import {
 
 import { Figure } from './figure.js'
 import { FigureHistory } from './figure-history.js'
-import { inspectSource } from './figure-gate.js'
+import { consumablePayloadOf, inspectAnySource } from './figure-format.js'
 import { FigureInspection, FigureList } from './figure-type.js'
 
 @Resolver(Figure)
@@ -132,7 +132,7 @@ export class FigureQuery {
       .limit(1)
       .getOne()
 
-    return inspectSource(figure.source, released?.source)
+    return inspectAnySource(figure.source, released?.source, context.t)
   }
 
   @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
@@ -205,8 +205,15 @@ export class FigureQuery {
     const { figure, source: sourceToCompile, version } = found
 
     try {
-      const parsed = typeof sourceToCompile === 'string' ? JSON.parse(sourceToCompile) : sourceToCompile
-      return compile(parsed)
+      /*
+        A V2 figure hands over its compiled blueprint, as it always did. A V3 asset hands over the asset
+        itself under a `format` tag, because the thing that draws it — `registerFigureV3` — takes the asset
+        and compiles it with the kernel. A V2 blueprint carries no `format`, so a consumer that has not been
+        taught about V3 keeps working and a V3 payload is recognised rather than guessed at (ADR-0087).
+      */
+      const text = typeof sourceToCompile === 'string' ? sourceToCompile : JSON.stringify(sourceToCompile)
+      const payload = consumablePayloadOf(text)
+      return payload.format === 'v3' ? { format: 'v3', type, asset: payload.asset } : payload.blueprint
     } catch (err) {
       console.error(`[figureBlueprint] 타입 '${type}' (figure id: ${figure.id}) 청사진 컴파일 실패:`, err)