@things-factory/figure-service 10.1.117 → 10.1.122

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

@@ -0,0 +1,59 @@
+import { EntityManager, Not } from 'typeorm'
+
+import { isFigureNamespace } from '@hatiolab/figure-model'
+import { Domain, Refusal } from '@things-factory/shell'
+import { Setting } from '@things-factory/setting-base'
+
+import { Figure } from './figure.js'
+
+/** The domain setting that names the namespace this domain's figures are published under (ADR-0114). */
+export const FIGURE_NAMESPACE_SETTING = 'figure-namespace'
+
+/**
+ * The namespace a new figure is created under.
+ *
+ * It is read from the domain setting and copied onto the figure, so the full name `{namespace}/{type}` a board stores
+ * never moves. The setting is set once: a value that differs from the namespace this domain's figures already carry
+ * is refused, so editing it on the settings screen cannot rename anything.
+ */
+export async function namespaceForNewFigure(tx: EntityManager, domain: Domain): Promise<string> {
+  const setting = await tx.getRepository(Setting).findOne({
+    where: { domain: { id: domain.id }, name: FIGURE_NAMESPACE_SETTING }
+  })
+  const namespace = setting?.value?.trim() ?? ''
+  if (!isFigureNamespace(namespace)) {
+    throw new Refusal(
+      'figure-namespace-missing',
+      { setting: FIGURE_NAMESPACE_SETTING, value: namespace },
+      'this domain has no valid figure namespace. set {setting} first, for example hatiolab.com.'
+    )
+  }
+  await assertNamespaceUnchanged(tx, domain, namespace)
+  return namespace
+}
+
+/** Refuses when the domain's figures already carry another namespace than the setting now says. */
+export async function assertNamespaceUnchanged(tx: EntityManager, domain: Domain, namespace: string): Promise<void> {
+  const other = await tx.getRepository(Figure).findOne({
+    where: { domain: { id: domain.id }, namespace: Not(namespace) }
+  })
+  if (other?.namespace) {
+    throw new Refusal(
+      'figure-namespace-changed',
+      { setting: FIGURE_NAMESPACE_SETTING, value: namespace, namespace: other.namespace },
+      'the figure namespace of this domain is {namespace} and cannot change. set {setting} back to {namespace}.'
+    )
+  }
+}
+
+/** The namespace a figure already carries, refused when it has none (a figure made before namespaces). */
+export function namespaceOf(figure: Figure): string {
+  if (!figure.namespace) {
+    throw new Refusal(
+      'figure-namespace-missing',
+      { setting: FIGURE_NAMESPACE_SETTING, value: '' },
+      'this figure has no namespace. run the figure name migration first.'
+    )
+  }
+  return figure.namespace
+}

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

@@ -0,0 +1,116 @@
+import JSZip from 'jszip'
+import { In } from 'typeorm'
+
+import {
+  formatFigureRef,
+  parseFigureRef,
+  writeFigurePackage,
+  type FigurePackageBlobFile,
+  type FigurePackageRelease,
+  type FigureRef
+} from '@hatiolab/figure-model'
+import { getRepository, Refusal } from '@things-factory/shell'
+
+import { Figure } from './figure.js'
+import { FigureHistory } from './figure-history.js'
+import { sha256Of, thumbnailAttachmentOf, thumbnailFiles, type ThumbnailFiles } from './figure-thumbnail-store.js'
+
+/** The most releases one package carries. */
+export const FIGURE_PACKAGE_MAX = 200
+
+export interface FigurePackageRequest {
+  readonly refs: readonly string[]
+  readonly domain: { id: string; parentId?: string; subdomain?: string }
+  readonly exportedBy: string | null
+  /** The address a board server can get these releases from again (`figure.publicUrl`). */
+  readonly sourceUrl: string
+  readonly now?: Date
+  readonly files?: ThumbnailFiles
+}
+
+/**
+ * Released figures as one package file a board server imports (ADR-0114 결정 3·16).
+ *
+ * Only released versions travel, read from the release history -- the draft being edited is never exported. The
+ * figures are the ones this domain can read: its own and its parent's, the scope of `figureBlueprint`.
+ */
+export async function figurePackageOf(request: FigurePackageRequest): Promise<{ name: string; bytes: Buffer }> {
+  const refs = [...new Set(request.refs)]
+  if (refs.length === 0 || refs.length > FIGURE_PACKAGE_MAX) {
+    throw new Refusal('figure-package-size', { count: refs.length, max: FIGURE_PACKAGE_MAX }, 'a package carries 1 to {max} releases, not {count}.')
+  }
+
+  const files = request.files ?? thumbnailFiles()
+  const releases: FigurePackageRelease[] = []
+  const blobs = new Map<string, FigurePackageBlobFile>()
+
+  for (const text of refs) {
+    const ref = parseFigureRef(text)
+    if (!ref) throw new Refusal('figure-ref-malformed', { ref: text }, '{ref} is not a release reference of the form namespace/type@version.')
+    const { figure, history } = await releaseOf(ref, request.domain)
+    if (history.thumbnailHash && !blobs.has(history.thumbnailHash)) {
+      const picture = await thumbnailAttachmentOf({ getRepository }, figure.domainId!, history.thumbnailHash)
+      if (picture) {
+        const bytes = await files.read(picture.path)
+        if (sha256Of(bytes) === history.thumbnailHash) blobs.set(history.thumbnailHash, { bytes, contentType: picture.mimetype })
+      }
+    }
+    releases.push(packageReleaseOf(ref, figure, history, blobs))
+  }
+
+  const packed = writeFigurePackage(
+    {
+      source: { url: request.sourceUrl, domain: request.domain.subdomain ?? '' },
+      exportedAt: (request.now ?? new Date()).toISOString(),
+      exportedBy: request.exportedBy,
+      releases,
+      blobs
+    },
+    bytes => sha256Of(Buffer.from(bytes))
+  )
+
+  const zip = new JSZip()
+  for (const [path, bytes] of packed) zip.file(path, bytes, { createFolders: false })
+  const bytes = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' })
+  const name = refs.length === 1 ? `${refs[0]!.replace(/[/@]/g, '_')}.figpkg` : `figures-${refs.length}.figpkg`
+  return { name, bytes }
+}
+
+async function releaseOf(ref: FigureRef, domain: FigurePackageRequest['domain']): Promise<{ figure: Figure; history: FigureHistory }> {
+  const figure = await getRepository(Figure).findOne({
+    where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, type: ref.type, namespace: ref.namespace }
+  })
+  const history = figure
+    ? await getRepository(FigureHistory).findOne({ where: { originalId: figure.id, state: 'released', version: ref.version } })
+    : null
+  if (!figure || !history?.source) {
+    throw new Refusal('figure-package-release-not-found', { ref: formatFigureRef(ref) }, '{ref} is not a release this domain can read.')
+  }
+  return { figure, history }
+}
+
+function packageReleaseOf(
+  ref: FigureRef,
+  figure: Figure,
+  history: FigureHistory,
+  blobs: ReadonlyMap<string, FigurePackageBlobFile>
+): FigurePackageRelease {
+  const json = (text: string | null | undefined) => (text ? JSON.parse(text) : null)
+  return {
+    ref: formatFigureRef(ref),
+    name: history.name ?? figure.name ?? formatFigureRef(ref),
+    names: history.names ?? null,
+    description: history.description ?? null,
+    category: history.category ?? null,
+    source: history.source!,
+    assetFormat: history.assetFormat ?? json(history.source)?.version ?? '',
+    kernelVersion: history.kernelVersion ?? null,
+    metrics: json(history.metrics),
+    topView: json(history.topView),
+    changes: json(history.changes),
+    thumbnail: history.thumbnailHash && blobs.has(history.thumbnailHash) ? history.thumbnailHash : null,
+    deprecated: !!figure.deprecated,
+    supersededBy: figure.supersededBy && figure.namespace ? `${figure.namespace}/${figure.supersededBy}` : null,
+    releasedAt: new Date(history.createdAt ?? Date.now()).toISOString()
+  }
+}

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

@@ -8,6 +8,7 @@ import type { DataSource } from 'typeorm'
 const { DataSource: TypeOrmDataSource } = require('typeorm')
 const shell = require('@things-factory/shell')
 const authBase = require('@things-factory/auth-base')
+const settingBase = require('@things-factory/setting-base')
 const { createFigureAsset, addFigureBox, serializeFigureAsset } = require('@hatiolab/figure-model')
 
 let dataSource: DataSource | null = null
@@ -38,7 +39,7 @@ beforeAll(async () => {
     synchronize: true,
     dropSchema: true,
     namingStrategy: new shell.NamingStrategy(),
-    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory, FigureProposalRecord],
+    entities: [...shell.entities, ...authBase.entities, ...settingBase.entities, Figure, FigureHistory, FigureProposalRecord],
     logging: false
   })
   await dataSource.initialize()
@@ -49,10 +50,16 @@ afterAll(async () => {
   dataSource = null
 })
 
+/** The domain setting every figure here is created under (ADR-0114). */
+async function namespaced(domain: any) {
+  await dataSource!.getRepository(settingBase.Setting).save({ domain, name: 'figure-namespace', category: 'figure', value: 'system' })
+  return domain
+}
+
 let DOMAIN: { id: string }
 beforeEach(async () => {
   await dataSource!.synchronize(true)
-  DOMAIN = { id: (await dataSource!.getRepository(shell.Domain).save({ name: 'proposal-probe', subdomain: 'proposal-probe' })).id }
+  DOMAIN = { id: (await namespaced(await dataSource!.getRepository(shell.Domain).save({ name: 'proposal-probe', subdomain: 'proposal-probe' }))).id }
 })
 
 const text = (name: string, height = 100) =>

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

@@ -8,8 +8,10 @@ import {
   getRepository,
   ListParam,
   Refusal,
-  SpeakRefusals
+  SpeakRefusals,
+  refusalKey
 } from '@things-factory/shell'
+import { formatFigureRef, parseFigureName, type FigureName } from '@hatiolab/figure-model'
 
 import { Figure } from './figure.js'
 import { FigureHistory } from './figure-history.js'
@@ -304,6 +306,77 @@ export class FigureQuery {
       )
     }
   }
+
+  /**
+   * Released figures a board asks for together, by full name `{namespace}/{type}` (ADR-0114 결정 14).
+   *
+   * One answer per name: an item, or a refusal that names why. A refusal never takes another item away -- the board
+   * draws what it got and a stand-in with the reason for the rest. This server keeps its policy: the latest release,
+   * shadowed by the child domain as `figureBlueprint` does. `release` is null; a type map is the board server's.
+   */
+  @Directive('@privilege(category: "figure-published", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => GraphQLJSON, {
+    description:
+      'Released figures asked together by full name {namespace}/{type}: { release: null, items: [{ type, ref, asset }], refused: [{ type, code, message }] }. The latest release of each; one refusal never removes another item.'
+  })
+  async figureBlueprints(
+    @Arg('types', type => [String], { description: 'Full figure names {namespace}/{type}. At most 500.' }) types: string[],
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    const { domain } = context.state
+    const names = [...new Set(types)]
+    if (names.length > FIGURE_BLUEPRINTS_MAX) {
+      throw new Refusal('figure-names-too-many', { count: names.length, max: FIGURE_BLUEPRINTS_MAX }, 'at most {max} figure names can be asked at once, not {count}.')
+    }
+
+    const items: { type: string; ref: string; asset: unknown }[] = []
+    const refused: { type: string; code: string; message: string }[] = []
+    /* Plain text: a board draws the reason on a canvas, so a name with `/` is not escaped. */
+    const refuse = (type: string, refusal: Refusal) =>
+      refused.push({
+        type,
+        code: refusal.code,
+        message: context.t
+          ? context.t(refusalKey(refusal.code), { ...refusal.params, defaultValue: refusal.message, interpolation: { escapeValue: false } })
+          : refusal.message
+      })
+
+    for (const type of names) {
+      const name = parseFigureName(type)
+      if (!name) {
+        refuse(type, new Refusal('figure-name-malformed', { type }, '{type} is not a full figure name of the form namespace/type.'))
+        continue
+      }
+      const found =
+        (await releasedSourceOfName(domain.id, name)) ?? (domain.parentId ? await releasedSourceOfName(domain.parentId, name) : null)
+      if (!found) {
+        refuse(type, new Refusal('figure-not-released', { type }, 'no release is published here.'))
+        continue
+      }
+      try {
+        items.push({ type, ref: formatFigureRef({ ...name, version: found.version }), asset: consumablePayloadOf(found.source).asset })
+      } catch {
+        refuse(
+          type,
+          new Refusal(
+            'figure-release-does-not-compile',
+            { type, figureId: found.figure.id, version: found.version },
+            'the released source of {type} does not compile. open it in the modeller and release it again.'
+          )
+        )
+      }
+    }
+
+    return { release: null, items, refused }
+  }
+}
+
+const FIGURE_BLUEPRINTS_MAX = 500
+
+/** The released source of a full name in one domain: the type there, published under that namespace. */
+async function releasedSourceOfName(domainId: string, name: FigureName) {
+  const found = await releasedSourceOf(domainId, name.type)
+  return found && found.figure.namespace === name.namespace ? found : null
 }
 
 /** One numbered release of a figure, or null when it has none by that number. */

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

@@ -7,6 +7,7 @@ import type { DataSource } from 'typeorm'
 const { DataSource: TypeOrmDataSource } = require('typeorm')
 const shell = require('@things-factory/shell')
 const authBase = require('@things-factory/auth-base')
+const settingBase = require('@things-factory/setting-base')
 const { createFigureAsset, addFigureBox, serializeFigureAsset, applyFigureAuthoring, proposeFigureOccupancy, palletizerRobotFigure, FIGURE_KERNEL_VERSION } = require('@hatiolab/figure-model')
 
 let dataSource: DataSource | null = null
@@ -37,7 +38,7 @@ beforeAll(async () => {
     synchronize: true,
     dropSchema: true,
     namingStrategy: new shell.NamingStrategy(),
-    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory],
+    entities: [...shell.entities, ...authBase.entities, ...settingBase.entities, Figure, FigureHistory],
     subscribers: [Subscriber],
     logging: false
   })
@@ -49,11 +50,17 @@ afterAll(async () => {
   dataSource = null
 })
 
+/** The domain setting every figure here is created under (ADR-0114). */
+async function namespaced(domain: any) {
+  await dataSource!.getRepository(settingBase.Setting).save({ domain, name: 'figure-namespace', category: 'figure', value: 'system' })
+  return domain
+}
+
 const SOURCE = serializeFigureAsset(addFigureBox(createFigureAsset('Probe'), { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } }))
 
 async function release(extra: Record<string, unknown>) {
   const domain = await dataSource!.getRepository(shell.Domain).save({ name: `d-${Math.random()}`, subdomain: `d${Date.now()}${Math.random()}` })
-  const figure = await dataSource!.getRepository(Figure).save({ type: 'RECORD_PROBE', name: 'probe', source: SOURCE, state: 'draft', version: 0, domain })
+  const figure = await dataSource!.getRepository(Figure).save({ namespace: 'system', type: 'RECORD_PROBE', name: 'probe', source: SOURCE, state: 'draft', version: 0, domain })
   await dataSource!.getRepository(Figure).save({ ...figure, domain, version: 1, state: 'released', __releaseComment: 'first', ...extra })
   return dataSource!.getRepository(FigureHistory).findOneOrFail({ where: { originalId: figure.id } })
 }
@@ -84,10 +91,10 @@ describe('releaseFigure records it', () => {
     return serializeFigureAsset(applyFigureAuthoring(a, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(a, { over: 'range' }), placement: 'floor' }))
   }
   it('first release: [], the second: the wider room', async () => {
-    const domain = await dataSource!.getRepository(shell.Domain).save({ name: 'release-door', subdomain: 'release-door' })
+    const domain = await namespaced(await dataSource!.getRepository(shell.Domain).save({ name: 'release-door', subdomain: 'release-door' }))
     const tx = dataSource!.manager
     const context = { state: { domain, user: undefined, tx } }
-    const figure = await dataSource!.getRepository(Figure).save({ type: 'RELEASE_DOOR', name: 'door', source: releasable(100), state: 'draft', version: 0, domain })
+    const figure = await dataSource!.getRepository(Figure).save({ namespace: 'system', type: 'RELEASE_DOOR', name: 'door', source: releasable(100), state: 'draft', version: 0, domain })
     await new FigureMutation().releaseFigure(figure.id, 'one', context)
     await dataSource!.getRepository(Figure).save({ ...(await dataSource!.getRepository(Figure).findOneOrFail({ where: { id: figure.id } })), domain, source: releasable(300), state: 'draft' })
     await new FigureMutation().releaseFigure(figure.id, 'two', context)
@@ -116,9 +123,9 @@ describe('a release of a figure that moves keeps its joint list', () => {
     return serializeFigureAsset(applyFigureAuthoring(asset, { kind: 'set-joint', joint: { ...j4, axis: j4Axis } }))
   }
   it('schema 2, the wrist following -(j2 + j3), controls with both units; another axis is refused', async () => {
-    const domain = await dataSource!.getRepository(shell.Domain).save({ name: 'release-joints', subdomain: 'release-joints' })
+    const domain = await namespaced(await dataSource!.getRepository(shell.Domain).save({ name: 'release-joints', subdomain: 'release-joints' }))
     const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
-    const figure = await dataSource!.getRepository(Figure).save({ type: 'PALLETIZER', name: 'palletizer', source: palletizer(), state: 'draft', version: 0, domain })
+    const figure = await dataSource!.getRepository(Figure).save({ namespace: 'system', type: 'PALLETIZER', name: 'palletizer', source: palletizer(), state: 'draft', version: 0, domain })
     await new FigureMutation().releaseFigure(figure.id, 'one', context)
 
     const [row] = await dataSource!.getRepository(FigureHistory).find({ where: { originalId: figure.id } })

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

@@ -13,6 +13,7 @@ import type { DataSource } from 'typeorm'
 const { DataSource: TypeOrmDataSource } = require('typeorm')
 const shell = require('@things-factory/shell')
 const authBase = require('@things-factory/auth-base')
+const settingBase = require('@things-factory/setting-base')
 
 let dataSource: DataSource | null = null
 let Figure: any
@@ -46,7 +47,7 @@ beforeAll(async () => {
     synchronize: true,
     dropSchema: true,
     namingStrategy: new shell.NamingStrategy(),
-    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory],
+    entities: [...shell.entities, ...authBase.entities, ...settingBase.entities, Figure, FigureHistory],
     logging: false
   })
 
@@ -68,17 +69,24 @@ afterAll(async () => {
   dataSource = null
 })
 
+/** The domain setting every figure here is created under (ADR-0114). */
+async function namespaced(domain: any) {
+  await dataSource!.getRepository(settingBase.Setting).save({ domain, name: 'figure-namespace', category: 'figure', value: 'system' })
+  return domain
+}
+
 let DOMAIN: { id: string }
 
 /* 도형이 도메인을 가리킨다 — 행이 없으면 외래키가 먼저 막는다. */
 async function seedDomain() {
-  const saved = await dataSource!.getRepository(shell.Domain).save({ name: 'rename-probe', subdomain: 'rename-probe' })
+  const saved = await namespaced(await dataSource!.getRepository(shell.Domain).save({ name: 'rename-probe', subdomain: 'rename-probe' }))
   DOMAIN = { id: saved.id }
 }
 
 async function seedFigure(over: Record<string, unknown> = {}) {
   return await dataSource!.getRepository(Figure).save({
-    type: 'FIGURE_MU6SZ5DL',
+    namespace: 'system',
+    type: 'figure-mu6sz5dl',
     name: '초안',
     source: '{}',
     state: 'draft',
@@ -100,7 +108,7 @@ describe('이름을 바꾸기 전에 읽는 사실', () => {
   it('★ 판본 질의가 실제로 돈다 — 칸 이름이 틀리면 여기서 던진다', async () => {
     const figure = await seedFigure()
 
-    expect(await facts(figure, 'ROBOT_ARM')).toEqual({ version: 0, hasHistory: false, takenByAnother: false })
+    expect(await facts(figure, 'robot-arm')).toEqual({ version: 0, hasHistory: false, takenByAnother: false })
   })
 
   it('★ 판본이 있으면 그것을 읽어 온다', async () => {
@@ -114,14 +122,14 @@ describe('이름을 바꾸기 전에 읽는 사실', () => {
       domain: DOMAIN
     })
 
-    expect((await facts(figure, 'ROBOT_ARM')).hasHistory).toBe(true)
+    expect((await facts(figure, 'robot-arm')).hasHistory).toBe(true)
   })
 
   it('같은 도메인에서 그 이름을 쓰는 다른 도형을 찾는다', async () => {
     const figure = await seedFigure()
-    await seedFigure({ type: 'CONVEYOR', name: '컨베이어' })
+    await seedFigure({ type: 'conveyor', name: '컨베이어' })
 
-    expect((await facts(figure, 'CONVEYOR')).takenByAnother).toBe(true)
+    expect((await facts(figure, 'conveyor')).takenByAnother).toBe(true)
   })
 
   it('자기 이름은 겹침이 아니다', async () => {
@@ -165,13 +173,13 @@ describe('처음 저장에 타입 이름을 받는다', () => {
   const ids = ['8a1f2c3d-4b5e-4f60-8a71-92b3c4d5e6f7', '9b2e3d4c-5a6f-4e71-9b82-a3c4d5e6f708']
 
   it('준 이름으로 만든다 — 앞뒤 빈칸은 뺀다', async () => {
-    const saved = await save(ids[0], '  ROBOT_ARM ')
-    expect(saved.type).toBe('ROBOT_ARM')
+    const saved = await save(ids[0], '  robot-arm ')
+    expect(saved.type).toBe('robot-arm')
   })
 
   it('★ 이미 쓰는 이름이면 저장하지 않는다 — 임시 이름으로 남기지 않는다', async () => {
-    await seedFigure({ type: 'CONVEYOR', name: '컨베이어' })
-    await expect(save(ids[1], 'CONVEYOR')).rejects.toThrow(/이미 쓰고 있다/)
+    await seedFigure({ type: 'conveyor', name: '컨베이어' })
+    await expect(save(ids[1], 'conveyor')).rejects.toThrow(/이미 쓰고 있다/)
     expect(await dataSource!.getRepository(Figure).count({ where: { id: ids[1] } })).toBe(0)
   })
 

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

@@ -12,7 +12,7 @@ import { createFigureAsset, parseFigureAsset, serializeFigureAsset } from '@hati
 import { FigureRenameRefused, renameDraftType } from './figure-rename'
 
 const draft = (over: Record<string, unknown> = {}) => ({
-  type: 'FIGURE_MU6RJH47',
+  type: 'figure-mu6rjh47',
   source: serializeFigureAsset(createFigureAsset('새 Figure')),
   ...over
 })
@@ -26,26 +26,26 @@ describe('초안의 type 고치기', () => {
   */
   it('★ 행만 바뀌고, 원본은 그대로 다시 열린다', () => {
     const source = serializeFigureAsset(createFigureAsset('새 Figure'))
-    const result = renameDraftType({ type: 'FIGURE_ABCDEF12', source }, 'ROLLER_CONVEYOR', never)
+    const result = renameDraftType({ type: 'figure-abcdef12', source }, 'roller-conveyor', never)
 
-    expect(result.type).toBe('ROLLER_CONVEYOR')
+    expect(result.type).toBe('roller-conveyor')
     expect(result.source).toBe(source)
     expect(() => parseFigureAsset(result.source)).not.toThrow()
   })
 
   it('앞뒤 공백을 뗀다. 모양은 모델러가 묻는 규칙 그대로 — 대문자로 적지 않으면 거절한다(Q-D3, 2026-09-27)', () => {
-    expect(renameDraftType(draft(), '  ROBOT_ARM  ', never).type).toBe('ROBOT_ARM')
+    expect(renameDraftType(draft(), '  robot-arm  ', never).type).toBe('robot-arm')
     /* It was kept as written; the modeller always sent it upper-cased, and every stored type already is (56/56). */
     expect(() => renameDraftType(draft(), 'Robot_Arm', never)).toThrow(expect.objectContaining({ code: 'malformed-type' }))
   })
 
   it('★ 한 번이라도 발행됐으면 거절한다 — 판 번호로', () => {
-    expect(() => renameDraftType(draft(), 'ROBOT_ARM', { ...never, version: 1 })).toThrow(FigureRenameRefused)
+    expect(() => renameDraftType(draft(), 'robot-arm', { ...never, version: 1 })).toThrow(FigureRenameRefused)
   })
 
   it('★ 판 번호가 도로 0 이어도 이력이 있으면 거절한다 — 되돌리기가 그 자리를 만든다', () => {
     try {
-      renameDraftType(draft(), 'ROBOT_ARM', { ...never, hasHistory: true })
+      renameDraftType(draft(), 'robot-arm', { ...never, hasHistory: true })
       throw new Error('거절하지 않았다')
     } catch (e) {
       expect((e as FigureRenameRefused).code).toBe('already-released')
@@ -54,11 +54,11 @@ describe('초안의 type 고치기', () => {
 
   it('같은 도메인에서 쓰는 이름이면 거절하고, 어느 이름인지 말한다', () => {
     try {
-      renameDraftType(draft(), 'CONVEYOR', { ...never, takenByAnother: true })
+      renameDraftType(draft(), 'conveyor', { ...never, takenByAnother: true })
       throw new Error('거절하지 않았다')
     } catch (e) {
       expect((e as FigureRenameRefused).code).toBe('type-taken')
-      expect((e as Error).message).toContain('CONVEYOR')
+      expect((e as Error).message).toContain('conveyor')
     }
   })
 
@@ -108,10 +108,10 @@ describe('문이 이 규칙을 지난다', () => {
 
 describe('a type being set keeps the shape the modeller asks for (Q-D3, designer 2026-09-27)', () => {
   const free = { version: 0, hasHistory: false, takenByAnother: false }
-  it.each(['lower_case', 'X1', 'A'.repeat(33), '1ABC', 'AB-CD', 'AB__CD', '한글'])('refuses %s as malformed', wanted => {
-    expect(() => renameDraftType({ type: 'OLD', source: '{}' }, wanted, free)).toThrow(expect.objectContaining({ code: 'malformed-type' }))
+  it.each(['UPPER', 'snake_case', 'x', 'a'.repeat(65), '1abc', 'ab--cd', 'ab-', '한글'])('refuses %s as malformed', wanted => {
+    expect(() => renameDraftType({ type: 'old', source: '{}' }, wanted, free)).toThrow(expect.objectContaining({ code: 'malformed-type' }))
   })
-  it.each(['FIG_K3F9A2', 'CONVEYOR', 'LIFT_TABLE_2'])('takes %s', wanted => {
-    expect(renameDraftType({ type: 'OLD', source: '{}' }, wanted, free).type).toBe(wanted)
+  it.each(['fig-k3f9a2', 'conveyor', 'lift-table-2'])('takes %s', wanted => {
+    expect(renameDraftType({ type: 'old', source: '{}' }, wanted, free).type).toBe(wanted)
   })
 })

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

@@ -65,7 +65,7 @@ export function renameDraftType(
   if (!TYPE_PATTERN.test(next) || next.length < TYPE_LENGTH.min || next.length > TYPE_LENGTH.max) {
     throw new FigureRenameRefused(
       'malformed-type',
-      `type 「${next}」 는 대문자로 시작하고 대문자·숫자·밑줄만 쓰며 ${TYPE_LENGTH.min}~${TYPE_LENGTH.max}자여야 한다`
+      `type 「${next}」 는 소문자로 시작하고 소문자·숫자·하이픈 하나씩만 쓰며 ${TYPE_LENGTH.min}~${TYPE_LENGTH.max}자여야 한다`
     )
   }
 

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

@@ -42,6 +42,9 @@ function mapFiles() {
       koa.set('ETag', '"storage-md5"')
       koa.set('Cache-Control', 'public, max-age=31536000')
       koa.body = kept.get(path)
+    },
+    async read(path: string) {
+      return kept.get(path)!
     }
   }
 }

package/server/service/figure/figure-thumbnail-store.ts

@@ -33,6 +33,8 @@ export const sha256Of = (bytes: Buffer) => createHash('sha256').update(bytes).di
 export interface ThumbnailFiles {
   put(bytes: Buffer, mimetype: string, name: string, context: any): Promise<{ id: string; path: string; size: number; contents?: Buffer }>
   send(koa: any, path: string, next: () => Promise<any>): Promise<void>
+  /** The bytes kept at a path -- what a figure package carries. */
+  read(path: string): Promise<Buffer>
 }
 
 export const attachmentFiles: ThumbnailFiles = {
@@ -46,7 +48,8 @@ export const attachmentFiles: ThumbnailFiles = {
     const { id, path, size, contents } = await STORAGE.uploadFile({ file, context })
     return { id, path, size, contents }
   },
-  send: (koa, path, next) => STORAGE.sendFile(koa, path, next)
+  send: (koa, path, next) => STORAGE.sendFile(koa, path, next),
+  read: async path => Buffer.from(await STORAGE.readFile(path))
 }
 
 /*

package/server/service/figure/figure.ts

@@ -77,6 +77,14 @@ export class Figure {
   @Field({ description: 'Component type name. A stored identifier — unique per domain and immutable once created.' })
   type?: string
 
+  /**
+   * The namespace the figure is published under, copied from the domain setting `figure-namespace` when the figure is
+   * made. With the type it forms the full name `{namespace}/{type}` boards store (ADR-0114). Never changes.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Namespace of the full name {namespace}/{type}. Copied from the domain setting when created; never changes.' })
+  namespace?: string
+
   @Column()
   @Field({ description: 'Display name shown to authors. Safe to rename.' })
   name?: string

package/translations/en.json

@@ -89,5 +89,14 @@
   "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."
+  "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.",
+  "error.figure-namespace-missing": "this domain has no valid figure namespace ({value}). set {setting} first, for example hatiolab.com.",
+  "error.figure-namespace-changed": "the figure namespace of this domain is {namespace} and cannot change. set {setting} back to {namespace}.",
+  "error.figure-type-malformed": "{type} is not a figure type. use lower-case letters, digits and single hyphens, {min} to {max} characters, starting with a letter.",
+  "error.figure-name-malformed": "{type} is not a full figure name of the form namespace/type.",
+  "error.figure-not-released": "no release is published here.",
+  "error.figure-names-too-many": "at most {max} figure names can be asked at once, not {count}.",
+  "error.figure-package-size": "a package carries 1 to {max} releases, not {count}.",
+  "error.figure-ref-malformed": "{ref} is not a release reference of the form namespace/type@version.",
+  "error.figure-package-release-not-found": "{ref} is not a release this domain can read."
 }

package/translations/ko.json

@@ -89,5 +89,14 @@
   "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": "문의 경첩처럼 붙이는 자리라면 그대로 둡니다. 공간 가운데로 놓이게 하려면 원점을 가운데로 옮깁니다."
+  "figure.gate.origin-off-centre.how": "문의 경첩처럼 붙이는 자리라면 그대로 둡니다. 공간 가운데로 놓이게 하려면 원점을 가운데로 옮깁니다.",
+  "error.figure-namespace-missing": "이 도메인에 Figure namespace 가 없거나 형식이 맞지 않습니다({value}). 설정 {setting} 에 예를 들어 hatiolab.com 을 먼저 넣어 주세요.",
+  "error.figure-namespace-changed": "이 도메인의 Figure namespace 는 {namespace} 이며 바꿀 수 없습니다. 설정 {setting} 을 {namespace} 로 되돌려 주세요.",
+  "error.figure-type-malformed": "{type} 은 Figure type 이 아닙니다. 소문자로 시작하고 소문자·숫자·하이픈 하나씩만 써서 {min}~{max}자로 정해 주세요.",
+  "error.figure-name-malformed": "{type} 은 namespace/type 형식의 정식 이름이 아닙니다.",
+  "error.figure-not-released": "이 도메인에 발행판이 없습니다.",
+  "error.figure-names-too-many": "Figure 이름은 한 번에 {max}개까지 물을 수 있습니다({count}개).",
+  "error.figure-package-size": "꾸러미에는 발행판을 1~{max}개 담을 수 있습니다({count}개).",
+  "error.figure-ref-malformed": "{ref} 은 namespace/type@버전 형식의 발행판 참조가 아닙니다.",
+  "error.figure-package-release-not-found": "{ref} 은 이 도메인에서 읽을 수 있는 발행판이 아닙니다."
 }

package/coverage/clover.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<coverage generated="1789051204527" clover="3.2.0">
-  <project timestamp="1789051204527" name="All files">
-    <metrics statements="0" coveredstatements="0" conditionals="0" coveredconditionals="0" methods="0" coveredmethods="0" elements="0" coveredelements="0" complexity="0" loc="0" ncloc="0" packages="0" files="0" classes="0"/>
-  </project>
-</coverage>

package/coverage/coverage-final.json

@@ -1 +0,0 @@
-{}