@things-factory/figure-service 10.1.37 → 10.1.39

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

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

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

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

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

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 이 그 공백에서 사고를 냈다 —
@@ -51,13 +51,17 @@ function getDeps(): any {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const entity = require('./figure.js')
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const gate = require('./figure-gate.js')
+    const format = require('./figure-format.js')
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const propose = require('./figure-propose.js')
     _deps = {
       getRepository: shell.getRepository,
       Figure: entity.Figure,
-      inspectSource: gate.inspectSource,
+      /*
+        The format-aware door, so an AI asked about a V3 model gets the V3 judgement rather than a V2 parser's
+        complaint. The tool's own contract is unchanged: it reads, it never saves (ADR-0087).
+      */
+      inspectSource: format.inspectAnySource,
       proposeFigure: propose.proposeFigure,
       compile: model.compile,
       costOf: model.costOf,

package/server/service/figure/figure-v3-write.ts

@@ -1,4 +1,4 @@
-import { parseV3Asset, serializeV3Asset, compileV3Asset } from '@hatiolab/figure-model'
+import { parseV3Asset, serializeV3Asset, compileV3Asset, v3CostOf } from '@hatiolab/figure-model'
 
 export interface V3WriteCriteria {
   id: string
@@ -22,14 +22,30 @@ export function prepareV3Write(source: string, existing?: { source?: string }, e
     throw Error('다른 편집에서 모델이 변경되었습니다. 최신 모델을 다시 연 뒤 적용해 주세요.')
   }
   const asset = parseV3Asset(source)
-  const evaluated = compileV3Asset(asset).evaluate()
+  compileV3Asset(asset)
+  /*
+    The same measure `parseAnySource` uses, so the catalogue's budget columns do not depend on which mutation
+    wrote the row. `score` stays null: it measures V2 reuse and nothing has measured V3 (ADR-0087).
+  */
+  const cost = v3CostOf(asset)
   return {
     source: serializeV3Asset(asset),
     name: asset.name,
-    // V2 scores are not V3 evidence. Clear them instead of carrying a previous model's score.
     score: null,
-    triangles: null,
-    groups: evaluated.geometry.length,
+    triangles: cost.triangles,
+    groups: cost.groups,
     state: 'draft' as const
   }
 }
+
+/**
+ * The picture a card shows, when the modeller sent one.
+ *
+ * Absent means the author saved without one — a tab in the background cannot draw, and the source matters more
+ * than the picture, so the save goes on and the modeller fills it in next time. The timestamp moves only when
+ * the picture itself is new, so renaming a figure does not make every card look freshly drawn.
+ */
+export function pictureOf(thumbnail?: string, existing?: { thumbnail?: string }) {
+  if (thumbnail === undefined || thumbnail === existing?.thumbnail) return {}
+  return { thumbnail, thumbnailUpdatedAt: new Date() }
+}

package/translations/en.json

@@ -1,3 +1,25 @@
 {
-  "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."
+  "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}.",
+  "figure.gate.part-outside-occupancy.message": "'{part}' goes {mm} mm past the declared space on {axis}.",
+  "figure.gate.part-outside-occupancy.why": "The declared space sets the scale a figure is placed at. What lies past it is left out of that scale, so on a board this part lands outside the place given to the figure.",
+  "figure.gate.parts-off-placement-face.how": "Move '{part}' {mm} mm on Y so the face meets the plane, or choose a different mounting face.",
+  "figure.gate.parts-off-placement-face.message": "The mounting face of '{part}' is {mm} mm off the plane the figure stands on.",
+  "figure.gate.parts-off-placement-face.why": "The figure is declared to stand on that face. If the face does not reach the plane, the figure floats on the board by that much, and whatever is placed on it floats too.",
+  "figure.gate.placement-face-tilted.how": "Choose a mounting face parallel to the plane, or turn '{part}' upright.",
+  "figure.gate.placement-face-tilted.message": "The mounting face of '{part}' is tilted {degrees}° from the plane the figure stands on.",
+  "figure.gate.placement-face-tilted.why": "A tilted face cannot lie on the plane, so how the figure stands is not settled.",
+  "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

@@ -1,3 +1,25 @@
 {
-  "error.figure-release-does-not-compile": "{type} 의 발행판({version})이 지금 컴파일되지 않습니다. 저작 화면에서 열어 고친 뒤 다시 발행해야 보드에 나옵니다."
+  "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 안으로 옮기세요.",
+  "figure.gate.part-outside-occupancy.message": "'{part}' 부품이 공간 선언을 {axis} 로 {mm}mm 넘습니다.",
+  "figure.gate.part-outside-occupancy.why": "공간 선언이 도면에 놓일 때의 배율을 정합니다. 넘은 만큼은 그 배율에 들어가지 않아서, 도면에서 이 부품이 도형에 주어진 자리 밖으로 나갑니다.",
+  "figure.gate.parts-off-placement-face.how": "'{part}' 을 Y 로 {mm}mm 옮겨 그 면을 평면에 맞추거나, 장착면을 다른 면으로 다시 정하세요.",
+  "figure.gate.parts-off-placement-face.message": "장착면으로 정한 '{part}' 부품의 면이 놓이는 평면에서 {mm}mm 떨어져 있습니다.",
+  "figure.gate.parts-off-placement-face.why": "도형은 그 면으로 놓인다고 선언돼 있습니다. 닿지 않으면 도면에서 그만큼 떠 보이고, 자리에 놓인 물건도 함께 뜹니다.",
+  "figure.gate.placement-face-tilted.how": "평면과 나란한 면을 장착면으로 다시 정하거나, '{part}' 을 바로 세우세요.",
+  "figure.gate.placement-face-tilted.message": "장착면으로 정한 '{part}' 부품의 면이 놓이는 평면에서 {degrees}° 기울어 있습니다.",
+  "figure.gate.placement-face-tilted.why": "기운 면은 평면에 닿을 수 없어서, 도형이 어떤 자세로 놓이는지 정해지지 않습니다.",
+  "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": "이 발행이 이미 놓인 인스턴스를 깨는지는 확인되지 않았습니다."
 }