@things-factory/figure-service 10.1.15 → 10.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.15",
+  "version": "10.1.17",
   "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.17",
+    "@hatiolab/figure-model": "^0.1.18",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.8",
-    "@things-factory/auth-base": "^10.1.7",
+    "@things-factory/auth-base": "^10.1.17",
     "@things-factory/env": "^10.1.3",
-    "@things-factory/shell": "^10.1.7",
+    "@things-factory/shell": "^10.1.16",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "0186eb7ec008781fd9f80b6f59379a91e0908820"
+  "gitHead": "0c8214182702162ceb5398bdcf42ef14ea672394"
 }

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

@@ -175,4 +175,33 @@ describe('figureBlueprint 질의 — 소비처(board, twin, things-scene)를 위
     expect(result.groups[0].members[0].name).toBe('box-1')
     expect(result.groups[0].members[0].transform.size.x).toBe(100)
   })
+
+  /*
+    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
+    whether the declaration is there or not.
+
+    Without a declaration this field is open to callers who have not even signed in
+    (`auth-rebuild.md` §1), so that gap is the thing worth guarding. The check reads the source
+    rather than the compiled output because the declaration is authored there, and it pins the
+    category: `figure` is the authoring permission, and requiring it here would leave board and
+    twin users with an empty palette. Someone who hits that wall will be tempted to delete this
+    line; the failure message is for them.
+  */
+  it('declares figure-published on the consumer door, not the authoring permission', () => {
+    const { readFileSync } = require('fs')
+    const { join } = require('path')
+    const source = readFileSync(join(__dirname, 'figure-query.ts'), 'utf-8')
+
+    const at = source.indexOf('async figureBlueprint')
+    expect(at).toBeGreaterThan(-1)
+
+    const preceding = source.slice(0, at)
+    const directive = preceding.lastIndexOf("@Directive('@privilege(")
+    const declaration = preceding.slice(directive, preceding.indexOf('\n', directive))
+
+    expect(declaration).toContain('category: "figure-published"')
+    expect(declaration).toContain('privilege: "query"')
+    expect(declaration).toContain('domainOwnerGranted: true')
+  })
 })

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

@@ -0,0 +1,72 @@
+/**
+ * AI 로 figure 를 완성하는 길에 막히는 데가 있나 — 끝까지 걸어 본다.
+ *
+ * 개별 단계는 각자 시험이 있다. 없던 것은 **이어 붙였을 때**다. 만드는 데까지 되는데
+ * 발행에서 막히면 저작자는 AI 로 시작해서 손으로 끝내야 하고, 그것은 이 기능이 있으나 마나다.
+ */
+import { createAIClient, setDefaultAIClient } from '@things-factory/ai-client-base'
+import '@things-factory/ai-client-base'
+
+import { proposeFigure } from './figure-propose'
+import { inspectSource } from './figure-gate'
+import { parseSource } from './figure-source'
+
+const PALETTE = ['palette.primary', 'palette.accent', 'palette.neutral']
+const on = process.env.RUN_FIGURE_LLM_SMOKE === '1'
+const describeIf = on ? describe : describe.skip
+
+describeIf('AI 로 만든 figure 가 발행까지 가나', () => {
+  beforeAll(() => {
+    setDefaultAIClient(createAIClient({ provider: 'gemini', apiKey: process.env.GEMINI_API_KEY!, model: 'gemini-3.5-flash' } as any))
+  })
+  afterAll(() => setDefaultAIClient(undefined))
+
+  const walk = async (label: string, prompt: string, type: string) => {
+    const made = await proposeFigure({ prompt, type, palette: PALETTE, refine: true })
+
+    /* 1. 저장 문을 지나는가 — 형식 오류면 여기서 던진다. */
+    const saved = parseSource(JSON.stringify(made.source))
+
+    /* 2. 발행 게이트를 지나는가 — 여기서 막히면 AI 로 시작해 손으로 끝내야 한다. */
+    const gate = inspectSource(saved.source)
+    const blocking = gate.findings.filter(f => f.blocking)
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `[${label}] 부품 ${made.source.parts.length} · 삼각형 ${made.cost.triangles} · 등급 ${made.score.grade}` +
+        ` · 위반 ${made.violations.length} · 발행 ${gate.blocked ? '막힘: ' + blocking.map(f => f.code + '(' + (f.at ?? '') + ')').join(', ') : '통과'}`
+    )
+    return { made, gate, blocking }
+  }
+
+  test('늘려도 안 부서지는 것을 만든다 — 앵커를 가르친 뒤', async () => {
+    const { gate, blocking } = await walk(
+      '신호탑',
+      'a signal tower: a tall slim pole standing on a foot, with three stacked lamps at the very top. the lamps must stay on top of the pole when the tower is made taller.',
+      'SIGNAL_TOWER_E2E'
+    )
+    expect(gate.blocked).toBe(false)
+    expect(blocking).toEqual([])
+  }, 120_000)
+
+  test('반복하는 것을 만든다 — 컨베이어', async () => {
+    const { made, gate } = await walk(
+      '컨베이어',
+      'a roller conveyor: a frame with rollers repeating along its length. when the conveyor is made longer the number of rollers must grow, not their size.',
+      'CONVEYOR_E2E'
+    )
+    expect(gate.blocked).toBe(false)
+    expect(made.source.parts.some((p: any) => p.sizing === 'repeat')).toBe(true)
+  }, 120_000)
+
+  test('움직이는 것을 만든다 — 문', async () => {
+    const { made, gate } = await walk(
+      '자동문',
+      'a двух-panel automatic door in a frame. add an animation clip that opens both panels together by sliding them apart.',
+      'AUTO_DOOR_E2E'
+    )
+    expect(gate.blocked).toBe(false)
+    expect(made.source.animations?.length).toBeGreaterThan(0)
+    expect(made.source.animations![0]!.channels.length).toBeGreaterThan(0)
+  }, 120_000)
+})

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

@@ -30,3 +30,71 @@ describe('release-gate repair candidates', () => {
     expect(split?.fixes?.every(fix => fix.resolved > 0)).toBe(true)
   })
 })
+
+/*
+ * The base box is a promise to whoever places this figure.
+ *
+ * `base` is the number an instance is scaled by (`instanceScale = width/base.x`) and the placement
+ * height comes out of `base.y`. A figure whose box disagrees with its parts renders at the wrong
+ * size and the wrong height the moment it lands on a board, so publishing it breaks that promise
+ * even though the source itself is well formed.
+ *
+ * Saving is still allowed — these are violations, not errors — so a figure already standing on a
+ * board 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. */
+  const sound = {
+    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 } },
+        material: { token: 'palette.primary' }
+      }
+    ]
+  }
+
+  const inspect = (source: unknown) => inspectSource(JSON.stringify(source))
+
+  it('lets a sound figure through', () => {
+    const inspection = inspect(sound)
+    expect(inspection.blocked).toBe(false)
+  })
+
+  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 inspection = inspect(over)
+    const finding = inspection.findings.find(f => f.code === 'part-outside-base')
+
+    expect(finding?.blocking).toBe(true)
+    expect(inspection.blocked).toBe(true)
+  })
+
+  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 inspection = inspect(floating)
+    const finding = inspection.findings.find(f => f.code === 'parts-off-placement-face')
+
+    expect(finding?.blocking).toBe(true)
+    expect(inspection.blocked).toBe(true)
+  })
+
+  it('still only reports the violations that are about taste', () => {
+    /*
+      Slack in the box is a declaration, not a defect — clearance in front of a conveyor, the pitch
+      of a rack bay. A roomy box with an odd segment count is told about and published.
+    */
+    const roomy = {
+      ...sound,
+      base: { x: 3000, y: 200, z: 3000 },
+      parts: [{ ...sound.parts[0], primitive: 'cylinder', segments: 9 }]
+    }
+    const inspection = inspect(roomy)
+
+    expect(inspection.findings.some(f => f.code === 'segments-off-preset')).toBe(true)
+    expect(inspection.blocked).toBe(false)
+  })
+})

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

@@ -1,4 +1,4 @@
-import { compile, sizingReport, validate } from '@hatiolab/figure-model'
+import { blocksRelease, compile, sizingReport, validate } from '@hatiolab/figure-model'
 import type { Axis, FigureSource } from '@hatiolab/figure-model'
 
 /** Service transport shape. It deliberately contains only an explicit, reversible FigureSource edit. */
@@ -26,20 +26,24 @@ export interface GateFix {
  *
  * 판정은 `figure-model` 의 `gate.ts` 가 이미 문서로 정해 두었다. 여기서 새로 정하지 않는다.
  *
- *   sizing-splits   크기를 바꾸면 조각이 갈라진다   **막는다**
- *   sizing-loose    1배에서 이미 여러 조각이다      알린다
- *   violations      형식이 권하지 않는 것          알린다 (저장 때 이미 보여 준 것들)
+ *   sizing-splits              크기를 바꾸면 조각이 갈라진다      **막는다**
+ *   part-outside-base          부품이 기준 상자를 넘는다          **막는다**
+ *   parts-off-placement-face   기준면에 안 닿는다                 **막는다**
+ *   sizing-loose               1배에서 이미 여러 조각이다         알린다
+ *   그 밖의 violations          형식이 권하지 않는 것              알린다 (저장 때 이미 보여 준 것들)
  *
  * 갈라짐을 막는 이유는 사람 눈에 「부서졌다」로 보이기 때문이다 — 시그널타워를 3배로 세우니 램프가
  * 기둥 위 공중에 떴던 그것이고, 앵커 규칙이 생긴 이유다. 소비처가 형상을 늘려 쓰는 것은 막을 수
  * 없으니(그것이 이 형식의 값이다), 늘려도 견디는지를 발행 전에 본다.
  *
- * ## 재 본 값
+ * ## 몇 개가 걸리나는 여기 안 적는다
  *
- * [확인함] 2026-09-09 · 표본 15개(시드 14 + 저작 1)
- *   형식 오류 0 · 1배 분리 0 · **갈라짐 1**(MIXER, z·y-z 조합) · 조용함 14
+ * 한동안 「표본 15개 중 갈라짐 1 · 조용함 14」를 적어 두고 **게이트가 벽이 아니라는 근거**로
+ * 삼았다. 수는 굳고 카탈로그는 움직인다 — 기준 상자 판정이 붙자 그 비율이 하루 만에 뒤집혔다.
+ * 굳은 수를 근거로 든 문장은 그때부터 사실이 아닌 채로 사람을 안심시킨다.
  *
- * 게이트가 벽이 아니라는 뜻이다. 열넷은 그대로 발행되고, 하나는 고칠 것이 있다.
+ * 무엇이 걸리고 얼마나 넘쳤나는 **저작 도구가 재서 보여 준다.** 그것을 볼 사람은 고치는
+ * 사람이고, 그 사람이 보는 자리는 여기가 아니다.
  */
 
 /** 게이트가 낸 한 가지. `blocking` 이 참이면 발행이 안 된다. */
@@ -161,7 +165,12 @@ export function inspectSource(sourceJson?: string | null): Inspection {
   }
 
   for (const violation of result.violations) {
-    findings.push({ code: violation.code, message: violation.message, blocking: false })
+    findings.push({
+      code: violation.code,
+      message: violation.message,
+      /* 어느 위반이 막나는 형식이 안다 — 여기 목록을 또 들면 둘이 갈린다(ADR-0044 결정 ②). */
+      blocking: blocksRelease(violation.code)
+    })
   }
 
   if (result.errors.length === 0) {

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

@@ -10,12 +10,48 @@
  * 모델은 부르지 않는다. 부르면 시험이 느리고 답이 매번 다르다 — 여기서 볼 것은
  * 모델의 솜씨가 아니라 **우리 거름망**이다.
  */
-import { LIMITS, PART_LIMIT, PRIMITIVE_KINDS, SEGMENT_PRESETS } from '@hatiolab/figure-model'
+import {
+  ANCHOR_RULES,
+  DETAIL_LEVELS,
+  CHANNEL_PATHS,
+  CLIP_DRIVES,
+  FIGURE_PLACEMENTS,
+  INTERPOLATIONS,
+  LABEL_WHENS,
+  LIMITS,
+  MATERIAL_SLOTS,
+  PART_LIMIT,
+  PART_ROLES,
+  PRIMITIVE_KINDS,
+  REPEAT_LIMIT,
+  SEGMENT_PRESETS,
+  SIZING_RULES
+} from '@hatiolab/figure-model'
 import { setDefaultAIClient } from '@things-factory/ai-client-base'
 import type { AIClient } from '@things-factory/ai-client-base'
 
+import { readFileSync } from 'fs'
+
+import * as model from '@hatiolab/figure-model'
+
 import { ProposeFailure, inspect, proposeFigure, rulesPrompt } from './figure-propose'
 
+
+/**
+ * 형식이 선언한 칸 이름을 **형식 소스에서** 읽는다.
+ *
+ * 손으로 옮겨 적으면 형식이 자라도 이 파일은 그대로 있고, 그러면 이 시험이 지키려는 것을
+ * 스스로 어긴다. 타입은 런타임에 안 남으므로 선언을 읽는다.
+ */
+function declaredFields(name: string): string[] {
+  const path = require.resolve('@hatiolab/figure-model/package.json')
+  const root = path.replace(/package\.json$/, '')
+  const source = readFileSync(`${root}dist/types.d.ts`, 'utf8')
+  const body = source.match(new RegExp(`interface ${name} \\{([\\s\\S]*?)\\n\\}`))
+  if (!body) throw new Error(`형식에서 ${name} 을 못 찾았다 — 이름이 바뀌었으면 시험도 따라가야 한다`)
+  return [...body[1].matchAll(/^\s{4}([a-zA-Z]+)\??:/gm)].map(m => m[1]!)
+}
+
 const PALETTE = ['palette.primary', 'palette.accent', 'palette.neutral']
 
 /** 온전한 후보. 시험할 곳만 덮어쓴다. */
@@ -94,6 +130,151 @@ describe('규칙을 프롬프트로 옮길 때', () => {
   })
 })
 
+/*
+ * ── Every authorable feature has to reach the model ──────────────────────────
+ *
+ * The prompt is the only place the model learns what a figure may contain. Until 2026-09-16 it
+ * taught `{ type, base, placement, detailLevel, parts }` and one stray line naming the animation
+ * paths, so anchors, repeats, capabilities, labels, lamps, hollows and movement were unreachable:
+ * the model was told there is a limit of two animated parts without ever being told where an
+ * animation goes. What came back was coloured boxes.
+ *
+ * These check per feature rather than per word, because a vocabulary list the model cannot place
+ * in the JSON is worse than no mention at all — it produces confident, invalid output.
+ */
+/*
+ * ── The format is the only vocabulary, and the prompt must follow it ─────────
+ *
+ * Checking feature by feature does not hold: a list of features has to be extended by hand every
+ * time the format grows, which is the failure it is supposed to prevent. Until 2026-09-16 the
+ * prompt taught five fields out of thirteen and a single stray line naming the animation paths,
+ * and nothing failed — because nothing compared the prompt against the format.
+ *
+ * So these walk `@hatiolab/figure-model` itself. Every enum it exports is either something an
+ * author writes into a FigureSource, in which case the model has to be taught all of its values,
+ * or it is not, in which case it is named below with the reason. Adding an enum to the format
+ * forces that decision instead of letting it be forgotten.
+ */
+describe('프롬프트는 형식을 따라간다 — 손으로 적은 목록이 아니라', () => {
+  /*
+    저작자가 FigureSource 에 적는 값이 아닌 열거. 여기 없는 새 열거가 형식에 생기면 아래 시험이
+    깨지고, 가르칠지 말지를 그때 정하게 된다.
+  */
+  const NOT_AUTHORED: Record<string, string> = {
+    ERROR_CODES: '검증 결과다 — 저작자가 적는 값이 아니다',
+    VIOLATION_CODES: '같다',
+    RELEASE_BLOCKING_VIOLATIONS: '위반 코드의 부분집합이다 — 어느 것이 발행을 막나는 관문이 알 일이지 저작자가 적는 값이 아니다',
+    AXES: "'x'·'y'·'z' 는 축 이름이고 값이 아니다 — 쓰는 자리에서 anchor.<axis> 로 가르친다",
+    SURFACE_KINDS: 'material.surface 는 things-scene 에 소비처가 0건이다 — 그릴 수 없는 것을 시키지 않는다'
+  }
+
+  it('저작에 쓰이는 열거는 값 하나도 빠짐없이 프롬프트에 있다', () => {
+    const prompt = rulesPrompt(PALETTE)
+    const missing: string[] = []
+
+    for (const [name, value] of Object.entries(model as Record<string, unknown>)) {
+      if (!Array.isArray(value) || value.some(v => typeof v !== 'string')) continue
+      if (name in NOT_AUTHORED) continue
+      for (const member of value as string[]) {
+        if (!prompt.includes(member)) missing.push(`${name}.${member}`)
+      }
+    }
+
+    expect(missing).toEqual([])
+  })
+
+  it('저작에 안 쓰이는 열거는 이유가 적혀 있다 — 조용히 빠지지 않는다', () => {
+    const enums = Object.entries(model as Record<string, unknown>)
+      .filter(([, v]) => Array.isArray(v) && v.length > 0 && v.every(x => typeof x === 'string'))
+      .map(([k]) => k)
+
+    /* 형식에 열거가 늘면 가르치거나 NOT_AUTHORED 에 이유와 함께 적어야 한다. */
+    const prompt = rulesPrompt(PALETTE)
+    const unclassified = enums.filter(
+      name => !(name in NOT_AUTHORED) && !(model as any)[name].every((m: string) => prompt.includes(m))
+    )
+
+    expect(unclassified).toEqual([])
+  })
+
+  it('한도는 형식의 값을 그대로 인용한다 — 프롬프트에 숫자를 적어 두지 않는다', () => {
+    const prompt = rulesPrompt(PALETTE)
+
+    for (const [key, limit] of Object.entries(LIMITS)) {
+      if (typeof limit !== 'number') continue
+      /* 한도를 안 가르치는 것은 괜찮다. 다른 수를 가르치는 것은 안 된다. */
+      const wrong = new RegExp(`${key}[^\\n]*<=\\s*(?!${limit}\\b)\\d+`, 'i')
+      expect(prompt).not.toMatch(wrong)
+    }
+    expect(prompt).toContain(String(REPEAT_LIMIT))
+    for (const level of DETAIL_LEVELS) expect(prompt).toContain(`${level}=${PART_LIMIT[level]}`)
+  })
+
+  /*
+    가르치지 않는 칸. 열거와 같은 규율이다 — 여기 없는 새 칸이 형식에 생기면 아래가 깨지고,
+    그때 가르칠지 말지를 정하게 된다. 「아직 안 가르쳤다」가 조용히 남지 않는다.
+  */
+  const NOT_TAUGHT: Record<string, Record<string, string>> = {
+    FigureSource: {
+      type: '요청에서 온다 — 모델이 지어내면 거절한다',
+      parts: '모양 첫 줄에 이미 있다',
+      version: '저장할 때 서버가 찍는다',
+      styleKit: '읽는 쪽이 0건이다 — 그릴 수 없는 것을 시키면 무동작 설정이 된다'
+    },
+    FigurePart: {
+      name: '모양 첫 줄에 있다',
+      primitive: '같다',
+      transform: '같다',
+      material: '같다'
+    },
+    PartMaterial: {
+      token: '모양 첫 줄에 있다',
+      preset: '같다',
+      surface: 'things-scene 에 소비처가 0건이다 — 그릴 수 없는 것을 시키지 않는다'
+    }
+  }
+
+  for (const iface of ['FigureSource', 'FigurePart', 'PartMaterial']) {
+    it(`${iface} 의 칸은 가르치거나 이유를 적었거나 둘 중 하나다`, () => {
+      const prompt = rulesPrompt(PALETTE)
+      const silent = declaredFields(iface).filter(
+        field => !(field in NOT_TAUGHT[iface]!) && !prompt.includes(field)
+      )
+
+      expect(silent).toEqual([])
+    })
+
+    it(`${iface} 의 제외 목록에 죽은 이름이 없다`, () => {
+      /* 형식에서 없어진 칸을 제외 목록이 계속 들고 있으면, 그 목록이 형식을 안 따라간 것이다. */
+      const declared = new Set(declaredFields(iface))
+      const stale = Object.keys(NOT_TAUGHT[iface]!).filter(field => !declared.has(field))
+
+      expect(stale).toEqual([])
+    })
+  }
+})
+
+describe('고치라는 요청일 때', () => {
+  it('요청이 안 건드린 것을 그대로 실으라고 못 박는다', async () => {
+    /*
+      이 문장이 없으면 애니메이션이 있는 도형을 「색만 바꿔 줘」로 고쳤을 때 모델이 clip 을
+      안 실어 보내고, 그것이 오류 없이 통과해 조용히 사라진다.
+    */
+    const client = stubClient([candidate()])
+    setDefaultAIClient(client as any)
+    await proposeFigure({ prompt: '색을 바꿔 줘', base: candidate() as any, palette: PALETTE })
+
+    const sent = firstAsk(client)
+    expect(sent).toMatch(/Carry over everything the request did not ask you to change/)
+    expect(sent).toMatch(/dropping one is silent/)
+
+    /* 잃기 쉬운 칸은 이름으로 짚어 준다 — 「전부 지켜라」만으로는 모델이 빠뜨린다. */
+    for (const field of ['animations', 'capabilities', 'anchor', 'repeat', 'label', 'materialSlot']) {
+      expect(sent).toContain(field)
+    }
+  })
+})
+
 describe('후보를 받아 볼 때', () => {
   it('온전하면 통과시킨다', () => {
     const looked = inspect(candidate(), PALETTE)

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

@@ -1,10 +1,18 @@
 import {
+  ANCHOR_RULES,
+  AXES,
   CHANNEL_PATHS,
+  CLIP_DRIVES,
   DETAIL_LEVELS,
+  INTERPOLATIONS,
+  LABEL_WHENS,
   LIMITS,
   MATERIAL_PRESETS,
+  MATERIAL_SLOTS,
   PART_LIMIT,
+  PART_ROLES,
   PRIMITIVE_KINDS,
+  REPEAT_LIMIT,
   SEGMENT_PRESETS,
   SIZING_RULES,
   FIGURE_PLACEMENTS,
@@ -51,9 +59,14 @@ import type { FigureQualityReview } from './figure-quality.js'
   강제 규칙과 취향 규칙을 갈라 적는다.
 
   `validate()` 가 막는 것만 「hard」다. 한때 「부품은 기준 상자 안에 있어야 한다」를
-  강제 규칙으로 적었는데 **그런 규칙이 없다** — `base` 는 경계 상자가 아니라 배치
-  크기가 나오는 비율 기준이고, 밖으로 나가도 오류가 아니다 [확인함]. 없는 규칙을
-  강제라고 적으면 모델이 그것 때문에 좋은 답을 버린다.
+  강제 규칙으로 적었다가, 그런 규칙이 없다는 이유로 취향 쪽으로 내렸다. **지금은 다시
+  강제다** — `part-outside-base` 와 `parts-off-placement-face` 가 생겼고 발행 관문이
+  그 둘을 거절한다(2026-09-16, 아키텍트 판정).
+
+  **검사가 거절하는 것을 지시가 같은 낱말로 말해야 한다.** 갈리면 모델은 거절당하는
+  것을 계속 만들고 사람이 매번 손으로 고친다. 실제로 그 자국이 카탈로그에 남았다 —
+  AI 가 만든 OHT 하나만 원점·상자·단위 셋이 한꺼번에 어긋나 있었는데, 그 표본이 특이한
+  것이 아니라 **여기에 그 말이 없었다.**
 */
 
 /** 몇 번까지 다시 시키나. 이보다 늘려도 대개 같은 자리에서 막힌다. */
@@ -132,11 +145,12 @@ 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: [...] }',
+    '  { type, base: {x,y,z}, placement?, detailLevel, parts: [...], animations?: [...], capabilities?: [...] }',
     '',
     'A part is:',
     '  { name, primitive, transform: { position: {x,y,z}, size: {x,y,z}, rotation?: {x,y,z} },',
-    '    material: {token, preset?}, segments?, shape?, sizing? }',
+    '    material: { token, preset?, flatShading?, transparent?, emissive? },',
+    '    segments?, shape?, materialSlot?, keepRound?, sizing?, anchor?, repeat?, label?, capability? }',
     '',
     'Hard vocabulary — anything outside these is rejected:',
     `  placement   ${FIGURE_PLACEMENTS.join(' | ')} (floor: default, ground equipment; ceiling: overhead hoist/OHT; center: airborne/drone/sensor)`,
@@ -144,10 +158,25 @@ export function rulesPrompt(palette: string[]): string {
     `  segments    ${SEGMENT_PRESETS.join(' | ')} (only for cylinder and sphere)`,
     `  material.token  ${palette.join(' | ')}`,
     `  material.preset ${MATERIAL_PRESETS.join(' | ')}`,
+    `  materialSlot    ${MATERIAL_SLOTS.join(' | ')}`,
     `  sizing      ${SIZING_RULES.join(' | ')}`,
+    `  anchor.<axis>   ${ANCHOR_RULES.join(' | ')}   (axis is one of ${AXES.join(', ')})`,
+    `  repeat.axis     ${AXES.join(' | ')}`,
+    `  capability.roles  ${PART_ROLES.join(' | ')}`,
+    `  label.when      ${LABEL_WHENS.join(' | ')}`,
     `  animation.path  ${CHANNEL_PATHS.join(' | ')}`,
+    `  animation.drive ${CLIP_DRIVES.join(' | ')}`,
+    `  animation.interpolation ${INTERPOLATIONS.join(' | ')}`,
     `  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.',
+    '  base is the number an instance is scaled by, so a part outside it grows wrongly on a board.',
+    '  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.',
+    '  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.',
+    '',
     'Hard limits — exceeding these makes the figure unusable at scale:',
     `  parts        by detailLevel: ${partLimits}`,
     `  material groups (distinct token+preset+slot combinations)  <= ${LIMITS.materialGroups}`,
@@ -159,16 +188,65 @@ export function rulesPrompt(palette: string[]): string {
     '  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.',
     '  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',
     '  of the real thing (body, lid, motor, leg-front-left), never part-1.',
     '',
+    'How a figure reacts to being resized — this is the point of the format:',
+    '  An instance is scaled from the base box, and by default every part scales with it.',
+    '  sizing says what a part does instead:',
+    "    scale    default. grows with the instance",
+    "    fixed    keeps its real size. bolts, lamps, sensors, control boxes",
+    "    stretch  grows along its longest axis only. beams, rails, belts",
+    "    repeat   the part is laid out along one axis at a fixed pitch, and the COUNT grows",
+    '  repeat is { axis, pitch } — pitch is centre-to-centre distance, not the gap between copies.',
+    `  Rollers on a conveyor, shelves in a rack, legs under a table. At most ${REPEAT_LIMIT} copies.`,
+    '  anchor is which face of the base a part holds on to while the rest grows:',
+    `    { x?, y?, z? }, each one of ${ANCHOR_RULES.join(' | ')}. Unset axes hold the nearer face.`,
+    '  Anchors are what keeps a figure whole when it is stretched. A lamp on top of a mast anchors',
+    '  y:"max" so it stays on top; a foot anchors y:"min". Getting this wrong is the single most',
+    '  common reason a figure is rejected at publish — the parts drift apart and it looks broken.',
+    '  keepRound keeps a cylinder or sphere circular under uneven scaling. Default true. Turn it',
+    '  off for small details nobody inspects; leave it on for wheels, rolls and tanks.',
+    '',
+    'Shapes beyond a plain box:',
+    '  rect and polygon are extruded from a 2D outline. shape carries that outline:',
+    '    { path?: [{x,y}, ...], round?, hollow?: { wall, floor? } }',
+    '    path is for polygon and needs at least three points. round softens the corners.',
+    '  hollow scoops the inside out, so a tray, tote, bin, case or frame is ONE part and not a',
+    '  floor with four walls around it. wall is the side thickness; floor is the bottom, and',
+    '  floor 0 leaves both ends open — a duct or a frame rather than a container.',
+    '  transform.size is the outside measurement; the cavity is inside it.',
+    '',
+    'Parts that mean something to the running factory:',
+    '  capability marks a part as a place the simulation uses, rather than only something drawn.',
+    '    { roles: [...], accepts?: [type names], capacity?: n, direction?: {x,y,z} }',
+    "    slot      where a thing sits — a pallet bed, a rack cell, an AGV deck",
+    "    port-in   where flow enters      port-out  where flow leaves",
+    '    A part may hold several roles: an AGV deck is a slot that things also enter and leave.',
+    '    Omit capacity when the part repeats — the count then follows the instance size.',
+    '    direction is the way a port faces, in the part\'s own axes; default is +z.',
+    '  capabilities (top level) is what the whole figure can do, as plain names the scene knows.',
+    '  materialSlot + material.emissive make a status lamp: the token is the OFF look and',
+    '  emissive { token, intensity, on? } is the ON look. A dark lamp is not a red lamp dimmed.',
+    '  label is a place a number is shown on the figure: { name, source, when }. The figure says',
+    '  where it goes; the scene says what the value is.',
+    '',
+    'Movement:',
+    '  animations is on the FigureSource, not inside a part, because one clip moves several parts.',
+    '    [{ name, drive?, channels: [{ target, path, pivot?, interpolation?, keys: [...] }] }]',
+    '    target is a part name. keys are [{ at: seconds, value: {x,y,z} }].',
+    '    At least TWO keys, with `at` strictly increasing — one key is a pose, not motion.',
+    '    translation is an offset, rotation is DEGREES, scale is a multiplier where 1 is full size.',
+    '    pivot is the centre of rotation in the part\'s own axes; without it the part spins on itself.',
+    '    drive loop repeats forever, hold plays once and stays. Clip length is the last key\'s time.',
+    '  Doors that open together belong in one clip with two channels, not two clips.',
+    '',
     'Taste rules — this is what makes it low-poly rather than a pile of boxes:',
     '  Few colours. Reuse one token for the mass and reserve accents for what must stand out.',
     '  Recognisable silhouette from directly above — that is how it is seen on a board.',
     '  Prefer fewer, larger parts. A detail smaller than a twentieth of the base is not visible.',
-    '  Use the coarsest segment count that keeps the silhouette right.',
-    '  Keep parts within the base box unless the real thing overhangs. The base is the reference',
-    '  the instance is scaled from, so a part far outside it grows in a way nobody intended.'
+    '  Use the coarsest segment count that keeps the silhouette right.'
   ].join('\n')
 }
 
@@ -181,6 +259,10 @@ 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',
+      '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-query.ts

@@ -140,9 +140,25 @@ export class FigureQuery {
    * 4. 한 번도 발행된 적 없는 초안 자산이거나 존재하지 않는 타입인 경우 null을 반환하여
    *    미완성 자산이 씬 화면에 유출되는 것을 엄격히 차단한다.
    * 5. 도메인 상속 시 자식 도메인의 타입이 부모 도메인의 동일 타입을 항상 오버라이드한다.
-   * 6. 소비처(board, twin, things-scene) 사용자에게 저작 권한(figure:query)이 없어도
-   *    발행된 청사진을 열람할 수 있도록 도메인 인증 상태에서 열람을 허용한다.
+   * 6. 권한은 저작(`figure`)과 **다른 category** 인 `figure-published` 다. 소비처 사용자에게
+   *    저작 권한을 요구하면 board·twin 의 팔레트가 안 뜨고, 그렇다고 선언을 비우면 이 집에서는
+   *    로그인조차 안 한 사람에게 열린다(`auth-rebuild.md` §1). `<module>-published` 는
+   *    「그 모듈이 발행한 것을 남이 읽는 문」이라는 규약이다 — 아키텍트 판정(2026-09-15).
+   *
+   * ## 열거는 막혀 있다 — 지금은 우연이다
+   *
+   * 이 문의 열쇠는 `type` 하나뿐이라 이름을 모르면 못 꺼낸다. 그런데 그것이 **설계가 아니다** —
+   * 목록을 내는 `figures`·`figureTypeNames` 가 `figure` category 로 잠겨 있어서 결과적으로
+   * 그런 것뿐이다. 나중에 누가 소비처용 목록 문을 하나 더 열고 `figure-published` 를 붙이면
+   * 열거가 함께 열리고, 「이름을 알아야 한다」에 기대고 있던 가정이 조용히 사라진다.
+   * 그 문을 낼 사람이 이 단락을 읽고 그때 정하면 된다.
    */
+  /*
+    This directive is attached by schema assembly, so a test that calls the resolver method
+    directly never exercises it. `figure-blueprint-query.test.ts` reads this source for the
+    declaration instead — see the test named for it there.
+  */
+  @Directive('@privilege(category: "figure-published", privilege: "query", domainOwnerGranted: true)')
   @Query(returns => GraphQLJSON, {
     nullable: true,
     description: 'Compiled FigureBlueprint for external consumers (board, twin, things-scene). Only returns released figures.'