@things-factory/figure-service 10.1.81 → 10.1.84

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

@@ -0,0 +1,39 @@
+import type { EntityManager } from 'typeorm'
+import { In } from 'typeorm'
+
+import { Figure } from './figure.js'
+import { FigureProposalRecord } from './figure-proposal-record.js'
+
+/*
+ * What became of an AI proposal (ADR-0097 §5.6 item 5; AI lane, 2026-09-27): the saves that held its step. The key is the
+ * one `proposeFigureCandidate` gave it; a new figure made from it is created under that key, so the same proposal
+ * taken twice meets the first figure, never a second one.
+ */
+
+const KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/** Records, in the save's transaction, the proposals its source holds. Keys not of the tool's making are not recorded. */
+export async function recordProposals(tx: EntityManager, domain: { id: string }, figureId: string, keys?: readonly string[]) {
+  const wanted = [...new Set((keys ?? []).filter(key => KEY.test(key)))]
+  if (!wanted.length) return
+  const records = tx.getRepository(FigureProposalRecord)
+  const already = new Set(
+    (await records.find({ where: { domain: { id: domain.id }, figureId, proposalKey: In(wanted) } })).map(record => record.proposalKey)
+  )
+  const fresh = wanted.filter(key => !already.has(key))
+  if (fresh.length) await records.insert(fresh.map(proposalKey => ({ domain: { id: domain.id }, figureId, proposalKey })))
+}
+
+/** The figures a proposal was saved into, with their names as they are now. None: not saved -- or not known here. */
+export async function proposalOutcomeOf(tx: EntityManager, domain: { id: string }, proposalKey: string) {
+  const records = await tx.getRepository(FigureProposalRecord).find({ where: { domain: { id: domain.id }, proposalKey }, order: { recordedAt: 'ASC' } })
+  if (!records.length) return []
+  const figures = await tx.getRepository(Figure).find({ where: { domain: { id: domain.id }, id: In(records.map(r => r.figureId!)) } })
+  const byId = new Map(figures.map(f => [f.id, f]))
+  return records.map(record => ({
+    figureId: record.figureId!,
+    recordedAt: record.recordedAt,
+    type: byId.get(record.figureId!)?.type,
+    name: byId.get(record.figureId!)?.name
+  }))
+}

package/server/service/figure/figure-propose-clips.test.ts

@@ -0,0 +1,73 @@
+/**
+ * figure-propose-steps and clips (designer 2026-09-27): an AI answer that would stop a clip is refused whole, and the
+ * model is told it may not -- never how to agree. An answer that stops none keeps every clip. Consent the model writes
+ * into its answer is read as nothing.
+ */
+import { addFigureBox, applyFigureAuthoring, createFigureAsset, editFigurePart } from '@hatiolab/figure-model'
+import type { FigureAsset } from '@hatiolab/figure-model'
+import { setDefaultAIClient } from '@things-factory/ai-client-base'
+import type { AIClient } from '@things-factory/ai-client-base'
+
+import { ProposeFigureFailure, judgeFigureAnswer, proposeFigureSteps } from './figure-propose-steps'
+
+function stubClient(answers: unknown[]): AIClient & { calls: number; sent: any[][] } {
+  const client = {
+    id: 'stub',
+    calls: 0,
+    sent: [] as any[][],
+    async chat() {
+      return ''
+    },
+    async generateJSON(messages: any[]) {
+      client.sent.push(JSON.parse(JSON.stringify(messages)))
+      return answers[Math.min(client.calls++, answers.length - 1)]
+    }
+  }
+  return client as unknown as AIClient & { calls: number; sent: any[][] }
+}
+
+afterEach(() => setDefaultAIClient(undefined))
+
+function door(): FigureAsset {
+  let a = createFigureAsset('Door')
+  a = addFigureBox(a, { id: 'frame', size: { x: 1000, y: 100, z: 200 }, position: { x: 0, y: 50, z: 0 } })
+  a = addFigureBox(a, { id: 'leaf', size: { x: 900, y: 1800, z: 40 }, position: { x: 0, y: 1000, z: 0 } })
+  a = addFigureBox(a, { id: 'sign', size: { x: 200, y: 100, z: 10 }, position: { x: 0, y: 2200, z: 200 } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'leaf', face: 'bottom', to: { part: 'frame', face: 'top' } })
+  const j = a.joints!.find(k => k.body1.part === 'leaf')!
+  a = applyFigureAuthoring(a, { kind: 'set-joint', joint: { ...j, type: 'revolute', axis: 'Y', state: { id: 'open' } } })
+  return editFigurePart(a, { kind: 'set-driver', state: 'open', clip: 'swing', duration: 2, keys: [{ seconds: 0, value: 0 }, { seconds: 2, value: 80 }] })
+}
+const lossy = { steps: [{ kind: 'rename', name: 'Door by AI' }, { kind: 'remove-part', target: 'leaf' }] }
+
+describe('an AI answer and the clips of the draft it revises', () => {
+  it('an answer that would stop a clip is refused whole, and the model is told it may not -- not how to agree', () => {
+    const base = door()
+    const judged = judgeFigureAnswer(base, lossy, true)
+    expect(judged.source).toBeUndefined()
+    expect(judged.reasons.join('\n')).toMatch(/CLIPS_DROPPED: .*swing.*may never remove a clip; only the person can/)
+    expect(judged.reasons.join('\n')).not.toMatch(/dropClips/)
+    expect(base.drivers?.map(d => d.clip)).toEqual(['swing'])
+  })
+
+  it('asked three times and three times lossy, nothing comes back: no half-made figure to save', async () => {
+    const client = stubClient([lossy])
+    setDefaultAIClient(client)
+    await expect(proposeFigureSteps({ prompt: '문을 없애 줘', base: door() })).rejects.toBeInstanceOf(ProposeFigureFailure)
+    expect(client.calls).toBe(3)
+    expect(JSON.stringify(client.sent)).not.toMatch(/dropClips/)
+  })
+
+  it('consent the model writes into its answer is read as nothing', () => {
+    const judged = judgeFigureAnswer(door(), { ...lossy, dropClips: ['swing/open'], steps: lossy.steps.map(s => ({ ...s, dropClips: ['swing/open'] })) }, true)
+    expect(judged.source).toBeUndefined()
+    expect(judged.reasons.join('\n')).toMatch(/^CLIPS_DROPPED/)
+  })
+
+  it('an answer that stops no clip keeps every clip, a rename of the part it hangs from included', async () => {
+    const base = door()
+    setDefaultAIClient(stubClient([{ steps: [{ kind: 'rename', name: 'Door 2' }, { kind: 'nudge-part', part: 'sign', by: { x: 50 } }, { kind: 'rename-part', target: 'frame', name: 'jamb' }] }]))
+    const made = await proposeFigureSteps({ prompt: '이름을 바꿔 줘', base })
+    expect(made.source.drivers).toEqual(base.drivers)
+  })
+})

package/server/service/figure/figure-propose-steps.ts

@@ -114,8 +114,20 @@ export function judgeFigureAnswer(base: FigureAsset, answer: unknown, revising:
 
   let source: FigureAsset
   try {
+    /* Never with consent: only the person may let a clip go (designer 2026-09-27). */
     source = applyFigureProposal(base, steps as FigureProposalStep[])
   } catch (e) {
+    /*
+      The kernel's refusal tells a person how to agree; the model is told it may not, and what to keep instead -- it
+      must not learn to write a consent (designer 2026-09-27).
+    */
+    const clips = (e as { code?: string; clips?: Array<{ clip: string; state: string }> }).code === 'CLIPS_DROPPED' ? (e as { clips: Array<{ clip: string; state: string }> }).clips : undefined
+    if (clips)
+      return {
+        reasons: [
+          `CLIPS_DROPPED: these steps would stop the clips ${clips.map(c => `${c.clip} (plays ${c.state})`).join(', ')}. A proposal may never remove a clip; only the person can. Keep the parts and the motions those clips play as they are.`
+        ]
+      }
     return { reasons: [(e as Error).message] }
   }
 

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

@@ -14,7 +14,10 @@ import {
 import { Figure } from './figure.js'
 import { FigureHistory } from './figure-history.js'
 import { consumablePayloadOf, inspectSource } from './figure-format.js'
-import { FigureInspection, FigureList } from './figure-type.js'
+import { FigureInspection, FigureList, FigureProposalOutcome } from './figure-type.js'
+import { FigureReplacedDraft } from './figure-replaced-draft.js'
+import { replacedDraftsOf } from './figure-revert.js'
+import { proposalOutcomeOf } from './figure-proposal.js'
 
 @Resolver(Figure)
 @UseMiddleware(SpeakRefusals)
@@ -88,6 +91,24 @@ export class FigureQuery {
    * 도형의 현재 정본은 저작 중일 수 있다(초안). 배치된 것이 보는 것은 **마지막으로 발행된 판**이고,
    * 그것을 이 자리가 답한다.
    */
+  /** What became of an AI proposal: the figures a save put it into (ADR-0097 §5.6 item 5). */
+  @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => [FigureProposalOutcome], {
+    description: 'The figures an AI proposal was saved into, oldest first. None: it was not saved, or not in this domain.'
+  })
+  async figureProposalOutcome(@Arg('proposalKey') proposalKey: string, @Ctx() context: ResolverContext): Promise<FigureProposalOutcome[]> {
+    const { domain, tx } = context.state
+    return await proposalOutcomeOf(getRepository(Figure, tx).manager, domain, proposalKey)
+  }
+
+  /** The drafts reverts kept for a figure, newest first -- apart from its released versions (ADR-0097 §5.6). */
+  @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => [FigureReplacedDraft], { description: 'Drafts kept when a revert wrote over them, newest first. Not released versions.' })
+  async figureReplacedDrafts(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<FigureReplacedDraft[]> {
+    const { domain, tx } = context.state
+    return await replacedDraftsOf(getRepository(FigureReplacedDraft, tx).manager, domain, id)
+  }
+
   @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
   @Query(returns => FigureHistory, { nullable: true, description: 'The most recently released version of a figure.' })
   async figureReleased(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<FigureHistory> {

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

@@ -33,9 +33,10 @@ describe('초안의 type 고치기', () => {
     expect(() => parseFigureAsset(result.source)).not.toThrow()
   })
 
-  it('앞뒤 공백을 뗀다. 대소문자는 저작자가 적은 대로 둔다', () => {
+  it('앞뒤 공백을 뗀다. 모양은 모델러가 묻는 규칙 그대로 — 대문자로 적지 않으면 거절한다(Q-D3, 2026-09-27)', () => {
     expect(renameDraftType(draft(), '  ROBOT_ARM  ', never).type).toBe('ROBOT_ARM')
-    expect(renameDraftType(draft(), 'Robot_Arm', never).type).toBe('Robot_Arm')
+    /* It was kept as written; the modeller always sent it upper-cased, and every stored type already is (56/56). */
+    expect(() => renameDraftType(draft(), 'Robot_Arm', never)).toThrow(expect.objectContaining({ code: 'malformed-type' }))
   })
 
   it('★ 한 번이라도 발행됐으면 거절한다 — 판 번호로', () => {
@@ -104,3 +105,13 @@ describe('문이 이 규칙을 지난다', () => {
     expect(/class FigurePatch \{[\s\S]{0,400}type\?: string/.test(type)).toBe(true)
   })
 })
+
+describe('a type being set keeps the shape the modeller asks for (Q-D3, designer 2026-09-27)', () => {
+  const free = { version: 0, hasHistory: false, takenByAnother: false }
+  it.each(['lower_case', 'X1', 'A'.repeat(33), '1ABC', 'AB-CD', 'AB__CD', '한글'])('refuses %s as malformed', wanted => {
+    expect(() => renameDraftType({ type: 'OLD', source: '{}' }, wanted, free)).toThrow(expect.objectContaining({ code: 'malformed-type' }))
+  })
+  it.each(['FIG_K3F9A2', 'CONVEYOR', 'LIFT_TABLE_2'])('takes %s', wanted => {
+    expect(renameDraftType({ type: 'OLD', source: '{}' }, wanted, free).type).toBe(wanted)
+  })
+})

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

@@ -1,3 +1,4 @@
+import { TYPE_LENGTH, TYPE_PATTERN } from '@hatiolab/figure-model'
 /**
  * 초안의 타입을 고치는 규칙 — ADR-0063 결정 4.
  *
@@ -32,7 +33,7 @@ export interface RenameFacts {
 
 export class FigureRenameRefused extends Error {
   constructor(
-    readonly code: 'empty-type' | 'already-released' | 'type-taken',
+    readonly code: 'empty-type' | 'malformed-type' | 'already-released' | 'type-taken',
     message: string
   ) {
     super(message)
@@ -57,6 +58,17 @@ export function renameDraftType(
     throw new FigureRenameRefused('empty-type', 'type 이 비어 있다 — 도면에 적히는 이름이라 비울 수 없다')
   }
 
+  /*
+    The shape the modeller has always asked for, now asked here too (designer 2026-09-27, Q-D3): only a type being set
+    is held to it -- every type in the development data already keeps it (56 of 56, 2026-09-27), and none is renamed.
+  */
+  if (!TYPE_PATTERN.test(next) || next.length < TYPE_LENGTH.min || next.length > TYPE_LENGTH.max) {
+    throw new FigureRenameRefused(
+      'malformed-type',
+      `type 「${next}」 는 대문자로 시작하고 대문자·숫자·밑줄만 쓰며 ${TYPE_LENGTH.min}~${TYPE_LENGTH.max}자여야 한다`
+    )
+  }
+
   if ((facts.version ?? 0) > 0 || facts.hasHistory) {
     throw new FigureRenameRefused(
       'already-released',

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

@@ -0,0 +1,90 @@
+import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'
+import { Field, ID, Int, ObjectType } from 'type-graphql'
+
+import { User } from '@things-factory/auth-base'
+import { Domain, longTextColumn } from '@things-factory/shell'
+
+/**
+ * A figure's draft as it stood before a revert wrote over it -- kept, so what was saved just before a revert can be
+ * brought back, after a reload too (ADR-0097 §5.6, designer 2026-09-27; table chosen with the chief architect).
+ *
+ * Not a released version: it has no version number of its own, is not listed with the releases, and never changes
+ * what a board uses. Kept in the same transaction as the revert that replaces the draft -- kept, or neither happens.
+ * `requestId` makes a retried revert (its answer lost) the same revert, not a second one.
+ *
+ * An undo of a revert is a revert too (`kind: 'undo'`): it keeps what it replaces the same way.
+ */
+@Entity()
+@Index('ix_figure_replaced_draft_1', (kept: FigureReplacedDraft) => [kept.domain, kept.requestId], { unique: true })
+@Index('ix_figure_replaced_draft_2', (kept: FigureReplacedDraft) => [kept.domain, kept.figureId])
+@ObjectType({ description: 'A figure draft kept when a revert wrote over it. Not a released version.' })
+export class FigureReplacedDraft {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the kept draft.' })
+  readonly id?: string
+
+  @ManyToOne(type => Domain)
+  domain?: Domain
+
+  @RelationId((kept: FigureReplacedDraft) => kept.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'The figure whose draft this was.' })
+  figureId?: string
+
+  @Column({ default: 'revert' })
+  @Field({ description: "What replaced it: 'revert' (a released version written over it) or 'undo' (an undo of a revert)." })
+  kind?: 'revert' | 'undo'
+
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({ nullable: true, description: 'The figure asset JSON the draft held.' })
+  source?: string
+
+  @Column({ nullable: true, ...longTextColumn() })
+  properties?: string
+
+  @Column({ nullable: true, ...longTextColumn() })
+  thumbnail?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The state the figure was in.' })
+  state?: string
+
+  @Column({ nullable: true })
+  @Field(type => Int, { nullable: true, description: 'The released version number the figure had then.' })
+  version?: number
+
+  @Column({ nullable: true })
+  @Field(type => Int, { nullable: true, description: 'The released version the revert wrote over it; none for an undo.' })
+  revertedToVersion?: number
+
+  /* What replaced it, whole: an undo proceeds only while the figure still holds exactly this (compare-and-swap). */
+  @Column({ nullable: true, ...longTextColumn() })
+  writtenSource?: string
+
+  /* Its content hash, for finding and retrying without reading the whole text (chief architect, 2026-09-27). */
+  @Column()
+  writtenSourceHash?: string
+
+  @Column()
+  requestId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When this draft was brought back by an undo.' })
+  restoredAt?: Date
+
+  @Column({ nullable: true })
+  restoreRequestId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'When it was kept -- when the revert replaced it.' })
+  createdAt?: Date
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'Who reverted.' })
+  creator?: User
+
+  @RelationId((kept: FigureReplacedDraft) => kept.creator)
+  creatorId?: string
+}

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