@things-factory/figure-service 10.1.81 → 10.1.82

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

@@ -0,0 +1,159 @@
+/**
+ * Reverting keeps the draft it writes over -- on sqlite, for real (ADR-0097 §5.6, designer 2026-09-27; chief architect's
+ * ruling on the storage). One transaction, one request one revert, an undo only while nothing changed since.
+ */
+import type { DataSource, EntityManager } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+const { createFigureAsset, addFigureBox, serializeFigureAsset } = require('@hatiolab/figure-model')
+
+let dataSource: DataSource | null = null
+let Figure: any
+let FigureHistory: any
+let FigureReplacedDraft: any
+let revertKeepingDraft: any
+let undoRevert: any
+let replacedDraftsOf: any
+
+function loadCompiled(modulePath: string): any {
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+  const resolved = join(__dirname, '..', '..', '..', 'dist-server', `${modulePath}.js`)
+  if (!existsSync(resolved))
+    throw new Error(`figure-service 산출물이 없다: ${resolved}\n먼저 빌드할 것:\n  yarn workspace @things-factory/figure-service build:server`)
+  return require(resolved)
+}
+
+beforeAll(async () => {
+  Figure = loadCompiled('service/figure/figure').Figure
+  FigureHistory = loadCompiled('service/figure/figure-history').FigureHistory
+  FigureReplacedDraft = loadCompiled('service/figure/figure-replaced-draft').FigureReplacedDraft
+  ;({ revertKeepingDraft, undoRevert, replacedDraftsOf } = loadCompiled('service/figure/figure-revert'))
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory, FigureReplacedDraft],
+    logging: false
+  })
+  await dataSource.initialize()
+})
+
+afterAll(async () => {
+  await dataSource?.destroy()
+  dataSource = null
+})
+
+let DOMAIN: { id: string }
+const text = (name: string, height = 100) =>
+  serializeFigureAsset(addFigureBox(createFigureAsset(name), { id: 'body', size: { x: 100, y: height, z: 100 }, position: { x: 0, y: height / 2, z: 0 } }))
+const V1 = text('Released one', 100)
+const DRAFT = text('Draft after it', 300)
+
+beforeEach(async () => {
+  await dataSource!.synchronize(true)
+  DOMAIN = { id: (await dataSource!.getRepository(shell.Domain).save({ name: 'revert-probe', subdomain: 'revert-probe' })).id }
+})
+
+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 })
+  return figure
+}
+const uuid = () => require('crypto').randomUUID()
+const inTx = <T>(work: (tx: EntityManager) => Promise<T>) => dataSource!.transaction(work)
+const row = async (id: string) => dataSource!.getRepository(Figure).findOneOrFail({ where: { id } })
+const kept = async () => dataSource!.getRepository(FigureReplacedDraft).find()
+
+describe('a revert keeps the draft it writes over', () => {
+  it('keeps the whole draft, apart from the releases, and writes the version over it', async () => {
+    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')
+    const [one] = await kept()
+    expect(one.source).toBe(DRAFT)
+    expect(one.thumbnail).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. */
+    expect(await dataSource!.getRepository(FigureHistory).count()).toBe(1)
+    /* Found again from the store, as after a reload. */
+    expect((await inTx(tx => replacedDraftsOf(tx, DOMAIN, figure.id))).map((k: any) => k.id)).toEqual([one.id])
+  })
+
+  it('keeps nothing and writes nothing when the write fails -- one transaction', async () => {
+    const figure = await figureWithRelease()
+    /* The figure changes after the check but before the write: the conditional write finds no row, and all rolls back. */
+    await expect(
+      inTx(async tx => {
+        const repo = tx.getRepository(Figure)
+        const update = repo.update.bind(repo)
+        repo.update = async (where: any, set: any) => (await tx.query(`UPDATE figures SET source = 'moved' WHERE id = ?`, [figure.id]), update(where, set))
+        const real = tx.getRepository.bind(tx)
+        tx.getRepository = ((target: any) => (target === Figure ? repo : real(target))) as any
+        return revertKeepingDraft(tx, DOMAIN, undefined, { id: figure.id, version: 1, requestId: uuid(), expectedSource: DRAFT })
+      })
+    ).rejects.toMatchObject({ extensions: { code: 'FIGURE_SOURCE_CONFLICT' } })
+    expect(await kept()).toEqual([])
+    expect((await row(figure.id)).source).toBe(DRAFT)
+  })
+
+  it('refuses a revert of a figure changed since it was seen, and keeps nothing', async () => {
+    const figure = await figureWithRelease()
+    await expect(inTx(tx => revertKeepingDraft(tx, DOMAIN, undefined, { id: figure.id, version: 1, requestId: uuid(), expectedSource: 'stale' }))).rejects.toMatchObject({
+      extensions: { code: 'FIGURE_SOURCE_CONFLICT' }
+    })
+    expect(await kept()).toEqual([])
+  })
+
+  it('one request, one revert: asked again, the same answer, nothing kept or written twice', async () => {
+    const figure = await figureWithRelease()
+    const requestId = uuid()
+    const first = await inTx(tx => revertKeepingDraft(tx, DOMAIN, undefined, { id: figure.id, version: 1, requestId, expectedSource: DRAFT }))
+    /* The answer was lost; asked again with what the reverter still believes. */
+    const again = await inTx(tx => revertKeepingDraft(tx, DOMAIN, undefined, { id: figure.id, version: 1, requestId, expectedSource: DRAFT }))
+    expect(again.kept.id).toBe(first.kept.id)
+    expect(await kept()).toHaveLength(1)
+    /* The same id for another revert is refused. */
+    await expect(inTx(tx => revertKeepingDraft(tx, DOMAIN, undefined, { id: figure.id, version: 2, requestId, expectedSource: DRAFT }))).rejects.toMatchObject({
+      extensions: { code: 'FIGURE_REVERT_REQUEST' }
+    })
+  })
+})
+
+describe('an undo brings the kept draft back only while nothing changed since', () => {
+  it('brings it back, keeping what it replaces; asked again, the same undo', async () => {
+    const figure = await figureWithRelease()
+    const reverted = await inTx(tx => revertKeepingDraft(tx, DOMAIN, undefined, { id: figure.id, version: 1, requestId: uuid(), expectedSource: DRAFT }))
+    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')
+    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()
+    /* The answer lost: the same undo again changes nothing more. */
+    await inTx(tx => undoRevert(tx, DOMAIN, undefined, { keptId: reverted.kept.id, requestId }))
+    expect(await kept()).toHaveLength(2)
+    /* Another request for a draft already back is refused. */
+    await expect(inTx(tx => undoRevert(tx, DOMAIN, undefined, { keptId: reverted.kept.id, requestId: uuid() }))).rejects.toMatchObject({ extensions: { code: 'FIGURE_KEPT_RESTORED' } })
+  })
+
+  it('refuses when the figure was edited after the revert, and the kept draft stays', async () => {
+    const figure = await figureWithRelease()
+    const reverted = await inTx(tx => revertKeepingDraft(tx, DOMAIN, undefined, { id: figure.id, version: 1, requestId: uuid(), expectedSource: DRAFT }))
+    await dataSource!.getRepository(Figure).update({ id: figure.id }, { source: text('Edited after', 500) })
+    await expect(inTx(tx => undoRevert(tx, DOMAIN, undefined, { keptId: reverted.kept.id, requestId: uuid() }))).rejects.toMatchObject({
+      extensions: { code: 'FIGURE_SOURCE_CONFLICT' }
+    })
+    expect(JSON.parse((await row(figure.id)).source).name).toBe('Edited after')
+    const records = await kept()
+    expect(records).toHaveLength(1)
+    expect(records[0].restoredAt).toBeFalsy()
+  })
+})

package/server/service/figure/figure-revert-race.pg.test.ts

@@ -0,0 +1,168 @@
+import { join } from 'path'
+
+/**
+ * Reverting, undoing and saving at the same moment, on postgres (ADR-0097 §5.6; the chief architect asked for this
+ * before the revert is turned back on in the screen).
+ *
+ * sqlite holds one connection and cannot run two transactions side by side, so it says nothing about this. This needs
+ * a real server, and runs only when FIGURE_PG_URL names one:
+ *
+ *   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-revert-race
+ *
+ * Each round must end one way: one of the two won, the other was refused by name, and what was replaced is kept
+ * exactly once. Both succeeding, a draft replaced without being kept, or a kept draft for a revert that did not
+ * happen is the defect.
+ */
+
+const url = process.env.FIGURE_PG_URL
+const maybe = url ? describe : describe.skip
+const ROUNDS = 40
+
+maybe('reverting at once, on postgres', () => {
+  const { DataSource } = require('typeorm')
+  const { randomUUID } = require('crypto')
+  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 { createFigureAsset, addFigureBox, serializeFigureAsset } = require('@hatiolab/figure-model')
+  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 { revertKeepingDraft, undoRevert } = require(join(DIST, 'figure-revert.js'))
+  const { compareAndSwapFigure } = require(join(DIST, 'figure-write.js'))
+
+  let db: any
+  let domain: { id: string }
+
+  const text = (name: string, height: number) =>
+    serializeFigureAsset(addFigureBox(createFigureAsset(name), { id: 'body', size: { x: 100, y: height, z: 100 }, position: { x: 0, y: height / 2, z: 0 } }))
+  const V1 = text('Released one', 100)
+  const DRAFT = text('Draft after it', 300)
+  const EDIT = text('Saved meanwhile', 500)
+
+  beforeAll(async () => {
+    db = new DataSource({
+      type: 'postgres',
+      url,
+      synchronize: true,
+      dropSchema: true,
+      entities: entityClosure([Figure, FigureHistory, FigureReplacedDraft]),
+      namingStrategy: new NamingStrategy()
+    })
+    await db.initialize()
+    domain = { id: (await db.getRepository(Domain).save({ name: 'race', subdomain: 'race' })).id }
+  }, 60000)
+
+  afterAll(async () => db?.destroy())
+
+  const aFigure = async (round: number) => {
+    const figure = await db.getRepository(Figure).save({ type: `RACE_${round}`, name: `race ${round}`, source: DRAFT, state: 'draft', version: 1, domain })
+    await db.getRepository(FigureHistory).save({ originalId: figure.id, version: 1, type: figure.type, name: figure.name, source: V1, state: 'released', domain })
+    return figure
+  }
+  const revert = (figure: any, requestId = randomUUID()) =>
+    db.transaction((tx: any) => revertKeepingDraft(tx, domain, undefined, { id: figure.id, version: 1, requestId, expectedSource: DRAFT }))
+  const undo = (keptId: string, requestId = randomUUID()) => db.transaction((tx: any) => undoRevert(tx, domain, undefined, { keptId, requestId }))
+  const save = (figure: any, expected: string) =>
+    db.transaction((tx: any) => compareAndSwapFigure((criteria: any) => tx.getRepository(Figure).update(criteria, { source: EDIT }), figure.id, domain.id, expected))
+
+  const sourceOf = async (figure: any) => (await db.getRepository(Figure).findOneOrFail({ where: { id: figure.id } })).source
+  const keptOf = (figure: any) => db.getRepository(FigureReplacedDraft).find({ where: { figureId: figure.id } })
+  /* A few milliseconds either way, so each side wins some rounds -- the revert does more before its write. */
+  const later = <T>(work: () => Promise<T>) => new Promise<T>((done, fail) => setTimeout(() => work().then(done, fail), Math.random() * 12))
+  const codeOf = (settled: PromiseSettledResult<any>) => (settled.status === 'rejected' ? settled.reason?.extensions?.code ?? String(settled.reason) : 'ok')
+
+  it('two reverts of the same draft: one reverts and keeps it once, the other is refused', async () => {
+    for (let round = 0; round < ROUNDS; round++) {
+      const figure = await aFigure(round)
+      const results = await Promise.allSettled([revert(figure), revert(figure)])
+      expect(results.map(codeOf).sort()).toEqual(['FIGURE_SOURCE_CONFLICT', 'ok'])
+      expect(await sourceOf(figure)).toBe(V1)
+      const kept = await keptOf(figure)
+      expect(kept).toHaveLength(1)
+      expect(kept[0].source).toBe(DRAFT)
+    }
+  }, 60000)
+
+  it('the same revert sent twice at once: it happens once, and asked again later answers with it', async () => {
+    for (let round = 0; round < ROUNDS; round++) {
+      const figure = await aFigure(ROUNDS + round)
+      const requestId = randomUUID()
+      const results = await Promise.allSettled([revert(figure, requestId), revert(figure, requestId)])
+      /* The second either found the first's revert, or met it in flight and was told so -- never a second revert. */
+      for (const code of results.map(codeOf)) expect(['ok', 'FIGURE_REVERT_IN_FLIGHT']).toContain(code)
+      expect(results.map(codeOf)).toContain('ok')
+      const kept = await keptOf(figure)
+      expect(kept).toHaveLength(1)
+      expect(await sourceOf(figure)).toBe(V1)
+      expect((await revert(figure, requestId)).kept.id).toBe(kept[0].id)
+    }
+  }, 60000)
+
+  it('a revert and a save at once: one wins; a lost revert keeps nothing', async () => {
+    const wins: string[] = []
+    for (let round = 0; round < ROUNDS; round++) {
+      const figure = await aFigure(2 * ROUNDS + round)
+      const [reverted, saved] = await Promise.allSettled([revert(figure), later(() => save(figure, DRAFT))])
+      const kept = await keptOf(figure)
+      if (reverted.status === 'fulfilled') {
+        expect(codeOf(saved)).toBe('FIGURE_SOURCE_CONFLICT')
+        expect(await sourceOf(figure)).toBe(V1)
+        expect(kept.map((k: any) => k.source)).toEqual([DRAFT])
+        wins.push('revert')
+      } else {
+        expect(codeOf(reverted)).toBe('FIGURE_SOURCE_CONFLICT')
+        expect(saved.status).toBe('fulfilled')
+        expect(await sourceOf(figure)).toBe(EDIT)
+        expect(kept).toEqual([])
+        wins.push('save')
+      }
+    }
+    /* Both endings must be seen, or one branch above was never checked. */
+    expect(new Set(wins)).toEqual(new Set(['revert', 'save']))
+  }, 60000)
+
+  it('an undo and a save at once: one wins; the kept draft stays until an undo succeeds', async () => {
+    const wins: string[] = []
+    for (let round = 0; round < ROUNDS; round++) {
+      const figure = await aFigure(3 * ROUNDS + round)
+      const { kept } = await revert(figure)
+      const [undone, saved] = await Promise.allSettled([undo(kept.id), later(() => save(figure, V1))])
+      const records = await keptOf(figure)
+      const original = records.find((k: any) => k.id === kept.id)
+      if (undone.status === 'fulfilled') {
+        expect(codeOf(saved)).toBe('FIGURE_SOURCE_CONFLICT')
+        expect(await sourceOf(figure)).toBe(DRAFT)
+        expect(original.restoredAt).toBeTruthy()
+        expect(records.filter((k: any) => k.kind === 'undo').map((k: any) => k.source)).toEqual([V1])
+        wins.push('undo')
+      } else {
+        expect(codeOf(undone)).toBe('FIGURE_SOURCE_CONFLICT')
+        expect(saved.status).toBe('fulfilled')
+        expect(await sourceOf(figure)).toBe(EDIT)
+        expect(original.restoredAt).toBeFalsy()
+        expect(records.filter((k: any) => k.kind === 'undo')).toEqual([])
+        wins.push('save')
+      }
+    }
+    expect(new Set(wins)).toEqual(new Set(['undo', 'save']))
+  }, 60000)
+
+  it('two undos of the same kept draft: it comes back once', async () => {
+    for (let round = 0; round < ROUNDS; round++) {
+      const figure = await aFigure(4 * ROUNDS + round)
+      const { kept } = await revert(figure)
+      const results = await Promise.allSettled([undo(kept.id), undo(kept.id)])
+      const codes = results.map(codeOf)
+      expect(codes.filter(code => code === 'ok')).toHaveLength(1)
+      for (const code of codes) expect(['ok', 'FIGURE_SOURCE_CONFLICT', 'FIGURE_KEPT_RESTORED']).toContain(code)
+      expect(await sourceOf(figure)).toBe(DRAFT)
+      expect((await keptOf(figure)).filter((k: any) => k.kind === 'undo')).toHaveLength(1)
+    }
+  }, 60000)
+})

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

@@ -0,0 +1,181 @@
+import { createHash } from 'crypto'
+import { In, type EntityManager } from 'typeorm'
+import { GraphQLError } from 'graphql'
+
+import { Figure } from './figure.js'
+import { FigureHistory } from './figure-history.js'
+import { FigureReplacedDraft } from './figure-replaced-draft.js'
+import { parseSource } from './figure-format.js'
+import { sourceConflict } from './figure-write.js'
+
+/*
+ * Reverting a figure to a released version, keeping the draft it writes over (ADR-0097 §5.6, designer 2026-09-27;
+ * chief architect's ruling on the storage the same day).
+ *
+ * - One transaction: the draft is kept, then the figure is written over -- conditional on it being what the reverter
+ *   saw (`expectedSource`). If either fails, neither stays: the caller's transaction is rolled back.
+ * - One request, one revert: `requestId` is unique in the domain. A retry -- the answer lost -- finds the revert it
+ *   asked for and answers with it; nothing is kept or written twice.
+ * - An undo brings a kept draft back only while the figure still holds exactly what that revert wrote
+ *   (`WHERE id = ? AND source = ?`, as a save's compare-and-swap); edited since, it is refused and the kept draft stays.
+ *   It keeps what it replaces the same way.
+ *
+ * Every function here runs on the caller's transaction (`tx`); the resolvers open it (`@transaction`).
+ */
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const hashOf = (text: string) => createHash('sha256').update(text).digest('hex')
+const refused = (code: string, message: string) => new GraphQLError(message, { extensions: { code } })
+
+/*
+ * The same request arriving twice at once: the second waits on the first's requestId and then meets the unique index.
+ * Named, not a raw database error -- asked again after the first has finished, it gets the first's answer.
+ */
+async function keep(kept: { save: (row: any) => Promise<any> }, row: any) {
+  try {
+    return await kept.save(row)
+  } catch (error: any) {
+    const unique = error?.code === '23505' || error?.driverError?.code === '23505' || /UNIQUE constraint failed/.test(String(error?.message))
+    if (unique) throw refused('FIGURE_REVERT_IN_FLIGHT', '같은 요청이 처리 중입니다. 잠시 뒤 다시 확인해 주세요.')
+    throw error
+  }
+}
+
+export interface RevertRequest {
+  id: string
+  version: number
+  requestId: string
+  /** The figure's source as the reverter saw it; the revert goes on only while the figure still holds it. */
+  expectedSource: string
+}
+
+export async function revertKeepingDraft(
+  tx: EntityManager,
+  domain: { id: string; parentId?: string | null },
+  user: { id: string } | undefined,
+  request: RevertRequest
+) {
+  if (!UUID.test(request.requestId ?? '')) throw refused('FIGURE_REVERT_REQUEST', '되돌리기 요청 식별자가 필요합니다.')
+  const figures = tx.getRepository(Figure)
+  const kept = tx.getRepository(FigureReplacedDraft)
+
+  /* The same request again: the revert it made, answered again. */
+  const before = await kept.findOne({ where: { domain: { id: domain.id }, requestId: request.requestId } })
+  if (before) {
+    if (before.figureId !== request.id || before.revertedToVersion !== request.version || before.kind !== 'revert')
+      throw refused('FIGURE_REVERT_REQUEST', '이 되돌리기 요청 식별자는 다른 되돌리기에 이미 쓰였습니다.')
+    return { figure: await figures.findOneOrFail({ where: { id: request.id, domain: { id: domain.id } } }), violations: [], kept: before }
+  }
+
+  /* Exact tenant ownership, as a save: an inherited figure is not written from a child domain. */
+  const figure = await figures.findOne({ where: { id: request.id, domain: { id: domain.id } } })
+  if (!figure) throw refused('FIGURE_NOT_FOUND', `Figure ${request.id} 를 찾을 수 없습니다.`)
+  if (figure.source !== request.expectedSource) throw sourceConflict('다른 편집에서 모델이 변경되었습니다. 최신 모델을 다시 연 뒤 되돌려 주세요.')
+
+  const history = await tx.getRepository(FigureHistory).findOne({
+    where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean) as string[]) }, originalId: request.id, version: request.version }
+  })
+  if (!history) throw refused('FIGURE_VERSION_NOT_FOUND', `Figure '${figure.type}' 에 ${request.version} 판이 없습니다.`)
+  /* The format is checked again: an old version may break today's rules, and is not let in quietly. */
+  const { source, derived, violations } = parseSource(history.source)
+
+  const record = await keep(kept, {
+    domain: { id: domain.id },
+    figureId: figure.id,
+    kind: 'revert' as const,
+    source: figure.source,
+    properties: figure.properties,
+    thumbnail: figure.thumbnail,
+    state: figure.state,
+    version: figure.version,
+    revertedToVersion: request.version,
+    writtenSource: source,
+    writtenSourceHash: hashOf(source),
+    requestId: request.requestId,
+    ...(user ? { creator: { id: user.id } } : {})
+  })
+
+  const written = await figures.update(
+    { id: figure.id, domain: { id: domain.id }, source: request.expectedSource },
+    {
+      source,
+      ...derived,
+      properties: history.properties,
+      thumbnail: history.thumbnail,
+      thumbnailUpdatedAt: history.thumbnail === figure.thumbnail ? figure.thumbnailUpdatedAt : new Date(),
+      state: 'draft',
+      ...(user ? { updater: { id: user.id } } : {})
+    }
+  )
+  if (written.affected !== 1) throw sourceConflict('다른 편집에서 모델이 변경되었습니다. 최신 모델을 다시 연 뒤 되돌려 주세요.')
+
+  return { figure: await figures.findOneOrFail({ where: { id: figure.id, domain: { id: domain.id } } }), violations, kept: record }
+}
+
+/** Brings a kept draft back -- only while the figure holds exactly what that revert wrote. */
+export async function undoRevert(
+  tx: EntityManager,
+  domain: { id: string },
+  user: { id: string } | undefined,
+  request: { keptId: string; requestId: string }
+) {
+  if (!UUID.test(request.requestId ?? '')) throw refused('FIGURE_REVERT_REQUEST', '되돌리기 취소 요청 식별자가 필요합니다.')
+  const figures = tx.getRepository(Figure)
+  const kept = tx.getRepository(FigureReplacedDraft)
+
+  const record = await kept.findOne({ where: { id: request.keptId, domain: { id: domain.id } } })
+  if (!record) throw refused('FIGURE_KEPT_NOT_FOUND', '되살릴 초안을 찾을 수 없습니다.')
+  if (record.restoredAt) {
+    /* Asked again with the same request: the undo it made. Another request for a draft already back: refused. */
+    if (record.restoreRequestId === request.requestId)
+      return { figure: await figures.findOneOrFail({ where: { id: record.figureId, domain: { id: domain.id } } }), kept: record }
+    throw refused('FIGURE_KEPT_RESTORED', '이 초안은 이미 되살렸습니다.')
+  }
+
+  const figure = await figures.findOne({ where: { id: record.figureId, domain: { id: domain.id } } })
+  if (!figure) throw refused('FIGURE_NOT_FOUND', `Figure ${record.figureId} 를 찾을 수 없습니다.`)
+
+  /* What the undo replaces is kept too -- the same rule as a revert. */
+  const { derived } = parseSource(record.source!)
+  await keep(kept, {
+    domain: { id: domain.id },
+    figureId: figure.id,
+    kind: 'undo' as const,
+    source: figure.source,
+    properties: figure.properties,
+    thumbnail: figure.thumbnail,
+    state: figure.state,
+    version: figure.version,
+    writtenSource: record.source,
+    writtenSourceHash: hashOf(record.source!),
+    requestId: request.requestId,
+    ...(user ? { creator: { id: user.id } } : {})
+  })
+
+  const written = await figures.update(
+    { id: figure.id, domain: { id: domain.id }, source: record.writtenSource },
+    {
+      source: record.source,
+      ...derived,
+      properties: record.properties,
+      thumbnail: record.thumbnail,
+      thumbnailUpdatedAt: record.thumbnail === figure.thumbnail ? figure.thumbnailUpdatedAt : new Date(),
+      state: 'draft',
+      ...(user ? { updater: { id: user.id } } : {})
+    }
+  )
+  if (written.affected !== 1)
+    throw sourceConflict('되돌린 뒤 모델이 다시 바뀌어 되돌리기를 취소하지 않았습니다. 보관한 초안은 그대로 남아 있습니다.')
+
+  await kept.update({ id: record.id }, { restoredAt: new Date(), restoreRequestId: request.requestId })
+  return { figure: await figures.findOneOrFail({ where: { id: figure.id, domain: { id: domain.id } } }), kept: { ...record, restoredAt: new Date(), restoreRequestId: request.requestId } }
+}
+
+/** The drafts reverts kept for a figure, newest first -- found again after a reload. */
+export async function replacedDraftsOf(tx: EntityManager, domain: { id: string }, figureId: string) {
+  return await tx.getRepository(FigureReplacedDraft).find({
+    where: { domain: { id: domain.id }, figureId },
+    order: { createdAt: 'DESC' },
+    relations: ['creator']
+  })
+}

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

@@ -34,6 +34,7 @@
  * 사람이 목록에서 고르는 길에서는 드러나지 않지만, 모델은 대화 내용에 이끌려 임의의 id 를 넘길 수
  * 있다. 그래서 호출자 도메인 소속을 먼저 확인한다.
  */
+import { randomUUID } from 'crypto'
 import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
 
 /*
@@ -376,6 +377,12 @@ function figureToolSpecs(): ToolSpec[] {
         const name = result.source.name || 'Figure'
         return {
           proposed: true,
+          /*
+            The proposal's own name, given once here (ADR-0097 §5.6 item 5; AI lane, 09-27): the dock keys its card by
+            it, a new figure made from it is created under it (the row id), and a save records it -- so what became of
+            it can be asked after a reload, and the same proposal never makes two figures.
+          */
+          key: randomUUID(),
           icon: 'view_in_ar',
           label: create ? `${name} 만들기` : `${name} 고치기`,
           reason:

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

@@ -1,3 +1,4 @@
+import { FigureReplacedDraft } from './figure-replaced-draft.js'
 import { Field, InputType, Int, ObjectType } from 'type-graphql'
 
 import { Figure } from './figure.js'
@@ -129,6 +130,35 @@ export class FigureSaveResult {
   violations: FigureFinding[]
 }
 
+/** An AI proposal saved into a figure, with the figure's names as they are now (ADR-0097 §5.6 item 5). */
+@ObjectType({ description: 'A figure an AI proposal was saved into.' })
+export class FigureProposalOutcome {
+  @Field({ description: 'The figure it was saved into.' })
+  figureId: string
+
+  @Field({ nullable: true, description: "The figure's type name now." })
+  type?: string
+
+  @Field({ nullable: true, description: "The figure's display name now." })
+  name?: string
+
+  @Field({ nullable: true, description: 'When the save that held it was made.' })
+  recordedAt?: Date
+}
+
+/** A revert's outcome: the figure as it now is, and the draft kept for it (ADR-0097 §5.6). */
+@ObjectType({ description: 'The result of a revert, or of an undo of one.' })
+export class FigureRevertResult {
+  @Field(type => Figure, { description: 'The figure, as it now is.' })
+  figure: Figure
+
+  @Field(type => [FigureFinding], { description: 'Non-blocking findings on the source written.' })
+  violations: FigureFinding[]
+
+  @Field(type => FigureReplacedDraft, { description: 'The draft kept for this revert -- or, for an undo, the one brought back.' })
+  kept: FigureReplacedDraft
+}
+
 /**
  * 발행 판정 한 줄.
  *

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

@@ -0,0 +1,15 @@
+/**
+ * A stale expected source is refused with a code of its own (FIGURE_SOURCE_CONFLICT), so the modeller can tell it from a
+ * refusal on grounds and read the row back before saying its save failed (D, designer 2026-09-27).
+ */
+import { compareAndSwapFigure, prepareFigureWrite } from './figure-write'
+
+describe('a write whose expected source is not the row', () => {
+  it('is refused as a source conflict, by code', async () => {
+    await expect(compareAndSwapFigure(async () => ({ affected: 0 }), 'id', 'domain', 'old')).rejects.toMatchObject({ extensions: { code: 'FIGURE_SOURCE_CONFLICT' } })
+    expect(() => prepareFigureWrite('{}', { source: 'theirs' }, 'mine')).toThrow(expect.objectContaining({ extensions: { code: 'FIGURE_SOURCE_CONFLICT' } }))
+  })
+  it('passes when the row is what was expected', async () => {
+    await expect(compareAndSwapFigure(async () => ({ affected: 1 }), 'id', 'domain', 'same')).resolves.toBeUndefined()
+  })
+})

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

@@ -1,5 +1,15 @@
+import { GraphQLError } from 'graphql'
 import { parseFigureAsset, serializeFigureAsset, compileFigureAsset, figureCostOf, figureScoreOf } from '@hatiolab/figure-model'
 
+/**
+ * The row is not what the writer expected: another edit, or the writer's own earlier save whose answer it never got.
+ * Coded, so a client can tell it from a refusal on grounds (permission, validation) and read the row back before
+ * saying its save failed (D, designer 2026-09-27).
+ */
+export function sourceConflict(message: string) {
+  return new GraphQLError(message, { extensions: { code: 'FIGURE_SOURCE_CONFLICT' } })
+}
+
 export interface FigureWriteCriteria {
   id: string
   domain: { id: string }
@@ -13,13 +23,13 @@ export async function compareAndSwapFigure(
 ) {
   if (expectedSource === undefined) throw Error('수정 전 정본이 필요합니다.')
   const result = await update({ id, domain: { id: domainId }, source: expectedSource })
-  if (result.affected !== 1) throw Error('다른 편집에서 모델이 변경되었습니다. 최신 모델을 다시 열어 주세요.')
+  if (result.affected !== 1) throw sourceConflict('다른 편집에서 모델이 변경되었습니다. 최신 모델을 다시 열어 주세요.')
 }
 
 /** Early validation only. The repository must also compare expectedSource in its atomic UPDATE. */
 export function prepareFigureWrite(source: string, existing?: { source?: string }, expectedSource?: string) {
   if (existing && (expectedSource === undefined || existing.source !== expectedSource)) {
-    throw Error('다른 편집에서 모델이 변경되었습니다. 최신 모델을 다시 연 뒤 적용해 주세요.')
+    throw sourceConflict('다른 편집에서 모델이 변경되었습니다. 최신 모델을 다시 연 뒤 적용해 주세요.')
   }
   const asset = parseFigureAsset(source)
   compileFigureAsset(asset)

package/server/service/figure/index.ts

@@ -1,9 +1,11 @@
 import { Figure } from './figure.js'
 import { FigureHistory } from './figure-history.js'
+import { FigureReplacedDraft } from './figure-replaced-draft.js'
+import { FigureProposalRecord } from './figure-proposal-record.js'
 import { FigureQuery } from './figure-query.js'
 import { FigureMutation } from './figure-mutation.js'
 import { FigureHistoryEntitySubscriber } from './event-subscriber.js'
 
-export const entities = [Figure, FigureHistory]
+export const entities = [Figure, FigureHistory, FigureReplacedDraft, FigureProposalRecord]
 export const resolvers = [FigureQuery, FigureMutation]
 export const subscribers = [FigureHistoryEntitySubscriber]

package/translations/en.json

@@ -20,9 +20,9 @@
   "figure.gate.placement-face-tilted.how": "Choose a mounting face parallel to the plane, or turn '{part}' upright.",
   "figure.gate.placement-face-tilted.message": "The mounting face of '{part}' is tilted {degrees}° from the plane the figure stands on.",
   "figure.gate.placement-face-tilted.why": "A tilted face cannot lie on the plane, so how the figure stands is not settled.",
-  "figure.gate.state-range-sampled.how": "Re-author the motion that could not be proven, and the whole range can be proven.",
-  "figure.gate.state-range-sampled.message": "The whole range of motion could not be proven, so {states} poses were checked.",
-  "figure.gate.state-range-sampled.why": "Between the poses that were checked, a part may still go past the declared space.",
+  "figure.gate.state-range-sampled.how": "To cover the whole range, re-author what could not be proven.",
+  "figure.gate.state-range-sampled.message": "The whole range of sizes and motion could not be proven, so {states} combinations of size and pose were checked.",
+  "figure.gate.state-range-sampled.why": "Between the combinations that were checked, a part may still go past the declared space.",
   "figure.gate.type-is-placeholder.how": "Set the type in the type field, then publish.",
   "figure.gate.type-is-placeholder.message": "'{type}' is a temporary type given when the figure was first saved.",
   "figure.gate.type-is-placeholder.why": "Boards call a figure by its type, and it cannot change once the figure is published.",