@things-factory/figure-service 10.1.26 → 10.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.26",
+  "version": "10.1.28",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,13 +25,13 @@
   "dependencies": {
     "@hatiolab/figure-model": "^0.1.21",
     "@operato/typeorm-history": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.26",
-    "@things-factory/auth-base": "^10.1.26",
+    "@things-factory/ai-client-base": "^10.1.28",
+    "@things-factory/auth-base": "^10.1.28",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.26",
+    "@things-factory/shell": "^10.1.28",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "151bda14d899442c6846532ddded1e2bfe23a2f5"
+  "gitHead": "3a260a0f79bc6b41a692a103955bfcc541aff60e"
 }

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

@@ -1,4 +1,4 @@
-import { blocksRelease, compile, sizingReport, validate } from '@hatiolab/figure-model'
+import { blocksRelease, compile, contractChanges, sizingReport, validate } from '@hatiolab/figure-model'
 import type { Axis, FigureSource } from '@hatiolab/figure-model'
 
 /** Service transport shape. It deliberately contains only an explicit, reversible FigureSource edit. */
@@ -127,8 +127,11 @@ function measuredFixes(source: FigureSource, factor: number): GateFix[] {
  *
  * 정본이 없거나(아직 저장 전) JSON 이 아니면 **막는다** — 발행할 대상이 없는 것이다. 그 경우를
  * 조용히 통과시키면 빈 것이 발행된다.
+ *
+ * `releasedJson` 은 **직전 발행판의 정본**이다. 주면 그것과 견주어 「이미 놓인 인스턴스를 깨는
+ * 발행인가」를 함께 낸다(ADR-0063 결정 3). 한 번도 발행된 적 없으면 견줄 것이 없으므로 안 준다.
  */
-export function inspectSource(sourceJson?: string | null): Inspection {
+export function inspectSource(sourceJson?: string | null, releasedJson?: string | null): Inspection {
   if (!sourceJson) {
     return {
       blocked: true,
@@ -187,11 +190,48 @@ export function inspectSource(sourceJson?: string | null): Inspection {
         how: finding.how,
         /* 숫자가 아니라 자리를 말한다 — 어느 부품들이 갈라져 나왔나. */
         at: finding.clumps.map(clump => [...clump].sort().join('+')).join(' | ') || undefined,
-        fixes: finding.code === 'sizing-splits' ? fixes.filter(fix => fix.findingWay === finding.way) : undefined,
+          fixes: finding.code === 'sizing-splits' ? fixes.filter(fix => fix.findingWay === finding.way) : undefined,
         blocking: finding.code === 'sizing-splits'
       })
     }
+
+    findings.push(...contractFindings(source, releasedJson))
   }
 
   return { findings, blocked: findings.some(finding => finding.blocking) }
 }
+
+/**
+ * 직전 발행판과 견준 것 — **약속을 깨는 발행인가**(ADR-0063 결정 3).
+ *
+ * 무엇이 달라졌고 그것이 막는 것인지는 형식이 정한다(`contractChanges`). 여기서는 화면과 발행 문이
+ * 읽는 모양으로 옮기기만 한다.
+ *
+ * **앞 판을 오늘 형식으로 못 읽으면 조용히 넘어가지 않는다.** 판 1 은 오늘 형식이 거절하는 판으로
+ * 적혀 있을 수 있고, 그때 견주기를 건너뛰면 아무 말 없이 관문이 없는 것이 된다. 막지는 않는다 —
+ * 그러면 그 도형은 영영 다시 발행할 수 없다.
+ */
+function contractFindings(source: FigureSource, releasedJson?: string | null): GateFinding[] {
+  if (!releasedJson) return []
+
+  let released: FigureSource
+  try {
+    released = JSON.parse(releasedJson) as FigureSource
+    return contractChanges(released, source).map(change => ({
+      code: change.code,
+      message: change.message,
+      why: change.why,
+      at: change.subject,
+      blocking: change.blocking
+    }))
+  } catch (e) {
+    return [
+      {
+        code: 'released-unreadable',
+        message: `직전 발행판을 오늘 형식으로 읽을 수 없어 견주지 못했다: ${(e as Error).message}`,
+        why: '이 발행이 이미 놓인 인스턴스를 깨는지는 확인되지 않았다.',
+        blocking: false
+      }
+    ]
+  }
+}

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

@@ -168,7 +168,19 @@ export class FigureMutation {
 
       막는 이유는 사유와 함께 낸다. 「발행할 수 없습니다」로 뭉치면 무엇을 고쳐야 하는지 모른다.
     */
-    const inspection = inspectSource(figure.source)
+    /*
+      직전 발행판을 먼저 꺼낸다. 판 번호를 세는 데도 쓰고, **약속을 깨는 발행인가**를 견주는 데도
+      쓴다(ADR-0063 결정 3) — 도면은 type 만 적고 늘 최신 발행판을 그리므로, 다시 발행하는 것은
+      그 type 을 놓아 둔 모든 도면에게 같은 약속을 다시 하는 일이다.
+    */
+    const released = await historyRepository
+      .createQueryBuilder('history')
+      .where('history.originalId = :id', { id: figure.id })
+      .orderBy('history.version', 'DESC')
+      .limit(1)
+      .getOne()
+
+    const inspection = inspectSource(figure.source, released?.source)
     if (inspection.blocked) {
       const reasons = inspection.findings
         .filter(finding => finding.blocking)
@@ -177,13 +189,7 @@ export class FigureMutation {
       throw new Error(`Figure '${figure.type}' 은 아직 발행할 수 없다 — ${reasons.join(' · ')}`)
     }
 
-    const highest = await historyRepository
-      .createQueryBuilder('history')
-      .select('MAX(history.version)', 'max')
-      .where('history.originalId = :id', { id: figure.id })
-      .getRawOne()
-
-    const nextVersion = highest?.max ? Number(highest.max) + 1 : 1
+    const nextVersion = released?.version ? Number(released.version) + 1 : 1
 
     return await repository.save({
       /*

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

@@ -255,6 +255,16 @@ describe('프롬프트는 형식을 따라간다 — 손으로 적은 목록이
   }
 })
 
+describe('joints (ADR-0066)', () => {
+  it('teaches the joint shape with the type vocabulary, and a joint channel with no path and a number per key', () => {
+    const prompt = rulesPrompt(PALETTE)
+    expect(prompt).toContain(`type: ${(model as any).JOINT_TYPES.join(' | ')}`)
+    expect(prompt).toMatch(/NO path, NO pivot/)
+    expect(prompt).toMatch(/limits must include 0/)
+    expect(prompt).toMatch(/ONLY place a parent is written/)
+  })
+})
+
 describe('고치라는 요청일 때', () => {
   it('요청이 안 건드린 것을 그대로 실으라고 못 박는다', async () => {
     /*
@@ -270,7 +280,7 @@ describe('고치라는 요청일 때', () => {
     expect(sent).toMatch(/dropping one is silent/)
 
     /* 잃기 쉬운 칸은 이름으로 짚어 준다 — 「전부 지켜라」만으로는 모델이 빠뜨린다. */
-    for (const field of ['animations', 'capabilities', 'anchor', 'repeat', 'label', 'materialSlot']) {
+    for (const field of ['animations', 'parameters', 'joints', 'capabilities', 'parent', 'anchor', 'repeat', 'label', 'materialSlot']) {
       expect(sent).toContain(field)
     }
   })

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

@@ -17,6 +17,7 @@ import {
   SEGMENT_PRESETS,
   SIZING_RULES,
   FIGURE_PLACEMENTS,
+  JOINT_TYPES,
   FIGURE_SOURCE_VERSION,
   compile,
   costOf,
@@ -148,12 +149,12 @@ export function rulesPrompt(palette: string[]): string {
     '',
     'The JSON is a FigureSource:',
     `  { version: ${FIGURE_SOURCE_VERSION}, type, base: {x,y,z}, placement?, detailLevel, parts: [...],`,
-    '    animations?: [...], parameters?: [...], capabilities?: [...] }',
+    '    animations?: [...], parameters?: [...], capabilities?: [...], joints?: [...] }',
     '',
     'A part is:',
     '  { name, primitive, transform: { position: {x,y,z}, size: {x,y,z}, rotation?: {x,y,z} },',
     '    material: { token, preset?, flatShading?, transparent?, emissive? },',
-    '    segments?, shape?, materialSlot?, keepRound?, sizing?, anchor?, repeat?, label?, capability? }',
+    '    segments?, shape?, materialSlot?, keepRound?, sizing?, anchor?, repeat?, label?, capability?, parent? }',
     '',
     'Hard vocabulary — anything outside these is rejected:',
     `  placement   ${FIGURE_PLACEMENTS.join(' | ')} (floor: default, ground equipment; ceiling: overhead hoist/OHT; center: airborne/drone/sensor)`,
@@ -274,6 +275,23 @@ export function rulesPrompt(palette: string[]): string {
     '    Do NOT answer it with a capability. Capabilities say what a figure does in the FLOW;',
     '    how a pose is driven is a different axis entirely.',
     '',
+    'Joints — a part that moves RELATIVE TO ANOTHER PART, carrying what is attached to it:',
+    '  An arm whose shoulder turns and carries the elbow, wrist and gripper; a crane whose bridge',
+    '  slides and carries the trolley and hook. Without joints every channel moves one part alone,',
+    '  so two turning links do not compose.',
+    '  parent on a part names the part it is attached to. It is the ONLY place a parent is written.',
+    '    A part without parent hangs from the figure. Following parents must end; no loops.',
+    `  joints: [{ name, child, type: ${JOINT_TYPES.join(' | ')}, origin: {x,y,z}, axis: {x,y,z}, limits?: { min, max } }]`,
+    '    child is the part that moves; its parent is what it moves relative to. One joint per part.',
+    '    origin is the point it turns about or slides from, in the same coordinates as part',
+    '    positions (y from the bottom of the base). axis is the direction: turning follows the',
+    '    right-hand rule. revolute and continuous are in degrees, prismatic in mm.',
+    '    Parts are drawn in the pose where every joint is 0, so limits must include 0.',
+    '    continuous has no limits. Joint names and part names must all be different.',
+    '  A joint moves only through a parameter (or an animation for endless turning): a channel',
+    '    { target: <joint name>, keys: [{ at, value: <number> }] } — NO path, NO pivot, and each',
+    '    value is the joint coordinate, within limits. A 6-axis arm is six joints and six parameters.',
+    '',
     '  Names are shared between the two lists: an instance addresses a curve by name, so an',
     '    animation and a parameter may not be called the same thing.',
     '  Doors that open together belong in one curve with two channels, not two curves.',
@@ -295,8 +313,8 @@ function taskPrompt(input: ProposeInput): string {
       '',
       'Revise this existing figure. Keep the part names that still mean the same thing —',
       'renaming a part breaks bindings on instances already placed.',
-      'Carry over everything the request did not ask you to change. animations, capabilities,',
-      'capability, anchor, repeat, label and materialSlot are easy to drop by writing them out of',
+      'Carry over everything the request did not ask you to change. animations, parameters, joints,',
+      'capabilities, capability, parent, anchor, repeat, label and materialSlot are easy to drop by writing them out of',
       'the JSON, and dropping one is silent — the figure still validates, it just stops doing what',
       'it did. If the request says nothing about movement, the clips come back unchanged.',
       JSON.stringify(input.base)

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

@@ -113,7 +113,18 @@ export class FigureQuery {
       throw new Error(`Figure ${id} 를 찾을 수 없다`)
     }
 
-    return inspectSource(figure.source)
+    /*
+      **화면이 발행 문과 같은 것을 본다.** 직전 발행판을 여기서도 함께 넘기지 않으면, 저작 화면은
+      조용한데 발행을 누른 순간 계약 위반으로 막힌다 — 그때는 이미 열 군데를 고친 뒤다.
+    */
+    const released = await getRepository(FigureHistory)
+      .createQueryBuilder('history')
+      .where('history.originalId = :id', { id })
+      .orderBy('history.version', 'DESC')
+      .limit(1)
+      .getOne()
+
+    return inspectSource(figure.source, released?.source)
   }
 
   @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')

package/server/service/figure/figure-tool-doors.test.ts

@@ -0,0 +1,38 @@
+/*
+ * figure 도구가 지나는 문 — ADR-0072 결정 2.
+ *
+ * 선언만 해 두고 아무도 읽지 않으면 그 선언은 다음 사람이 지우거나 바꿔도 아무 일이 없다. 여기서는
+ * 실제로 등록된 명세를 등록기에 넣고, 등록기가 무엇도 문제 삼지 않는지 묻는다. 도구 목록이 늘면
+ * 이 시험이 먼저 문다.
+ */
+import { clearToolRegistry, getAllToolSpecs, getToolRegistryWarnings } from '@things-factory/ai-client-base'
+
+import { registerFigureToolCategories } from './figure-tools'
+
+describe('figure tools — declared doors', () => {
+  beforeEach(() => {
+    clearToolRegistry()
+    registerFigureToolCategories()
+  })
+  afterAll(() => clearToolRegistry())
+
+  it('★ every figure tool says which doors it reaches, as a list', () => {
+    const undeclared = getAllToolSpecs()
+      .filter(spec => !Array.isArray((spec as any).doors))
+      .map(spec => spec.name)
+
+    expect(undeclared).toEqual([])
+  })
+
+  it('★ a door a tool reaches comes with the privilege that guards it', () => {
+    const unguarded = getAllToolSpecs()
+      .filter(spec => ((spec as any).doors ?? []).length > 0 && !(spec as any).privilege)
+      .map(spec => spec.name)
+
+    expect(unguarded).toEqual([])
+  })
+
+  it('the registry itself finds nothing to report about these specs', () => {
+    expect(getToolRegistryWarnings().map(w => `${w.code}:${w.params.tool ?? ''}`)).toEqual([])
+  })
+})

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

@@ -117,7 +117,12 @@ test('실제 registryAssistantChat 경계가 열린 모델 문맥을 Figure 도
     } } as any,
     messages: [{ role: 'user', content: '현재 모델을 조회해줘' }],
     systemPrompt: 'Read the current figure.', toolCategories: ['figure-authoring'],
-    state: { domain: MINE }, hostContext: { figureId: 'fig-1', draftSource: SOURCE }
+    state: { domain: MINE }, hostContext: { figureId: 'fig-1', draftSource: SOURCE },
+    /*
+     * 도구가 닿는 문의 권한을 선언한 뒤로(ADR-0071 결정 2), 권한을 물어볼 길을 주지 않으면 그 도구는
+     * 닫힌다 — 그것이 맞는 기본값이다. 여기서 보는 것은 권한이 아니라 배선이므로 「가진 사람」으로 둔다.
+     */
+    toolAccess: async () => true
   })
   expect(seen).toHaveLength(2)
   expect(JSON.stringify(seen[1])).toContain('MIXER')

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

@@ -232,7 +232,7 @@ function unsavedFigure(host: any): any | undefined {
 const FIGURE_ID_ARG = {
   figureId: {
     type: 'string',
-    description: 'The figure to read. Omit when host context has an open figureId or an unsaved new editor draft. On the catalog, first resolve the user’s requested figure with listFigures.'
+    description: 'The figure to read. Omit to read the one the person has open, saved or not — the server fills it in, and you cannot see which it is. On the catalog nothing is open, so resolve the figure the person asked for with listFigures first.'
   }
 } as const
 
@@ -247,6 +247,9 @@ function figureToolSpecs(): ToolSpec[] {
     {
       kind: 'read',
       name: 'listFigures',
+      /* 이 도메인의 도형 목록 — 저장소를 직접 읽지만 같은 일을 하는 문은 이것이다. */
+      doors: ['Query.figures'],
+      privilege: { category: 'figure', privilege: 'query', owner: true },
       description:
         'Lists the figures in this tenant with their type names, states and part counts. ' +
         'Call it before naming a type — type names are stored identifiers and must not be invented.',
@@ -274,9 +277,13 @@ function figureToolSpecs(): ToolSpec[] {
     {
       kind: 'read',
       name: 'getFigureSource',
+      /* 저장된 도형의 원본. **저장 전 초안**을 물으면 저장소에 갈 것이 없어 화면이 보낸 것을 그대로 돌려준다 —
+       * 그 갈래에는 닿는 문이 없지만 `doors: []` 로 적지 않는다. 그러면 저장된 도형을 읽는 권한 검사가 선언에서 사라진다. */
+      doors: ['Query.figure'],
+      privilege: { category: 'figure', privilege: 'query', owner: true },
       description:
         'Returns the canonical FigureSource of one figure, with its measured cost ' +
-        '(triangles, draw calls, how many fit on one board). Call it before proposing a revision — ' +
+        '(triangles, part groups, and how many of it hold 60fps on one screen). Call it before proposing a revision — ' +
         'revising without reading it means proposing against a guess.',
       schema: { type: 'object', properties: { ...FIGURE_ID_ARG } },
       builder: async (args: any, ctx: any) => {
@@ -309,6 +316,9 @@ function figureToolSpecs(): ToolSpec[] {
     {
       kind: 'read',
       name: 'inspectFigure',
+      /* 검사 결과 — 같은 일을 하는 문. */
+      doors: ['Query.inspectFigure'],
+      privilege: { category: 'figure', privilege: 'query', owner: true },
       description:
         'Says whether a figure may be released and, when it may not, what is wrong — each finding ' +
         'carries why it is a problem and what to change. Call it when asked about releasing, or ' +
@@ -328,6 +338,9 @@ function figureToolSpecs(): ToolSpec[] {
     {
       kind: 'read',
       name: 'proposeFigureCandidate',
+      /* 후보 생성 — 저장은 하지 않지만 같은 문의 권한을 쓴다. */
+      doors: ['Mutation.proposeFigure'],
+      privilege: { category: 'figure', privilege: 'mutation', owner: true },
       description:
         'Asks for a figure candidate from a description, optionally revising an existing one. ' +
         'Returns the candidate with its score and cost. NOTHING IS SAVED — the author accepts or ' +