@things-factory/figure-service 10.1.114 → 10.1.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.114",
+  "version": "10.1.116",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,16 +25,16 @@
     "test:templates": "node --test scripts/templates.test.mts"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.2.12",
+    "@hatiolab/figure-model": "^0.3.2",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.114",
-    "@things-factory/attachment-base": "^10.1.113",
-    "@things-factory/auth-base": "^10.1.113",
+    "@things-factory/attachment-base": "^10.1.116",
+    "@things-factory/auth-base": "^10.1.116",
     "@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": "0d8f9bc0ff0cb50431f2c76cb166aaf3809d3cf7"
+  "gitHead": "49fa935cc703be70200eef4d29f473de98f871ce"
 }

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

@@ -14,7 +14,7 @@ import { FigureHistory } from './figure-history.js'
  *
  * 발행 메모는 Figure 의 칸이 아니다. `releaseFigure` 가 저장할 엔티티에 `__releaseComment` 로 얹어
  * 두면 여기서 판본의 `comment` 로 옮긴다 — 메모는 그 판의 것이지 도형의 것이 아니다. 정본 형식
- * (`__releaseFormat`), 직전 판에 견준 변경(`__releaseChanges`), 발행 때 잰 값(`__releaseMetrics`)과
+ * (`__releaseFormat`), 잰 커널의 판(`__releaseKernel`, ADR-0109 C1), 직전 판에 견준 변경(`__releaseChanges`), 발행 때 잰 값(`__releaseMetrics`)과
  * 윗모습(`__releaseTopView`)도 같은 길로 옮긴다(ADR-0104).
  */
 /** What `releaseFigure` laid on the entity for this release, moved onto the history row. */
@@ -22,6 +22,7 @@ function releaseRecordOnto(history: FigureHistory, entity: Figure): FigureHistor
   const e = entity as any
   ;(history as any).comment = e.__releaseComment ?? null
   history.assetFormat = e.__releaseFormat ?? null
+  history.kernelVersion = e.__releaseKernel ?? null
   /* [] stays "[]" (nothing changed); null stays null (not compared). */
   history.changes = e.__releaseChanges == null ? null : JSON.stringify(e.__releaseChanges)
   history.metrics = e.__releaseMetrics == null ? null : JSON.stringify(e.__releaseMetrics)

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

@@ -350,7 +350,7 @@ describe('figure-format — 판을 알아보는 문', () => {
     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 code of ['occupancy-changed', 'contact-face-changed', 'public-input-gone', 'public-input-range-narrowed', 'public-input-added', 'state-input-joints-changed', 'joint-axis-changed', 'joint-motion-unit-changed', 'joint-child-changed', 'joint-list-unread'])
         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

@@ -3,7 +3,7 @@
  * board (`consumablePayloadOf`). The format is `figure-asset-1`, and the asset says so in its `version`; a source
  * that does not is refused by name, because a source the server cannot identify is one it must not save.
  */
-import { compileFigureAsset, inspectFigureAsset, isPlaceholderType, parseFigureAsset, serializeFigureAsset, figureContractChanges, figureCostOf, figureOriginCentredOf, figureReleaseMetricsOf, figureScoreOf, figureTopViewOf } from '@hatiolab/figure-model'
+import { FIGURE_KERNEL_VERSION, compileFigureAsset, inspectFigureAsset, isPlaceholderType, parseFigureAsset, serializeFigureAsset, figureContractChanges, figureCostOf, figureOriginCentredOf, figureReleaseMetricsOf, figureScoreOf, figureTopViewOf } from '@hatiolab/figure-model'
 import type { FigureAsset, FigureContractChange, FigureContractError, FigureReleaseMetrics, FigureTopView, FigureViolation } from '@hatiolab/figure-model'
 
 import type { FigureFinding } from './figure-type.js'
@@ -461,6 +461,37 @@ function figureContractWording(change: FigureContractChange, say: Say): Pick<Gat
         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.')
       }
+    /* The joints a controller drives (ADR-0107 decision 7): what writing a state input moves, compared release to release. */
+    case 'state-input-joints-changed': {
+      const after = v.after || say('figure.gate.contract.joints-none', {}, 'nothing')
+      return {
+        message: say(key('message'), { ...v, after }, `The control '${v.id}' moved ${v.before}. It now moves ${after}.`),
+        why: say(key('why'), {}, 'A controller writes this value to drive those joints. After this release the same value moves other joints, or by other amounts.'),
+        ...gone
+      }
+    }
+    case 'joint-axis-changed':
+      return {
+        message: say(key('message'), v, `The axis of the joint '${v.joint}' changed from ${v.before} to ${v.after}.`),
+        why: say(key('why'), {}, "A controller's stored values turn or slide the joint about this axis. After this release the same value moves it another way."),
+        ...gone
+      }
+    case 'joint-motion-unit-changed':
+      return {
+        message: say(key('message'), v, `The joint '${v.joint}' now moves in ${v.after}, not ${v.before}.`),
+        why: say(key('why'), {}, "A controller's stored values were written for the old unit. After this release the same value means another motion."),
+        ...gone
+      }
+    case 'joint-child-changed':
+      return {
+        message: say(key('message'), v, `The joint '${v.joint}' now moves '${v.after}' instead of '${v.before}'.`),
+        why: say(key('why'), {}, "A controller's values keep their meaning. On screen the joint now moves the new part.")
+      }
+    case 'joint-list-unread':
+      return {
+        message: say(key('message'), v, `The last release's joint list could not be read, so its joints were not compared: ${v.reason}`),
+        why: say(key('why'), {}, "Whether this release changes what a controller's values move has not been checked. The last release was made by a kernel that did not measure joints.")
+      }
   }
 }
 
@@ -473,9 +504,9 @@ function figureContractWording(change: FigureContractChange, say: Say): Pick<Gat
 export function releaseRecordOf(
   sourceJson: string,
   releasedJson?: string | null
-): { format: string; changes: FigureContractChange[] | null; metrics: FigureReleaseMetrics; topView: FigureTopView } {
+): { format: string; kernel: string; changes: FigureContractChange[] | null; metrics: FigureReleaseMetrics; topView: FigureTopView } {
   const asset = parseFigureAsset(sourceJson)
-  const measured = { format: asset.version, metrics: figureReleaseMetricsOf(asset), topView: figureTopViewOf(asset, null) }
+  const measured = { format: asset.version, kernel: FIGURE_KERNEL_VERSION, metrics: figureReleaseMetricsOf(asset), topView: figureTopViewOf(asset, null) }
   if (!releasedJson) return { ...measured, changes: [] }
   let before: FigureAsset
   try {

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

@@ -124,11 +124,24 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   })
   changes?: string
 
+  /*
+   * 이 판을 잰 커널의 판(figure-model `FIGURE_KERNEL_VERSION`). 점수 · 묶음 · metrics 는 그 커널의 규칙으로 센 값이다 —
+   * 규칙이 바뀌어도 발행된 값을 다시 세서 덮지 않고(ADR-0109 C1), 읽는 쪽은 이 칸으로 「남긴 값」과 「지금 규칙의 값」을
+   * 가른다. 이 칸이 생기기 전에 발행된 판은 비어 있다.
+   */
+  @Column({ nullable: true })
+  @Field({
+    nullable: true,
+    description:
+      'The figure-model kernel version that measured this release (score, groups, metrics). null for releases made before releases recorded it.'
+  })
+  kernelVersion?: string
+
   @Column({ nullable: true, ...longTextColumn() })
   @Field({
     nullable: true,
     description:
-      'What this version measured once, as JSON (figure-model figureReleaseMetricsOf): { atLargest?: { size, triangles, groups }, linear?: { scalable, parts, probe } }. Only for a figure that takes its size from the instance; {} otherwise.'
+      'What this version measured once, as JSON (figure-model figureReleaseMetricsOf): { atLargest?: { size, triangles, groups }, linear?: { scalable, parts, probe }, origin?: { centred, off }, joints?: { schema, derivation, joints, unlisted } }. atLargest and linear only for a figure that takes its size from the instance. joints is the joint list a controller reads (schema 2, figure-model figureJointsOf), present when anything moves.'
   })
   metrics?: string
 

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

@@ -348,9 +348,10 @@ export class FigureMutation {
       version: nextVersion,
       state: 'released',
       updater: user,
-      /* 판본 구독자가 이것들을 판본의 comment · assetFormat · changes 로 옮긴다. Figure 의 칸이 아니다. */
+      /* 판본 구독자가 이것들을 판본의 comment · assetFormat · kernelVersion · changes 로 옮긴다. Figure 의 칸이 아니다. */
       __releaseComment: comment ?? null,
       __releaseFormat: record.format,
+      __releaseKernel: record.kernel,
       __releaseChanges: record.changes,
       __releaseMetrics: record.metrics,
       __releaseTopView: record.topView

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

@@ -7,13 +7,14 @@ 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')
+const { createFigureAsset, addFigureBox, serializeFigureAsset, applyFigureAuthoring, proposeFigureOccupancy, palletizerRobotFigure, FIGURE_KERNEL_VERSION } = require('@hatiolab/figure-model')
 
 let dataSource: DataSource | null = null
 let Figure: any
 let FigureHistory: any
 let Subscriber: any
 let FigureMutation: any
+let releaseRecordOf: any
 
 function loadCompiled(modulePath: string): any {
   const { existsSync } = require('fs')
@@ -29,6 +30,7 @@ beforeAll(async () => {
   FigureHistory = loadCompiled('service/figure/figure-history').FigureHistory
   Subscriber = loadCompiled('service/figure/event-subscriber').FigureHistoryEntitySubscriber
   FigureMutation = loadCompiled('service/figure/figure-mutation').FigureMutation
+  releaseRecordOf = loadCompiled('service/figure/figure-format').releaseRecordOf
   dataSource = new TypeOrmDataSource({
     type: 'sqlite',
     database: ':memory:',
@@ -65,6 +67,8 @@ describe('a release record on its history row', () => {
     expect(row.comment).toBe('first')
     expect(row.metrics).toBeNull()
     expect(row.topView).toBeNull()
+    /* A row the release did not stamp says so: not measured by a known kernel, rather than by today's. */
+    expect(row.kernelVersion).toBeNull()
   })
   it('[] stays nothing changed, null stays not compared', async () => {
     expect((await release({ __releaseFormat: 'figure-asset-1', __releaseChanges: [] })).changes).toBe('[]')
@@ -90,6 +94,8 @@ describe('releaseFigure records it', () => {
     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('[]')
+    /* Each release names the kernel that measured it (ADR-0109 C1). */
+    expect(rows.map((r: any) => r.kernelVersion)).toEqual([FIGURE_KERNEL_VERSION, FIGURE_KERNEL_VERSION])
     const codes = JSON.parse(rows[1].changes).map((c: any) => c.code)
     expect(codes).toContain('occupancy-changed')
     /* What each release measured, and its plan from above, are on its own row. */
@@ -97,3 +103,41 @@ describe('releaseFigure records it', () => {
     expect(JSON.parse(rows[1].topView).shapes.map((s: any) => s.id)).toEqual(['body'])
   })
 })
+
+/*
+  The joint list a controller reads rides the release's metrics (ADR-0107 decision 7): measured once, at release, and
+  read back from the history row. A re-release that turns a joint about another axis is refused with the sentence.
+*/
+describe('a release of a figure that moves keeps its joint list', () => {
+  const palletizer = (j4Axis?: string) => {
+    const { asset } = palletizerRobotFigure()
+    if (!j4Axis) return serializeFigureAsset(asset)
+    const j4 = asset.joints.find((j: any) => j.id === 'j4')
+    return serializeFigureAsset(applyFigureAuthoring(asset, { kind: 'set-joint', joint: { ...j4, axis: j4Axis } }))
+  }
+  it('schema 2, the wrist following -(j2 + j3), controls with both units; another axis is refused', async () => {
+    const domain = await dataSource!.getRepository(shell.Domain).save({ name: 'release-joints', subdomain: 'release-joints' })
+    const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
+    const figure = await dataSource!.getRepository(Figure).save({ type: 'PALLETIZER', name: 'palletizer', source: palletizer(), state: 'draft', version: 0, domain })
+    await new FigureMutation().releaseFigure(figure.id, 'one', context)
+
+    const [row] = await dataSource!.getRepository(FigureHistory).find({ where: { originalId: figure.id } })
+    const list = JSON.parse(row.metrics).joints
+    expect(list.schema).toBe(2)
+    const byId = new Map(list.joints.map((j: any) => [j.id, j]))
+    expect(byId.get('wrist')).toMatchObject({
+      type: 'revolute',
+      follows: { sum: [{ joint: 'j2', multiplier: -1 }, { joint: 'j3', multiplier: -1 }], offset: 0 }
+    })
+    expect((byId.get('wrist') as any).control).toBeUndefined()
+    for (const id of ['j1', 'j2', 'j3', 'j4']) expect((byId.get(id) as any).control).toMatchObject({ inputUnit: 'deg', motionUnit: 'deg' })
+    expect(list.unlisted).toEqual([])
+
+    /* The same figure with J4 turning about X: the kernel's comparison blocks it, and the door refuses with its sentence. */
+    const changes = releaseRecordOf(palletizer('X'), row.source).changes
+    expect(changes).toContainEqual(expect.objectContaining({ code: 'joint-axis-changed', blocking: true, subject: 'j4' }))
+    await dataSource!.getRepository(Figure).save({ ...(await dataSource!.getRepository(Figure).findOneOrFail({ where: { id: figure.id } })), domain, source: palletizer('X'), state: 'draft' })
+    await expect(new FigureMutation().releaseFigure(figure.id, 'two', context)).rejects.toThrow(/The axis of the joint 'j4' changed/)
+    expect(await dataSource!.getRepository(FigureHistory).count({ where: { originalId: figure.id } })).toBe(1)
+  })
+})

package/translations/en.json

@@ -75,6 +75,17 @@
   "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.",
+  "figure.gate.contract.joints-none": "nothing",
+  "figure.gate.contract.state-input-joints-changed.message": "The control '{id}' moved {before}. It now moves {after}.",
+  "figure.gate.contract.state-input-joints-changed.why": "A controller writes this value to drive those joints. After this release the same value moves other joints, or by other amounts.",
+  "figure.gate.contract.joint-axis-changed.message": "The axis of the joint '{joint}' changed from {before} to {after}.",
+  "figure.gate.contract.joint-axis-changed.why": "A controller's stored values turn or slide the joint about this axis. After this release the same value moves it another way.",
+  "figure.gate.contract.joint-motion-unit-changed.message": "The joint '{joint}' now moves in {after}, not {before}.",
+  "figure.gate.contract.joint-motion-unit-changed.why": "A controller's stored values were written for the old unit. After this release the same value means another motion.",
+  "figure.gate.contract.joint-child-changed.message": "The joint '{joint}' now moves '{after}' instead of '{before}'.",
+  "figure.gate.contract.joint-child-changed.why": "A controller's values keep their meaning. On screen the joint now moves the new part.",
+  "figure.gate.contract.joint-list-unread.message": "The last release's joint list could not be read, so its joints were not compared: {reason}",
+  "figure.gate.contract.joint-list-unread.why": "Whether this release changes what a controller's values move has not been checked. The last release was made by a kernel that did not measure joints.",
   "error.figure-release-not-found": "{type} has no release {version}. its latest release is {latest}.",
   "figure.gate.origin-off-centre.message": "The origin is off the middle of the declared room: {off}.",
   "figure.gate.origin-off-centre.why": "A drawing that places figures by the middle of their room puts this one that far from where it is drawn.",

package/translations/ko.json

@@ -75,6 +75,17 @@
   "figure.gate.contract.public-input-range-narrowed.why": "새 범위 밖의 값을 준 인스턴스가 있을 수 있습니다. 어떤 값이 놓였는지는 기록하지 않습니다.",
   "figure.gate.contract.public-input-added.message": "'{input}' 값을 이제 보드에서 정할 수 있습니다.",
   "figure.gate.contract.public-input-added.why": "값을 주지 않은 인스턴스는 기본값으로 섭니다.",
+  "figure.gate.contract.joints-none": "없음",
+  "figure.gate.contract.state-input-joints-changed.message": "'{id}' 조작값이 움직이던 관절이 {before} 에서 {after} 로 바뀌었습니다.",
+  "figure.gate.contract.state-input-joints-changed.why": "컨트롤러는 이 값을 써서 그 관절들을 움직입니다. 이 발행 뒤에는 같은 값이 다른 관절을 움직이거나 다른 양만큼 움직입니다.",
+  "figure.gate.contract.joint-axis-changed.message": "'{joint}' 관절의 축이 {before} 에서 {after} 로 바뀌었습니다.",
+  "figure.gate.contract.joint-axis-changed.why": "컨트롤러가 저장한 값은 이 축을 기준으로 관절을 회전하거나 이동합니다. 이 발행 뒤에는 같은 값이 다른 방향으로 움직입니다.",
+  "figure.gate.contract.joint-motion-unit-changed.message": "'{joint}' 관절의 움직임 단위가 {before} 에서 {after} 로 바뀌었습니다.",
+  "figure.gate.contract.joint-motion-unit-changed.why": "컨트롤러가 저장한 값은 옛 단위에 맞춰 쓰였습니다. 이 발행 뒤에는 같은 값이 다른 움직임이 됩니다.",
+  "figure.gate.contract.joint-child-changed.message": "'{joint}' 관절이 '{before}' 대신 '{after}' 부품을 움직입니다.",
+  "figure.gate.contract.joint-child-changed.why": "컨트롤러의 값은 뜻이 그대로입니다. 화면에서는 그 관절이 새 부품을 움직입니다.",
+  "figure.gate.contract.joint-list-unread.message": "직전 발행본의 관절 목록을 읽지 못해 관절을 비교하지 않았습니다: {reason}",
+  "figure.gate.contract.joint-list-unread.why": "이 발행이 컨트롤러의 값이 움직이는 것을 바꾸는지는 확인하지 않았습니다. 직전 발행본은 관절을 재지 않던 커널로 발행되었습니다.",
   "error.figure-release-not-found": "{type} 에는 {version} 번 발행판이 없습니다. 최신 발행판은 {latest} 번입니다.",
   "figure.gate.origin-off-centre.message": "원점이 차지 공간 가운데에서 비켜 있습니다: {off}.",
   "figure.gate.origin-off-centre.why": "공간 가운데로 도형을 놓는 도면에서는 그린 자리에서 그만큼 떨어져 놓입니다.",