@things-factory/figure-service 10.1.110 → 10.1.112

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

@@ -60,8 +60,8 @@ beforeEach(async () => {
 })
 
 async function figureWithRelease() {
-  const figure = await dataSource!.getRepository(Figure).save({ type: 'REVERT_PROBE', name: 'probe', source: DRAFT, state: 'draft', version: 1, thumbnail: 'draft-picture', domain: DOMAIN })
-  await dataSource!.getRepository(FigureHistory).save({ originalId: figure.id, version: 1, type: 'REVERT_PROBE', name: 'probe', source: V1, state: 'released', thumbnail: 'v1-picture', domain: DOMAIN })
+  const figure = await dataSource!.getRepository(Figure).save({ type: 'REVERT_PROBE', name: 'probe', source: DRAFT, state: 'draft', version: 1, thumbnailHash: 'draft-picture', domain: DOMAIN })
+  await dataSource!.getRepository(FigureHistory).save({ originalId: figure.id, version: 1, type: 'REVERT_PROBE', name: 'probe', source: V1, state: 'released', thumbnailHash: 'v1-picture', domain: DOMAIN })
   return figure
 }
 const uuid = () => require('crypto').randomUUID()
@@ -74,10 +74,11 @@ describe('a revert keeps the draft it writes over', () => {
     const figure = await figureWithRelease()
     const result = await inTx(tx => revertKeepingDraft(tx, DOMAIN, undefined, { id: figure.id, version: 1, requestId: uuid(), expectedSource: DRAFT }))
     expect(JSON.parse((await row(figure.id)).source).name).toBe('Released one')
-    expect((await row(figure.id)).thumbnail).toBe('v1-picture')
+    /* The picture goes by its hash (ADR-0104 decision 6): the release's own comes back with its source. */
+    expect((await row(figure.id)).thumbnailHash).toBe('v1-picture')
     const [one] = await kept()
     expect(one.source).toBe(DRAFT)
-    expect(one.thumbnail).toBe('draft-picture')
+    expect(one.thumbnailHash).toBe('draft-picture')
     expect(one.revertedToVersion).toBe(1)
     expect(result.kept.id).toBe(one.id)
     /* Not a release: the released versions are as they were. */
@@ -133,7 +134,7 @@ describe('an undo brings the kept draft back only while nothing changed since',
     const requestId = uuid()
     await inTx(tx => undoRevert(tx, DOMAIN, undefined, { keptId: reverted.kept.id, requestId }))
     expect((await row(figure.id)).source).toBe(DRAFT)
-    expect((await row(figure.id)).thumbnail).toBe('draft-picture')
+    expect((await row(figure.id)).thumbnailHash).toBe('draft-picture')
     const records = await kept()
     expect(records.map((k: any) => k.kind).sort()).toEqual(['revert', 'undo'])
     expect(records.find((k: any) => k.kind === 'revert').restoredAt).toBeTruthy()

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

@@ -86,6 +86,7 @@ export async function revertKeepingDraft(
     source: figure.source,
     properties: figure.properties,
     thumbnail: figure.thumbnail,
+    thumbnailHash: figure.thumbnailHash,
     state: figure.state,
     version: figure.version,
     revertedToVersion: request.version,
@@ -101,8 +102,10 @@ export async function revertKeepingDraft(
       source,
       ...derived,
       properties: history.properties,
-      thumbnail: history.thumbnail,
-      thumbnailUpdatedAt: history.thumbnail === figure.thumbnail ? figure.thumbnailUpdatedAt : new Date(),
+      /* The picture goes by its hash (ADR-0104 decision 6); the release's own, as the source is. */
+      thumbnail: null,
+      thumbnailHash: history.thumbnailHash ?? null,
+      thumbnailUpdatedAt: history.thumbnailHash === figure.thumbnailHash ? figure.thumbnailUpdatedAt : new Date(),
       state: 'draft',
       ...(user ? { updater: { id: user.id } } : {})
     }
@@ -144,6 +147,7 @@ export async function undoRevert(
     source: figure.source,
     properties: figure.properties,
     thumbnail: figure.thumbnail,
+    thumbnailHash: figure.thumbnailHash,
     state: figure.state,
     version: figure.version,
     writtenSource: record.source,
@@ -158,8 +162,9 @@ export async function undoRevert(
       source: record.source,
       ...derived,
       properties: record.properties,
-      thumbnail: record.thumbnail,
-      thumbnailUpdatedAt: record.thumbnail === figure.thumbnail ? figure.thumbnailUpdatedAt : new Date(),
+      thumbnail: null,
+      thumbnailHash: record.thumbnailHash ?? null,
+      thumbnailUpdatedAt: record.thumbnailHash === figure.thumbnailHash ? figure.thumbnailUpdatedAt : new Date(),
       state: 'draft',
       ...(user ? { updater: { id: user.id } } : {})
     }

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

@@ -0,0 +1,218 @@
+/**
+ * A figure's picture kept by attachment-base under its content hash (ADR-0104 decision 6; chief architect's ruling
+ * 2026-10-02): written once per content per domain, served only behind the figure permission from the figure's own
+ * domain, and the base64 an install already holds moved at start without losing one. On sqlite with the history
+ * subscriber on; the files go to a map instead of the configured storage.
+ */
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+const attachmentBase = require('@things-factory/attachment-base')
+const { createFigureAsset, addFigureBox, serializeFigureAsset } = require('@hatiolab/figure-model')
+
+let dataSource: DataSource | null = null
+let Figure: any, FigureHistory: any, FigureReplacedDraft: any, Subscriber: any, FigureMutation: any
+let keepThumbnail: any, sha256Of: any, useThumbnailFiles: any, moveBase64Thumbnails: any, sendFigureThumbnail: 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)
+}
+
+/** Files in a map: put keeps the bytes under a new id, send hands them back. */
+function mapFiles() {
+  const kept = new Map<string, Buffer>()
+  let n = 0
+  return {
+    kept,
+    async put(bytes: Buffer, _mimetype: string, name: string) {
+      const id = `00000000-0000-4000-8000-${String(++n).padStart(12, '0')}`
+      const path = `${id}.${name.split('.').pop()}`
+      kept.set(path, bytes)
+      return { id, path, size: bytes.length }
+    },
+    async send(koa: any, path: string) {
+      koa.body = kept.get(path)
+    }
+  }
+}
+
+const picture = (colour: number) => `data:image/webp;base64,${Buffer.from([0x52, 0x49, 0x46, 0x46, colour, colour, 1, 2]).toString('base64')}`
+const bytesOf = (dataUrl: string) => Buffer.from(dataUrl.split(',')[1]!, 'base64')
+const SOURCE = serializeFigureAsset(addFigureBox(createFigureAsset('Probe'), { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } }))
+
+beforeAll(async () => {
+  Figure = loadCompiled('service/figure/figure').Figure
+  FigureHistory = loadCompiled('service/figure/figure-history').FigureHistory
+  FigureReplacedDraft = loadCompiled('service/figure/figure-replaced-draft').FigureReplacedDraft
+  Subscriber = loadCompiled('service/figure/event-subscriber').FigureHistoryEntitySubscriber
+  FigureMutation = loadCompiled('service/figure/figure-mutation').FigureMutation
+  ;({ keepThumbnail, sha256Of, useThumbnailFiles } = loadCompiled('service/figure/figure-thumbnail-store'))
+  ;({ moveBase64Thumbnails } = loadCompiled('service/figure/figure-thumbnail-upgrade'))
+  ;({ sendFigureThumbnail } = loadCompiled('routers/figure-thumbnail-router'))
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, ...attachmentBase.entities, Figure, FigureHistory, FigureReplacedDraft],
+    subscribers: [Subscriber],
+    logging: false
+  })
+  await dataSource.initialize()
+  shell.addDataSource('default', dataSource)
+  shell.addDataSource('tx', dataSource)
+})
+
+afterAll(async () => {
+  shell.removeDataSource('default')
+  shell.removeDataSource('tx')
+  await dataSource?.destroy()
+  dataSource = null
+})
+
+let seq = 0
+const newDomain = async (parent?: any) => {
+  const name = `thumb-${++seq}`
+  const saved = await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name, ...(parent ? { parent } : {}) })
+  return dataSource!.getRepository(shell.Domain).findOneOrFail({ where: { id: saved.id } })
+}
+const attachments = (domainId?: string) =>
+  dataSource!.getRepository(attachmentBase.Attachment).find({ where: { refType: 'figure-thumbnail', ...(domainId ? { domain: { id: domainId } } : {}) } })
+function koa(ifNoneMatch?: string) {
+  const headers: Record<string, string> = {}
+  return {
+    status: 200,
+    type: '',
+    body: undefined as any,
+    headers,
+    set(k: string, v: string) {
+      headers[k] = v
+    },
+    get fresh() {
+      return !!ifNoneMatch && ifNoneMatch === headers['ETag']
+    }
+  }
+}
+
+describe('a picture kept by its content', () => {
+  it('the same picture twice in a domain is one attachment; in another domain, its own', async () => {
+    const files = mapFiles()
+    const a = await newDomain(),
+      b = await newDomain()
+    const tx = dataSource!.manager
+    const one = await keepThumbnail(tx, a, undefined, picture(7), files)
+    expect(await keepThumbnail(tx, a, undefined, picture(7), files)).toBe(one)
+    expect(one).toBe(sha256Of(bytesOf(picture(7))))
+    expect((await attachments(a.id)).length).toBe(1)
+    await keepThumbnail(tx, b, undefined, picture(7), files)
+    expect((await attachments(b.id)).length).toBe(1)
+    await expect(keepThumbnail(tx, a, undefined, 'not a picture', files)).rejects.toThrow(/data URL/)
+  })
+
+  it('a save names the picture by its hash and never writes the bytes onto the row', async () => {
+    const was = useThumbnailFiles(mapFiles())
+    const domain = await newDomain()
+    const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
+    const figure = await dataSource!.getRepository(Figure).save({ type: 'SAVED', name: 'saved', source: SOURCE, state: 'draft', version: 0, domain })
+    await new FigureMutation().updateFigure(figure.id, { thumbnail: picture(9) }, context)
+    const row = await dataSource!.getRepository(Figure).findOneOrFail({ where: { id: figure.id } })
+    expect([row.thumbnail, row.thumbnailHash]).toEqual([null, sha256Of(bytesOf(picture(9)))])
+    expect(row.thumbnailUpdatedAt).toBeTruthy()
+    useThumbnailFiles(was)
+  })
+})
+
+describe('served behind the permission, from the figure\'s own domain', () => {
+  it('an inherited figure\'s picture is the parent\'s, even when the child holds the same hash elsewhere', async () => {
+    const files = mapFiles()
+    const parent = await newDomain()
+    const child = await newDomain(parent)
+    const hash = await keepThumbnail(dataSource!.manager, parent, undefined, picture(3), files)
+    const figure = await dataSource!.getRepository(Figure).save({ type: 'INHERITED', name: 'x', source: SOURCE, state: 'released', version: 1, thumbnailHash: hash, thumbnailUpdatedAt: new Date(), domain: parent })
+    /* The child holds an attachment under the same hash, pointing at other bytes: it must not be picked. */
+    files.kept.set('child-copy.webp', Buffer.from('not the parent picture'))
+    await dataSource!.getRepository(attachmentBase.Attachment).save({ domain: child, name: 'x', mimetype: 'image/webp', encoding: 'binary', refType: 'figure-thumbnail', refBy: hash, category: 'image', size: '1', path: 'child-copy.webp' })
+    const ctx = koa()
+    await sendFigureThumbnail(ctx, async () => {}, figure.id, child, files)
+    expect(ctx.status).toBe(200)
+    expect(Buffer.compare(ctx.body, bytesOf(picture(3)))).toBe(0)
+    expect(ctx.headers['Cache-Control']).toBe('private, max-age=31536000')
+    expect(ctx.headers['ETag']).toBe(`"${hash}"`)
+    const again = koa(`"${hash}"`)
+    await sendFigureThumbnail(again, async () => {}, figure.id, child, files)
+    expect([again.status, again.body]).toEqual([304, undefined])
+  })
+
+  it('a figure with no picture, or of a domain the caller cannot read, is 404', async () => {
+    const files = mapFiles()
+    const mine = await newDomain(),
+      other = await newDomain()
+    const bare = await dataSource!.getRepository(Figure).save({ type: 'BARE', name: 'x', source: SOURCE, state: 'draft', version: 0, domain: mine })
+    const ctx = koa()
+    await sendFigureThumbnail(ctx, async () => {}, bare.id, mine, files)
+    expect(ctx.status).toBe(404)
+    const hash = await keepThumbnail(dataSource!.manager, other, undefined, picture(5), files)
+    const theirs = await dataSource!.getRepository(Figure).save({ type: 'THEIRS', name: 'x', source: SOURCE, state: 'draft', version: 0, thumbnailHash: hash, domain: other })
+    const denied = koa()
+    await sendFigureThumbnail(denied, async () => {}, theirs.id, mine, files)
+    expect(denied.status).toBe(404)
+  })
+})
+
+/*
+ * The upgrade, for every shape an install may hold: a figure with base64 only, its releases (with a domain, and an old
+ * one without), a draft a revert kept, a row with no picture, and a picture that is not a data URL. Run twice.
+ */
+describe('the base64 an install holds, moved at start without losing one', () => {
+  it('every shape moves once; what cannot move keeps its base64; a second start changes nothing', async () => {
+    const files = mapFiles()
+    const domain = await newDomain()
+    const figures = dataSource!.getRepository(Figure)
+    const histories = dataSource!.getRepository(FigureHistory)
+    /* Old rows are written as an install wrote them: straight to the table, no subscriber. */
+    const insert = (entity: any, values: any) => dataSource!.createQueryBuilder().insert().into(entity).values(values).callListeners(false).execute()
+    const figureId = '11111111-1111-4111-8111-111111111111'
+    await insert(Figure, { id: figureId, type: 'OLD', name: 'old', source: SOURCE, state: 'draft', version: 2, thumbnail: picture(1), domain: { id: domain.id } })
+    await insert(FigureHistory, { originalId: figureId, version: 1, type: 'OLD', state: 'released', thumbnail: picture(2), domain: { id: domain.id }, action: 'updated' })
+    await insert(FigureHistory, { originalId: figureId, version: 2, type: 'OLD', state: 'released', thumbnail: picture(1), action: 'updated' })
+    await insert(FigureReplacedDraft, { figureId, kind: 'revert', requestId: 'r-1', source: SOURCE, thumbnail: picture(4), state: 'draft', version: 2, writtenSource: SOURCE, writtenSourceHash: 'x', domain: { id: domain.id } })
+    await insert(Figure, { type: 'NONE', name: 'none', source: SOURCE, state: 'draft', version: 0, domain: { id: domain.id } })
+    await insert(Figure, { type: 'BROKEN', name: 'broken', source: SOURCE, state: 'draft', version: 0, thumbnail: 'garbage', domain: { id: domain.id } })
+
+    const first = await moveBase64Thumbnails(dataSource, files)
+    expect(first).toEqual([
+      { table: 'figure', moved: 1, kept: 1 },
+      { table: 'figure_history', moved: 2, kept: 0 },
+      { table: 'figure_replaced_draft', moved: 1, kept: 0 }
+    ])
+    const row = await figures.findOneOrFail({ where: { id: figureId } })
+    expect([row.thumbnail, row.thumbnailHash]).toEqual([null, sha256Of(bytesOf(picture(1)))])
+    const releases = await histories.find({ where: { originalId: figureId }, order: { version: 'ASC' } })
+    expect(releases.map((r: any) => [r.thumbnail, r.thumbnailHash])).toEqual([
+      [null, sha256Of(bytesOf(picture(2)))],
+      [null, sha256Of(bytesOf(picture(1)))]
+    ])
+    const [kept] = await dataSource!.getRepository(FigureReplacedDraft).find()
+    expect([kept.thumbnail, kept.thumbnailHash]).toEqual([null, sha256Of(bytesOf(picture(4)))])
+    expect((await figures.findOneOrFail({ where: { type: 'BROKEN' } })).thumbnail).toBe('garbage')
+    expect((await figures.findOneOrFail({ where: { type: 'NONE' } })).thumbnailHash).toBeNull()
+    /* Three contents, three attachments: the figure and its second release share one. */
+    expect((await attachments(domain.id)).length).toBe(3)
+
+    const second = await moveBase64Thumbnails(dataSource, files)
+    expect(second).toEqual([
+      { table: 'figure', moved: 0, kept: 1 },
+      { table: 'figure_history', moved: 0, kept: 0 },
+      { table: 'figure_replaced_draft', moved: 0, kept: 0 }
+    ])
+    expect((await attachments(domain.id)).length).toBe(3)
+  })
+})

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

@@ -0,0 +1,107 @@
+import { createHash } from 'crypto'
+import { Readable } from 'stream'
+
+import { Attachment, STORAGE } from '@things-factory/attachment-base'
+
+/*
+ * A figure's picture, kept by attachment-base and named by its content (ADR-0104 decision 6, chief architect's ruling
+ * 2026-10-02).
+ *
+ *   stored    by attachment-base's storage (file, S3, database -- whichever the install configures), one attachment
+ *             per (domain, content): refType `figure-thumbnail`, refBy the SHA-256 of the bytes. A figure, its
+ *             releases and the drafts a revert kept carry that hash, never the bytes.
+ *   served    only through `/figure-thumbnail/:id`, behind the figure query permission -- never through attachment-
+ *             base's public `/attachment/:path`, which checks nothing (a known gap, recorded in ADR-0104).
+ *   the same  content twice in one domain is one attachment, read by its hash. Two writers that both find none both
+ *             write one; either serves the same bytes, so the result is the same (ruling, condition 2).
+ *
+ * The file is written before the row that names it: a file cannot be rolled back, so it goes first, and a row that
+ * fails to commit leaves a file the next write of the same content writes again.
+ */
+
+export const THUMBNAIL_REF_TYPE = 'figure-thumbnail'
+
+/** `data:image/webp;base64,....` as its type and bytes; undefined when it is not one. */
+export function decodeDataUrl(dataUrl: string): { type: string; bytes: Buffer } | undefined {
+  const matched = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrl)
+  return matched ? { type: matched[1]!, bytes: Buffer.from(matched[2]!, 'base64') } : undefined
+}
+
+export const sha256Of = (bytes: Buffer) => createHash('sha256').update(bytes).digest('hex')
+
+/** Where the bytes go: attachment-base's storage. Tests give another. */
+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>
+}
+
+export const attachmentFiles: ThumbnailFiles = {
+  async put(bytes, mimetype, name, context) {
+    const file = Promise.resolve({
+      createReadStream: () => Readable.from([bytes]),
+      filename: name,
+      mimetype,
+      encoding: 'binary'
+    })
+    const { id, path, size, contents } = await STORAGE.uploadFile({ file, context })
+    return { id, path, size, contents }
+  },
+  send: (koa, path, next) => STORAGE.sendFile(koa, path, next)
+}
+
+/*
+ * The files in use: attachment-base's storage, unless a test gives its own. One seam for every writer and the router,
+ * so a test of a save or a revert need not reach into each.
+ */
+let inUse: ThumbnailFiles = attachmentFiles
+export const thumbnailFiles = (): ThumbnailFiles => inUse
+/** For tests: use these files until set back; returns the ones it replaced. */
+export function useThumbnailFiles(files: ThumbnailFiles): ThumbnailFiles {
+  const was = inUse
+  inUse = files
+  return was
+}
+
+type Tx = { getRepository: (target: any) => any }
+
+/** The attachment holding this content in this domain, or undefined. */
+export async function thumbnailAttachmentOf(tx: Tx, domainId: string, hash: string): Promise<Attachment | undefined> {
+  return (await tx.getRepository(Attachment).findOne({ where: { domain: { id: domainId }, refType: THUMBNAIL_REF_TYPE, refBy: hash } })) ?? undefined
+}
+
+/**
+ * Keeps a picture and gives its hash. Refused when it is not a data URL -- a picture the server cannot read is one it
+ * must not keep under a name.
+ */
+export async function keepThumbnail(
+  tx: Tx,
+  domain: { id: string },
+  user: unknown,
+  dataUrl: string,
+  files: ThumbnailFiles = thumbnailFiles()
+): Promise<string> {
+  const decoded = decodeDataUrl(dataUrl)
+  if (!decoded) throw new Error('썸네일은 data URL(data:image/...;base64,...) 이어야 한다')
+  const hash = sha256Of(decoded.bytes)
+  if (await thumbnailAttachmentOf(tx, domain.id, hash)) return hash
+  const ext = decoded.type.split('/')[1]?.split('+')[0] || 'bin'
+  const name = `${hash}.${ext}`
+  /* The file first: it cannot be rolled back. The row that names it comes after, in the caller's transaction. */
+  const put = await files.put(decoded.bytes, decoded.type, name, { state: { domain, user, tx } })
+  await tx.getRepository(Attachment).save({
+    domain,
+    creator: user,
+    updater: user,
+    id: put.id,
+    name,
+    mimetype: decoded.type,
+    encoding: 'binary',
+    refType: THUMBNAIL_REF_TYPE,
+    refBy: hash,
+    category: 'image',
+    size: String(put.size),
+    path: put.path,
+    ...(put.contents ? { contents: put.contents } : {})
+  })
+  return hash
+}

package/server/service/figure/figure-thumbnail-upgrade.pg.test.ts

@@ -0,0 +1,93 @@
+import { join } from 'path'
+
+/**
+ * Two starts moving the same install's pictures at once, on postgres (chief architect's ruling 2026-10-02, condition 2:
+ * the same hash written twice must come to the same result). sqlite holds one connection and cannot show this. Runs
+ * only when FIGURE_PG_URL names a server:
+ *
+ *   docker run -d --name fig-revert-pg -e POSTGRES_PASSWORD=figrv -e POSTGRES_USER=figrv -e POSTGRES_DB=figrv \
+ *     -p 55441:5432 postgres:14-alpine
+ *   yarn workspace @things-factory/figure-service build:server
+ *   FIGURE_PG_URL=postgres://figrv:figrv@localhost:55441/figrv \
+ *     node_modules/.bin/jest --selectProjects figure-service-ts --coverage=false figure-thumbnail-upgrade
+ *
+ * Every round must end with every picture moved exactly as it was: each row names its own content's hash, no base64
+ * is left, and every hash has an attachment holding those bytes. A row emptied without its hash, or a hash with no
+ * file, is the defect.
+ */
+
+const url = process.env.FIGURE_PG_URL
+const maybe = url ? describe : describe.skip
+const ROUNDS = 6
+const ROWS = 24
+
+maybe('two starts moving pictures at once, on postgres', () => {
+  /*
+   * attachment-base picks its `contents` column type from `ormconfig.type` when it is loaded; the test process has no
+   * ormconfig, which reads as sqlite's blob. This file alone sees postgres, before anything loads attachment-base.
+   */
+  jest.doMock('@things-factory/env', () => {
+    const real = jest.requireActual('@things-factory/env')
+    return { ...real, config: { ...real.config, get: (key: string, fallback?: unknown) => (key === 'ormconfig' ? { type: 'postgres' } : real.config.get(key, fallback)) } }
+  })
+  const { DataSource } = require('typeorm')
+  const { entityClosure } = require(join(__dirname, '..', '..', '..', '..', 'ops-master', 'test', 'support', 'database.cjs'))
+  const { NamingStrategy } = require('@things-factory/shell/dist-server/initializers/naming-strategy.js')
+  const { Domain } = require('@things-factory/shell')
+  const { Attachment } = require('@things-factory/attachment-base')
+  const DIST = join(__dirname, '..', '..', '..', 'dist-server', 'service', 'figure')
+  const { Figure } = require(join(DIST, 'figure.js'))
+  const { FigureHistory } = require(join(DIST, 'figure-history.js'))
+  const { FigureReplacedDraft } = require(join(DIST, 'figure-replaced-draft.js'))
+  const { moveBase64Thumbnails } = require(join(DIST, 'figure-thumbnail-upgrade.js'))
+  const { sha256Of } = require(join(DIST, 'figure-thumbnail-store.js'))
+
+  const kept = new Map<string, Buffer>()
+  let n = 0
+  const files = {
+    async put(bytes: Buffer, _m: string, name: string) {
+      const id = require('crypto').randomUUID()
+      const path = `${id}.${name.split('.').pop()}`
+      kept.set(path, bytes)
+      n++
+      return { id, path, size: bytes.length }
+    },
+    async send() {}
+  }
+  const open = async (dropSchema: boolean) => {
+    const db = new DataSource({ type: 'postgres', url, synchronize: true, dropSchema, entities: entityClosure([Figure, FigureHistory, FigureReplacedDraft, Attachment]), namingStrategy: new NamingStrategy() })
+    await db.initialize()
+    return db
+  }
+  let one: any, two: any
+  beforeAll(async () => {
+    one = await open(true)
+    two = await open(false)
+  }, 60000)
+  afterAll(async () => {
+    await one?.destroy()
+    await two?.destroy()
+  })
+
+  const picture = (k: number) => `data:image/webp;base64,${Buffer.from([0x52, 0x49, k % 7, k % 5, 9]).toString('base64')}`
+
+  it('every round: each row moved once, to its own hash, with its bytes kept', async () => {
+    for (let round = 0; round < ROUNDS; round++) {
+      const domain = await one.getRepository(Domain).save({ name: `pg-${round}`, subdomain: `pg-${round}` })
+      const ids: string[] = []
+      for (let k = 0; k < ROWS; k++) {
+        const r = await one.createQueryBuilder().insert().into(Figure).values({ type: `T${round}_${k}`, name: 'x', source: '{}', state: 'draft', version: 0, thumbnail: picture(k), domain: { id: domain.id } }).callListeners(false).execute()
+        ids.push(r.identifiers[0].id)
+      }
+      await Promise.all([moveBase64Thumbnails(one, files), moveBase64Thumbnails(two, files)])
+      for (const [k, id] of ids.entries()) {
+        const row = await one.getRepository(Figure).findOneOrFail({ where: { id } })
+        const want = sha256Of(Buffer.from(picture(k).split(',')[1], 'base64'))
+        expect([row.thumbnail, row.thumbnailHash]).toEqual([null, want])
+        const holders = await one.getRepository(Attachment).find({ where: { domain: { id: domain.id }, refType: 'figure-thumbnail', refBy: want } })
+        expect(holders.length).toBeGreaterThan(0)
+        for (const h of holders) expect(sha256Of(kept.get(h.path)!)).toBe(want)
+      }
+    }
+  }, 120000)
+})

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

@@ -0,0 +1,70 @@
+import { IsNull, Not } from 'typeorm'
+
+import { Figure } from './figure.js'
+import { FigureHistory } from './figure-history.js'
+import { FigureReplacedDraft } from './figure-replaced-draft.js'
+import { keepThumbnail, thumbnailFiles, type ThumbnailFiles } from './figure-thumbnail-store.js'
+
+/*
+ * Moves the pictures an install kept as base64 into attachment-base, by their content (ADR-0104 decision 6; chief
+ * architect's ruling 2026-10-02, condition 3). Run at start, in the boot's one line (`inBootTurn`).
+ *
+ *   per row   the file first -- it cannot be rolled back -- then, in one transaction, the attachment row, the hash,
+ *             and the base64 emptied. The update only takes a row whose base64 is still the one read, so two starts
+ *             at once, or a save in between, never empty a picture that was not moved.
+ *   again     safe: a row already moved has no base64 and is not read; a picture already kept is found by its hash.
+ *   kept      a picture that is not a data URL, or a row whose domain cannot be found, keeps its base64 and is
+ *             counted -- nothing is emptied that was not moved.
+ */
+
+type Moved = { table: string; moved: number; kept: number }
+
+const TABLES = [
+  { table: 'figure', entity: Figure },
+  { table: 'figure_history', entity: FigureHistory },
+  { table: 'figure_replaced_draft', entity: FigureReplacedDraft }
+] as const
+
+export async function moveBase64Thumbnails(dataSource: any, files: ThumbnailFiles = thumbnailFiles()): Promise<Moved[]> {
+  const out: Moved[] = []
+  for (const { table, entity } of TABLES) {
+    const rows: any[] = await dataSource.getRepository(entity).find({
+      where: { thumbnail: Not(IsNull()) },
+      relations: { domain: true },
+      select: { id: true, thumbnail: true, domain: { id: true }, ...(entity === FigureHistory ? { originalId: true } : {}) },
+      withDeleted: true
+    })
+    let moved = 0,
+      kept = 0
+    for (const row of rows) {
+      /* A release written before releases carried their domain names it through the figure it belongs to. */
+      const domainId: string | undefined =
+        row.domain?.id ??
+        (entity === FigureHistory && row.originalId
+          ? (await dataSource.getRepository(Figure).findOne({ where: { id: row.originalId }, relations: { domain: true }, select: { id: true, domain: { id: true } }, withDeleted: true }))?.domain?.id
+          : undefined)
+      if (!domainId) {
+        kept++
+        continue
+      }
+      try {
+        await dataSource.transaction(async (tx: any) => {
+          const hash = await keepThumbnail(tx, { id: domainId }, undefined, row.thumbnail, files)
+          await tx
+            .createQueryBuilder()
+            .update(entity)
+            .set({ thumbnailHash: hash, thumbnail: null })
+            .where('id = :id AND thumbnail = :was', { id: row.id, was: row.thumbnail })
+            .callListeners(false)
+            .execute()
+        })
+        moved++
+      } catch (error) {
+        console.error(`[figure-service] ${table} ${row.id} 의 썸네일을 옮기지 못했다 — base64 를 그대로 둔다: ${(error as Error)?.message ?? error}`)
+        kept++
+      }
+    }
+    out.push({ table, moved, kept })
+  }
+  return out
+}

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-write.ts

@@ -1,3 +1,4 @@
+import { keepThumbnail, type ThumbnailFiles } from './figure-thumbnail-store.js'
 import { GraphQLError } from 'graphql'
 import { parseFigureAsset, serializeFigureAsset, compileFigureAsset, figureCostOf, figureScoreOf } from '@hatiolab/figure-model'
 
@@ -48,13 +49,23 @@ export function prepareFigureWrite(source: string, existing?: { source?: string
 }
 
 /**
- * The picture a card shows, when the modeller sent one.
+ * The picture a card shows, when the modeller sent one: kept by its content (`keepThumbnail`) and named on the row by
+ * its hash.
  *
  * 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() }
+export async function pictureOf(
+  tx: { getRepository: (target: any) => any },
+  domain: { id: string },
+  user: unknown,
+  thumbnail?: string,
+  existing?: { thumbnailHash?: string | null },
+  files?: ThumbnailFiles
+): Promise<{ thumbnailHash?: string; thumbnail?: null; thumbnailUpdatedAt?: Date }> {
+  if (thumbnail === undefined) return {}
+  const thumbnailHash = await keepThumbnail(tx, domain, user, thumbnail, files)
+  if (thumbnailHash === existing?.thumbnailHash) return {}
+  return { thumbnailHash, thumbnail: null, thumbnailUpdatedAt: new Date() }
 }