@things-factory/figure-service 10.1.81 → 10.1.84

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.",

package/translations/ko.json

@@ -20,9 +20,9 @@
   "figure.gate.placement-face-tilted.how": "평면과 나란한 면을 장착면으로 다시 정하거나, '{part}' 부품을 바로 세우세요.",
   "figure.gate.placement-face-tilted.message": "장착면으로 정한 '{part}' 부품의 면이 놓이는 평면에서 {degrees}° 기울어 있습니다.",
   "figure.gate.placement-face-tilted.why": "기운 면은 평면에 닿을 수 없어서, 도형이 어떤 자세로 놓이는지 정해지지 않습니다.",
-  "figure.gate.state-range-sampled.how": "증명하지 못한 움직임을 다시 저작하면 범위 전체를 증명할 수 있습니다.",
-  "figure.gate.state-range-sampled.message": "움직이는 범위 전체를 증명하지 못해 자세 {states}개만 검사했습니다.",
-  "figure.gate.state-range-sampled.why": "검사한 자세 사이에서 부품이 공간 선언을 넘을 수 있습니다.",
+  "figure.gate.state-range-sampled.how": "범위 전체를 보장하려면 증명하지 못한 항목을 다시 저작하세요.",
+  "figure.gate.state-range-sampled.message": "크기와 움직임의 범위 전체를 증명하지 못해 크기·자세 조합 {states}개만 검사했습니다.",
+  "figure.gate.state-range-sampled.why": "검사한 조합 사이에서 부품이 공간 선언을 넘을 수 있습니다.",
   "figure.gate.type-is-placeholder.how": "타입 칸에서 타입을 정한 뒤 발행하세요.",
   "figure.gate.type-is-placeholder.message": "'{type}' 타입은 처음 저장할 때 붙은 임시 타입입니다.",
   "figure.gate.type-is-placeholder.why": "보드는 이 타입으로 도형을 부르고, 발행한 뒤에는 바꿀 수 없습니다.",