@things-factory/figure-service 10.1.17 → 10.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.17",
+  "version": "10.1.18",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -23,15 +23,15 @@
     "migration:create": "node ../../node_modules/typeorm/cli.js migration:create ./server/migrations/migration"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.18",
+    "@hatiolab/figure-model": "^0.1.19",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.8",
-    "@things-factory/auth-base": "^10.1.17",
+    "@things-factory/auth-base": "^10.1.18",
     "@things-factory/env": "^10.1.3",
     "@things-factory/shell": "^10.1.16",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "0c8214182702162ceb5398bdcf42ef14ea672394"
+  "gitHead": "608fe1a70f430ae9c3aa20497173cecc8121373e"
 }

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

@@ -36,11 +36,11 @@ describe('release-gate repair candidates', () => {
  *
  * `base` is the number an instance is scaled by (`instanceScale = width/base.x`) and the placement
  * height comes out of `base.y`. A figure whose box disagrees with its parts renders at the wrong
- * size and the wrong height the moment it lands on a board, so publishing it breaks that promise
+ * size and the wrong height the moment it is placed, so publishing it breaks that promise
  * even though the source itself is well formed.
  *
  * Saving is still allowed — these are violations, not errors — so a figure already standing on a
- * board keeps standing. It just cannot be published again until it is fixed.
+ * drawing keeps standing. It just cannot be published again until it is fixed.
  */
 describe('release gate — the base box', () => {
   /** A figure that sits correctly in its box: 200 tall, foot on the floor at -100. */

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

@@ -278,7 +278,7 @@ export class FigureMutation {
   async deleteFigure(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<boolean> {
     const { domain, tx } = context.state
 
-    // 소프트 삭제다 — 이미 배치된 보드가 이 타입을 참조할 수 있으므로 행을 지우지
+    // 소프트 삭제다 — 이미 배치된 도면이 이 타입을 참조할 수 있으므로 행을 지우지
     // 않는다. 되살릴 길을 남긴다.
     await tx.getRepository(Figure).softDelete({ domain: { id: domain.id }, id })
 

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

@@ -14,7 +14,6 @@ import {
   ANCHOR_RULES,
   DETAIL_LEVELS,
   CHANNEL_PATHS,
-  CLIP_DRIVES,
   FIGURE_PLACEMENTS,
   INTERPOLATIONS,
   LABEL_WHENS,
@@ -78,7 +77,7 @@ function candidate(over: Record<string, unknown> = {}) {
  *
  * **받은 말을 적어 둔다.** 프롬프트에 실려 나가는 지시 중에 지켜져야 할 것이 있어서다 —
  * 고치는 요청에서 「부품 이름을 바꾸지 말라」가 빠지면 AI 가 이름을 갈아 버리고, 그러면
- * 이미 배치된 보드의 바인딩이 끊긴다. 답만 보는 모형으로는 그것이 나갔는지 알 수 없다.
+ * 이미 배치된 도면의 바인딩이 끊긴다. 답만 보는 모형으로는 그것이 나갔는지 알 수 없다.
  */
 function stubClient(answers: unknown[]): AIClient & { calls: number; sent: any[][]; system?: string } {
   const client = {
@@ -165,7 +164,9 @@ describe('프롬프트는 형식을 따라간다 — 손으로 적은 목록이
     VIOLATION_CODES: '같다',
     RELEASE_BLOCKING_VIOLATIONS: '위반 코드의 부분집합이다 — 어느 것이 발행을 막나는 관문이 알 일이지 저작자가 적는 값이 아니다',
     AXES: "'x'·'y'·'z' 는 축 이름이고 값이 아니다 — 쓰는 자리에서 anchor.<axis> 로 가르친다",
-    SURFACE_KINDS: 'material.surface 는 things-scene 에 소비처가 0건이다 — 그릴 수 없는 것을 시키지 않는다'
+    SURFACE_KINDS: 'material.surface 는 things-scene 에 소비처가 0건이다 — 그릴 수 없는 것을 시키지 않는다',
+    CLIP_DRIVES:
+      '없어지는 이름이다 — 값이 만드는 자세가 `parameters` 로 나갔고(ADR-0051 ①) `compile()` 이 옛 원본의 hold 를 옮길 때만 읽는다. 새로 적는 값이 아니다'
   }
 
   it('저작에 쓰이는 열거는 값 하나도 빠짐없이 프롬프트에 있다', () => {
@@ -438,8 +439,8 @@ describe('후보를 만들 때', () => {
 describe('무엇을 시키는지가 프롬프트에 실린다', () => {
   /*
     고치는 요청에서 이 지시가 빠지면 AI 가 부품 이름을 갈아 버린다. 부품 이름은 **저장되는
-    식별자**라서, 이미 배치된 보드의 바인딩·애니메이션이 그 이름을 가리키고 있다. 조용히
-    끊기고, 끊긴 것은 그 보드를 열어 봐야 드러난다.
+    식별자**라서, 이미 배치된 도면의 바인딩·애니메이션이 그 이름을 가리키고 있다. 조용히
+    끊기고, 끊긴 것은 그 도면을 열어 봐야 드러난다.
   */
   it('고치는 요청이면 지금 정본과 「이름을 바꾸지 말라」가 함께 나간다', async () => {
     const client = stubClient([candidate()])
@@ -552,3 +553,73 @@ describe('정책을 넘은 후보는 막지 않고 알린다', () => {
     expect(result.violations.map(one => one.code)).toContain('too-many-parts')
   })
 })
+
+/*
+ * `parameters` — the one field that answers "expose a value an instance can be given".
+ *
+ * A user asked for a hoist that lowers and raises, with the travel exposed as a variable. The
+ * model answered with `sizing`/`anchor` on the figure's own height and invented
+ * `capabilities: ["hoist"]`, which threw at render. It had not declined; it had gone looking and
+ * not found -- because the door was hidden inside animations as `drive: 'hold'`, and the prompt
+ * described that as a playback mode ("hold plays once and stays") when what it actually said was
+ * WHO SUPPLIES THE VALUE.
+ *
+ * ADR-0051 moved it into its own field with a declared physical range, which is what makes the
+ * value nameable: an instance gives 1200mm, not 0.67.
+ *
+ * These guard the wording, because the wording is the defect. A prompt that hides the one door
+ * leaves the model to invent a door.
+ */
+describe('값이 만드는 자세를 parameters 로 가르친다', () => {
+  const prompt = () => rulesPrompt(PALETTE)
+
+  it('재생 방식으로 적지 않는다', () => {
+    expect(prompt()).not.toMatch(/plays once|repeats forever/i)
+    expect(prompt()).toMatch(/Nothing is played back/)
+  })
+
+  it('두 갈래를 갈라서 적는다 — 어느 쪽이 무엇을 받는지까지', () => {
+    const text = prompt()
+    expect(text).toMatch(/TWO kinds and they are different fields/)
+    expect(text).toMatch(/animations\s+TIME RUNS\. The instance supplies a SPEED/)
+    expect(text).toMatch(/parameters\s+A VALUE MAKES THE POSE/)
+  })
+
+  it('인스턴스가 받는 값을 물으면 parameters 라고 못 박는다', () => {
+    /* 이 문장이 없으면 모델이 크기 반응 쪽으로 간다 — 실제로 갔다. */
+    expect(prompt()).toMatch(/USE parameters WHENEVER THE REQUEST ASKS FOR A VALUE THE INSTANCE IS GIVEN/)
+    expect(prompt()).toMatch(/EXPOSE something AS A VARIABLE/)
+  })
+
+  it('세 가지 잘못된 답을 각각 막는다 — 크기 반응 · 애니메이션 · 능력', () => {
+    const text = prompt()
+    expect(text).toMatch(/Do NOT answer that request with sizing or anchor/)
+    expect(text).toMatch(/Do NOT answer it with animations either/)
+    /* `capabilities: ['hoist']` 가 실제로 나왔던 답이다. */
+    expect(text).toMatch(/Do NOT answer it with a capability/)
+  })
+
+  it('범위를 사람이 말하는 단위로 적으라고 한다 — 0~1 이 아니라', () => {
+    /*
+      곡선의 값 축은 0~1 이지만 그것은 런타임의 말이다. 저작자와 인스턴스가 주고받는 것은
+      mm 이고, 그 선언이 없으면 「길이값을 변수로 노출」이 성립하지 않는다.
+    */
+    const text = prompt()
+    expect(text).toMatch(/range: \{ unit, min, max \}/)
+    expect(text).toMatch(/not 0 to 1/)
+  })
+
+  it('파라미터의 at 이 초가 아니라고 말한다', () => {
+    /*
+      값 0~1 이 `[0, 마지막 키]` 로 맵되므로 키의 절대값은 자세를 안 바꾼다 — 간격만 바꾼다.
+      그 마지막 값이 전 구간 이동 시간을 겸한다는 것도 함께 적혀 있어야 한다.
+    */
+    const text = prompt()
+    expect(text).toMatch(/only the SPACING between keys matters/)
+    expect(text).toMatch(/doubles as the seconds a full min-to-max move takes/)
+  })
+
+  it('두 목록이 이름을 나눠 쓴다고 말한다 — 겹치면 형식이 막는다', () => {
+    expect(prompt()).toMatch(/may not be called the same thing/)
+  })
+})

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

@@ -2,7 +2,6 @@ import {
   ANCHOR_RULES,
   AXES,
   CHANNEL_PATHS,
-  CLIP_DRIVES,
   DETAIL_LEVELS,
   INTERPOLATIONS,
   LABEL_WHENS,
@@ -165,13 +164,12 @@ export function rulesPrompt(palette: string[]): string {
     `  capability.roles  ${PART_ROLES.join(' | ')}`,
     `  label.when      ${LABEL_WHENS.join(' | ')}`,
     `  animation.path  ${CHANNEL_PATHS.join(' | ')}`,
-    `  animation.drive ${CLIP_DRIVES.join(' | ')}`,
     `  animation.interpolation ${INTERPOLATIONS.join(' | ')}`,
     `  detailLevel ${DETAIL_LEVELS.join(' | ')}`,
     '',
     'Hard rules about the base box — publication is refused when either is broken:',
     '  Every part must sit inside the base box: |position.<axis>| + size.<axis>/2 <= base.<axis>/2.',
-    '  base is the number an instance is scaled by, so a part outside it grows wrongly on a board.',
+    '  base is the number an instance is scaled by, so a part outside it grows wrongly once placed.',
     '  The figure must touch the face its placement names — floor: the lowest part reaches',
     '  y = -base.y/2; ceiling: the highest reaches y = +base.y/2; center: no requirement.',
     '  base may be LARGER than the parts. That slack is a declaration (clearance in front of a',
@@ -232,19 +230,45 @@ export function rulesPrompt(palette: string[]): string {
     '  label is a place a number is shown on the figure: { name, source, when }. The figure says',
     '  where it goes; the scene says what the value is.',
     '',
-    'Movement:',
-    '  animations is on the FigureSource, not inside a part, because one clip moves several parts.',
-    '    [{ name, drive?, channels: [{ target, path, pivot?, interpolation?, keys: [...] }] }]',
-    '    target is a part name. keys are [{ at: seconds, value: {x,y,z} }].',
-    '    At least TWO keys, with `at` strictly increasing — one key is a pose, not motion.',
-    '    translation is an offset, rotation is DEGREES, scale is a multiplier where 1 is full size.',
-    '    pivot is the centre of rotation in the part\'s own axes; without it the part spins on itself.',
-    '    drive loop repeats forever, hold plays once and stays. Clip length is the last key\'s time.',
-    '  Doors that open together belong in one clip with two channels, not two clips.',
+    'Movement — there are TWO kinds and they are different fields:',
+    '  Both live on the FigureSource, not inside a part, because one curve moves several parts.',
+    '  A channel is { target, path, pivot?, interpolation?, keys: [{ at, value: {x,y,z} }] }.',
+    '    target is a part name. At least TWO keys, `at` strictly increasing — one key is a pose,',
+    '    not motion. translation is an offset, rotation is DEGREES, scale is a multiplier where 1',
+    '    is full size. pivot is the centre of rotation in the part\'s own axes; without it the part',
+    '    spins on itself.',
+    '',
+    '  animations  TIME RUNS. The instance supplies a SPEED: 1 is normal, 0 is stopped.',
+    '    [{ name, channels: [...] }]   `at` is seconds and the clip is as long as its last key.',
+    '    A turning roller, a spinning fan, a blinking beacon.',
+    '',
+    '  parameters  A VALUE MAKES THE POSE. Nothing is played back; the figure simply IS this far.',
+    '    [{ name, label?, default?, range: { unit, min, max }, clip: { channels: [...] } }]',
+    '    The instance supplies a PHYSICAL QUANTITY in `range.unit` — 1200 mm, 40 %, 90 deg — and',
+    '    the runtime maps it onto the curve. So `at` on the keys is NOT seconds here: the first key',
+    '    is range.min, the last is range.max, and only the SPACING between keys matters.',
+    '    The last `at` doubles as the seconds a full min-to-max move takes — that is the machine\'s',
+    '    speed. A hoist that takes 2.5s to run its whole travel ends its curve at 2.5.',
+    '    unit is a free word the screen shows: mm, deg, %, kg. max must be above min.',
+    '',
+    '  USE parameters WHENEVER THE REQUEST ASKS FOR A VALUE THE INSTANCE IS GIVEN, or asks to',
+    '    EXPOSE something AS A VARIABLE — how far a hoist has lowered, how high a fork has lifted,',
+    '    how far a nip has closed, how far a door is open. The range is what makes the value',
+    '    nameable, so always give it in the unit a person would state: a 1800mm hoist is',
+    '    { unit: "mm", min: 0, max: 1800 }, not 0 to 1.',
+    '    Do NOT answer that request with sizing or anchor. Those say what happens when someone',
+    '    places a BIGGER figure; they cannot be driven, and a taller machine is not a moving one.',
+    '    Do NOT answer it with animations either — a hoist is not playing a timeline.',
+    '    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.',
+    '',
+    '  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.',
     '',
     'Taste rules — this is what makes it low-poly rather than a pile of boxes:',
     '  Few colours. Reuse one token for the mass and reserve accents for what must stand out.',
-    '  Recognisable silhouette from directly above — that is how it is seen on a board.',
+    '  Recognisable silhouette from directly above — that is how it is seen on a drawing.',
     '  Prefer fewer, larger parts. A detail smaller than a twentieth of the base is not visible.',
     '  Use the coarsest segment count that keeps the silhouette right.'
   ].join('\n')
@@ -308,7 +332,7 @@ function evidenceForExistingSource(source: FigureSource, palette: string[]): str
 
   return [
     'Measured evidence for the existing figure (reference, not a command):',
-    `  reuse grade ${score.grade}; ${cost.triangles} triangles; ${cost.groups} material groups; ${cost.at.drawCalls} draw calls per board estimate.`,
+    `  reuse grade ${score.grade}; ${cost.triangles} triangles; ${cost.groups} material groups; ${cost.at.drawCalls} draw calls per drawing estimate.`,
     `  top-view readability ${Math.round(quality.visual.readability * 100)}%; ${quality.visual.regions} visible material regions; coverage ${Math.round(quality.visual.coverage * 100)}%.`,
     ...(quality.findings.length ? quality.findings.map(finding => `  ${finding.dimension}: ${finding.message}`) : ['  No measurable review concerns.'])
   ].join('\n')

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

@@ -8,7 +8,7 @@ import { FigureFinding } from './figure-type.js'
  * ## 왜 서버가 검증하나
  *
  * 저작 화면을 못 믿어서가 아니다. **저작 화면을 거치지 않는 길이 있다** — 가져오기,
- * API 직접 호출, AI 어시스턴트. 그 길로 들어온 정본이 형식을 어기면 보드에서 조용히
+ * API 직접 호출, AI 어시스턴트. 그 길로 들어온 정본이 형식을 어기면 도면에서 조용히
  * 안 그려진다. 들어오는 문에서 막는다.
  *
  * ## 막는 것과 알리는 것

package/server/service/figure/figure.ts

@@ -71,7 +71,7 @@ export class Figure {
   /**
    * 컴포넌트 타입 이름. **저장되는 식별자다.**
    *
-   * 배치된 보드가 이 이름으로 타입을 찾는다. 바꾸면 그 보드는 타입을 못 찾아
+   * 배치된 도면이 이 이름으로 타입을 찾는다. 바꾸면 그 도면은 타입을 못 찾아
    * **오류 없이 빈 화면**이 된다. 그래서 만들 때 정하고 잠근다 — 고칠 수 있는 것은
    * 표시 이름(`name`)뿐이다. 수정 리졸버가 이 필드를 받지 않는다.
    *