@things-factory/figure-service 10.1.167 → 10.1.169

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

@@ -0,0 +1,447 @@
+/**
+ * What of a figure the model is shown (ADR-0061 2026-10-16 decision 4).
+ *
+ * The kernel keeps a figure up to 1 MiB (`FIGURE_JSON_MAX_BYTES`); that is whether the figure is valid. How much of it the
+ * model reads at once is another question with its own number. A figure that fits is shown whole. One that does not is
+ * shown as an outline -- its sections, and every part by name, shape and what it is fastened to -- and in full only the
+ * parts and sections asked for, while they fit. A section too large for the outline is left out, named by its JSON
+ * Pointer with the entries inside it, and read by pointer. The full source stays on the server: a proposal is applied
+ * and judged on it, on the version the request was made on.
+ *
+ * A proposal on a figure shown in part changes only what it was shown: no part not read in full, and nothing inside a
+ * section left out and not read. Read is what the server put before the writer, never what a model says it read.
+ */
+import type { FigureAsset, FigureProposalStep } from '@hatiolab/figure-model'
+
+/** The most of a figure, serialized, the model is shown in one read. Not a validity limit: that is the kernel's. */
+export const FIGURE_CONTEXT_BUDGET = 100_000
+
+/** Of the budget, what the outline's sections may take; the rest is for the parts and sections read beside it. */
+const OUTLINE_SHARE = FIGURE_CONTEXT_BUDGET / 2
+
+/** How many entries of a section left out, or pointers in a reason, are named: the largest first. */
+const ENTRIES_NAMED = 20
+
+type Dynamic = any
+
+export interface FigureOutlinePart {
+  id: string
+  /** The operation that makes its shape (`box@1`, `extrude@1`, ...). */
+  shape?: string
+  /** What it is fastened to: `<part>.<face>`, `mounting-plane`, or nothing when unfastened. */
+  on?: string
+  joint?: { id: string; type: string }
+  material?: string
+  /** How long its part read is: what reading it costs. */
+  chars: number
+}
+
+export interface FigureOmittedSection {
+  /** The JSON Pointer of the section left out. */
+  section: string
+  chars: number
+  /** Its largest entries, by pointer: what to read when the whole does not fit. */
+  entries?: { section: string; chars: number }[]
+}
+
+export interface FigureOutline {
+  /** The whole source's length, and the budget it does not fit. */
+  chars: number
+  budget: number
+  parts: FigureOutlinePart[]
+  /** Parts the outline had no room to list, past the ones listed. */
+  partsNotListed?: number
+  /** Sections left out because they would crowd the outline. */
+  omitted?: FigureOmittedSection[]
+  [section: string]: unknown
+}
+
+export interface FigurePartRead {
+  appearance: Dynamic
+  /** The fastenings that name it: its own (body1) and its children's (body0). */
+  joints: Dynamic[]
+  /** The graph nodes and constants under its name: `<part>` and `<part>.*` (a part id has no dot). */
+  nodes: Dynamic[]
+  constants: Dynamic[]
+}
+
+export interface FigureReadRequest {
+  parts?: readonly string[]
+  /** JSON Pointers (RFC 6901) into the source, such as `/document/capabilities/bindings/0`. */
+  sections?: readonly string[]
+}
+
+export interface FigureView {
+  whole: boolean
+  /** Whole: the source as it is. */
+  source?: FigureAsset
+  outline?: FigureOutline
+  /** The parts shown in full, by id, in the order asked. */
+  parts?: Record<string, FigurePartRead>
+  shown?: string[]
+  /** The sections read, by pointer. */
+  sections?: Record<string, unknown>
+  /** What was asked for and not shown, with why and what to read instead. */
+  notRead?: ({ part: string; reason: string } | { section: string; reason: string })[]
+}
+
+const length = (value: unknown) => JSON.stringify(value)?.length ?? 0
+const under = (part: string) => (id: unknown) => id === part || (typeof id === 'string' && id.startsWith(`${part}.`))
+
+/* ── JSON Pointer (RFC 6901) ─────────────────────────────────────────────────────────── */
+
+const escapeToken = (token: string) => token.replace(/~/g, '~0').replace(/\//g, '~1')
+const pointerOf = (tokens: readonly (string | number)[]) => tokens.map(t => `/${escapeToken(String(t))}`).join('')
+function tokensOf(pointer: string): string[] | undefined {
+  if (typeof pointer !== 'string' || !pointer.startsWith('/')) return undefined
+  return pointer.slice(1).split('/').map(t => t.replace(/~1/g, '/').replace(/~0/g, '~'))
+}
+function valueAt(root: unknown, tokens: readonly string[]): { found: boolean; value?: unknown } {
+  let at: Dynamic = root
+  for (const token of tokens) {
+    if (at === null || typeof at !== 'object' || !Object.prototype.hasOwnProperty.call(at, token)) return { found: false }
+    at = at[token]
+  }
+  return { found: true, value: at }
+}
+/** `inner` is `outer` or inside it. */
+const within = (inner: string, outer: string) => inner === outer || inner.startsWith(`${outer}/`)
+
+/** A value's entries by pointer, largest first, the first ENTRIES_NAMED of them. */
+function entriesOf(pointer: string, value: unknown): { section: string; chars: number }[] {
+  if (value === null || typeof value !== 'object') return []
+  const tokens = tokensOf(pointer)!
+  return Object.entries(value as object)
+    .map(([key, entry]) => ({ section: pointerOf([...tokens, key]), chars: length(entry) }))
+    .sort((a, b) => b.chars - a.chars)
+    .slice(0, ENTRIES_NAMED)
+}
+
+/* ── Parts ───────────────────────────────────────────────────────────────────────────── */
+
+export function figurePartReadOf(asset: FigureAsset, part: string): FigurePartRead | undefined {
+  const appearance = asset.appearance.find(a => a.target === part)
+  if (!appearance) return undefined
+  const model = asset.document.model as Dynamic
+  const own = under(part)
+  return {
+    appearance,
+    joints: ((asset as Dynamic).joints ?? []).filter((j: Dynamic) => j?.body1?.part === part || j?.body0?.part === part),
+    nodes: model.nodes.filter((n: Dynamic) => own(n.id)),
+    constants: model.constants.filter((c: Dynamic) => own(c.id))
+  }
+}
+
+/** Where a part's records are, by pointer: for a part too large to read as one. */
+function partPointers(asset: FigureAsset, part: string): string[] {
+  const model = asset.document.model as Dynamic
+  const own = under(part)
+  return [
+    ...asset.appearance.flatMap((a, i) => (a.target === part ? [pointerOf(['appearance', i])] : [])),
+    ...((asset as Dynamic).joints ?? []).flatMap((j: Dynamic, i: number) => (j?.body1?.part === part || j?.body0?.part === part ? [pointerOf(['joints', i])] : [])),
+    ...model.nodes.flatMap((n: Dynamic, i: number) => (own(n.id) ? [pointerOf(['document', 'model', 'nodes', i])] : [])),
+    ...model.constants.flatMap((c: Dynamic, i: number) => (own(c.id) ? [pointerOf(['document', 'model', 'constants', i])] : []))
+  ]
+}
+
+/* ── The outline ─────────────────────────────────────────────────────────────────────── */
+
+/*
+  The sections of an outline: every top-level field but the parts' records, the document's fields but its model, and the
+  model's fields but its graph. Each may be left out by its pointer.
+*/
+const PART_RECORDS = ['/document', '/appearance', '/joints', '/document/model', '/document/model/nodes', '/document/model/constants']
+function sectionsOf(asset: FigureAsset): string[] {
+  const out: string[] = []
+  const walk = (tokens: string[]) => {
+    const { value } = valueAt(asset, tokens)
+    for (const key of Object.keys(value as object)) {
+      const pointer = pointerOf([...tokens, key])
+      if (pointer === '/document' || pointer === '/document/model') walk([...tokens, key])
+      else if (!PART_RECORDS.includes(pointer)) out.push(pointer)
+    }
+  }
+  walk([])
+  return out
+}
+
+function outlinePartsOf(asset: FigureAsset): FigureOutlinePart[] {
+  const nodes = (asset.document.model as Dynamic).nodes
+  const joints = (asset as Dynamic).joints ?? []
+  return asset.appearance.map((look: Dynamic) => {
+    const id = look.target
+    const joint = joints.find((j: Dynamic) => j?.body1?.part === id)
+    const body0 = joint?.body0
+    const on = !joint ? undefined : body0?.part ? `${body0.part}.${body0.face}` : (body0?.plane ?? 'mounting-plane')
+    const shape = nodes.find((n: Dynamic) => n.id === `${id}.shape`)?.op
+    return {
+      id,
+      ...(shape ? { shape } : {}),
+      ...(on ? { on } : {}),
+      ...(joint ? { joint: { id: joint.id, type: joint.type } } : {}),
+      ...(look.material?.token ? { material: look.material.token } : {}),
+      chars: length(figurePartReadOf(asset, id))
+    }
+  })
+}
+
+/** Writes a section into the outline at its pointer, making the objects on the way. */
+function place(outline: Dynamic, tokens: readonly string[], value: unknown) {
+  let at = outline
+  tokens.slice(0, -1).forEach(token => (at = at[token] ??= {}))
+  at[tokens[tokens.length - 1]!] = value
+}
+
+/**
+ * The outline: within OUTLINE_SHARE for its sections, the largest left out first; and, every field counted, within the
+ * budget -- a figure of very many parts lists them by id only, then as many as fit.
+ */
+export function figureOutlineOf(asset: FigureAsset, chars = length(asset)): FigureOutline {
+  const model = asset.document.model as Dynamic
+  const sections = sectionsOf(asset).map(pointer => ({ pointer, value: valueAt(asset, tokensOf(pointer)!).value }))
+  const sized = sections.map(s => ({ ...s, chars: length(s.value) })).sort((a, b) => b.chars - a.chars)
+
+  let total = sized.reduce((sum, s) => sum + s.chars, 0)
+  const omitted: FigureOmittedSection[] = []
+  const kept = new Set(sized.map(s => s.pointer))
+  for (const s of sized) {
+    if (total <= OUTLINE_SHARE) break
+    kept.delete(s.pointer)
+    total -= s.chars
+    const entries = entriesOf(s.pointer, s.value)
+    omitted.push({ section: s.pointer, chars: s.chars, ...(entries.length ? { entries } : {}) })
+  }
+
+  const outline: Dynamic = { chars, budget: FIGURE_CONTEXT_BUDGET }
+  place(outline, ['document', 'model', 'nodes'], model.nodes.length)
+  place(outline, ['document', 'model', 'constants'], model.constants.length)
+  for (const s of sections) if (kept.has(s.pointer)) place(outline, tokensOf(s.pointer)!, s.value)
+  if (omitted.length) outline.omitted = omitted
+
+  let parts: Dynamic[] = outlinePartsOf(asset)
+  outline.parts = parts
+  if (length(outline) > FIGURE_CONTEXT_BUDGET) outline.parts = parts = parts.map(p => ({ id: p.id }))
+  if (length(outline) > FIGURE_CONTEXT_BUDGET) {
+    /* As many as fit, in part order, with how many more there are. */
+    let room = FIGURE_CONTEXT_BUDGET - length({ ...outline, parts: [], partsNotListed: parts.length })
+    const listed: Dynamic[] = []
+    for (const p of parts) {
+      room -= length(p) + 1
+      if (room < 0) break
+      listed.push(p)
+    }
+    outline.parts = listed
+    outline.partsNotListed = parts.length - listed.length
+  }
+  return outline as FigureOutline
+}
+
+/* ── The view ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * The view of a figure the model is shown: whole when it fits, else the outline and what was asked for -- parts, then
+ * sections, each in the order asked -- while it fits beside it. Every field counted, the view is within the budget.
+ */
+export function figureViewOf(asset: FigureAsset, request: FigureReadRequest = {}): FigureView {
+  const chars = length(asset)
+  if (chars <= FIGURE_CONTEXT_BUDGET) return { whole: true, source: asset }
+
+  const outline = figureOutlineOf(asset, chars)
+  const view: FigureView = { whole: false, outline, parts: {}, shown: [], sections: {}, notRead: [] }
+  const room = () => FIGURE_CONTEXT_BUDGET - length(view)
+  const refuse = (one: { part: string; reason: string } | { section: string; reason: string }) => {
+    if (length(one) + 1 <= room()) view.notRead!.push(one)
+  }
+
+  for (const part of [...new Set(request.parts ?? [])]) {
+    const one = figurePartReadOf(asset, part)
+    if (!one) {
+      refuse({ part, reason: `${part} is not a part of this figure; the outline lists its parts` })
+      continue
+    }
+    const cost = length(one) + length(part) + length(part) + 3
+    view.parts![part] = one
+    view.shown!.push(part)
+    if (room() >= 0) continue
+    delete view.parts![part]
+    view.shown!.pop()
+    if (cost <= FIGURE_CONTEXT_BUDGET - length(outline)) {
+      refuse({ part, reason: `${part} (${cost} characters) does not fit beside what is already read; read it in another call with fewer parts or sections` })
+    } else {
+      const pointers = partPointers(asset, part)
+      refuse({
+        part,
+        reason:
+          `${part} (${cost} characters) is too large to show beside the outline; read its records as sections: ` +
+          `${pointers.slice(0, ENTRIES_NAMED).join(', ')}${pointers.length > ENTRIES_NAMED ? ` and ${pointers.length - ENTRIES_NAMED} more` : ''}. ` +
+          'Parts read as sections are not counted as read in full: they cannot be changed'
+      })
+    }
+  }
+
+  for (const section of [...new Set(request.sections ?? [])]) {
+    const tokens = tokensOf(section)
+    const at = tokens && tokens.length ? valueAt(asset, tokens) : { found: false }
+    if (!at.found) {
+      refuse({ section, reason: `there is no section ${section}; a section is a JSON Pointer such as /document/capabilities/bindings/0` })
+      continue
+    }
+    const cost = length(at.value) + length(section) + 2
+    view.sections![section] = at.value
+    if (room() >= 0) continue
+    delete view.sections![section]
+    const entries = entriesOf(section, at.value)
+    refuse({
+      section,
+      reason: entries.length
+        ? `${section} (${cost} characters) is too large to show at once here; read its entries: ${entries.map(e => `${e.section} (${e.chars})`).join(', ')}`
+        : `${section} is one value of ${length(at.value)} characters, larger than can be shown here; it cannot be read or changed by a proposal`
+    })
+  }
+
+  if (!view.notRead!.length) delete view.notRead
+  return view
+}
+
+/* ── What a proposal may change ──────────────────────────────────────────────────────── */
+
+type StepOf<K extends FigureProposalStep['kind']> = Extract<FigureProposalStep, { kind: K }>
+type Subject = string | undefined
+
+/**
+ * The part each kind of step changes, read from the field the kernel reads for that kind (audit D4-R1: a `part` beside a
+ * `set-material`'s `target` is not read by the kernel, so it may not stand in for it). Every kind of the kernel's step
+ * type is here, or this does not compile. A step that changes no one part says so with undefined: what it does to the
+ * figure's sections is held by `unreadSectionEdits`.
+ */
+const SUBJECT: { [K in FigureProposalStep['kind']]: (step: StepOf<K>, base: FigureAsset) => Subject } = {
+  'add-part': () => undefined,
+  'fit-room': () => undefined,
+  'set-section-corner': step => step.part,
+  'set-cavity': step => step.part,
+  'set-section': step => step.part,
+  attach: step => step.part,
+  'link-dimension': step => step.part,
+  'follow-size': step => step.part,
+  'unlink-dimension': step => step.part,
+  'scale-position': step => step.part,
+  'fix-position': step => step.part,
+  'nudge-part': step => step.part,
+  detach: step => step.part,
+  'make-repeat': step => step.part,
+  'set-repeat': step => step.part,
+  'remove-repeat': step => step.part,
+  'set-mounting-face': step => step.part,
+  'add-binding': step => step.part,
+  'set-joint': step => step.joint?.body1?.part,
+  'remove-joint': (step, base) => ((base as Dynamic).joints ?? []).find((j: Dynamic) => j?.id === step.id)?.body1?.part,
+  'set-material': step => step.target,
+  'set-segments': step => step.target,
+  'rename-part': step => step.target,
+  'set-visibility': step => step.target,
+  'remove-part': step => step.target,
+  'duplicate-part': step => step.target,
+  'move-part': step => step.target,
+  'set-placement': () => undefined,
+  'declare-occupancy': () => undefined,
+  'declare-instance-size': () => undefined,
+  'clear-mounting-face': () => undefined,
+  'scale-uniformly': () => undefined,
+  'follow-size-in-proportion': () => undefined,
+  'set-detail-level': () => undefined,
+  'add-design-input': () => undefined,
+  'set-input-range': () => undefined,
+  'publish-input': () => undefined,
+  'unpublish-input': () => undefined,
+  'remove-binding': () => undefined,
+  'set-slot-layout': () => undefined,
+  'remove-slot-layout': () => undefined,
+  'set-extension': () => undefined,
+  rename: () => undefined,
+  'set-capabilities': () => undefined,
+  'set-state-input': () => undefined,
+  'set-state-defaults': () => undefined,
+  'set-driver': () => undefined,
+  'remove-driver': () => undefined,
+  'set-clip': () => undefined,
+  'set-motion-group': () => undefined,
+  'remove-motion-group': () => undefined,
+  'set-data-schema': () => undefined,
+  'rename-data-field': () => undefined,
+  'set-data-binding': () => undefined,
+  'remove-data-binding': () => undefined,
+  'set-status-port': () => undefined,
+  'remove-status-port': () => undefined
+}
+
+/**
+ * The steps that change a part of the base not shown in full, as reasons said back to the writer. A part may still be
+ * named to fasten to or to follow -- the kernel works from it, nothing about it is guessed -- and a new part is the
+ * steps' own. A kind this table does not know is refused: it is not let through unjudged.
+ */
+export function unreadPartEdits(base: FigureAsset, steps: readonly FigureProposalStep[], view: FigureView): string[] {
+  const existing = new Set(base.appearance.map(a => a.target))
+  const shown = new Set(view.shown ?? [])
+  const allowed = [...shown].join(', ') || 'none'
+  return steps.flatMap((step, i) => {
+    const kind = (step as Dynamic)?.kind
+    if (typeof kind !== 'string') return []
+    const judge = (SUBJECT as Record<string, (step: Dynamic, base: FigureAsset) => Subject>)[kind]
+    if (!Object.prototype.hasOwnProperty.call(SUBJECT, kind) || !judge)
+      return [`UNKNOWN_STEP: steps[${i}] has the kind "${kind}", which is not one of the commands; use only the commands taught.`]
+    const part = judge(step, base)
+    if (typeof part !== 'string' || !existing.has(part) || shown.has(part)) return []
+    return [
+      `UNREAD_PART: steps[${i}] (${kind}) changes "${part}", which was not shown in full, so its source is not known here. ` +
+        `Change only the parts shown in full (${allowed}) or parts the steps add. To change ${part}, read it with getFigureSource parts and pass it in parts to proposeFigureCandidate.`
+    ]
+  })
+}
+
+/** Entries of a value, keyed by `id` when every entry of a list has a distinct one, else by place. */
+function keyedEntries(value: unknown): Map<string, { token: string; value: unknown }> {
+  const out = new Map<string, { token: string; value: unknown }>()
+  if (Array.isArray(value)) {
+    const ids = value.map(v => (v && typeof v === 'object' && typeof (v as Dynamic).id === 'string' ? (v as Dynamic).id : undefined))
+    const byId = ids.every(Boolean) && new Set(ids).size === ids.length
+    value.forEach((v, i) => out.set(byId ? `id:${ids[i]}` : `at:${i}`, { token: String(i), value: v }))
+  } else if (value && typeof value === 'object') {
+    for (const [key, v] of Object.entries(value)) out.set(`key:${key}`, { token: key, value: v })
+  }
+  return out
+}
+
+/**
+ * What of the sections left out of the outline and not read the steps changed, as reasons said back to the writer. Judged
+ * on what the steps made, not on what they say: nothing that was there may be changed or taken away. A new entry -- a
+ * record in a list, a key in a map -- is the steps' own.
+ */
+export function unreadSectionEdits(base: FigureAsset, after: FigureAsset, view: FigureView): string[] {
+  const read = Object.keys(view.sections ?? {})
+  const reasons: string[] = []
+  const say = (pointer: string, what: string) =>
+    reasons.push(
+      `UNREAD_SECTION: the steps ${what} ${pointer}, which was left out of the outline and not read, so it is not known here. ` +
+        `Leave it as it is; to change it, read it with getFigureSource sections and pass it in sections to proposeFigureCandidate.`
+    )
+  const check = (pointer: string, before: unknown, now: unknown) => {
+    if (reasons.length >= ENTRIES_NAMED || read.some(r => within(pointer, r))) return
+    const records = (v: unknown) => v !== null && typeof v === 'object'
+    if (!records(before) || !records(now) || Array.isArray(before) !== Array.isArray(now)) {
+      if (JSON.stringify(before) !== JSON.stringify(now)) say(pointer, 'change')
+      return
+    }
+    const later = keyedEntries(now)
+    for (const [key, entry] of keyedEntries(before)) {
+      const child = `${pointer}/${escapeToken(entry.token)}`
+      const kept = later.get(key)
+      if (kept) check(child, entry.value, kept.value)
+      else if (!read.some(r => within(child, r))) say(child, 'remove')
+    }
+  }
+  for (const omitted of view.outline?.omitted ?? []) {
+    const tokens = tokensOf(omitted.section)!
+    check(omitted.section, valueAt(base, tokens).value, valueAt(after, tokens).value)
+  }
+  return reasons
+}

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

@@ -185,6 +185,23 @@ describe('figure-format — 판을 알아보는 문', () => {
       expect(`${finding.message}${finding.why}${finding.how}`).not.toMatch(/declared volume|leaves/)
     })
 
+    it('확장 속성의 키가 없어지면 발행을 막고 키 이름으로 말한다; 값이 바뀌면 알리기만 한다 (ADR-0123)', () => {
+      const carrier = { type: 'ROLL', dimensions: { width: 1000, length: 600, height: 200 } }
+      const withKey = applyFigureAuthoring(figureAsset(), { kind: 'set-extension', key: 'fmsim/carrier', value: carrier })
+      const released = serializeFigureAsset(withKey)
+
+      const gone = inspectSource(serializeFigureAsset(figureAsset()), released, translatorOf(KO)).findings.find(f => f.code === 'extension-gone')!
+      expect(gone.blocking).toBe(true)
+      expect(gone.message).toBe("'fmsim/carrier' 확장 속성이 없어졌습니다.")
+
+      const changed = applyFigureAuthoring(withKey, { kind: 'set-extension', key: 'fmsim/carrier', value: { ...carrier, type: 'ROLL2' } })
+      const said = inspectSource(serializeFigureAsset(changed), released, translatorOf(KO))
+      const finding = said.findings.find(f => f.code === 'extension-changed')!
+      expect(finding.blocking).toBe(false)
+      expect(finding.message).toBe("'fmsim/carrier' 확장 속성의 값이 바뀌었습니다.")
+      expect(said.findings.some(f => f.code === 'extension-gone')).toBe(false)
+    })
+
     it('공간을 선언하지 않은 도형은 무엇을 누르면 되는지 말한다', () => {
       const finding = inspectSource(bare(), null, translatorOf(KO)).findings.find(f => f.code === 'occupancy-undeclared')!
 
@@ -350,7 +367,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', 'state-input-joints-changed', 'joint-axis-changed', 'joint-motion-unit-changed', 'joint-child-changed', 'joint-list-unread', 'carrier-gone', 'carrier-type-changed', 'carrier-dimensions-changed', 'carrier-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', 'extension-gone', 'extension-changed', 'extension-added'])
         for (const dict of [KO, EN]) for (const field of ['message', 'why']) expect(dict[`figure.gate.contract.${code}.${field}`]).toBeTruthy()
     })
     it('the data changes have their sentences under figure-model 0.6.6\'s codes, in all six languages', () => {

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

@@ -478,28 +478,22 @@ 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.')
       }
-    /* What live data names a carrier by, and the size a holder fits it by (ADR-0123). */
-    case 'carrier-gone':
+    /* A value another product reads by its key (ADR-0123): only a key that goes refuses; what a change means is its owner's. */
+    case 'extension-gone':
       return {
-        message: say(key('message'), v, `The figure is no longer carrier type ${v.type}.`),
-        why: say(key('why'), {}, 'Live data names carriers by this code. After this release carriers of this type find no figure.'),
+        message: say(key('message'), v, `The extension '${v.key}' is gone.`),
+        why: say(key('why'), {}, 'Another product reads this value by its key. After this release it finds none.'),
         ...gone
       }
-    case 'carrier-type-changed':
+    case 'extension-changed':
       return {
-        message: say(key('message'), v, `The carrier type changed from ${v.before} to ${v.after}.`),
-        why: say(key('why'), {}, 'Live data names carriers by this code. After this release carriers of the old type find no figure.'),
-        ...gone
-      }
-    case 'carrier-dimensions-changed':
-      return {
-        message: say(key('message'), v, `The carrier size changed from ${v.before} to ${v.after} mm.`),
-        why: say(key('why'), {}, 'Holders fit and stack carriers by this size. Where they stand and what fits is judged again once the map takes this release.')
+        message: say(key('message'), v, `The value of the extension '${v.key}' changed.`),
+        why: say(key('why'), {}, 'The product that owns this key reads the new value and judges the change.')
       }
-    case 'carrier-added':
+    case 'extension-added':
       return {
-        message: say(key('message'), v, `The figure is now carrier type ${v.type}.`),
-        why: say(key('why'), {}, 'Live data with this code finds this figure once the type map takes this release.')
+        message: say(key('message'), v, `The extension '${v.key}' is new.`),
+        why: say(key('why'), {}, 'The product that owns this key reads this value.')
       }
     /* What a consumer's data mapping and a board's motion selection lean on (ADR-0051 §2.2, §3.2). */
     case 'data-field-gone':

package/server/service/figure/figure-llm-smoke.test.ts

@@ -11,9 +11,9 @@
  */
 import { createAIClient, type AIClient } from '@things-factory/ai-client-base'
 
-import { applyFigureProposal, createFigureAsset, inspectFigureAsset } from '@hatiolab/figure-model'
+import { applyFigureProposal, compileFigureAsset, createFigureAsset, figureShapeBoundsOf, inspectFigureAsset, type FigureAsset } from '@hatiolab/figure-model'
 
-import { proposeFigureSteps } from './figure-propose-steps'
+import { judgeFigureAnswer, proposeFigureSteps } from './figure-propose-steps'
 
 // Provider modules register themselves on import. Keep this separate from the deterministic tests.
 import '@things-factory/ai-client-base'
@@ -35,6 +35,83 @@ function provider(): { provider: Provider; apiKey: string } | undefined {
   return undefined
 }
 
+/** A mixer: a body standing on the floor, a port fastened to its front. */
+function mixerDraft(): FigureAsset {
+  return applyFigureProposal(createFigureAsset('Mixer'), [
+    { kind: 'add-part', part: { id: 'body', kind: 'cylinder', dimensions: { radius: 140, length: 320 } } },
+    { kind: 'add-part', part: { id: 'port', kind: 'box', dimensions: { width: 80, height: 60, depth: 30 } } },
+    { kind: 'attach', part: 'body', face: 'bottom', to: { plane: 'mounting-plane' } },
+    { kind: 'attach', part: 'port', face: 'back', to: { part: 'body', face: 'front' } },
+    { kind: 'fit-room', placement: 'floor' }
+  ] as any)
+}
+
+/**
+ * Each part's reach along its own axes and the colour it is drawn in, at the figure's default size. The colour is the
+ * palette's value for the part's token: two tokens of one colour draw the same.
+ */
+function drawn(asset: FigureAsset): Record<string, { size: Record<'x' | 'y' | 'z', number>; colour: string }> {
+  const geometry = compileFigureAsset(asset).evaluate({}).geometry as any[]
+  return Object.fromEntries(
+    geometry.map(body => {
+      const bounds = figureShapeBoundsOf(body.shape)
+      const size = { x: bounds.x.max - bounds.x.min, y: bounds.y.max - bounds.y.min, z: bounds.z.max - bounds.z.min }
+      /* The kernel refuses a token the palette has no colour for, so every body has one. */
+      return [body.id, { size, colour: String(asset.palette![body.material.token]).toLowerCase() }]
+    })
+  )
+}
+
+/**
+ * What "make the port twice as wide and give it an accent colour" asks of the mixer, said as what is missing: the port
+ * twice as wide (X), its height and depth kept, a colour it did not have, and the body left as it was. Nothing missing:
+ * an empty list. Checking only that the parts still exist let a revision that changed nothing pass.
+ */
+function portRevisionMisses(before: FigureAsset, after: FigureAsset): string[] {
+  const was = drawn(before),
+    now = drawn(after)
+  const misses: string[] = []
+  const near = (a: number, b: number) => Math.abs(a - b) <= 0.5
+  if (!now.port) return ['the port is gone']
+  if (!near(now.port.size.x, was.port.size.x * 2)) misses.push(`port width ${now.port.size.x}, asked ${was.port.size.x * 2}`)
+  for (const axis of ['y', 'z'] as const) if (!near(now.port.size[axis], was.port.size[axis])) misses.push(`port ${axis} changed to ${now.port.size[axis]}`)
+  if (now.port.colour === was.port.colour) misses.push(`port colour still ${was.port.colour}`)
+  if (!now.body) misses.push('the body is gone')
+  else for (const axis of ['x', 'y', 'z'] as const) if (!near(now.body.size[axis], was.body.size[axis])) misses.push(`body ${axis} changed to ${now.body.size[axis]}`)
+  if (now.body && now.body.colour !== was.body.colour) misses.push(`body colour changed to ${now.body.colour}`)
+  return misses
+}
+
+/* The check above, held to answers whose verdict is known - so it is seen to fail a wrong revision without a provider. */
+describe('the revision check of the smoke test', () => {
+  const draft = mixerDraft()
+  const answer = (steps: unknown[]) => {
+    const judged = judgeFigureAnswer(draft, { steps }, true)
+    if (!judged.source) throw new Error(judged.reasons.join('\n'))
+    return judged.source
+  }
+  const accent = { kind: 'set-material', target: 'port', material: { token: 'palette.accent' }, palette: { 'palette.accent': '#d08a2c' } }
+
+  it('passes the revision asked for', () => {
+    expect(portRevisionMisses(draft, answer([{ kind: 'set-section', part: 'port', across: { x: 160 } }, accent]))).toEqual([])
+  })
+
+  it('fails a revision that left the width, or widened the body instead, or kept the colour', () => {
+    expect(portRevisionMisses(draft, answer([accent]))).toEqual(['port width 80, asked 160'])
+    expect(portRevisionMisses(draft, answer([{ kind: 'set-section', part: 'port', across: { x: 160 } }, { kind: 'set-section', part: 'body', across: { x: 320 } }, accent]))).toEqual(
+      expect.arrayContaining(['body x changed to 320'])
+    )
+    expect(portRevisionMisses(draft, answer([{ kind: 'set-section', part: 'port', across: { x: 160 } }]))).toEqual([`port colour still ${draft.palette!['palette.primary']}`])
+  })
+
+  /* A new token is not a new colour: an alias of the colour the port already had changes nothing on screen. */
+  it('fails a new token that names the colour the port already had', () => {
+    const same = draft.palette!['palette.primary']!
+    const alias = { kind: 'set-material', target: 'port', material: { token: 'palette.accent' }, palette: { 'palette.accent': same.toUpperCase() } }
+    expect(portRevisionMisses(draft, answer([{ kind: 'set-section', part: 'port', across: { x: 160 } }, alias]))).toEqual([`port colour still ${same}`])
+  })
+})
+
 const picked = process.env.RUN_FIGURE_LLM_SMOKE === '1' ? provider() : undefined
 const describeIf = picked ? describe : describe.skip
 
@@ -66,20 +143,12 @@ describeIf('Figure 실제 LLM smoke', () => {
   )
 
   test(
-    '고치는 제안은 건드리지 않은 부품을 그대로 둔다',
+    '고치는 제안은 요청한 것만 바꾼다 — 포트 폭 두 배, 새 색, 몸통은 그대로',
     async () => {
-      const draft = applyFigureProposal(createFigureAsset('Mixer'), [
-        { kind: 'add-part', part: { id: 'body', kind: 'cylinder', dimensions: { radius: 140, length: 320 } } },
-        { kind: 'add-part', part: { id: 'port', kind: 'box', dimensions: { width: 80, height: 60, depth: 30 } } },
-        { kind: 'attach', part: 'body', face: 'bottom', to: { plane: 'mounting-plane' } },
-        { kind: 'attach', part: 'port', face: 'back', to: { part: 'body', face: 'front' } },
-        { kind: 'fit-room', placement: 'floor' }
-      ] as any)
+      const draft = mixerDraft()
       const result = await proposeFigureSteps({ client, prompt: 'make the port twice as wide and give it an accent colour', base: draft })
 
-      const ids = result.source.document.model.nodes.map((n: any) => n.id)
-      expect(ids.some((id: string) => id.includes('body'))).toBe(true)
-      expect(ids.some((id: string) => id.includes('port'))).toBe(true)
+      expect(portRevisionMisses(draft, result.source)).toEqual([])
       // eslint-disable-next-line no-console
       console.log(`[figure-llm-smoke] revise: ${JSON.stringify(result.steps)}`)
     },