@things-factory/figure-service 10.1.106 → 10.1.109

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.106",
+  "version": "10.1.109",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,15 +25,15 @@
     "test:templates": "node --test scripts/templates.test.mts"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.2.7",
+    "@hatiolab/figure-model": "^0.2.8",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.81",
-    "@things-factory/auth-base": "^10.1.106",
+    "@things-factory/auth-base": "^10.1.107",
     "@things-factory/env": "^10.1.20",
     "@things-factory/shell": "^10.1.106",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "8d78c14708420773ec32d18b8dd44c300771c44d"
+  "gitHead": "4d51757c50d8347e83c96aeba73d770bdde55b73"
 }

package/server/service/figure/event-subscriber.ts

@@ -13,8 +13,19 @@ import { FigureHistory } from './figure-history.js'
  * **발행한 것**이므로 그때만 베낀다. board 가 같은 규칙으로 돈다(`board-service` 의 같은 이름 파일).
  *
  * 발행 메모는 Figure 의 칸이 아니다. `releaseFigure` 가 저장할 엔티티에 `__releaseComment` 로 얹어
- * 두면 여기서 판본의 `comment` 로 옮긴다 — 메모는 그 판의 것이지 도형의 것이 아니다.
+ * 두면 여기서 판본의 `comment` 로 옮긴다 — 메모는 그 판의 것이지 도형의 것이 아니다. 정본 형식
+ * (`__releaseFormat`)과 직전 판에 견준 변경(`__releaseChanges`)도 같은 길로 옮긴다(ADR-0104).
  */
+/** What `releaseFigure` laid on the entity for this release, moved onto the history row. */
+function releaseRecordOnto(history: FigureHistory, entity: Figure): FigureHistory {
+  const e = entity as any
+  ;(history as any).comment = e.__releaseComment ?? null
+  history.assetFormat = e.__releaseFormat ?? null
+  /* [] stays "[]" (nothing changed); null stays null (not compared). */
+  history.changes = e.__releaseChanges == null ? null : JSON.stringify(e.__releaseChanges)
+  return history
+}
+
 @EventSubscriber()
 export class FigureHistoryEntitySubscriber extends HistoryEntitySubscriber<Figure, FigureHistory> {
   public get entity() {
@@ -26,13 +37,11 @@ export class FigureHistoryEntitySubscriber extends HistoryEntitySubscriber<Figur
   }
 
   public beforeInsertHistory(history: FigureHistory, entity: Figure): FigureHistory {
-    ;(history as any).comment = (entity as any).__releaseComment ?? null
-    return history
+    return releaseRecordOnto(history, entity)
   }
 
   public beforeUpdateHistory(history: FigureHistory, entity: Figure): FigureHistory {
-    ;(history as any).comment = (entity as any).__releaseComment ?? null
-    return history
+    return releaseRecordOnto(history, entity)
   }
 
   public async afterInsert(event: any): Promise<void> {

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

@@ -9,7 +9,7 @@
 import { createFigureAsset, addFigureBox, addFigurePrimitive, serializeFigureAsset, applyFigureAuthoring, proposeFigureOccupancy, placeholderType, figureScoreOf } from '@hatiolab/figure-model'
 import type { FigureAsset } from '@hatiolab/figure-model'
 
-import { FigureSourceError, consumablePayloadOf, inspectSource, parseSource } from './figure-format'
+import { FigureSourceError, consumablePayloadOf, inspectSource, parseSource, releaseRecordOf } from './figure-format'
 
 /** 온전한 자산 하나: 바닥에 선 상자와, 부품에서 제안받아 확정한 점유 부피. */
 function figureAsset(): FigureAsset {
@@ -320,4 +320,33 @@ describe('figure-format — 판을 알아보는 문', () => {
       expect(() => consumablePayloadOf(JSON.stringify(broken))).toThrow()
     })
   })
+
+  /* ADR-0104 decision 5: a release records its format and what changed against the last one, once, as it was then. */
+  describe('발행이 스스로 남기는 것 — 형식과 직전 판에 견준 변경', () => {
+    const wider = () => {
+      let asset = createFigureAsset('Mixer')
+      asset = addFigureBox(asset, { id: 'body', size: { x: 300, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+      asset = applyFigureAuthoring(asset, { kind: 'attach', part: 'body', face: 'bottom', to: { plane: 'mounting-plane' } })
+      return serializeFigureAsset(applyFigureAuthoring(asset, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(asset, { over: 'range' }), placement: 'floor' }))
+    }
+    it('a first release: its format, and nothing changed', () => {
+      expect(releaseRecordOf(serializeFigureAsset(figureAsset()))).toEqual({ format: 'figure-asset-1', changes: [] })
+    })
+    it('the same again changes nothing; a wider room is said and does not block', () => {
+      const v1 = serializeFigureAsset(figureAsset())
+      expect(releaseRecordOf(v1, v1).changes).toEqual([])
+      const room = releaseRecordOf(wider(), v1).changes!.find(c => c.code === 'occupancy-changed')!
+      expect(room.blocking).toBe(false)
+      expect(String(room.values.after)).toMatch(/x -150…150/)
+    })
+    it('a last release that cannot be read is "not compared" (null), never "nothing changed" ([])', () => {
+      expect(releaseRecordOf(serializeFigureAsset(figureAsset()), '{ not json').changes).toBeNull()
+    })
+    it('every new change has its sentence in both languages', () => {
+      const KO = require('../../../translations/ko.json') as Record<string, string>
+      const EN = require('../../../translations/en.json') as Record<string, string>
+      for (const code of ['occupancy-changed', 'contact-face-changed', 'public-input-gone', 'public-input-range-narrowed', 'public-input-added'])
+        for (const dict of [KO, EN]) for (const field of ['message', 'why']) expect(dict[`figure.gate.contract.${code}.${field}`]).toBeTruthy()
+    })
+  })
 })

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

@@ -420,7 +420,51 @@ function figureContractWording(change: FigureContractChange, say: Say): Pick<Gat
         message: say(key('message'), v, `The capability '${v.name}' is new.`),
         why: say(key('why'), {}, 'It adds what the figure can do. Placed instances stand as they are.')
       }
+    /* Said, never refused (ADR-0104): a consumer that pins a release reads these before it moves to this one. */
+    case 'occupancy-changed':
+      return {
+        message: say(key('message'), v, `The room the figure takes changed from ${v.before || 'none'} to ${v.after || 'none'}.`),
+        why: say(key('why'), {}, 'A consumer places the figure by this room. One that moves to this release sees it take the new room.')
+      }
+    case 'contact-face-changed':
+      return {
+        message: say(key('message'), v, 'The face the figure is mounted by changed.'),
+        why: say(key('why'), {}, 'A consumer that moves to this release sees it stand on the new face.')
+      }
+    case 'public-input-gone':
+      return {
+        message: say(key('message'), { ...v, input: change.subject ?? '' }, `'${change.subject}' is no longer set on a board.`),
+        why: say(key('why'), {}, 'Values placed instances give it do nothing after this release.')
+      }
+    case 'public-input-range-narrowed':
+      return {
+        message: say(key('message'), { ...v, input: change.subject ?? '' }, `The range of '${change.subject}' narrowed from ${v.before} to ${v.after}.`),
+        why: say(key('why'), {}, 'An instance may have set a value outside the new range. Which values are placed is not recorded.')
+      }
+    case 'public-input-added':
+      return {
+        message: say(key('message'), { ...v, input: change.subject ?? '' }, `'${change.subject}' can now be set on a board.`),
+        why: say(key('why'), {}, 'Placed instances that give no value stand at its default.')
+      }
+  }
+}
+
+/**
+ * What a release records about itself (ADR-0104 decision 5): the format its asset is written in, and what changed
+ * against the previous release -- the kernel's own comparison, kept as it was then so a consumer that pins releases
+ * reads it rather than computing it again. `[]` for a first release; `null` when the previous release could not be
+ * read, which is a different fact from "nothing changed".
+ */
+export function releaseRecordOf(sourceJson: string, releasedJson?: string | null): { format: string; changes: FigureContractChange[] | null } {
+  const asset = parseFigureAsset(sourceJson)
+  if (!releasedJson) return { format: asset.version, changes: [] }
+  let before: FigureAsset
+  try {
+    before = parseFigureAsset(releasedJson)
+  } catch {
+    return { format: asset.version, changes: null }
   }
+  return { format: asset.version, changes: figureContractChanges(before, asset) }
 }
 
 /**

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

@@ -94,6 +94,22 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   @Field({ nullable: true, description: 'The note left when this version was released.' })
   comment?: string
 
+  /*
+   * 이 판의 정본 형식(`figure-asset-1`)과, 직전 판에 견준 변경(ADR-0104 결정 5). 발행할 때 한 번 정하고 다시
+   * 계산하지 않는다 — 판을 고정해 쓰는 쪽은 다음 판으로 옮기기 전에 이것을 읽는다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The asset format this version was written in (figure-asset-1).' })
+  assetFormat?: string
+
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({
+    nullable: true,
+    description:
+      'What changed against the previous release, as JSON: [{ code, blocking, subject?, values, detail }]. [] for the first release; null when the previous release could not be read.'
+  })
+  changes?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'When the original figure was created.' })
   createdAt?: Date

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

@@ -11,7 +11,7 @@ import { FigureReplacedDraft } from './figure-replaced-draft.js'
 import { revertKeepingDraft, undoRevert } from './figure-revert.js'
 import { recordProposals } from './figure-proposal.js'
 import { FigureProposal, ProposeRequest } from './figure-propose-type.js'
-import { inspectSource } from './figure-format.js'
+import { inspectSource, releaseRecordOf } from './figure-format.js'
 import { renameDraftType, renameFacts } from './figure-rename.js'
 import { parseSource } from './figure-format.js'
 import { ProposeFigureFailure, proposeFigureSteps } from './figure-propose-steps.js'
@@ -319,6 +319,8 @@ export class FigureMutation {
     }
 
     const nextVersion = released?.version ? Number(released.version) + 1 : 1
+    /* What this release records about itself: its format, and what changed against the last one (ADR-0104). */
+    const record = releaseRecordOf(figure.source!, released?.source)
 
     return await repository.save({
       /*
@@ -333,8 +335,10 @@ export class FigureMutation {
       version: nextVersion,
       state: 'released',
       updater: user,
-      /* 판본 구독자가 이것을 판본의 comment 로 옮긴다. Figure 의 칸이 아니다. */
-      __releaseComment: comment ?? null
+      /* 판본 구독자가 이것들을 판본의 comment · assetFormat · changes 로 옮긴다. Figure 의 칸이 아니다. */
+      __releaseComment: comment ?? null,
+      __releaseFormat: record.format,
+      __releaseChanges: record.changes
     } as any)
   }
 

package/server/service/figure/figure-release-record-db.test.ts

@@ -0,0 +1,94 @@
+/**
+ * A release keeps its format and what changed against the last one on its history row -- on sqlite, through the
+ * subscriber that writes history (ADR-0104 decision 5). `[]` and `null` stay apart: nothing changed is not "not compared".
+ */
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+const { createFigureAsset, addFigureBox, serializeFigureAsset, applyFigureAuthoring, proposeFigureOccupancy } = require('@hatiolab/figure-model')
+
+let dataSource: DataSource | null = null
+let Figure: any
+let FigureHistory: any
+let Subscriber: any
+let FigureMutation: 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
+  Subscriber = loadCompiled('service/figure/event-subscriber').FigureHistoryEntitySubscriber
+  FigureMutation = loadCompiled('service/figure/figure-mutation').FigureMutation
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory],
+    subscribers: [Subscriber],
+    logging: false
+  })
+  await dataSource.initialize()
+})
+
+afterAll(async () => {
+  await dataSource?.destroy()
+  dataSource = null
+})
+
+const SOURCE = serializeFigureAsset(addFigureBox(createFigureAsset('Probe'), { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } }))
+
+async function release(extra: Record<string, unknown>) {
+  const domain = await dataSource!.getRepository(shell.Domain).save({ name: `d-${Math.random()}`, subdomain: `d${Date.now()}${Math.random()}` })
+  const figure = await dataSource!.getRepository(Figure).save({ type: 'RECORD_PROBE', name: 'probe', source: SOURCE, state: 'draft', version: 0, domain })
+  await dataSource!.getRepository(Figure).save({ ...figure, domain, version: 1, state: 'released', __releaseComment: 'first', ...extra })
+  return dataSource!.getRepository(FigureHistory).findOneOrFail({ where: { originalId: figure.id } })
+}
+
+describe('a release record on its history row', () => {
+  it('keeps the format and the changes as they were', async () => {
+    const changes = [{ code: 'occupancy-changed', blocking: false, values: { before: 'x -50…50', after: 'x -150…150' }, detail: 'declared room changed' }]
+    const row = await release({ __releaseFormat: 'figure-asset-1', __releaseChanges: changes })
+    expect(row.assetFormat).toBe('figure-asset-1')
+    expect(JSON.parse(row.changes)).toEqual(changes)
+    expect(row.comment).toBe('first')
+  })
+  it('[] stays nothing changed, null stays not compared', async () => {
+    expect((await release({ __releaseFormat: 'figure-asset-1', __releaseChanges: [] })).changes).toBe('[]')
+    expect((await release({ __releaseFormat: 'figure-asset-1', __releaseChanges: null })).changes).toBeNull()
+  })
+})
+
+/* The whole door, called as the resolver is: releaseFigure works the record out and the row carries it. */
+describe('releaseFigure records it', () => {
+  const releasable = (width: number) => {
+    let a = addFigureBox(createFigureAsset('Mixer'), { id: 'body', size: { x: width, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+    a = applyFigureAuthoring(a, { kind: 'attach', part: 'body', face: 'bottom', to: { plane: 'mounting-plane' } })
+    return serializeFigureAsset(applyFigureAuthoring(a, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(a, { over: 'range' }), placement: 'floor' }))
+  }
+  it('first release: [], the second: the wider room', async () => {
+    const domain = await dataSource!.getRepository(shell.Domain).save({ name: 'release-door', subdomain: 'release-door' })
+    const tx = dataSource!.manager
+    const context = { state: { domain, user: undefined, tx } }
+    const figure = await dataSource!.getRepository(Figure).save({ type: 'RELEASE_DOOR', name: 'door', source: releasable(100), state: 'draft', version: 0, domain })
+    await new FigureMutation().releaseFigure(figure.id, 'one', context)
+    await dataSource!.getRepository(Figure).save({ ...(await dataSource!.getRepository(Figure).findOneOrFail({ where: { id: figure.id } })), domain, source: releasable(300), state: 'draft' })
+    await new FigureMutation().releaseFigure(figure.id, 'two', context)
+    const rows = await dataSource!.getRepository(FigureHistory).find({ where: { originalId: figure.id }, order: { version: 'ASC' } })
+    expect(rows.map((r: any) => [r.version, r.assetFormat, r.comment])).toEqual([[1, 'figure-asset-1', 'one'], [2, 'figure-asset-1', 'two']])
+    expect(rows[0].changes).toBe('[]')
+    const codes = JSON.parse(rows[1].changes).map((c: any) => c.code)
+    expect(codes).toContain('occupancy-changed')
+  })
+})

package/translations/en.json

@@ -64,5 +64,15 @@
   "figure.gate.contract.capability-gone.message": "The capability '{name}' is gone.",
   "figure.gate.contract.capability-gone.why": "Scenes attach behaviour by this name. Placed instances lose what it did.",
   "figure.gate.contract.capability-added.message": "The capability '{name}' is new.",
-  "figure.gate.contract.capability-added.why": "It adds what the figure can do. Placed instances stand as they are."
+  "figure.gate.contract.capability-added.why": "It adds what the figure can do. Placed instances stand as they are.",
+  "figure.gate.contract.occupancy-changed.message": "The room the figure takes changed: {before} → {after}.",
+  "figure.gate.contract.occupancy-changed.why": "A consumer places the figure by this room. One that moves to this release sees it take the new room.",
+  "figure.gate.contract.contact-face-changed.message": "The face the figure is mounted by changed.",
+  "figure.gate.contract.contact-face-changed.why": "A consumer that moves to this release sees it stand on the new face.",
+  "figure.gate.contract.public-input-gone.message": "'{input}' is no longer set on a board.",
+  "figure.gate.contract.public-input-gone.why": "Values placed instances give it do nothing after this release.",
+  "figure.gate.contract.public-input-range-narrowed.message": "The range of '{input}' narrowed: {before} → {after}.",
+  "figure.gate.contract.public-input-range-narrowed.why": "An instance may have set a value outside the new range. Which values are placed is not recorded.",
+  "figure.gate.contract.public-input-added.message": "'{input}' can now be set on a board.",
+  "figure.gate.contract.public-input-added.why": "Placed instances that give no value stand at its default."
 }

package/translations/ko.json

@@ -64,5 +64,15 @@
   "figure.gate.contract.capability-gone.message": "'{name}' 능력이 없어졌습니다.",
   "figure.gate.contract.capability-gone.why": "씬이 이 이름으로 동작을 붙입니다. 놓인 인스턴스가 그 동작을 잃습니다.",
   "figure.gate.contract.capability-added.message": "'{name}' 능력이 새로 생겼습니다.",
-  "figure.gate.contract.capability-added.why": "도형이 할 수 있는 일이 늘어납니다. 놓인 인스턴스는 그대로 서 있습니다."
+  "figure.gate.contract.capability-added.why": "도형이 할 수 있는 일이 늘어납니다. 놓인 인스턴스는 그대로 서 있습니다.",
+  "figure.gate.contract.occupancy-changed.message": "도형이 차지하는 공간이 바뀌었습니다: {before} → {after}.",
+  "figure.gate.contract.occupancy-changed.why": "받는 쪽은 이 공간으로 도형을 놓습니다. 이 발행본으로 옮기면 새 공간으로 놓입니다.",
+  "figure.gate.contract.contact-face-changed.message": "도형이 붙는 면이 바뀌었습니다.",
+  "figure.gate.contract.contact-face-changed.why": "이 발행본으로 옮기면 새 면으로 섭니다.",
+  "figure.gate.contract.public-input-gone.message": "'{input}' 값은 이제 보드에서 정할 수 없습니다.",
+  "figure.gate.contract.public-input-gone.why": "놓인 인스턴스가 준 값은 이 발행본부터 아무 일도 하지 않습니다.",
+  "figure.gate.contract.public-input-range-narrowed.message": "'{input}' 값의 범위가 좁아졌습니다: {before} → {after}.",
+  "figure.gate.contract.public-input-range-narrowed.why": "새 범위 밖의 값을 준 인스턴스가 있을 수 있습니다. 어떤 값이 놓였는지는 기록하지 않습니다.",
+  "figure.gate.contract.public-input-added.message": "'{input}' 값을 이제 보드에서 정할 수 있습니다.",
+  "figure.gate.contract.public-input-added.why": "값을 주지 않은 인스턴스는 기본값으로 섭니다."
 }