@things-factory/figure-service 10.1.25 → 10.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.25",
+  "version": "10.1.27",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,13 +25,13 @@
   "dependencies": {
     "@hatiolab/figure-model": "^0.1.21",
     "@operato/typeorm-history": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.25",
-    "@things-factory/auth-base": "^10.1.24",
+    "@things-factory/ai-client-base": "^10.1.26",
+    "@things-factory/auth-base": "^10.1.27",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.20",
+    "@things-factory/shell": "^10.1.27",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "8407b1e9d1f47f6676af144d4a33c8ac01cb49c4"
+  "gitHead": "d04dc762cacf2aac8ba0b0f5d768eca365fc09da"
 }

package/server/service/figure/figure-ai-flow.test.ts

@@ -13,10 +13,10 @@ import { proposeFigure } from './figure-propose'
 
 const DOMAIN = { id: 'domain-mine' }
 const SOURCE = {
-  type: 'MIXER', base: { x: 300, y: 500, z: 300 }, detailLevel: 'M',
+  version: 2, type: 'MIXER', base: { x: 300, y: 500, z: 300 }, detailLevel: 'M',
   parts: [{
     name: 'body', primitive: 'cylinder', segments: 12,
-    transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 300, y: 400, z: 300 } },
+    transform: { position: { x: 0, y: 250, z: 0 }, size: { x: 300, y: 400, z: 300 } },
     material: { token: 'palette.primary' }
   }]
 }

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

@@ -27,14 +27,14 @@ function loadCompiled(modulePath: string): any {
 }
 
 const sampleSource = JSON.stringify({
-  version: 1,
+  version: 2,
   type: 'TEST_BOX',
   base: { x: 100, y: 100, z: 100 },
   parts: [
     {
       name: 'box-1',
       primitive: 'cube',
-      transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 100, y: 100, z: 100 } },
+      transform: { position: { x: 0, y: 50, z: 0 }, size: { x: 100, y: 100, z: 100 } },
       material: { token: 'palette.primary' }
     }
   ]
@@ -134,14 +134,14 @@ describe('figureBlueprint 질의 — 소비처(board, twin, things-scene)를 위
 
     const v1Source = sampleSource
     const v2DraftSource = JSON.stringify({
-      version: 1,
+      version: 2,
       type: 'UPDATING_FIGURE',
       base: { x: 200, y: 200, z: 200 },
       parts: [
         {
           name: 'box-modified',
           primitive: 'cube',
-          transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 200, y: 200, z: 200 } },
+          transform: { position: { x: 0, y: 100, z: 0 }, size: { x: 200, y: 200, z: 200 } },
           material: { token: 'palette.primary' }
         }
       ]
@@ -176,6 +176,45 @@ describe('figureBlueprint 질의 — 소비처(board, twin, things-scene)를 위
     expect(result.groups[0].members[0].transform.size.x).toBe(100)
   })
 
+  describe('a child domain shadows its parent only with a released version', () => {
+    const boxOf = (type: string, part: string) =>
+      JSON.stringify({ ...JSON.parse(sampleSource), type, parts: [{ ...JSON.parse(sampleSource).parts[0], name: part }] })
+
+    async function childOf(parent: any) {
+      const repo = dataSource!.getRepository(shell.Domain)
+      const saved = await repo.save({ name: 'child-domain', subdomain: 'child-domain', parent })
+      return repo.findOne({ where: { id: saved.id } })
+    }
+
+    const contextIn = (domain: any) => ({ state: { domain, user: { id: 'user-1' } } }) as any
+
+    it('falls back to the parent release when the child has only a draft', async () => {
+      const child = await childOf(testDomain)
+      expect(child.parentId).toBe(testDomain.id)
+
+      const repo = dataSource!.getRepository(Figure)
+      await repo.save({ domain: testDomain, type: 'CONVEYOR', name: '표준', state: 'released', source: boxOf('CONVEYOR', 'standard'), version: 1 })
+      await repo.save({ domain: child, type: 'CONVEYOR', name: '테넌트 초안', state: 'draft', source: boxOf('CONVEYOR', 'tenant'), version: 0 })
+
+      const result = await new FigureQuery().figureBlueprint('CONVEYOR', contextIn(child))
+
+      expect(result).not.toBeNull()
+      expect(result.groups[0].members[0].name).toBe('standard')
+    })
+
+    it('uses the child release when the child has one', async () => {
+      const child = await childOf(testDomain)
+
+      const repo = dataSource!.getRepository(Figure)
+      await repo.save({ domain: testDomain, type: 'CONVEYOR', name: '표준', state: 'released', source: boxOf('CONVEYOR', 'standard'), version: 1 })
+      await repo.save({ domain: child, type: 'CONVEYOR', name: '테넌트', state: 'released', source: boxOf('CONVEYOR', 'tenant'), version: 1 })
+
+      const result = await new FigureQuery().figureBlueprint('CONVEYOR', contextIn(child))
+
+      expect(result.groups[0].members[0].name).toBe('tenant')
+    })
+  })
+
   /*
     Every test above calls the resolver method directly, so none of them passes through the
     `@privilege` directive — that is attached when the schema is assembled. They stay green

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

@@ -3,18 +3,19 @@ import { inspectSource } from './figure-gate'
 describe('release-gate repair candidates', () => {
   it('returns data, not parsed prose, for a measured sizing split', () => {
     const source = {
+      version: 2,
       type: 'STACK',
       base: { x: 100, y: 200, z: 100 },
       detailLevel: 'M',
       parts: [
         {
           name: 'foot', primitive: 'cube',
-          transform: { position: { x: 0, y: -50, z: 0 }, size: { x: 100, y: 100, z: 100 } },
+          transform: { position: { x: 0, y: 50, z: 0 }, size: { x: 100, y: 100, z: 100 } },
           material: { token: 'palette.primary' }, anchor: { y: 'min' }
         },
         {
           name: 'lamp', primitive: 'cube',
-          transform: { position: { x: 0, y: 10, z: 0 }, size: { x: 60, y: 20, z: 60 } },
+          transform: { position: { x: 0, y: 110, z: 0 }, size: { x: 60, y: 20, z: 60 } },
           material: { token: 'palette.accent' }, anchor: { y: 'max' }
         }
       ]
@@ -43,15 +44,16 @@ describe('release-gate repair candidates', () => {
  * drawing keeps standing. It just cannot be published again until it is fixed.
  */
 describe('release gate — the base box', () => {
-  /** A figure that sits correctly in its box: 200 tall, foot on the floor at -100. */
+  /** A figure that sits correctly in its box: 200 tall, foot on the floor at 0. */
   const sound = {
+    version: 2,
     type: 'POST',
     base: { x: 100, y: 200, z: 100 },
     detailLevel: 'M',
     parts: [
       {
         name: 'post', primitive: 'cube',
-        transform: { position: { x: 0, y: -50, z: 0 }, size: { x: 100, y: 100, z: 100 } },
+        transform: { position: { x: 0, y: 50, z: 0 }, size: { x: 100, y: 100, z: 100 } },
         material: { token: 'palette.primary' }
       }
     ]
@@ -65,7 +67,7 @@ describe('release gate — the base box', () => {
   })
 
   it('refuses a part that overflows the box', () => {
-    const over = { ...sound, parts: [{ ...sound.parts[0], transform: { position: { x: 0, y: -120, z: 0 }, size: { x: 100, y: 100, z: 100 } } }] }
+    const over = { ...sound, parts: [{ ...sound.parts[0], transform: { position: { x: 0, y: -20, z: 0 }, size: { x: 100, y: 100, z: 100 } } }] }
     const inspection = inspect(over)
     const finding = inspection.findings.find(f => f.code === 'part-outside-base')
 
@@ -74,7 +76,7 @@ describe('release gate — the base box', () => {
   })
 
   it('refuses a figure that does not reach the face its placement names', () => {
-    const floating = { ...sound, parts: [{ ...sound.parts[0], transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 100, y: 100, z: 100 } } }] }
+    const floating = { ...sound, parts: [{ ...sound.parts[0], transform: { position: { x: 0, y: 100, z: 0 }, size: { x: 100, y: 100, z: 100 } } }] }
     const inspection = inspect(floating)
     const finding = inspection.findings.find(f => f.code === 'parts-off-placement-face')
 

package/server/service/figure/figure-llm-smoke.test.ts

@@ -73,10 +73,10 @@ describeIf('Figure 실제 LLM smoke', () => {
         palette: PALETTE,
         refine: true,
         base: {
-          type: 'MIXER_SMOKE', base: { x: 300, y: 400, z: 300 }, detailLevel: 'M',
+          version: 2, type: 'MIXER_SMOKE', base: { x: 300, y: 400, z: 300 }, detailLevel: 'M',
           parts: [
-            { name: 'body', primitive: 'cylinder', segments: 12, transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 280, y: 320, z: 280 } }, material: { token: 'palette.primary' } },
-            { name: 'port', primitive: 'cube', transform: { position: { x: 0, y: 30, z: -155 }, size: { x: 80, y: 60, z: 30 } }, material: { token: 'palette.accent' } }
+            { name: 'body', primitive: 'cylinder', segments: 12, transform: { position: { x: 0, y: 200, z: 0 }, size: { x: 280, y: 320, z: 280 } }, material: { token: 'palette.primary' } },
+            { name: 'port', primitive: 'cube', transform: { position: { x: 0, y: 230, z: -155 }, size: { x: 80, y: 60, z: 30 } }, material: { token: 'palette.accent' } }
           ]
         },
         feedback: [{ outcome: 'discarded', selectedChanges: 0, totalChanges: 2, note: 'the port must read clearly in top view' }]

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

@@ -58,6 +58,7 @@ const PALETTE = ['palette.primary', 'palette.accent', 'palette.neutral']
 /** 온전한 후보. 시험할 곳만 덮어쓴다. */
 function candidate(over: Record<string, unknown> = {}) {
   return {
+    version: 2,
     type: 'MIXER',
     base: { x: 300, y: 500, z: 300 },
     detailLevel: 'M',
@@ -66,7 +67,7 @@ function candidate(over: Record<string, unknown> = {}) {
         name: 'body',
         primitive: 'cylinder',
         segments: 12,
-        transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 300, y: 400, z: 300 } },
+        transform: { position: { x: 0, y: 250, z: 0 }, size: { x: 300, y: 400, z: 300 } },
         material: { token: 'palette.primary' }
       }
     ],
@@ -166,9 +167,7 @@ describe('프롬프트는 형식을 따라간다 — 손으로 적은 목록이
     VIOLATION_CODES: '같다',
     RELEASE_BLOCKING_VIOLATIONS: '위반 코드의 부분집합이다 — 어느 것이 발행을 막나는 관문이 알 일이지 저작자가 적는 값이 아니다',
     AXES: "'x'·'y'·'z' 는 축 이름이고 값이 아니다 — 쓰는 자리에서 anchor.<axis> 로 가르친다",
-    SURFACE_KINDS: 'material.surface 는 things-scene 에 소비처가 0건이다 — 그릴 수 없는 것을 시키지 않는다',
-    CLIP_DRIVES:
-      '없어지는 이름이다 — 값이 만드는 자세가 `parameters` 로 나갔고(ADR-0051 ①) `compile()` 이 옛 원본의 hold 를 옮길 때만 읽는다. 새로 적는 값이 아니다'
+    SURFACE_KINDS: 'material.surface 는 things-scene 에 소비처가 0건이다 — 그릴 수 없는 것을 시키지 않는다'
   }
 
   it('저작에 쓰이는 열거는 값 하나도 빠짐없이 프롬프트에 있다', () => {
@@ -221,7 +220,6 @@ describe('프롬프트는 형식을 따라간다 — 손으로 적은 목록이
     FigureSource: {
       type: '요청에서 온다 — 모델이 지어내면 거절한다',
       parts: '모양 첫 줄에 이미 있다',
-      version: '저장할 때 서버가 찍는다',
       styleKit: '읽는 쪽이 0건이다 — 그릴 수 없는 것을 시키면 무동작 설정이 된다'
     },
     FigurePart: {
@@ -257,6 +255,16 @@ describe('프롬프트는 형식을 따라간다 — 손으로 적은 목록이
   }
 })
 
+describe('joints (ADR-0066)', () => {
+  it('teaches the joint shape with the type vocabulary, and a joint channel with no path and a number per key', () => {
+    const prompt = rulesPrompt(PALETTE)
+    expect(prompt).toContain(`type: ${(model as any).JOINT_TYPES.join(' | ')}`)
+    expect(prompt).toMatch(/NO path, NO pivot/)
+    expect(prompt).toMatch(/limits must include 0/)
+    expect(prompt).toMatch(/ONLY place a parent is written/)
+  })
+})
+
 describe('고치라는 요청일 때', () => {
   it('요청이 안 건드린 것을 그대로 실으라고 못 박는다', async () => {
     /*
@@ -272,7 +280,7 @@ describe('고치라는 요청일 때', () => {
     expect(sent).toMatch(/dropping one is silent/)
 
     /* 잃기 쉬운 칸은 이름으로 짚어 준다 — 「전부 지켜라」만으로는 모델이 빠뜨린다. */
-    for (const field of ['animations', 'capabilities', 'anchor', 'repeat', 'label', 'materialSlot']) {
+    for (const field of ['animations', 'parameters', 'joints', 'capabilities', 'parent', 'anchor', 'repeat', 'label', 'materialSlot']) {
       expect(sent).toContain(field)
     }
   })
@@ -340,14 +348,14 @@ describe('후보를 만들 때', () => {
 
   it('요청하면 측정된 품질 근거를 다음 후보 개선에 돌려준다', async () => {
     const generic = candidate({ parts: [
-      { name: 'part-1', primitive: 'cube', transform: { position: { x: -100, y: 0, z: 0 }, size: { x: 100, y: 100, z: 100 } }, material: { token: 'palette.primary' } },
-      { name: 'part-2', primitive: 'cube', transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 100, y: 100, z: 100 } }, material: { token: 'palette.primary' } },
-      { name: 'part-3', primitive: 'cube', transform: { position: { x: 100, y: 0, z: 0 }, size: { x: 100, y: 100, z: 100 } }, material: { token: 'palette.primary' } },
-      { name: 'part-4', primitive: 'cube', transform: { position: { x: 150, y: 0, z: 0 }, size: { x: 50, y: 100, z: 100 } }, material: { token: 'palette.primary' } }
+      { name: 'part-1', primitive: 'cube', transform: { position: { x: -100, y: 250, z: 0 }, size: { x: 100, y: 100, z: 100 } }, material: { token: 'palette.primary' } },
+      { name: 'part-2', primitive: 'cube', transform: { position: { x: 0, y: 250, z: 0 }, size: { x: 100, y: 100, z: 100 } }, material: { token: 'palette.primary' } },
+      { name: 'part-3', primitive: 'cube', transform: { position: { x: 100, y: 250, z: 0 }, size: { x: 100, y: 100, z: 100 } }, material: { token: 'palette.primary' } },
+      { name: 'part-4', primitive: 'cube', transform: { position: { x: 150, y: 250, z: 0 }, size: { x: 50, y: 100, z: 100 } }, material: { token: 'palette.primary' } }
     ] })
     const refined = candidate({ parts: [{
       name: 'vessel', primitive: 'cylinder', segments: 12,
-      transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 280, y: 400, z: 280 } }, material: { token: 'palette.primary' }
+      transform: { position: { x: 0, y: 250, z: 0 }, size: { x: 280, y: 400, z: 280 } }, material: { token: 'palette.primary' }
     }] })
     const client = stubClient([generic, refined])
     setDefaultAIClient(client)
@@ -544,7 +552,7 @@ describe('정책을 넘은 후보는 막지 않고 알린다', () => {
     const many = Array.from({ length: PART_LIMIT.S + 1 }, (_, at) => ({
       name: `part-${at}`,
       primitive: PRIMITIVE_KINDS[0],
-      transform: { position: { x: at * 10, y: 0, z: 0 }, size: { x: 20, y: 20, z: 20 } },
+      transform: { position: { x: at * 10, y: 250, z: 0 }, size: { x: 20, y: 20, z: 20 } },
       material: { token: PALETTE[0] }
     }))
     setDefaultAIClient(stubClient([candidate({ detailLevel: 'S', parts: many })]))
@@ -649,14 +657,32 @@ describe('값이 만드는 자세를 parameters 로 가르친다', () => {
     expect(text).toMatch(/not 0 to 1/)
   })
 
-  it('파라미터의 at 이 초가 아니라고 말한다', () => {
+  /*
+    Source edition 2 measures y up from the bottom face of the base box (ADR-0065). The prompt taught
+    the box-centre origin before; a model following that would write sources whose parts sit half a
+    box too low and that the release gate refuses.
+  */
+  it('teaches y from the bottom face of the base box and asks for version 2', () => {
+    const text = prompt()
+    expect(text).toMatch(/y is measured UP from its bottom face/)
+    expect(text).toMatch(/floor: the lowest part reaches\s+y = 0; ceiling: the highest reaches y = base\.y/)
+    expect(text).toMatch(/\{ version: 2, type, base/)
+    expect(text).not.toMatch(/-base\.y ?\/ ?2/)
+    expect(text).not.toMatch(/origin \(0,0,0\) is the centre of the base box/)
+  })
+
+  it('tells the model a parameter key sits on the value span', () => {
     /*
-      값 0~1 이 `[0, 마지막 키]` 로 맵되므로 키의 절대값은 자세를 안 바꾼다 — 간격만 바꾼다.
-      그 마지막 값이 전 구간 이동 시간을 겸한다는 것도 함께 적혀 있어야 한다.
+      Keys sit on the 0..1 value span and the format refuses a key above 1 (ADR-0051); the transition
+      time is clip.duration. The prompt once taught that the last at doubles as seconds, which led the
+      model to write keys in seconds and produce sources the format refuses.
     */
     const text = prompt()
-    expect(text).toMatch(/only the SPACING between keys matters/)
-    expect(text).toMatch(/doubles as the seconds a full min-to-max move takes/)
+    expect(text).toMatch(/it is the\s+value span, 0 to 1/)
+    expect(text).toMatch(/An `at` above 1 is refused/)
+    expect(text).toMatch(/clip: \{ duration\?, channels/)
+    expect(text).toMatch(/Leave it\s+out and a new value takes effect at once/)
+    expect(text).not.toMatch(/doubles as the seconds/)
   })
 
   it('두 목록이 이름을 나눠 쓴다고 말한다 — 겹치면 형식이 막는다', () => {

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

@@ -17,6 +17,8 @@ import {
   SEGMENT_PRESETS,
   SIZING_RULES,
   FIGURE_PLACEMENTS,
+  JOINT_TYPES,
+  FIGURE_SOURCE_VERSION,
   compile,
   costOf,
   scoreOf,
@@ -146,13 +148,13 @@ export function rulesPrompt(palette: string[]): string {
     'Answer with a single JSON object and nothing else — no prose, no code fence.',
     '',
     'The JSON is a FigureSource:',
-    '  { type, base: {x,y,z}, placement?, detailLevel, parts: [...],',
-    '    animations?: [...], parameters?: [...], capabilities?: [...] }',
+    `  { version: ${FIGURE_SOURCE_VERSION}, type, base: {x,y,z}, placement?, detailLevel, parts: [...],`,
+    '    animations?: [...], parameters?: [...], capabilities?: [...], joints?: [...] }',
     '',
     'A part is:',
     '  { name, primitive, transform: { position: {x,y,z}, size: {x,y,z}, rotation?: {x,y,z} },',
     '    material: { token, preset?, flatShading?, transparent?, emissive? },',
-    '    segments?, shape?, materialSlot?, keepRound?, sizing?, anchor?, repeat?, label?, capability? }',
+    '    segments?, shape?, materialSlot?, keepRound?, sizing?, anchor?, repeat?, label?, capability?, parent? }',
     '',
     'Hard vocabulary — anything outside these is rejected:',
     `  placement   ${FIGURE_PLACEMENTS.join(' | ')} (floor: default, ground equipment; ceiling: overhead hoist/OHT; center: airborne/drone/sensor)`,
@@ -175,10 +177,11 @@ export function rulesPrompt(palette: string[]): string {
     `  detailLevel ${DETAIL_LEVELS.join(' | ')}`,
     '',
     'Hard rules about the base box — publication is refused when either is broken:',
-    '  Every part must sit inside the base box: |position.<axis>| + size.<axis>/2 <= base.<axis>/2.',
+    '  Every part must sit inside the base box: |position.x| + size.x/2 <= base.x/2 (same for z),',
+    '  and position.y - size.y/2 >= 0 and position.y + size.y/2 <= base.y.',
     '  base is the number an instance is scaled by, so a part outside it grows wrongly once placed.',
     '  The figure must touch the face its placement names — floor: the lowest part reaches',
-    '  y = -base.y/2; ceiling: the highest reaches y = +base.y/2; center: no requirement.',
+    '  y = 0; ceiling: the highest reaches y = base.y; center: no requirement.',
     '  base may be LARGER than the parts. That slack is a declaration (clearance in front of a',
     '  conveyor, the pitch of a rack bay) and is never an error. Only overflow and not reaching are.',
     '',
@@ -191,7 +194,8 @@ export function rulesPrompt(palette: string[]): string {
     'Geometry rules:',
     '  Axes are the usual 3D ones: x right, y UP, z towards the viewer — same as glTF and three.js.',
     '  transform.position is the CENTRE of the part, not a corner.',
-    '  The origin (0,0,0) is the centre of the base box, so the floor is at y = -base.y / 2.',
+    '  x and z are measured from the centre of the base box; y is measured UP from its bottom face.',
+    `  So the floor is y = 0, and a part standing on it has position.y = size.y / 2. Always write version: ${FIGURE_SOURCE_VERSION}.`,
     '  base and transform.size are extents along each axis: size.y is the height.',
     '  Every number is MILLIMETRES. A conveyor is about 2000 long and 800 tall, not 2 and 0.8.',
     '  part names are stored identifiers — lowercase, hyphenated, unique, and descriptive',
@@ -251,12 +255,13 @@ export function rulesPrompt(palette: string[]): string {
     '    A turning roller, a spinning fan, a blinking beacon.',
     '',
     '  parameters  A VALUE MAKES THE POSE. Nothing is played back; the figure simply IS this far.',
-    '    [{ name, label?, default?, range: { unit, min, max }, clip: { channels: [...] } }]',
+    '    [{ name, label?, default?, range: { unit, min, max }, clip: { duration?, channels: [...] } }]',
     '    The instance supplies a PHYSICAL QUANTITY in `range.unit` — 1200 mm, 40 %, 90 deg — and',
-    '    the runtime maps it onto the curve. So `at` on the keys is NOT seconds here: the first key',
-    '    is range.min, the last is range.max, and only the SPACING between keys matters.',
-    '    The last `at` doubles as the seconds a full min-to-max move takes — that is the machine\'s',
-    '    speed. A hoist that takes 2.5s to run its whole travel ends its curve at 2.5.',
+    '    the runtime maps it onto the curve. So `at` on the keys is NOT seconds here: it is the',
+    '    value span, 0 to 1. at 0 is range.min, at 1 is range.max. An `at` above 1 is refused.',
+    '    `clip.duration` is the seconds a full min-to-max move takes — the machine\'s speed. Leave it',
+    '    out and a new value takes effect at once. A hoist that runs its whole travel in 2.5s has',
+    '    keys at 0 and 1 and duration 2.5.',
     '    unit is a free word the screen shows: mm, deg, %, kg. max must be above min.',
     '',
     '  USE parameters WHENEVER THE REQUEST ASKS FOR A VALUE THE INSTANCE IS GIVEN, or asks to',
@@ -270,6 +275,23 @@ export function rulesPrompt(palette: string[]): string {
     '    Do NOT answer it with a capability. Capabilities say what a figure does in the FLOW;',
     '    how a pose is driven is a different axis entirely.',
     '',
+    'Joints — a part that moves RELATIVE TO ANOTHER PART, carrying what is attached to it:',
+    '  An arm whose shoulder turns and carries the elbow, wrist and gripper; a crane whose bridge',
+    '  slides and carries the trolley and hook. Without joints every channel moves one part alone,',
+    '  so two turning links do not compose.',
+    '  parent on a part names the part it is attached to. It is the ONLY place a parent is written.',
+    '    A part without parent hangs from the figure. Following parents must end; no loops.',
+    `  joints: [{ name, child, type: ${JOINT_TYPES.join(' | ')}, origin: {x,y,z}, axis: {x,y,z}, limits?: { min, max } }]`,
+    '    child is the part that moves; its parent is what it moves relative to. One joint per part.',
+    '    origin is the point it turns about or slides from, in the same coordinates as part',
+    '    positions (y from the bottom of the base). axis is the direction: turning follows the',
+    '    right-hand rule. revolute and continuous are in degrees, prismatic in mm.',
+    '    Parts are drawn in the pose where every joint is 0, so limits must include 0.',
+    '    continuous has no limits. Joint names and part names must all be different.',
+    '  A joint moves only through a parameter (or an animation for endless turning): a channel',
+    '    { target: <joint name>, keys: [{ at, value: <number> }] } — NO path, NO pivot, and each',
+    '    value is the joint coordinate, within limits. A 6-axis arm is six joints and six parameters.',
+    '',
     '  Names are shared between the two lists: an instance addresses a curve by name, so an',
     '    animation and a parameter may not be called the same thing.',
     '  Doors that open together belong in one curve with two channels, not two curves.',
@@ -291,8 +313,8 @@ function taskPrompt(input: ProposeInput): string {
       '',
       'Revise this existing figure. Keep the part names that still mean the same thing —',
       'renaming a part breaks bindings on instances already placed.',
-      'Carry over everything the request did not ask you to change. animations, capabilities,',
-      'capability, anchor, repeat, label and materialSlot are easy to drop by writing them out of',
+      'Carry over everything the request did not ask you to change. animations, parameters, joints,',
+      'capabilities, capability, parent, anchor, repeat, label and materialSlot are easy to drop by writing them out of',
       'the JSON, and dropping one is silent — the figure still validates, it just stops doing what',
       'it did. If the request says nothing about movement, the clips come back unchanged.',
       JSON.stringify(input.base)

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

@@ -11,12 +11,12 @@ function review(source: FigureSource) {
 describe('AI candidate quality review', () => {
   it('calls out only explainable, measurable concerns', () => {
     const result = review({
-      type: 'CONVEYOR', base: { x: 600, y: 180, z: 240 }, detailLevel: 'M',
+      version: 2, type: 'CONVEYOR', base: { x: 600, y: 180, z: 240 }, detailLevel: 'M',
       parts: [
-        { name: 'part-1', primitive: 'cube', transform: { position: { x: -180, y: 0, z: 0 }, size: { x: 120, y: 100, z: 180 } }, material: { token: 'palette.a' } },
-        { name: 'box-2', primitive: 'cube', transform: { position: { x: -60, y: 0, z: 0 }, size: { x: 120, y: 100, z: 180 } }, material: { token: 'palette.b' } },
-        { name: 'shape-3', primitive: 'cube', transform: { position: { x: 60, y: 0, z: 0 }, size: { x: 120, y: 100, z: 180 } }, material: { token: 'palette.c' } },
-        { name: 'item-4', primitive: 'cube', transform: { position: { x: 180, y: 0, z: 0 }, size: { x: 120, y: 100, z: 180 } }, material: { token: 'palette.d' } }
+        { name: 'part-1', primitive: 'cube', transform: { position: { x: -180, y: 90, z: 0 }, size: { x: 120, y: 100, z: 180 } }, material: { token: 'palette.a' } },
+        { name: 'box-2', primitive: 'cube', transform: { position: { x: -60, y: 90, z: 0 }, size: { x: 120, y: 100, z: 180 } }, material: { token: 'palette.b' } },
+        { name: 'shape-3', primitive: 'cube', transform: { position: { x: 60, y: 90, z: 0 }, size: { x: 120, y: 100, z: 180 } }, material: { token: 'palette.c' } },
+        { name: 'item-4', primitive: 'cube', transform: { position: { x: 180, y: 90, z: 0 }, size: { x: 120, y: 100, z: 180 } }, material: { token: 'palette.d' } }
       ]
     })
 
@@ -29,10 +29,10 @@ describe('AI candidate quality review', () => {
 
   it('does not pretend that a clear model review is a visual aesthetic score', () => {
     const result = review({
-      type: 'MIXER', base: { x: 300, y: 500, z: 300 }, detailLevel: 'M',
+      version: 2, type: 'MIXER', base: { x: 300, y: 500, z: 300 }, detailLevel: 'M',
       parts: [
-        { name: 'vessel', primitive: 'cylinder', segments: 12, transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 260, y: 420, z: 260 } }, material: { token: 'palette.primary' } },
-        { name: 'lid', primitive: 'cylinder', segments: 8, transform: { position: { x: 0, y: 220, z: 0 }, size: { x: 220, y: 30, z: 220 } }, material: { token: 'palette.primary' } }
+        { name: 'vessel', primitive: 'cylinder', segments: 12, transform: { position: { x: 0, y: 250, z: 0 }, size: { x: 260, y: 420, z: 260 } }, material: { token: 'palette.primary' } },
+        { name: 'lid', primitive: 'cylinder', segments: 8, transform: { position: { x: 0, y: 470, z: 0 }, size: { x: 220, y: 30, z: 220 } }, material: { token: 'palette.primary' } }
       ]
     })
 

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

@@ -169,38 +169,21 @@ export class FigureQuery {
   ): Promise<any> {
     const { domain } = context.state
 
-    // 자식 도메인 자산 우선 탐색 후, 부모 도메인 표준 자산으로 폴백 (오버라이드 보장)
-    let figure = await getRepository(Figure).findOne({
-      where: { domain: { id: domain.id }, type }
-    })
-    if (!figure && domain.parentId) {
-      figure = await getRepository(Figure).findOne({
-        where: { domain: { id: domain.parentId }, type }
-      })
-    }
-
-    if (!figure) {
+    /*
+      A child domain shadows the same type in its parent, which is how a tenant replaces the standard
+      CONVEYOR with its own. Only a released version shadows. When the child has just a draft, the
+      parent's release is used, so starting a draft never makes placed figures disappear (chief
+      architect ruling, 2026-09-17). This used to skip the fallback as soon as a child row existed and
+      return null.
+    */
+    const found =
+      (await releasedSourceOf(domain.id, type)) ?? (domain.parentId ? await releasedSourceOf(domain.parentId, type) : null)
+
+    if (!found) {
       return null
     }
 
-    let sourceToCompile: string | null = null
-
-    if (figure.state === 'released' && figure.source) {
-      sourceToCompile = figure.source
-    } else if (figure.id) {
-      // 저작 중(draft)인 경우 최근 발행 이력(FigureHistory)을 확인한다
-      const latestReleased = await getRepository(FigureHistory).findOne({
-        where: { domain: { id: figure.domain?.id ?? domain.id }, originalId: figure.id, state: 'released' },
-        order: { version: 'DESC' }
-      })
-      if (latestReleased && latestReleased.source) {
-        sourceToCompile = latestReleased.source
-      }
-    }
-
-    if (!sourceToCompile) {
-      return null
-    }
+    const { figure, source: sourceToCompile } = found
 
     try {
       const parsed = typeof sourceToCompile === 'string' ? JSON.parse(sourceToCompile) : sourceToCompile
@@ -211,3 +194,25 @@ export class FigureQuery {
     }
   }
 }
+
+/**
+ * Finds the released source of a type in one domain, or null.
+ *
+ * A released row gives its own source; a draft row gives the source of its latest released history.
+ * A figure that was never released gives null, because drafts never reach consumers.
+ */
+async function releasedSourceOf(domainId: string, type: string): Promise<{ figure: Figure; source: string } | null> {
+  const figure = await getRepository(Figure).findOne({ where: { domain: { id: domainId }, type } })
+  if (!figure) return null
+
+  if (figure.state === 'released' && figure.source) {
+    return { figure, source: figure.source }
+  }
+
+  const latestReleased = await getRepository(FigureHistory).findOne({
+    where: { domain: { id: domainId }, originalId: figure.id, state: 'released' },
+    order: { version: 'DESC' }
+  })
+
+  return latestReleased?.source ? { figure, source: latestReleased.source } : null
+}

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

@@ -21,7 +21,7 @@ function part(over: Record<string, unknown> = {}) {
   return {
     name: 'body',
     primitive: 'cube',
-    transform: { position: { x: 0, y: -350, z: 0 }, size: { x: 100, y: 100, z: 100 } },
+    transform: { position: { x: 0, y: 50, z: 0 }, size: { x: 100, y: 100, z: 100 } },
     material: { token: 'palette.primary' },
     ...over
   }
@@ -30,7 +30,7 @@ function part(over: Record<string, unknown> = {}) {
 /** 온전한 정본 하나. */
 function source(over: Record<string, unknown> = {}) {
   return {
-    version: 1,
+    version: 2,
     type: 'MIXER',
     base: { x: 300, y: 800, z: 300 },
     detailLevel: 'M',
@@ -105,10 +105,18 @@ describe('figure-source — 들어오는 문', () => {
       expect(parseSource(raw).source).toBe(raw)
     })
 
-    it('version이 누락된 구형/외부 정본은 FIGURE_SOURCE_VERSION으로 보정 직렬화한다', () => {
+    /*
+      A source without a version was written before edition 2, with y measured from the box centre.
+      It is refused rather than stamped with the current edition, which would move every part.
+    */
+    it('refuses a source without a version instead of stamping the current edition on it', () => {
       const withoutVersion = json({ type: 'MIXER', base: { x: 300, y: 800, z: 300 }, detailLevel: 'M', parts: [part()] })
-      const parsed = JSON.parse(parseSource(withoutVersion).source)
-      expect(parsed.version).toBe(1)
+      expect(() => parseSource(withoutVersion)).toThrow(FigureSourceError)
+      try {
+        parseSource(withoutVersion)
+      } catch (e) {
+        expect((e as FigureSourceError).findings.map(one => one.code)).toContain('source-version-unsupported')
+      }
     })
   })
 

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

@@ -1,4 +1,4 @@
-import { FIGURE_SOURCE_VERSION, compile, costOf, scoreOf, validate } from '@hatiolab/figure-model'
+import { compile, costOf, scoreOf, validate } from '@hatiolab/figure-model'
 
 import { FigureFinding } from './figure-type.js'
 
@@ -65,13 +65,12 @@ export function parseSource(sourceJson: string): ParsedSource {
     )
   }
 
-  // version이 누락된 구형/외부 입력의 경우 FIGURE_SOURCE_VERSION을 부여하여 스키마를 정규화한다.
-  // 이미 version이 있는 정본은 포맷 훼손을 막기 위해 sourceJson 원본을 그대로 보존한다.
-  let normalizedSource = sourceJson
-  if (parsed && typeof parsed === 'object' && (parsed as any).version === undefined) {
-    (parsed as any).version = FIGURE_SOURCE_VERSION
-    normalizedSource = JSON.stringify(parsed, null, 2)
-  }
+  /*
+    No version is stamped here. validate has already refused a source without one: every source saved
+    without a version was written with y measured from the box centre, and stamping the current
+    edition on it would move every part (ADR-0065).
+  */
+  const normalizedSource = sourceJson
 
   // 여기까지 왔으면 형식은 맞다. 청사진을 만들어 셈에 쓴다.
   // 청사진 자체는 **저장하지 않는다** — 파생 캐시이므로 소비하는 쪽이 다시 만든다.