@things-factory/figure-service 10.1.109 → 10.1.111

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.109",
+  "version": "10.1.111",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,15 +25,15 @@
     "test:templates": "node --test scripts/templates.test.mts"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.2.8",
+    "@hatiolab/figure-model": "^0.2.10",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.81",
-    "@things-factory/auth-base": "^10.1.107",
+    "@things-factory/auth-base": "^10.1.111",
     "@things-factory/env": "^10.1.20",
     "@things-factory/shell": "^10.1.106",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "4d51757c50d8347e83c96aeba73d770bdde55b73"
+  "gitHead": "f33122c15e5b3e45393129e9418e2c367a273ade"
 }

package/server/service/figure/event-subscriber.ts

@@ -14,7 +14,8 @@ import { FigureHistory } from './figure-history.js'
  *
  * 발행 메모는 Figure 의 칸이 아니다. `releaseFigure` 가 저장할 엔티티에 `__releaseComment` 로 얹어
  * 두면 여기서 판본의 `comment` 로 옮긴다 — 메모는 그 판의 것이지 도형의 것이 아니다. 정본 형식
- * (`__releaseFormat`)과 직전 판에 견준 변경(`__releaseChanges`)도 같은 길로 옮긴다(ADR-0104).
+ * (`__releaseFormat`), 직전 판에 견준 변경(`__releaseChanges`), 발행 때 잰 값(`__releaseMetrics`)과
+ * 윗모습(`__releaseTopView`)도 같은 길로 옮긴다(ADR-0104).
  */
 /** What `releaseFigure` laid on the entity for this release, moved onto the history row. */
 function releaseRecordOnto(history: FigureHistory, entity: Figure): FigureHistory {
@@ -23,6 +24,8 @@ function releaseRecordOnto(history: FigureHistory, entity: Figure): FigureHistor
   history.assetFormat = e.__releaseFormat ?? null
   /* [] stays "[]" (nothing changed); null stays null (not compared). */
   history.changes = e.__releaseChanges == null ? null : JSON.stringify(e.__releaseChanges)
+  history.metrics = e.__releaseMetrics == null ? null : JSON.stringify(e.__releaseMetrics)
+  history.topView = e.__releaseTopView == null ? null : JSON.stringify(e.__releaseTopView)
   return history
 }
 

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

@@ -374,6 +374,44 @@ describe('figureBlueprint 질의 — 소비처(board, twin, things-scene)에 발
     expect(source.slice(0, at)).toContain('@UseMiddleware(SpeakRefusals)')
   })
 
+  /* ADR-0104 decision 2: a consumer that pins a release asks for it by number; every answer carries its number. */
+  describe('a release asked for by number', () => {
+    async function threeReleases(type: string) {
+      const figure = await dataSource!.getRepository(Figure).save({ domain: testDomain, type, name: 'pinned', state: 'draft', source: boxNamed(type, 'unreleased'), version: 3 })
+      for (const version of [1, 2, 3])
+        await dataSource!.getRepository(FigureHistory).save({ domain: testDomain, originalId: figure.id, type, name: `v${version}`, state: 'released', version, source: boxNamed(type, `v${version}`) })
+      return figure
+    }
+
+    it('answers the latest with its number when no number is asked', async () => {
+      await threeReleases('PINNED')
+      const result = await new FigureQuery().figureBlueprint('PINNED', makeContext())
+      expect([result.version, partsOf(result)]).toEqual([3, ['v3']])
+    })
+
+    it('answers an older release by its number, not the latest', async () => {
+      await threeReleases('PINNED')
+      const result = await new FigureQuery().figureBlueprint('PINNED', makeContext(), 1)
+      expect([result.version, partsOf(result)]).toEqual([1, ['v1']])
+    })
+
+    it('refuses a number that was never released by name, never answering another release', async () => {
+      await threeReleases('PINNED')
+      await expect(new FigureQuery().figureBlueprint('PINNED', makeContext(), 7)).rejects.toMatchObject({ code: 'figure-release-not-found' })
+      for (const lang of ['ko', 'en']) expect(require(`../../../translations/${lang}.json`)['error.figure-release-not-found']).toMatch(/\{latest\}/)
+    })
+
+    it('a type nobody released is still null, whatever number is asked', async () => {
+      expect(await new FigureQuery().figureBlueprint('NOBODY', makeContext(), 1)).toBeNull()
+    })
+
+    it('a released row is answered with its own number', async () => {
+      await dataSource!.getRepository(Figure).save({ domain: testDomain, type: 'ROW', name: 'row', state: 'released', source: sampleSource, version: 4 })
+      expect((await new FigureQuery().figureBlueprint('ROW', makeContext())).version).toBe(4)
+      expect((await new FigureQuery().figureBlueprint('ROW', makeContext(), 4)).version).toBe(4)
+    })
+  })
+
   describe('a child domain shadows its parent only with a released version', () => {
     const boxOf = (_type: string, part: string) => box(part)
 

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

@@ -0,0 +1,107 @@
+/**
+ * Retiring a figure and its names by language (ADR-0104 decision 6), on sqlite with the history subscriber on.
+ * A retired figure stays released and is served as before; retiring writes no history row.
+ */
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+const { createFigureAsset, addFigureBox, serializeFigureAsset, applyFigureAuthoring, proposeFigureOccupancy } = require('@hatiolab/figure-model')
+
+let dataSource: DataSource | null = null
+let Figure: any
+let FigureHistory: any
+let Subscriber: any
+let FigureMutation: any
+let assertNames: 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먼저 빌드할 것:\n  yarn workspace @things-factory/figure-service build:server`)
+  return require(resolved)
+}
+
+beforeAll(async () => {
+  Figure = loadCompiled('service/figure/figure').Figure
+  FigureHistory = loadCompiled('service/figure/figure-history').FigureHistory
+  Subscriber = loadCompiled('service/figure/event-subscriber').FigureHistoryEntitySubscriber
+  ;({ FigureMutation, assertNames } = loadCompiled('service/figure/figure-mutation'))
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory],
+    subscribers: [Subscriber],
+    logging: false
+  })
+  await dataSource.initialize()
+})
+
+afterAll(async () => {
+  await dataSource?.destroy()
+  dataSource = null
+})
+
+const releasable = () => {
+  let a = addFigureBox(createFigureAsset('Mixer'), { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'body', face: 'bottom', to: { plane: 'mounting-plane' } })
+  return serializeFigureAsset(applyFigureAuthoring(a, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(a, { over: 'range' }), placement: 'floor' }))
+}
+
+let seq = 0
+async function released(type: string) {
+  const name = `retire-${++seq}`
+  const domain = await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name })
+  const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
+  const figure = await dataSource!.getRepository(Figure).save({ type, name: 'mixer', source: releasable(), state: 'draft', version: 0, domain })
+  await new FigureMutation().releaseFigure(figure.id, 'one', context)
+  return { figure, context, domain }
+}
+const historyCount = (id: string) => dataSource!.getRepository(FigureHistory).count({ where: { originalId: id } })
+
+describe('retiring a figure', () => {
+  it('stays released, writes no history row, and names what to use instead', async () => {
+    const { figure, context, domain } = await released('OLD_MIXER')
+    await dataSource!.getRepository(Figure).save({ type: 'NEW_MIXER', name: 'new', source: releasable(), state: 'draft', version: 0, domain })
+    const retired = await new FigureMutation().setFigureDeprecation(figure.id, true, context, 'NEW_MIXER')
+    expect([retired.deprecated, retired.supersededBy, retired.state, retired.version]).toEqual([true, 'NEW_MIXER', 'released', 1])
+    expect(await historyCount(figure.id)).toBe(1)
+    const back = await new FigureMutation().setFigureDeprecation(figure.id, false, context, 'NEW_MIXER')
+    expect([back.deprecated, back.supersededBy, back.state]).toEqual([false, null, 'released'])
+    expect(await historyCount(figure.id)).toBe(1)
+  })
+
+  it('refuses a replacement that is not there, or itself', async () => {
+    const { figure, context } = await released('LONE_MIXER')
+    await expect(new FigureMutation().setFigureDeprecation(figure.id, true, context, 'NOWHERE')).rejects.toThrow(/NOWHERE/)
+    await expect(new FigureMutation().setFigureDeprecation(figure.id, true, context, 'LONE_MIXER')).rejects.toThrow(/자기 자신/)
+  })
+})
+
+describe('names by language', () => {
+  it('a language code to a name of 1-128 characters', () => {
+    expect(() => assertNames({ en: 'Mixer', 'zh-Hans': '搅拌机' })).not.toThrow()
+    expect(() => assertNames({ English: 'Mixer' })).toThrow(/English/)
+    expect(() => assertNames({ en: '' })).toThrow(/en/)
+    expect(() => assertNames({ en: 'x'.repeat(129) })).toThrow(/en/)
+    expect(() => assertNames(['en'])).toThrow()
+  })
+
+  it('kept on the figure and copied onto the release it goes out with', async () => {
+    const name = `names-${++seq}`
+    const domain = await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name })
+    const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
+    const figure = await dataSource!.getRepository(Figure).save({ type: 'NAMED', name: 'mixer', source: releasable(), state: 'draft', version: 0, domain })
+    await new FigureMutation().updateFigure(figure.id, { names: { en: 'Mixer', ko: '믹서' } }, context)
+    await new FigureMutation().releaseFigure(figure.id, 'one', context)
+    const [row] = await dataSource!.getRepository(FigureHistory).find({ where: { originalId: figure.id } })
+    expect(row.names).toEqual({ en: 'Mixer', ko: '믹서' })
+    await expect(new FigureMutation().updateFigure(figure.id, { names: { English: 'x' } }, context)).rejects.toThrow(/English/)
+  })
+})

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

@@ -330,7 +330,12 @@ describe('figure-format — 판을 알아보는 문', () => {
       return serializeFigureAsset(applyFigureAuthoring(asset, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(asset, { over: 'range' }), placement: 'floor' }))
     }
     it('a first release: its format, and nothing changed', () => {
-      expect(releaseRecordOf(serializeFigureAsset(figureAsset()))).toEqual({ format: 'figure-asset-1', changes: [] })
+      const record = releaseRecordOf(serializeFigureAsset(figureAsset()))
+      expect([record.format, record.changes]).toEqual(['figure-asset-1', []])
+      /* Not sized from the instance: nothing measured across sizes, only where its origin is. Its plan is its one body from above. */
+      expect(record.metrics).toEqual({ origin: { centred: true, off: [] } })
+      expect(record.topView.shapes.map(s => s.id)).toEqual(['body'])
+      expect(record.topView.size).toBeNull()
     })
     it('the same again changes nothing; a wider room is said and does not block', () => {
       const v1 = serializeFigureAsset(figureAsset())
@@ -349,4 +354,17 @@ describe('figure-format — 판을 알아보는 문', () => {
         for (const dict of [KO, EN]) for (const field of ['message', 'why']) expect(dict[`figure.gate.contract.${code}.${field}`]).toBeTruthy()
     })
   })
+
+  /* ADR-0104 decision 4: off the middle of its room is said at release, never refused. */
+  it('an origin off the middle of the room is a warning, and the release goes on', () => {
+    let asset = createFigureAsset('Door')
+    asset = addFigureBox(asset, { id: 'leaf', size: { x: 100, y: 200, z: 40 }, position: { x: 50, y: 100, z: 0 } })
+    asset = applyFigureAuthoring(asset, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(asset), placement: 'floor' })
+    const result = inspectSource(serializeFigureAsset(asset), null, undefined, 'DOOR')
+    const off = result.findings.find(f => f.code === 'origin-off-centre')!
+    expect(off.blocking).toBe(false)
+    expect(off.message).toMatch(/X 50 mm/)
+    expect(result.findings.filter(f => f.blocking).map(f => f.code)).not.toContain('origin-off-centre')
+    expect(inspectSource(serializeFigureAsset(figureAsset()), null, undefined, 'MIXER').findings.map(f => f.code)).not.toContain('origin-off-centre')
+  })
 })

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

@@ -3,8 +3,8 @@
  * board (`consumablePayloadOf`). The format is `figure-asset-1`, and the asset says so in its `version`; a source
  * that does not is refused by name, because a source the server cannot identify is one it must not save.
  */
-import { compileFigureAsset, inspectFigureAsset, isPlaceholderType, parseFigureAsset, serializeFigureAsset, figureContractChanges, figureCostOf, figureScoreOf } from '@hatiolab/figure-model'
-import type { FigureAsset, FigureContractChange, FigureContractError, FigureViolation } from '@hatiolab/figure-model'
+import { compileFigureAsset, inspectFigureAsset, isPlaceholderType, parseFigureAsset, serializeFigureAsset, figureContractChanges, figureCostOf, figureOriginCentredOf, figureReleaseMetricsOf, figureScoreOf, figureTopViewOf } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureContractChange, FigureContractError, FigureReleaseMetrics, FigureTopView, FigureViolation } from '@hatiolab/figure-model'
 
 import type { FigureFinding } from './figure-type.js'
 
@@ -280,6 +280,21 @@ export function inspectSource(
       blocking: false
     })
   }
+  /*
+    Said, never refused (ADR-0104 decision 4): the origin is where the figure is fastened, and a door fastened at its
+    hinge is a right model. A drawing that places figures by the middle of their room reads this before it pins one.
+  */
+  const origin = figureOriginCentredOf(asset!)
+  if (origin && !origin.centred) {
+    const off = origin.off.map(o => `${o.axis.toUpperCase()} ${o.mm} mm`).join(', ')
+    findings.push({
+      code: 'origin-off-centre',
+      message: say('figure.gate.origin-off-centre.message', { off }, `The origin is off the middle of the declared room: ${off}.`),
+      why: say('figure.gate.origin-off-centre.why', {}, 'A drawing that places figures by the middle of their room puts this one that far from where it is drawn.'),
+      how: say('figure.gate.origin-off-centre.how', {}, 'Keep it when the figure is fastened there, as a door at its hinge. Move the origin to the middle to place it by its room.'),
+      blocking: false
+    })
+  }
   if (releasedJson) findings.push(...figureContractFindings(asset!, releasedJson, say))
   return { blocked: findings.some(finding => finding.blocking), findings }
 }
@@ -450,21 +465,25 @@ function figureContractWording(change: FigureContractChange, say: Say): Pick<Gat
 }
 
 /**
- * What a release records about itself (ADR-0104 decision 5): the format its asset is written in, and what changed
- * against the previous release -- the kernel's own comparison, kept as it was then so a consumer that pins releases
+ * What a release records about itself (ADR-0104 decision 5): the format its asset is written in, what it measured
+ * (its cost at its largest, whether resizing is stretching), its plan from above, and what changed against the previous release -- the kernel's own comparison, kept as it was then so a consumer that pins releases
  * reads it rather than computing it again. `[]` for a first release; `null` when the previous release could not be
  * read, which is a different fact from "nothing changed".
  */
-export function releaseRecordOf(sourceJson: string, releasedJson?: string | null): { format: string; changes: FigureContractChange[] | null } {
+export function releaseRecordOf(
+  sourceJson: string,
+  releasedJson?: string | null
+): { format: string; changes: FigureContractChange[] | null; metrics: FigureReleaseMetrics; topView: FigureTopView } {
   const asset = parseFigureAsset(sourceJson)
-  if (!releasedJson) return { format: asset.version, changes: [] }
+  const measured = { format: asset.version, metrics: figureReleaseMetricsOf(asset), topView: figureTopViewOf(asset, null) }
+  if (!releasedJson) return { ...measured, changes: [] }
   let before: FigureAsset
   try {
     before = parseFigureAsset(releasedJson)
   } catch {
-    return { format: asset.version, changes: null }
+    return { ...measured, changes: null }
   }
-  return { format: asset.version, changes: figureContractChanges(before, asset) }
+  return { ...measured, changes: figureContractChanges(before, asset) }
 }
 
 /**

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

@@ -1,4 +1,5 @@
 import { Field, ID, ObjectType, Float, Int } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
 import { Column, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'
 
 import {
@@ -55,6 +56,10 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   @Field({ nullable: true, description: 'The description at this version.' })
   description?: string
 
+  @Column('simple-json', { nullable: true, default: null })
+  @Field(type => GraphQLJSON, { nullable: true, description: 'Display names by language at this version.' })
+  names?: Record<string, string>
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'The classification code at this version.' })
   category?: string
@@ -106,10 +111,25 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   @Field({
     nullable: true,
     description:
-      'What changed against the previous release, as JSON: [{ code, blocking, subject?, values, detail }]. [] for the first release; null when the previous release could not be read.'
+      'What changed against the previous release, as JSON: [{ code, blocking, subject?, values, detail }]. [] for the first release. null when it was not compared: the previous release could not be read, or this release was made before releases recorded it (figure-service 10.1.109).'
   })
   changes?: string
 
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({
+    nullable: true,
+    description:
+      'What this version measured once, as JSON (figure-model figureReleaseMetricsOf): { atLargest?: { size, triangles, groups }, linear?: { scalable, parts, probe } }. Only for a figure that takes its size from the instance; {} otherwise.'
+  })
+  metrics?: string
+
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({
+    nullable: true,
+    description: 'The plan from above at the authored size, as JSON (figure-model figureTopViewOf): { shapes: [{ id, color, outline, holes, top, transparent }], size }.'
+  })
+  topView?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'When the original figure was created.' })
   createdAt?: Date

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

@@ -17,6 +17,15 @@ import { parseSource } from './figure-format.js'
 import { ProposeFigureFailure, proposeFigureSteps } from './figure-propose-steps.js'
 import { prepareFigureWrite, compareAndSwapFigure, pictureOf } from './figure-write.js'
 
+/** Display names by language: a language code to a name of 1-128 characters. Refused whole, with the bad entry named. */
+export function assertNames(names: unknown): asserts names is Record<string, string> {
+  if (!names || typeof names !== 'object' || Array.isArray(names)) throw new Error('names 는 { 언어: 이름 } 이어야 한다')
+  for (const [lang, name] of Object.entries(names)) {
+    if (!/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(lang)) throw new Error(`'${lang}' 는 언어 코드가 아니다`)
+    if (typeof name !== 'string' || !name.trim() || name.length > 128) throw new Error(`'${lang}' 의 이름은 1~128자 글이어야 한다`)
+  }
+}
+
 @Resolver(Figure)
 export class FigureMutation {
   @Directive('@transaction')
@@ -174,6 +183,8 @@ export class FigureMutation {
       행과 정본 둘 다 고친다. 정본 안에도 `type` 이 있어서 한쪽만 고치면 저장된 JSON 과
       행이 다른 이름을 말하고, 발행할 때 어느 쪽이 도면에 적히는지가 갈린다.
     */
+    if (patch.names !== undefined) assertNames(patch.names)
+
     let renamed: string | undefined
     if (patch.type !== undefined && patch.type !== figure.type) {
       const change = await this.renameType(figure, domain, patch.type, source, tx)
@@ -338,7 +349,9 @@ export class FigureMutation {
       /* 판본 구독자가 이것들을 판본의 comment · assetFormat · changes 로 옮긴다. Figure 의 칸이 아니다. */
       __releaseComment: comment ?? null,
       __releaseFormat: record.format,
-      __releaseChanges: record.changes
+      __releaseChanges: record.changes,
+      __releaseMetrics: record.metrics,
+      __releaseTopView: record.topView
     } as any)
   }
 
@@ -408,6 +421,37 @@ export class FigureMutation {
     return true
   }
 
+  /**
+   * 퇴역시키거나 되살린다(ADR-0104 결정 6).
+   *
+   * 표시일 뿐이다. 발행판은 그대로 남고 받는 쪽은 그대로 받는다 — 발행판은 지우지 않는다. 그래서 **발행을 풀지 않는다**:
+   * 행을 엔티티로 저장하지 않고 질의로 고친다. 엔티티로 저장하면 발행된 행이라 판본 구독자가 같은 번호로 판본을 또
+   * 뜬다. 대신 쓸 것(`supersededBy`)은 같은 도메인(또는 상위)에 있는 다른 type 이어야 한다.
+   */
+  @Directive('@transaction')
+  @Directive('@privilege(category: "figure", privilege: "mutation", domainOwnerGranted: true)')
+  @Mutation(returns => Figure, { description: 'Retires a figure or brings it back. It stays released and served; supersededBy names the type to use instead.' })
+  async setFigureDeprecation(
+    @Arg('id') id: string,
+    @Arg('deprecated') deprecated: boolean,
+    @Ctx() context: ResolverContext,
+    @Arg('supersededBy', { nullable: true }) supersededBy?: string
+  ): Promise<Figure> {
+    const { domain, tx } = context.state
+    const repository = tx.getRepository(Figure)
+    const scope = { id: In([domain.id, domain.parentId].filter(Boolean)) }
+    const figure = await repository.findOne({ where: { domain: scope, id } })
+    if (!figure) throw new Error(`Figure ${id} 를 찾을 수 없다`)
+    const instead = deprecated ? supersededBy?.trim() || null : null
+    if (instead) {
+      if (instead === figure.type) throw new Error(`Figure '${figure.type}' 는 자기 자신으로 대신할 수 없다`)
+      const other = await repository.findOne({ where: { domain: scope, type: instead } })
+      if (!other) throw new Error(`대신 쓸 Figure '${instead}' 가 이 도메인에 없다`)
+    }
+    await repository.createQueryBuilder().update(Figure).set({ deprecated, supersededBy: instead }).where('id = :id', { id }).callListeners(false).execute()
+    return await repository.findOneOrFail({ where: { id } })
+  }
+
   /**
    * 저작 보조에게 제안을 시킨다(ADR-0094).
    *

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

@@ -1,5 +1,5 @@
 import { In } from 'typeorm'
-import { Args, Arg, Ctx, Directive, Query, Resolver, UseMiddleware } from 'type-graphql'
+import { Args, Arg, Ctx, Directive, Int, Query, Resolver, UseMiddleware } from 'type-graphql'
 import { GraphQLJSON } from 'graphql-scalars'
 
 import {
@@ -242,11 +242,13 @@ export class FigureQuery {
   @Directive('@privilege(category: "figure-published", privilege: "query", domainOwnerGranted: true)')
   @Query(returns => GraphQLJSON, {
     nullable: true,
-    description: 'A released figure for its consumers (board, twin, things-scene): { type, asset } with the figure asset. Only returns released figures.'
+    description:
+      'A released figure for its consumers (board, twin, things-scene): { type, version, asset }. The latest release, or the one numbered `version` for a consumer that pins releases (ADR-0104). Only returns released figures.'
   })
   async figureBlueprint(
     @Arg('type') type: string,
-    @Ctx() context: ResolverContext
+    @Ctx() context: ResolverContext,
+    @Arg('version', type => Int, { nullable: true, description: 'A release number. Absent: the latest release.' }) pinned?: number
   ): Promise<any> {
     const { domain } = context.state
 
@@ -257,18 +259,32 @@ export class FigureQuery {
       architect ruling, 2026-09-17). This used to skip the fallback as soon as a child row existed and
       return null.
     */
-    const found =
+    const latest =
       (await releasedSourceOf(domain.id, type)) ?? (domain.parentId ? await releasedSourceOf(domain.parentId, type) : null)
 
-    if (!found) {
+    if (!latest) {
       return null
     }
 
+    /*
+      A pinned release is read from the same figure the latest comes from -- the shadowing rule decides whose
+      releases these are, then the number picks one. Releases are never deleted, so a number once handed out is
+      always there; a number that never was is refused by name rather than answered with another release.
+    */
+    const found = pinned === undefined || pinned === null || pinned === latest.version ? latest : await releaseNumbered(latest.figure, pinned)
+    if (!found) {
+      throw new Refusal(
+        'figure-release-not-found',
+        { type, version: pinned, latest: latest.version },
+        '{type} has no release {version}. its latest release is {latest}.'
+      )
+    }
+
     const { figure, source: sourceToCompile, version } = found
 
     try {
       const text = typeof sourceToCompile === 'string' ? sourceToCompile : JSON.stringify(sourceToCompile)
-      return { type, asset: consumablePayloadOf(text).asset }
+      return { type, version, asset: consumablePayloadOf(text).asset }
     } catch (err) {
       console.error(`[figureBlueprint] 타입 '${type}' (figure id: ${figure.id}) 자산 컴파일 실패:`, err)
 
@@ -290,6 +306,14 @@ export class FigureQuery {
   }
 }
 
+/** One numbered release of a figure, or null when it has none by that number. */
+async function releaseNumbered(figure: Figure, version: number): Promise<{ figure: Figure; source: string; version: number } | null> {
+  const row = await getRepository(FigureHistory).findOne({
+    where: { originalId: figure.id, state: 'released', version }
+  })
+  return row?.source ? { figure, source: row.source, version: row.version } : null
+}
+
 /**
  * Finds the released source of a type in one domain, or null.
  *

package/server/service/figure/figure-release-record-db.test.ts

@@ -63,6 +63,8 @@ describe('a release record on its history row', () => {
     expect(row.assetFormat).toBe('figure-asset-1')
     expect(JSON.parse(row.changes)).toEqual(changes)
     expect(row.comment).toBe('first')
+    expect(row.metrics).toBeNull()
+    expect(row.topView).toBeNull()
   })
   it('[] stays nothing changed, null stays not compared', async () => {
     expect((await release({ __releaseFormat: 'figure-asset-1', __releaseChanges: [] })).changes).toBe('[]')
@@ -90,5 +92,8 @@ describe('releaseFigure records it', () => {
     expect(rows[0].changes).toBe('[]')
     const codes = JSON.parse(rows[1].changes).map((c: any) => c.code)
     expect(codes).toContain('occupancy-changed')
+    /* What each release measured, and its plan from above, are on its own row. */
+    expect(JSON.parse(rows[0].metrics)).toEqual({ origin: { centred: true, off: [] } })
+    expect(JSON.parse(rows[1].topView).shapes.map((s: any) => s.id)).toEqual(['body'])
   })
 })

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

@@ -1,5 +1,6 @@
 import { FigureReplacedDraft } from './figure-replaced-draft.js'
 import { Field, InputType, Int, ObjectType } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
 
 import { Figure } from './figure.js'
 
@@ -61,6 +62,10 @@ export class FigurePatch {
   @Field({ nullable: true, description: 'The new description.' })
   description?: string
 
+  /* 언어별 표시 이름. 안 준 것은 그대로, `{}` 는 전부 지운다. */
+  @Field(type => GraphQLJSON, { nullable: true, description: 'Display names by language. {} clears them; omitting the field leaves them.' })
+  names?: Record<string, string>
+
   @Field({ nullable: true, description: 'The new classification code.' })
   category?: string
 

package/server/service/figure/figure.ts

@@ -10,6 +10,7 @@ import {
   UpdateDateColumn
 } from 'typeorm'
 import { Field, Float, ID, Int, ObjectType } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
 
 import { User } from '@things-factory/auth-base'
 import { Domain, longTextColumn } from '@things-factory/shell'
@@ -84,6 +85,26 @@ export class Figure {
   @Field({ nullable: true, description: 'A detailed description for the figure.' })
   description?: string
 
+  /*
+    언어별 표시 이름(ADR-0104 결정 6). 없는 언어는 `name` 을 보인다. 식별자는 여전히 `type` 이다 — 이름은 몇 번을
+    바꿔도 도면이 가리키는 것이 달라지지 않는다.
+  */
+  @Column('simple-json', { nullable: true, default: null })
+  @Field(type => GraphQLJSON, { nullable: true, description: 'Display names by language, e.g. { "en": "...", "ko": "..." }. A language not here shows `name`.' })
+  names?: Record<string, string>
+
+  /*
+    퇴역(ADR-0104 결정 6). 표시일 뿐이다 — 발행판은 지우지 않고 받는 쪽은 그대로 받는다. 무엇으로 대신하라는지는
+    `supersededBy`(그 도메인의 type)가 말한다. 퇴역은 저장이 아니라 `setFigureDeprecation` 이 정하고, 발행을 풀지 않는다.
+  */
+  @Column({ nullable: true, default: false })
+  @Field({ nullable: true, description: 'Retired: still released and still served, but not to be chosen for new work.' })
+  deprecated?: boolean
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The type to use instead of a retired figure.' })
+  supersededBy?: string
+
   /**
    * 분류 하나. **팔레트에서 묶어 보이는 기준이다.**
    *

package/translations/en.json

@@ -74,5 +74,9 @@
   "figure.gate.contract.public-input-range-narrowed.message": "The range of '{input}' narrowed: {before} → {after}.",
   "figure.gate.contract.public-input-range-narrowed.why": "An instance may have set a value outside the new range. Which values are placed is not recorded.",
   "figure.gate.contract.public-input-added.message": "'{input}' can now be set on a board.",
-  "figure.gate.contract.public-input-added.why": "Placed instances that give no value stand at its default."
+  "figure.gate.contract.public-input-added.why": "Placed instances that give no value stand at its default.",
+  "error.figure-release-not-found": "{type} has no release {version}. its latest release is {latest}.",
+  "figure.gate.origin-off-centre.message": "The origin is off the middle of the declared room: {off}.",
+  "figure.gate.origin-off-centre.why": "A drawing that places figures by the middle of their room puts this one that far from where it is drawn.",
+  "figure.gate.origin-off-centre.how": "Keep it when the figure is fastened there, as a door at its hinge. Move the origin to the middle to place it by its room."
 }

package/translations/ko.json

@@ -74,5 +74,9 @@
   "figure.gate.contract.public-input-range-narrowed.message": "'{input}' 값의 범위가 좁아졌습니다: {before} → {after}.",
   "figure.gate.contract.public-input-range-narrowed.why": "새 범위 밖의 값을 준 인스턴스가 있을 수 있습니다. 어떤 값이 놓였는지는 기록하지 않습니다.",
   "figure.gate.contract.public-input-added.message": "'{input}' 값을 이제 보드에서 정할 수 있습니다.",
-  "figure.gate.contract.public-input-added.why": "값을 주지 않은 인스턴스는 기본값으로 섭니다."
+  "figure.gate.contract.public-input-added.why": "값을 주지 않은 인스턴스는 기본값으로 섭니다.",
+  "error.figure-release-not-found": "{type} 에는 {version} 번 발행판이 없습니다. 최신 발행판은 {latest} 번입니다.",
+  "figure.gate.origin-off-centre.message": "원점이 차지 공간 가운데에서 비켜 있습니다: {off}.",
+  "figure.gate.origin-off-centre.why": "공간 가운데로 도형을 놓는 도면에서는 그린 자리에서 그만큼 떨어져 놓입니다.",
+  "figure.gate.origin-off-centre.how": "문의 경첩처럼 붙이는 자리라면 그대로 둡니다. 공간 가운데로 놓이게 하려면 원점을 가운데로 옮깁니다."
 }