@things-factory/figure-service 10.1.109 → 10.1.110

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.109",
+  "version": "10.1.110",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -35,5 +35,5 @@
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "4d51757c50d8347e83c96aeba73d770bdde55b73"
+  "gitHead": "b68feb6eccbef44af2a6365f384bd852dd70a8f9"
 }

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

@@ -374,6 +374,44 @@ describe('figureBlueprint 질의 — 소비처(board, twin, things-scene)에 발
     expect(source.slice(0, at)).toContain('@UseMiddleware(SpeakRefusals)')
   })
 
+  /* ADR-0104 decision 2: a consumer that pins a release asks for it by number; every answer carries its number. */
+  describe('a release asked for by number', () => {
+    async function threeReleases(type: string) {
+      const figure = await dataSource!.getRepository(Figure).save({ domain: testDomain, type, name: 'pinned', state: 'draft', source: boxNamed(type, 'unreleased'), version: 3 })
+      for (const version of [1, 2, 3])
+        await dataSource!.getRepository(FigureHistory).save({ domain: testDomain, originalId: figure.id, type, name: `v${version}`, state: 'released', version, source: boxNamed(type, `v${version}`) })
+      return figure
+    }
+
+    it('answers the latest with its number when no number is asked', async () => {
+      await threeReleases('PINNED')
+      const result = await new FigureQuery().figureBlueprint('PINNED', makeContext())
+      expect([result.version, partsOf(result)]).toEqual([3, ['v3']])
+    })
+
+    it('answers an older release by its number, not the latest', async () => {
+      await threeReleases('PINNED')
+      const result = await new FigureQuery().figureBlueprint('PINNED', makeContext(), 1)
+      expect([result.version, partsOf(result)]).toEqual([1, ['v1']])
+    })
+
+    it('refuses a number that was never released by name, never answering another release', async () => {
+      await threeReleases('PINNED')
+      await expect(new FigureQuery().figureBlueprint('PINNED', makeContext(), 7)).rejects.toMatchObject({ code: 'figure-release-not-found' })
+      for (const lang of ['ko', 'en']) expect(require(`../../../translations/${lang}.json`)['error.figure-release-not-found']).toMatch(/\{latest\}/)
+    })
+
+    it('a type nobody released is still null, whatever number is asked', async () => {
+      expect(await new FigureQuery().figureBlueprint('NOBODY', makeContext(), 1)).toBeNull()
+    })
+
+    it('a released row is answered with its own number', async () => {
+      await dataSource!.getRepository(Figure).save({ domain: testDomain, type: 'ROW', name: 'row', state: 'released', source: sampleSource, version: 4 })
+      expect((await new FigureQuery().figureBlueprint('ROW', makeContext())).version).toBe(4)
+      expect((await new FigureQuery().figureBlueprint('ROW', makeContext(), 4)).version).toBe(4)
+    })
+  })
+
   describe('a child domain shadows its parent only with a released version', () => {
     const boxOf = (_type: string, part: string) => box(part)
 

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

@@ -106,7 +106,7 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   @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.'
+      'What changed against the previous release, as JSON: [{ code, blocking, subject?, values, detail }]. [] for the first release. null when it was not compared: the previous release could not be read, or this release was made before releases recorded it (figure-service 10.1.109).'
   })
   changes?: string
 

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

@@ -1,5 +1,5 @@
 import { In } from 'typeorm'
-import { Args, Arg, Ctx, Directive, Query, Resolver, UseMiddleware } from 'type-graphql'
+import { Args, Arg, Ctx, Directive, Int, Query, Resolver, UseMiddleware } from 'type-graphql'
 import { GraphQLJSON } from 'graphql-scalars'
 
 import {
@@ -242,11 +242,13 @@ export class FigureQuery {
   @Directive('@privilege(category: "figure-published", privilege: "query", domainOwnerGranted: true)')
   @Query(returns => GraphQLJSON, {
     nullable: true,
-    description: 'A released figure for its consumers (board, twin, things-scene): { type, asset } with the figure asset. Only returns released figures.'
+    description:
+      'A released figure for its consumers (board, twin, things-scene): { type, version, asset }. The latest release, or the one numbered `version` for a consumer that pins releases (ADR-0104). Only returns released figures.'
   })
   async figureBlueprint(
     @Arg('type') type: string,
-    @Ctx() context: ResolverContext
+    @Ctx() context: ResolverContext,
+    @Arg('version', type => Int, { nullable: true, description: 'A release number. Absent: the latest release.' }) pinned?: number
   ): Promise<any> {
     const { domain } = context.state
 
@@ -257,18 +259,32 @@ export class FigureQuery {
       architect ruling, 2026-09-17). This used to skip the fallback as soon as a child row existed and
       return null.
     */
-    const found =
+    const latest =
       (await releasedSourceOf(domain.id, type)) ?? (domain.parentId ? await releasedSourceOf(domain.parentId, type) : null)
 
-    if (!found) {
+    if (!latest) {
       return null
     }
 
+    /*
+      A pinned release is read from the same figure the latest comes from -- the shadowing rule decides whose
+      releases these are, then the number picks one. Releases are never deleted, so a number once handed out is
+      always there; a number that never was is refused by name rather than answered with another release.
+    */
+    const found = pinned === undefined || pinned === null || pinned === latest.version ? latest : await releaseNumbered(latest.figure, pinned)
+    if (!found) {
+      throw new Refusal(
+        'figure-release-not-found',
+        { type, version: pinned, latest: latest.version },
+        '{type} has no release {version}. its latest release is {latest}.'
+      )
+    }
+
     const { figure, source: sourceToCompile, version } = found
 
     try {
       const text = typeof sourceToCompile === 'string' ? sourceToCompile : JSON.stringify(sourceToCompile)
-      return { type, asset: consumablePayloadOf(text).asset }
+      return { type, version, asset: consumablePayloadOf(text).asset }
     } catch (err) {
       console.error(`[figureBlueprint] 타입 '${type}' (figure id: ${figure.id}) 자산 컴파일 실패:`, err)
 
@@ -290,6 +306,14 @@ export class FigureQuery {
   }
 }
 
+/** One numbered release of a figure, or null when it has none by that number. */
+async function releaseNumbered(figure: Figure, version: number): Promise<{ figure: Figure; source: string; version: number } | null> {
+  const row = await getRepository(FigureHistory).findOne({
+    where: { originalId: figure.id, state: 'released', version }
+  })
+  return row?.source ? { figure, source: row.source, version: row.version } : null
+}
+
 /**
  * Finds the released source of a type in one domain, or null.
  *

package/translations/en.json

@@ -74,5 +74,6 @@
   "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."
+  "figure.gate.contract.public-input-added.why": "Placed instances that give no value stand at its default.",
+  "error.figure-release-not-found": "{type} has no release {version}. its latest release is {latest}."
 }

package/translations/ko.json

@@ -74,5 +74,6 @@
   "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": "값을 주지 않은 인스턴스는 기본값으로 섭니다."
+  "figure.gate.contract.public-input-added.why": "값을 주지 않은 인스턴스는 기본값으로 섭니다.",
+  "error.figure-release-not-found": "{type} 에는 {version} 번 발행판이 없습니다. 최신 발행판은 {latest} 번입니다."
 }