@things-factory/figure-service 10.1.27 → 10.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.27",
+  "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.27",
+    "@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.27",
+    "@things-factory/shell": "^10.1.28",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "d04dc762cacf2aac8ba0b0f5d768eca365fc09da"
+  "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-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 ' +