@things-factory/figure-service 10.1.38 → 10.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.38",
+  "version": "10.1.39",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,13 +25,13 @@
   "dependencies": {
     "@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.38",
+    "@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.38",
+    "@things-factory/shell": "^10.1.39",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "b947349fe1c27d11038b592ceadaba336f14785b"
+  "gitHead": "fe5257ad8995fe7e79275e287f36e95b5fd32d1c"
 }

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

@@ -10,7 +10,7 @@
  *   - V3 자산도 저장·발행·되돌리기·소비처를 지난다. 이 넷은 전에 V2 만 지날 수 있었다.
  *   - 예산 칸(`triangles`·`groups`)은 두 판에서 같은 뜻이다.
  */
-import { createV3Asset, addV3Box, addV3Primitive, serializeV3Asset, applyV3Authoring, proposeV3Occupancy } from '@hatiolab/figure-model'
+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'
@@ -219,6 +219,14 @@ describe('figure-format — 판을 알아보는 문', () => {
       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')!
 
@@ -226,6 +234,22 @@ describe('figure-format — 판을 알아보는 문', () => {
       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[] = []
@@ -233,6 +257,7 @@ describe('figure-format — 판을 알아보는 문', () => {
       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)

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

@@ -20,7 +20,7 @@
  * 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 { 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'
@@ -31,7 +31,7 @@ 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'
+export const V3_ASSET_VERSION = 'figure-v3-asset-1'
 
 /**
  * Which format this source is written in, read from the `version` the asset carries.
@@ -114,7 +114,7 @@ export type Translate = (key: string, options?: Record<string, unknown>) => stri
  * (`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'> {
+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
@@ -138,7 +138,14 @@ function v3Wording(violation: V3Violation, say: Say): Pick<GateFinding, 'message
         : {
             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.')
+            /*
+              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 {
@@ -161,7 +168,13 @@ 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 {
+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
@@ -174,8 +187,12 @@ export function inspectAnySource(sourceJson?: string | null, releasedJson?: stri
   if (format === 'v2') return inspectSource(sourceJson, releasedJson)
 
   let inspection
+  let hasParts = true
   try {
-    inspection = inspectV3Asset(parseV3Asset(sourceJson))
+    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 {
@@ -187,10 +204,25 @@ export function inspectAnySource(sourceJson?: string | null, releasedJson?: stri
   const say = sayerOf(t)
   const findings: GateFinding[] = inspection.violations.map(violation => ({
     code: violation.code.toLowerCase().replace(/_/g, '-'),
-    ...v3Wording(violation, say),
+    ...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({

package/server/service/figure/figure-inspect-db.test.ts

@@ -0,0 +1,130 @@
+/*
+ * The inspect doors, read against a real row.
+ *
+ * `inspectAnySource` is tested on its own in figure-format.test.ts, and that is where the temporary-type refusal was
+ * first pinned. It still did not reach the release panel: `inspectFigure` selected only `id` and `source`, so the row's
+ * `type` arrived as `undefined` and the refusal never ran. The panel enabled 「발행하기」 and the release mutation —
+ * which loads the whole row — refused on the press (2026-09-24). A test of the function could not see that; this
+ * one goes through the resolvers and the database.
+ */
+import type { DataSource } from 'typeorm'
+import {
+  addV3Box,
+  applyV3Authoring,
+  createV3Asset,
+  placeholderType,
+  proposeV3Occupancy,
+  serializeV3Asset
+} from '@hatiolab/figure-model'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+
+let dataSource: DataSource | null = null
+let Figure: any
+let FigureHistory: any
+let FigureQuery: any
+let domain: any
+
+function loadCompiled(modulePath: string): any {
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+  const resolved = join(__dirname, '..', '..', '..', 'dist-server', `${modulePath}.js`)
+  if (!existsSync(resolved)) {
+    throw new Error(`figure-service 산출물이 없다: ${resolved}\n  yarn workspace @things-factory/figure-service build:server`)
+  }
+  return require(resolved)
+}
+
+/** A V3 figure that passes the gate on its own: a box standing on the floor, with its space declared. */
+function sound(): string {
+  let asset = createV3Asset('Probe')
+  asset = addV3Box(asset, { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  asset = applyV3Authoring(asset, { kind: 'declare-occupancy', proposal: proposeV3Occupancy(asset, { over: 'range' }), placement: 'floor' })
+  return serializeV3Asset(asset)
+}
+
+beforeAll(async () => {
+  Figure = loadCompiled('service/figure/figure').Figure
+  FigureHistory = loadCompiled('service/figure/figure-history').FigureHistory
+  FigureQuery = loadCompiled('service/figure/figure-query').FigureQuery
+
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory],
+    logging: false
+  })
+  await dataSource.initialize()
+  shell.addDataSource('default', dataSource)
+  shell.addDataSource('tx', dataSource)
+})
+
+beforeEach(async () => {
+  await dataSource!.synchronize(true)
+  domain = await dataSource!.getRepository(shell.Domain).save({ name: 'inspect', subdomain: 'inspect' })
+})
+
+afterAll(async () => {
+  if (!dataSource) return
+  shell.removeDataSource('default')
+  shell.removeDataSource('tx')
+  await dataSource.destroy()
+  dataSource = null
+})
+
+const context = () => ({ state: { domain, user: { id: 'u' } } }) as any
+const save = (type: string, source = sound()) =>
+  dataSource!.getRepository(Figure).save({ domain, type, name: 'probe', state: 'draft', source, version: 0 })
+
+describe('inspectFigure — the release panel', () => {
+  it('refuses a V3 figure still under its temporary type — the type comes from the row', async () => {
+    const figure = await save(placeholderType())
+
+    const inspection = await new FigureQuery().inspectFigure(figure.id, context())
+
+    expect(inspection.blocked).toBe(true)
+    expect(inspection.findings.map((f: any) => f.code)).toContain('type-is-placeholder')
+  })
+
+  it('lets the same figure through once it is named', async () => {
+    const figure = await save('ROLLER_CONVEYOR')
+
+    expect((await new FigureQuery().inspectFigure(figure.id, context())).blocked).toBe(false)
+  })
+})
+
+describe('inspectFigureDraft — the verdict while editing', () => {
+  it('judges the unsaved source, not the stored one, and still reads the row type', async () => {
+    const figure = await save(placeholderType())
+    let edited = createV3Asset('Probe')
+    edited = addV3Box(edited, { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+
+    const inspection = await new FigureQuery().inspectFigureDraft(serializeV3Asset(edited), context(), figure.id)
+    const codes = inspection.findings.map((f: any) => f.code)
+
+    expect(codes).toContain('occupancy-undeclared')
+    expect(codes).toContain('type-is-placeholder')
+  })
+
+  it('a figure never saved has no row type to refuse', async () => {
+    const inspection = await new FigureQuery().inspectFigureDraft(sound(), context())
+
+    expect(inspection.blocked).toBe(false)
+  })
+
+  it('declares the same permission as inspectFigure', () => {
+    const { readFileSync } = require('fs')
+    const { join } = require('path')
+    const source = readFileSync(join(__dirname, 'figure-query.ts'), 'utf-8')
+    const at = source.indexOf('async inspectFigureDraft')
+    const preceding = source.slice(0, at)
+    const declaration = preceding.slice(preceding.lastIndexOf("@Directive('@privilege("))
+
+    expect(declaration).toContain('category: "figure", privilege: "query"')
+  })
+})

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

@@ -1,6 +1,7 @@
 import { In } from 'typeorm'
 import { Arg, Ctx, Directive, Mutation, Resolver } from 'type-graphql'
 
+import { placeholderType } from '@hatiolab/figure-model'
 import { getRepository } from '@things-factory/shell'
 
 import { Figure } from './figure.js'
@@ -37,8 +38,14 @@ export class FigureMutation {
         if (previous.source !== prepared.source) throw Error('이 생성 요청은 이미 다른 내용으로 저장되었습니다. 저장된 모델을 다시 열어 주세요.')
         return previous
       }
+      /*
+        The temporary name comes from the format's `placeholderType()`, the one rule the release gate and the AI
+        tools use to recognise it. This used to build its own (`FIGURE_<32 hex>`), which `isPlaceholderType` does
+        not match, so a new V3 figure could be published under a machine name that then froze (ADR-0063 decision 4)
+        — seen on :3300, 2026-09-24. A retry is still safe: the row id is the creation id, not the name.
+      */
       // insert, not save: a concurrent retry must never turn into an unchecked overwrite.
-      await repository.insert({ ...prepared, id: creationId, type: `FIGURE_${creationId.replace(/-/g, '').toUpperCase()}`,
+      await repository.insert({ ...prepared, id: creationId, type: placeholderType(),
         domain, creator: user, updater: user })
       return repository.findOneOrFail({ where: { id: creationId, domain: { id: domain.id } } })
     }
@@ -263,7 +270,7 @@ export class FigureMutation {
       .limit(1)
       .getOne()
 
-    const inspection = inspectAnySource(figure.source, released?.source, context.t)
+    const inspection = inspectAnySource(figure.source, released?.source, context.t, figure.type)
     if (inspection.blocked) {
       const reasons = inspection.findings
         .filter(finding => finding.blocking)

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

@@ -114,7 +114,12 @@ export class FigureQuery {
 
     const figure = await getRepository(Figure).findOne({
       where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, id },
-      select: { id: true, source: true }
+      /*
+        `type` is read too. A V3 asset carries no type, so the temporary-type refusal reads the row's; with only
+        id and source selected it saw `undefined`, the panel enabled 「발행하기」, and the release mutation — which
+        loads the whole row — refused on the press (2026-09-24).
+      */
+      select: { id: true, source: true, type: true }
     })
 
     if (!figure) {
@@ -132,7 +137,41 @@ export class FigureQuery {
       .limit(1)
       .getOne()
 
-    return inspectAnySource(figure.source, released?.source, context.t)
+    return inspectAnySource(figure.source, released?.source, context.t, figure.type)
+  }
+
+  /**
+   * The same judgement for a source that has not been saved — what the modeller shows **while** the author edits.
+   *
+   * Without it a V3 author saw nothing until they saved and opened the release panel. The judgement runs here, not
+   * in the browser, because the sentences are made from the request's language (`inspectAnySource` with `context.t`)
+   * and a second copy on the screen would drift from the one the release refuses with. When `id` names a saved
+   * figure, its row type and last release are read as `inspectFigure` does; a figure never saved has neither.
+   */
+  @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => FigureInspection, { description: 'Whether an unsaved figure source would be released, with the reasons.' })
+  async inspectFigureDraft(
+    @Arg('source') source: string,
+    @Ctx() context: ResolverContext,
+    @Arg('id', { nullable: true }) id?: string
+  ): Promise<FigureInspection> {
+    const { domain } = context.state
+    if (!id) return inspectAnySource(source, null, context.t)
+
+    const figure = await getRepository(Figure).findOne({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, id },
+      select: { id: true, type: true }
+    })
+    if (!figure) throw new Error(`Figure ${id} 를 찾을 수 없다`)
+
+    const released = await getRepository(FigureHistory)
+      .createQueryBuilder('history')
+      .where('history.originalId = :id', { id })
+      .orderBy('history.version', 'DESC')
+      .limit(1)
+      .getOne()
+
+    return inspectAnySource(source, released?.source, context.t, figure.type)
   }
 
   @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')

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

@@ -7,6 +7,8 @@
 import { readFileSync } from 'fs'
 import { join } from 'path'
 
+import { createV3Asset, parseV3Asset, serializeV3Asset } from '@hatiolab/figure-model'
+
 import { FigureRenameRefused, renameDraftType } from './figure-rename'
 
 const draft = (over: Record<string, unknown> = {}) => ({
@@ -25,6 +27,19 @@ describe('초안의 type 고치기', () => {
     expect(JSON.parse(result.source).type).toBe('ROBOT_ARM')
   })
 
+  /*
+    V3 자산에는 type 칸이 없고 V3 형식은 모르는 칸을 거절한다. V2 처럼 원본에 이름을 써 넣었더니
+    그 도형을 다시 열 수 없었다(`parseV3Asset` — "unknown type"). V3 는 행만 바뀐다.
+  */
+  it('★ V3 도형은 행만 바뀌고, 원본은 그대로 다시 열린다', () => {
+    const source = serializeV3Asset(createV3Asset('새 Figure'))
+    const result = renameDraftType({ type: 'FIGURE_ABCDEF12', source }, 'ROLLER_CONVEYOR', never)
+
+    expect(result.type).toBe('ROLLER_CONVEYOR')
+    expect(result.source).toBe(source)
+    expect(() => parseV3Asset(result.source)).not.toThrow()
+  })
+
   it('정본의 다른 값은 건드리지 않는다', () => {
     const before = JSON.parse(draft().source)
     const after = JSON.parse(renameDraftType(draft(), 'ROBOT_ARM', never).source)
@@ -91,6 +106,18 @@ describe('문이 이 규칙을 지난다', () => {
     expect(/renamed !== undefined \? \{ type: renamed \}/.test(mutation)).toBe(true)
   })
 
+  /*
+    V3 저장이 임시 이름을 스스로 지었다(`FIGURE_<32 hex>`). 형식의 `isPlaceholderType` 이 그것을 못 알아봐서
+    발행 판정이 기계 이름을 통과시켰다. 짓는 쪽과 알아보는 쪽이 한 규칙이어야 한다.
+  */
+  it('새 V3 도형의 임시 이름은 형식의 규칙으로 짓는다 — 판정이 알아보는 그 규칙', () => {
+    const mutation = readFileSync(join(__dirname, 'figure-mutation.ts'), 'utf8')
+    const save = mutation.slice(mutation.indexOf('async saveFigureV3'), mutation.indexOf('async createFigure'))
+
+    expect(save).toContain('type: placeholderType()')
+    expect(save).not.toMatch(/type: `FIGURE_/)
+  })
+
   it('문이 type 을 받는 칸을 갖는다', () => {
     const type = source('figure-type.ts')
 

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

@@ -19,6 +19,8 @@
  * 그래야 규칙을 DB 없이 시험한다. 문(`figure-mutation.ts`)이 그 셋을 읽어 넘긴다.
  */
 
+import { V3_ASSET_VERSION } from './figure-format.js'
+
 /** 이름을 바꿀 때 알아야 하는 사실. 부르는 쪽이 저장소에서 읽어 온다. */
 export interface RenameFacts {
   /** 발행 판 번호. 0 이면 한 번도 발행되지 않았다. */
@@ -67,9 +69,16 @@ export function renameDraftType(
     throw new FigureRenameRefused('type-taken', `type 「${next}」 는 이 도메인에서 이미 쓰고 있다`)
   }
 
-  const parsed = JSON.parse(current.source) as { type?: string }
-  parsed.type = next
+  const parsed = JSON.parse(current.source) as { type?: string; version?: unknown }
 
+  /*
+    A V3 asset carries no `type`: the name a board uses is the row's alone, and the V3 schema refuses a field it
+    does not know. Writing it in, as V2 needs, left a V3 figure that could no longer be opened — `parseV3Asset`
+    answered "unknown type" (checked 2026-09-24). So only the row changes for V3.
+  */
+  if (parsed.version === V3_ASSET_VERSION) return { type: next, source: current.source }
+
+  parsed.type = next
   return { type: next, source: JSON.stringify(parsed) }
 }
 

package/server/service/figure/figure-tool-doors.test.ts

@@ -1,9 +1,9 @@
 /*
- * figure 도구가 지나는 문 — ADR-0072 결정 2, ADR-0071 결정 2 보탬(2026-09-18).
+ * The doors figure's tools pass — ADR-0072 decision 2, ADR-0071 decision 2 addendum (2026-09-18).
  *
- * 선언만 해 두고 아무도 읽지 않으면 그 선언은 다음 사람이 지우거나 바꿔도 아무 일이 없다. 이제는
- * 읽는 쪽이 생겼다 — 관문이 이 목록으로 도구를 내보낼지 정한다. 그래서 여기서 묻는 것이 둘이다:
- * 도구가 문을 적었는가, 그리고 **그 문이 무엇인가를 지키는가.**
+ * A declaration nobody reads can be deleted or changed by the next person with no effect. Now it has a
+ * reader — the gate decides from this list whether to offer the tool. So this asks two things: did the
+ * tool name its doors, and **does each door guard anything.**
  */
 import { readdirSync, readFileSync } from 'fs'
 import { join } from 'path'
@@ -33,15 +33,15 @@ describe('figure tools — declared doors', () => {
 })
 
 /*
- * 도구가 가리키는 문이 무엇인가를 지키는가 — 관문이 딛고 선 사실.
+ * Does each door the tools point at guard anything — the fact the gate stands on.
  *
- * 2026-09-18 까지 도구 명세가 권한을 베껴 적었고 이 자리가 그 사본을 문과 견줬다. 사본은 없어졌다
- * (ADR-0071 결정 2 보탬) — 관문이 AUTH 의 필드 표에서 문의 선언을 직접 읽는다. 그래서 견줄 두 값도
- * 없다.
+ * Until 2026-09-18 the tool specs copied a privilege and this spot compared the copy with the door.
+ * The copy is gone (ADR-0071 decision 2 addendum) — the gate reads the door's declaration from AUTH's
+ * field table directly, so there are no longer two values to compare.
  *
- * 대신 관문이 **딛고 선 사실**이 남았다: 이 네 도구가 가리키는 문에 지시자가 붙어 있다는 것. 누가
- * `Query.figures` 에서 `@privilege` 를 떼면 그 문은 테넌트 안에서 열리고, 도구도 같이 열린다 —
- * 그 자리가 이제 아무 데서도 안 드러난다. 여기서 문다.
+ * What remains is **the fact the gate stands on**: the doors these four tools point at carry a
+ * directive. Strip `@privilege` from `Query.figures` and that door opens within the tenant, and the
+ * tool opens with it — and nothing else would show it. This catches it.
  */
 describe('figure tools — the doors they reach are guarded', () => {
   beforeEach(() => {
@@ -104,13 +104,13 @@ describe('figure tools — the doors they reach are guarded', () => {
     return found
   }
 
-  it('★ 도구가 가리키는 문마다 그 문을 지키는 지시자가 있다', () => {
+  it('★ every door a tool points at carries the directive that guards it', () => {
     const doors = doorPrivileges()
 
     const unguarded = getAllToolSpecs()
       .flatMap(spec =>
         ((spec as any).doors ?? []).map((door: string) =>
-          doors.has(door) ? undefined : `${spec.name} → ${door}: 그런 문이 없거나 그 문이 권한을 선언하지 않는다`
+          doors.has(door) ? undefined : `${spec.name} → ${door}: no such door, or the door declares no privilege`
         )
       )
       .filter(Boolean)

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

@@ -18,11 +18,11 @@
  * `ai-assistant:mutation` 이 지킨다 — 서로 다른 질문이라 서로 다른 권한이 지킨다. figure 가 board
  * 의 권한을 빌리지 않는다.
  *
- * ── 권한은 적지 않는다. 문에 적힌 것을 관문이 읽는다 ────────────────────────
- * 2026-09-18 까지 도구마다 `privilege: { category: 'figure', ... }` 를 적어 두었다. 문의 지시자와
- * 같은 값이라 그때는 맞았고, 문이 선언을 바꾸는 날 어긋난다 — 어긋나면 느슨한 쪽이 이긴다. 이제
- * 관문이 `doors` 에 적힌 문의 선언을 AUTH 의 표에서 읽어 묻는다(ADR-0071 결정 2 보탬). 여기 남길
- * 것은 **닿는 문**뿐이다.
+ * ── No privilege here. The gate reads what the door declares ─────────────────────
+ * Until 2026-09-18 each tool carried `privilege: { category: 'figure', ... }`. It matched the door's
+ * directive then, and would drift the day the door changed its declaration — and the looser copy wins.
+ * Now the gate reads the declaration of each door in `doors` from AUTH's table (ADR-0071 decision 2,
+ * addendum). What stays here is **the doors it reaches**.
  *
  * ── 규율을 도구와 함께 보낸다 ───────────────────────────────────────────────
  * 도구 목록만으로는 「언제 반드시 불러야 하는지」를 모른다. twin 이 그 공백에서 사고를 냈다 —

package/translations/en.json

@@ -2,6 +2,7 @@
   "error.figure-release-does-not-compile": "the released source of {type} (version {version}) does not compile. open it in the modeller, fix it and release it again before it draws on a board.",
   "figure.gate.occupancy-empty-axis.message": "The declared space is empty on {axis}.",
   "figure.gate.occupancy-undeclared.how": "Use \"fit to parts\" to declare the space from the parts as they are now.",
+  "figure.gate.occupancy-undeclared.how-no-parts": "Add a shape first, then use \"fit to parts\" to declare the space from it.",
   "figure.gate.occupancy-undeclared.message": "This figure has not declared the space it takes up.",
   "figure.gate.occupancy-undeclared.why": "Without a declared space the scale a figure is placed at cannot be set.",
   "figure.gate.part-outside-occupancy.how": "Use \"fit to parts\" to declare the space from the parts again, or move '{part}' {mm} mm inward on {axis}.",
@@ -16,6 +17,9 @@
   "figure.gate.state-range-sampled.how": "Re-author the motion that could not be proven, and the whole range can be proven.",
   "figure.gate.state-range-sampled.message": "The whole range of motion could not be proven, so {states} poses were checked.",
   "figure.gate.state-range-sampled.why": "Between the poses that were checked, a part may still go past the declared space.",
+  "figure.gate.type-is-placeholder.how": "Set the type in the type field, then publish.",
+  "figure.gate.type-is-placeholder.message": "'{type}' is a temporary type given when the figure was first saved.",
+  "figure.gate.type-is-placeholder.why": "Boards call a figure by its type, and it cannot change once the figure is published.",
   "figure.gate.v3-released-not-compared.message": "Not compared with the last release. V3 figures have no comparison between releases yet.",
   "figure.gate.v3-released-not-compared.why": "Whether this release breaks the instances already placed has not been checked."
 }

package/translations/ko.json

@@ -2,6 +2,7 @@
   "error.figure-release-does-not-compile": "{type} 의 발행판({version})이 지금 컴파일되지 않습니다. 저작 화면에서 열어 고친 뒤 다시 발행해야 보드에 나옵니다.",
   "figure.gate.occupancy-empty-axis.message": "공간 선언의 {axis} 가 비어 있습니다.",
   "figure.gate.occupancy-undeclared.how": "「부품에 맞추기」를 누르면 지금 부품으로 공간을 선언합니다.",
+  "figure.gate.occupancy-undeclared.how-no-parts": "먼저 도형을 추가한 뒤, 「부품에 맞추기」로 공간을 선언하세요.",
   "figure.gate.occupancy-undeclared.message": "이 도형은 차지하는 공간을 아직 선언하지 않았습니다.",
   "figure.gate.occupancy-undeclared.why": "공간 선언이 없으면 도면에 놓일 때의 배율을 정할 수 없습니다.",
   "figure.gate.part-outside-occupancy.how": "「부품에 맞추기」로 공간을 부품에서 다시 선언하거나, '{part}' 을 {axis} 로 {mm}mm 안으로 옮기세요.",
@@ -16,6 +17,9 @@
   "figure.gate.state-range-sampled.how": "증명하지 못한 움직임을 다시 저작하면 범위 전체를 증명할 수 있습니다.",
   "figure.gate.state-range-sampled.message": "움직이는 범위 전체를 증명하지 못해 자세 {states}개만 검사했습니다.",
   "figure.gate.state-range-sampled.why": "검사한 자세 사이에서 부품이 공간 선언을 넘을 수 있습니다.",
+  "figure.gate.type-is-placeholder.how": "타입 칸에서 타입을 정한 뒤 발행하세요.",
+  "figure.gate.type-is-placeholder.message": "'{type}' 은 처음 저장할 때 붙은 임시 타입입니다.",
+  "figure.gate.type-is-placeholder.why": "보드는 이 타입으로 도형을 부르고, 발행한 뒤에는 바꿀 수 없습니다.",
   "figure.gate.v3-released-not-compared.message": "직전 발행판과 견주지 못했습니다. V3 도형은 발행 사이의 비교가 아직 없습니다.",
   "figure.gate.v3-released-not-compared.why": "이 발행이 이미 놓인 인스턴스를 깨는지는 확인되지 않았습니다."
 }