@things-factory/figure-service 10.1.37 → 10.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.37",
+  "version": "10.1.39",
   "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.37",
+    "@things-factory/ai-client-base": "^10.1.39",
+    "@things-factory/auth-base": "^10.1.39",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.37",
+    "@things-factory/shell": "^10.1.39",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "d8a69e5c8803a4b9d3289df0cf38e161a207db61"
+  "gitHead": "fe5257ad8995fe7e79275e287f36e95b5fd32d1c"
 }

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

@@ -0,0 +1,289 @@
+/**
+ * figure-format — 한 문이 두 판을 읽는다.
+ *
+ * 전환 중에는 `source` 칸에 V2 정본과 V3 자산이 섞여 있다(ADR-0087). 저장·발행·되돌리기·소비처가
+ * 저마다 판을 따지면 네 자리에서 답이 갈린다. 여기서 한 번 묻는다.
+ *
+ * 이 파일이 지키는 것:
+ *   - 판은 자산이 적은 `version` 으로 안다. 생김새로 짐작하지 않는다.
+ *   - 판을 모르는 정본은 거절한다 — 알아보지 못하는 것을 저장하면 안 된다.
+ *   - V3 자산도 저장·발행·되돌리기·소비처를 지난다. 이 넷은 전에 V2 만 지날 수 있었다.
+ *   - 예산 칸(`triangles`·`groups`)은 두 판에서 같은 뜻이다.
+ */
+import { createV3Asset, addV3Box, addV3Primitive, serializeV3Asset, applyV3Authoring, proposeV3Occupancy, placeholderType } 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 empty = serializeV3Asset(createV3Asset('Empty'))
+      const finding = inspectAnySource(empty, null, translatorOf(KO)).findings.find(f => f.code === 'occupancy-undeclared')!
+
+      expect(finding.how).toBe('먼저 도형을 추가한 뒤, 「부품에 맞추기」로 공간을 선언하세요.')
+      expect(inspectAnySource(empty).findings.find(f => f.code === 'occupancy-undeclared')!.how).toMatch(/^Add a shape first/)
+    })
+
+    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.')
+    })
+
+    /*
+      V3 자산에는 type 이 없어 V2 의 임시 이름 검사가 돌지 않았고, 새 V3 도형이 `FIGURE_<uuid>` 로 발행됐다
+      (:3300, 2026-09-24). 발행하면 이름이 굳으므로 행의 type 으로 같은 거절을 한다.
+    */
+    it('임시 이름인 V3 도형은 발행을 막는다 — 이름은 행에 있다', () => {
+      /* The name a new V3 figure gets — the format's rule, the one the gate recognises. */
+      const placeholder = placeholderType()
+      const finding = inspectAnySource(v3Source(), null, translatorOf(KO), placeholder).findings.find(f => f.code === 'type-is-placeholder')
+
+      expect(finding?.blocking).toBe(true)
+      expect(finding!.message).toBe(`'${placeholder}' 은 처음 저장할 때 붙은 임시 타입입니다.`)
+      /* 화면의 칸 이름은 「타입」이다(`figure.label.figure-type`). */
+      expect(finding!.how).toContain('타입 칸')
+      expect(inspectAnySource(v3Source(), null, translatorOf(KO), 'ROLLER_CONVEYOR').blocked).toBe(false)
+    })
+
+    /* 코드가 묻는 키가 두 언어에 다 있어야 한다 — 없으면 그 언어의 화면에 영어가 섞인다. */
+    it('판정이 묻는 키는 ko · en 에 다 있다', () => {
+      const asked: string[] = []
+      const t = translatorOf(KO, asked)
+      inspectAnySource(outside(), null, t)
+      inspectAnySource(bare(), null, t)
+      inspectAnySource(v3Source(), v3Source(), t)
+      inspectAnySource(v3Source(), null, t, 'FIGURE_ABCDEF12')
+
+      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,267 @@
+/*
+ * 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, isPlaceholderType, 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. */
+export 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, hasParts: boolean): 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.'),
+            /*
+              A new figure is refused this way before it has a part, and 「fit to parts」 has nothing to measure then —
+              the screen does not offer it. Telling the author to press it sent them looking for a button that was not
+              there (:3300, 2026-09-24).
+            */
+            how: hasParts
+              ? say(key('how'), {}, 'Use "fit to parts" to declare the space from the parts as they are now.')
+              : say(key('how-no-parts'), {}, 'Add a shape first, then use "fit to parts" to declare the space from it.')
+          }
+    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,
+  /** The row's `type` — for V3 the only place the name lives, since the asset carries none. */
+  rowType?: string
+): 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
+  let hasParts = true
+  try {
+    const asset = parseV3Asset(sourceJson)
+    inspection = inspectV3Asset(asset)
+    const cost = v3CostOf(asset)
+    hasParts = cost.groups + cost.hidden > 0
+  } 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, hasParts),
+    at: violation.part,
+    blocking: true
+  }))
+  /*
+    V2 refuses a machine-made name at release (`type-is-placeholder`, from the source's own `type`). A V3 asset has
+    no `type`, so that check never ran and a new V3 figure was published as `FIGURE_<uuid>` — seen on :3300,
+    2026-09-24. Publishing freezes the name (ADR-0063 decision 4) and boards call a figure by it, so the same
+    refusal stands here, read off the row.
+  */
+  if (rowType && isPlaceholderType(rowType)) {
+    findings.push({
+      code: 'type-is-placeholder',
+      message: say('figure.gate.type-is-placeholder.message', { type: rowType }, `'${rowType}' is a temporary type given when the figure was first saved.`),
+      why: say('figure.gate.type-is-placeholder.why', {}, 'Boards call a figure by its type, and it cannot change once the figure is published.'),
+      how: say('figure.gate.type-is-placeholder.how', {}, 'Set the type in the type field, then publish.'),
+      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 }
+}