@things-factory/figure-service 10.1.111 → 10.1.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.111",
+  "version": "10.1.112",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -28,6 +28,7 @@
     "@hatiolab/figure-model": "^0.2.10",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.81",
+    "@things-factory/attachment-base": "^10.1.112",
     "@things-factory/auth-base": "^10.1.111",
     "@things-factory/env": "^10.1.20",
     "@things-factory/shell": "^10.1.106",
@@ -35,5 +36,5 @@
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "f33122c15e5b3e45393129e9418e2c367a273ade"
+  "gitHead": "e300d1b60b98ccb80380afe8df6d2807b1bcff91"
 }

package/server/index.ts

@@ -20,6 +20,21 @@ process.on('bootstrap-module-start' as any, () => {
   console.log(`[figure-service:bootstrap] recipe templates ${templates.length}${refused.length ? `, left out: ${refused.join(' | ')}` : ''}`)
 })
 
+/*
+ * The pictures an install kept as base64 move into attachment-base by their content, once, at start (ADR-0104 decision
+ * 6). In the boot's one line: it writes, and sqlite holds one runner. A failure is said and the server goes on.
+ */
+import { getDataSource, inBootTurn } from '@things-factory/shell'
+import { moveBase64Thumbnails } from './service/figure/figure-thumbnail-upgrade.js'
+process.on('bootstrap-module-start' as any, () => {
+  inBootTurn(() => moveBase64Thumbnails(getDataSource()))
+    .then(moved => {
+      const any = moved.filter(m => m.moved || m.kept)
+      if (any.length) console.log(`[figure-service:bootstrap] thumbnails moved: ${any.map(m => `${m.table} ${m.moved}${m.kept ? ` (kept as base64: ${m.kept})` : ''}`).join(', ')}`)
+    })
+    .catch(error => console.error(`[figure-service] 썸네일을 옮기지 못했다 — ${error?.message ?? error}`))
+})
+
 export * from './service/index.js'
 export * from './migrations/index.js'
 export { registerFigureToolCategories } from './service/figure/figure-tools.js'

package/server/routers/figure-thumbnail-router.ts

@@ -7,6 +7,7 @@ import { getRepository } from '@things-factory/shell'
 import { readFileSync } from 'fs'
 
 import { Figure } from '../service/figure/figure.js'
+import { thumbnailAttachmentOf, thumbnailFiles, type ThumbnailFiles } from '../service/figure/figure-thumbnail-store.js'
 import { recipeTemplates } from '../service/figure-recipe/figure-recipe-templates.js'
 
 /**
@@ -14,7 +15,7 @@ import { recipeTemplates } from '../service/figure-recipe/figure-recipe-template
  *
  * ## 왜 필요한가
  *
- * 썸네일은 base64 문자열로 칸에 들어 있다(`Board.thumbnail` 과 같은 방식). 그것을 목록 질의가
+ * 썸네일은 attachment-base 가 내용 해시로 갖는다(ADR-0104 결정 6). 옛날에는 base64 문자열로 칸에 있었고, 그것을 목록 질의가
  * 함께 실어 오면 카탈로그를 열 때마다 그림 전부가 JSON 안에 담겨 다시 온다 — data URL 은
  * 브라우저가 캐시할 수 없다. [확인함] 표본 14개에 227KB, 한 장 최대 20KB.
  *
@@ -29,21 +30,11 @@ import { recipeTemplates } from '../service/figure-recipe/figure-recipe-template
  *      `/thumbnail/:id` 로 두면 먼저 등록된 쪽이 이기고, 남의 표에서 id 를 찾아 404 를 낸다.
  *   2. **행 전체를 읽는다.** board 는 `findOneBy` 로 행을 다 읽는다. figure 행에는 정본(`source`)이
  *      붙어 있어, 그림 한 장에 정본까지 읽게 된다. 필요한 칸만 고른다.
- *   3. **png 로 못 박는다.** figure 썸네일은 webp 다(모델러가 그렇게 만든다). data URL 이 스스로
- *      말하는 형식을 쓴다 — 못 박으면 브라우저가 확장자와 다른 바이트를 받는다.
+ *   3. **png 로 못 박는다.** figure 썸네일은 webp 다(모델러가 그렇게 만든다). 저장할 때 data URL 이 스스로
+ *      말한 형식을 attachment 의 mimetype 으로 쓴다 — 못 박으면 브라우저가 확장자와 다른 바이트를 받는다.
  */
 export const figureThumbnailRouter = new Router()
 
-/** `data:image/webp;base64,....` → 형식과 바이트. 아니면 undefined. */
-function decodeDataUrl(dataUrl: string): { type: string; buffer: Buffer } | undefined {
-  const matched = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrl)
-  if (!matched) {
-    return undefined
-  }
-
-  return { type: matched[1], buffer: Buffer.from(matched[2], 'base64') }
-}
-
 figureThumbnailRouter.get('/figure-thumbnail/:id', async (context, next) => {
   const { domain, user, unsafeIP, prohibitedPrivileges } = context.state
 
@@ -71,46 +62,59 @@ figureThumbnailRouter.get('/figure-thumbnail/:id', async (context, next) => {
     return
   }
 
-  const { id } = context.params
+  await sendFigureThumbnail(context, next, context.params.id, domain)
+})
 
+/**
+ * The picture of a figure the caller may read, by its hash (ADR-0104 decision 6). Exported for tests, which give
+ * their own `files`.
+ */
+export async function sendFigureThumbnail(
+  context: any,
+  next: () => Promise<any>,
+  id: string,
+  domain: { id: string; parentId?: string },
+  files: ThumbnailFiles = thumbnailFiles()
+): Promise<void> {
   /*
     읽기는 부모 도메인까지 본다 — `figure` 질의와 같은 범위다. 물려받은 형상을 목록에는 보여 주고
     그림만 404 를 내면, 화면은 「그림이 아직 없다」고 거짓말하게 된다.
   */
   const found = await getRepository(Figure).findOne({
     where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, id },
-    select: { id: true, thumbnail: true, thumbnailUpdatedAt: true }
+    relations: { domain: true },
+    select: { id: true, thumbnailHash: true, thumbnailUpdatedAt: true, domain: { id: true } }
   })
-
-  const decoded = found?.thumbnail ? decodeDataUrl(found.thumbnail) : undefined
-
-  if (!decoded) {
+  if (!found?.thumbnailHash) {
     context.status = 404
     return
   }
 
   /*
-    **개인 캐시만 허락한다.** 이 그림은 권한을 본 뒤에 내주는 것이므로 공용 캐시(프록시)에 남으면
-    안 된다. 부르는 쪽이 `?v=` 로 판을 가리므로 오래 두어도 낡은 그림이 남지 않고, `v` 없이 부른
-    경우를 위해 시각을 함께 실어 다시 물어볼 수 있게 한다.
+    그림은 **그 figure 의 도메인**에서 찾는다 — 묻는 도메인이 아니다(판정 조건 4). 해시가 같아도 다른 도메인의 행을
+    집지 않는다. 물려받은 figure 의 그림은 부모 도메인에 있다.
   */
-  const stamp = found!.thumbnailUpdatedAt
+  const picture = await thumbnailAttachmentOf({ getRepository }, found.domain!.id, found.thumbnailHash)
+  if (!picture) {
+    context.status = 404
+    return
+  }
 
-  context.type = decoded.type
+  /*
+    **개인 캐시만 허락한다.** 이 그림은 권한을 본 뒤에 내주는 것이므로 공용 캐시(프록시)에 남으면 안 된다 —
+    attachment 의 공개 경로가 쓰는 `public` 을 따라 쓰지 않는다(판정 조건 1). 같은 내용은 같은 해시이므로 ETag 가
+    곧 내용이다. 부르는 쪽이 `?v=` 로 판을 가리므로 오래 두어도 낡은 그림이 남지 않는다.
+  */
+  context.type = picture.mimetype
   context.set('Cache-Control', 'private, max-age=31536000')
-  if (stamp) {
-    context.set('Last-Modified', new Date(stamp).toUTCString())
-    context.set('ETag', `"${new Date(stamp).getTime()}"`)
-
-    /* 브라우저가 가진 것이 아직 그것이면 바이트를 보내지 않는다. */
-    if (context.fresh) {
-      context.status = 304
-      return
-    }
+  context.set('ETag', `"${found.thumbnailHash}"`)
+  if (found.thumbnailUpdatedAt) context.set('Last-Modified', new Date(found.thumbnailUpdatedAt).toUTCString())
+  if (context.fresh) {
+    context.status = 304
+    return
   }
-
-  context.body = decoded.buffer
-})
+  await files.send(context, picture.path!, next)
+}
 
 /**
  * A recipe template's thumbnail (ADR-0095 amended): the file drawn from its model, served behind the same door as the

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

@@ -80,6 +80,15 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   @Field({ nullable: true, description: 'The thumbnail as it looked at this version.' })
   thumbnail?: string
 
+  /*
+   * 그림의 내용 해시(SHA-256). 그림 자체는 attachment-base 가 갖고(refType `figure-thumbnail`, refBy 이 해시),
+   * `/figure-thumbnail/:id` 가 권한을 본 뒤 내준다(ADR-0104 결정 6). `thumbnail` 칸은 옛 base64 가 남은 행을
+   * 기동 때 옮기기 위한 칸이다 — 옮긴 뒤에는 비어 있고, 새 그림은 그 칸에 쓰지 않는다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'SHA-256 of the thumbnail picture; the picture is served by /figure-thumbnail/:id.' })
+  thumbnailHash?: string
+
   /*
    * 그때의 비용이다. 오늘 다시 계산하면 오늘의 형식으로 나온다 — 그 판을 설명하지 못한다.
    */

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

@@ -65,7 +65,7 @@ export class FigureMutation {
     if (!id) {
       if (!creationId || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(creationId))
         throw Error('새 모델 저장에는 생성 요청 식별자가 필요합니다.')
-      const prepared = { ...prepareFigureWrite(source), ...pictureOf(thumbnail) }
+      const prepared = { ...prepareFigureWrite(source), ...(await pictureOf(tx, domain, user, thumbnail)) }
       const previous = await repository.findOne({ where: { id: creationId, domain: { id: domain.id } } })
       if (previous) {
         if (previous.source !== prepared.source) throw Error('이 생성 요청은 이미 다른 내용으로 저장되었습니다. 저장된 모델을 다시 열어 주세요.')
@@ -100,7 +100,7 @@ export class FigureMutation {
     // Exact tenant ownership: an inherited catalog entry is not writable in the child domain.
     const figure = await repository.findOne({ where: { id, domain: { id: domain.id } } })
     if (!figure) throw Error('편집할 Figure를 찾을 수 없습니다.')
-    const prepared = { ...prepareFigureWrite(source, figure, expectedSource), ...pictureOf(thumbnail, figure) }
+    const prepared = { ...prepareFigureWrite(source, figure, expectedSource), ...(await pictureOf(tx, domain, user, thumbnail, figure)) }
     // Compare-and-swap in the UPDATE itself: supported by SQLite as well as PostgreSQL.
     // A pessimistic row lock is not supported by the product's SQLite deployment.
     await compareAndSwapFigure(criteria => repository.update(criteria, { ...prepared, updater: user }),
@@ -128,12 +128,13 @@ export class FigureMutation {
     // 형식을 어기면 여기서 던진다. 파생값은 서버가 계산한다.
     const { source, derived, violations } = parseSource(figure.source)
 
+    const { thumbnail, ...rest } = figure
     const saved = await repository.save({
-      ...figure,
+      ...rest,
       source,
       ...derived,
       state: figure.state ?? 'draft',
-      thumbnailUpdatedAt: figure.thumbnail ? new Date() : undefined,
+      ...(await pictureOf(tx, domain, user, thumbnail)),
       domain,
       creator: user,
       updater: user
@@ -184,6 +185,9 @@ export class FigureMutation {
       행이 다른 이름을 말하고, 발행할 때 어느 쪽이 도면에 적히는지가 갈린다.
     */
     if (patch.names !== undefined) assertNames(patch.names)
+    /* The picture is kept by its content; the patch's data URL is never written to the row. */
+    const { thumbnail: picturePatch, ...patchRest } = patch
+    const picture = await pictureOf(tx, domain, user, picturePatch, figure)
 
     let renamed: string | undefined
     if (patch.type !== undefined && patch.type !== figure.type) {
@@ -206,7 +210,7 @@ export class FigureMutation {
       */
       domain,
       ...figure,
-      ...patch,
+      ...patchRest,
       /* 앞뒤 공백을 떼고 겹침까지 본 이름. `patch.type` 을 그대로 두면 다듬기 전 값이 들어간다. */
       ...(renamed !== undefined ? { type: renamed } : {}),
       source,
@@ -220,10 +224,8 @@ export class FigureMutation {
       state: 'draft',
       ...(derived ?? {}),
       // 썸네일이 **썸네일로서** 바뀐 때만 시각을 갱신한다. 이름·설명 변경에는 안 건드린다.
-      thumbnailUpdatedAt:
-        patch.thumbnail !== undefined && patch.thumbnail !== figure.thumbnail
-          ? new Date()
-          : figure.thumbnailUpdatedAt,
+      thumbnail: figure.thumbnail ?? null,
+      ...picture,
       updater: user
     })
 

package/server/service/figure/figure-replaced-draft.ts

@@ -47,6 +47,15 @@ export class FigureReplacedDraft {
   @Column({ nullable: true, ...longTextColumn() })
   thumbnail?: string
 
+  /*
+   * 그림의 내용 해시(SHA-256). 그림 자체는 attachment-base 가 갖고(refType `figure-thumbnail`, refBy 이 해시),
+   * `/figure-thumbnail/:id` 가 권한을 본 뒤 내준다(ADR-0104 결정 6). `thumbnail` 칸은 옛 base64 가 남은 행을
+   * 기동 때 옮기기 위한 칸이다 — 옮긴 뒤에는 비어 있고, 새 그림은 그 칸에 쓰지 않는다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'SHA-256 of the thumbnail picture; the picture is served by /figure-thumbnail/:id.' })
+  thumbnailHash?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'The state the figure was in.' })
   state?: string

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)
+  })
+})