@things-factory/figure-service 10.1.167 → 10.1.169

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.167",
+  "version": "10.1.169",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,9 +25,9 @@
     "test:templates": "node --test scripts/templates.test.mts"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.6.6",
+    "@hatiolab/figure-model": "^0.7.1",
     "@operato/typeorm-history": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.167",
+    "@things-factory/ai-client-base": "^10.1.169",
     "@things-factory/attachment-base": "^10.1.167",
     "@things-factory/auth-base": "^10.1.167",
     "@things-factory/env": "^10.1.149",
@@ -38,5 +38,5 @@
     "jszip": "^3.10.1",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "86283c5d35042880be6827f777067fc5e6417eed"
+  "gitHead": "9d71d02b443f3e0080b25de1768b982c51a64111"
 }

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

@@ -0,0 +1,288 @@
+/**
+ * figure-context — what of a figure the model is shown (ADR-0061 2026-10-16 decision 4).
+ *
+ * The kernel keeps a figure up to 1 MiB; the model is shown at most FIGURE_CONTEXT_BUDGET of it in one read. A figure past
+ * that is read as an outline and the parts asked for, and a proposal may change only the parts it was shown. The figures
+ * here are made by the kernel's own commands, as a person makes them in the modeller: a rack of shelves, each fastened on
+ * the one below, grown until it crosses the budget.
+ */
+import { FIGURE_PROPOSAL_KINDS, applyFigureProposal, createFigureAsset, serializeFigureAsset } from '@hatiolab/figure-model'
+import type { FigureAsset } from '@hatiolab/figure-model'
+import type { AIClient } from '@things-factory/ai-client-base'
+
+import { FIGURE_CONTEXT_BUDGET, figureViewOf, unreadPartEdits, unreadSectionEdits } from './figure-context'
+import { ProposeFigureFailure, judgeFigureAnswer, proposeFigureSteps } from './figure-propose-steps'
+import { parseSource } from './figure-format'
+
+const shelf = (i: number) => [
+  { kind: 'add-part', part: { id: `shelf-${i}`, kind: 'box', dimensions: { width: 1200, height: 40, depth: 600 } } },
+  i === 0
+    ? { kind: 'attach', part: 'shelf-0', face: 'bottom', to: { plane: 'mounting-plane' } }
+    : { kind: 'attach', part: `shelf-${i}`, face: 'bottom', to: { part: `shelf-${i - 1}`, face: 'top' }, gap: 300 }
+]
+
+/** The last rack the model is shown whole, and the first it is not: one shelf apart. */
+let under: FigureAsset
+let over: FigureAsset
+/** A small rack whose one seat has a 130,000-character label: large, and none of it in its parts (audit D4-R2). */
+let labelled: FigureAsset
+beforeAll(() => {
+  let small = createFigureAsset('Rack')
+  for (let i = 0; i < 3; i++) small = applyFigureProposal(small, shelf(i) as never)
+  labelled = applyFigureProposal(small, [
+    { kind: 'add-binding', id: 'seat', label: 'x'.repeat(130_000), role: 'seat', part: 'shelf-2', face: 'top', accepts: ['box'], capacity: 1 }
+  ] as never)
+
+  let rack = createFigureAsset('Rack')
+  for (let i = 0; ; i++) {
+    const next = applyFigureProposal(rack, shelf(i) as never)
+    if (serializeFigureAsset(next).length > FIGURE_CONTEXT_BUDGET) {
+      under = rack
+      over = next
+      return
+    }
+    rack = next
+  }
+})
+
+const size = (asset: FigureAsset) => serializeFigureAsset(asset).length
+const partsOf = (asset: FigureAsset) => asset.appearance.map(a => a.target)
+
+describe('the budget is the model’s, not the kernel’s', () => {
+  it('the racks sit one shelf either side of the budget, and the kernel takes both', () => {
+    expect(size(under)).toBeLessThanOrEqual(FIGURE_CONTEXT_BUDGET)
+    expect(size(over)).toBeGreaterThan(FIGURE_CONTEXT_BUDGET)
+    expect(size(over) - size(under)).toBeLessThan(5_000)
+    expect(() => parseSource(serializeFigureAsset(over))).not.toThrow()
+  })
+
+  it('just under: the whole source', () => {
+    const view = figureViewOf(under)
+    expect(view.whole).toBe(true)
+    expect(view.source).toBe(under)
+  })
+
+  it('just over: an outline that names every part, inside the budget, without the graph', () => {
+    const view = figureViewOf(over)
+    expect(view.whole).toBe(false)
+    expect(view.source).toBeUndefined()
+    expect(JSON.stringify(view.outline).length).toBeLessThan(FIGURE_CONTEXT_BUDGET)
+    expect(view.outline!.chars).toBe(size(over))
+    expect(view.outline!.parts.map(p => p.id)).toEqual(partsOf(over))
+    expect(view.outline!.parts[1]).toMatchObject({ id: 'shelf-1', on: 'shelf-0.top', joint: { id: 'shelf-1', type: 'fixed' } })
+    expect(view.outline!.parts[0].on).toBe('mounting-plane')
+    expect(view.outline!.document.model.nodes).toBe(over.document.model.nodes.length)
+    expect(view.outline!.palette).toEqual(over.palette)
+  })
+
+  it('a part read is its own records: its look, its fastenings, the nodes under its name', () => {
+    const view = figureViewOf(over, { parts: ['shelf-3'] })
+    const read = view.parts!['shelf-3']
+    expect(read.appearance.target).toBe('shelf-3')
+    expect(read.joints.map((j: any) => j.id).sort()).toEqual(['shelf-3', 'shelf-4'])
+    expect(read.nodes.length).toBeGreaterThan(0)
+    expect(read.nodes.every((n: any) => n.id === 'shelf-3' || n.id.startsWith('shelf-3.'))).toBe(true)
+    expect(read.nodes.some((n: any) => n.id.startsWith('shelf-30.'))).toBe(false)
+    expect(view.shown).toEqual(['shelf-3'])
+  })
+
+  it('what is not a part, or does not fit beside the rest, is said, not shown', () => {
+    const view = figureViewOf(over, { parts: ['shelf-2', 'ghost', ...partsOf(over)] })
+    expect(view.notRead).toContainEqual({ part: 'ghost', reason: expect.stringMatching(/not a part/) })
+    expect(view.notRead!.some(n => /does not fit/.test(n.reason))).toBe(true)
+    expect(JSON.stringify(view).length).toBeLessThanOrEqual(FIGURE_CONTEXT_BUDGET)
+  })
+})
+
+/*
+  Audit D4-R2: a figure whose size is in a section, not in its parts -- here a seat's label -- gave an outline of 132,709
+  characters against a budget of 100,000, and no room for any part. The outline leaves such a section out by its pointer
+  and the entries inside it; the model reads what it needs of it by pointer.
+*/
+describe('a section too large for the outline', () => {
+  const BINDINGS = '/document/capabilities/bindings'
+
+  it('the kernel takes the figure, and its view, every field counted, fits the budget with room for a part', () => {
+    expect(() => parseSource(serializeFigureAsset(labelled))).not.toThrow()
+    expect(size(labelled)).toBeGreaterThan(FIGURE_CONTEXT_BUDGET)
+    const view = figureViewOf(labelled, { parts: ['shelf-2'] })
+    expect(JSON.stringify(view).length).toBeLessThanOrEqual(FIGURE_CONTEXT_BUDGET)
+    expect(view.shown).toEqual(['shelf-2'])
+    const omitted = view.outline!.omitted!.find(o => o.section === '/document/capabilities')!
+    expect(omitted.chars).toBeGreaterThan(130_000)
+    expect(omitted.entries).toContainEqual({ section: BINDINGS, chars: expect.any(Number) })
+  })
+
+  it('a section is read by its pointer; one too large says which entries to read instead', () => {
+    const view = figureViewOf(labelled, { sections: ['/document/capabilities/version', BINDINGS, `${BINDINGS}/0/accepts`] })
+    expect(view.sections).toEqual({ '/document/capabilities/version': labelled.document.capabilities.version, [`${BINDINGS}/0/accepts`]: ['box'] })
+    const big = view.notRead!.find(n => n.section === BINDINGS)!
+    expect(big.reason).toMatch(/too large to show at once/)
+    expect(big.reason).toContain(`${BINDINGS}/0`)
+    const label = figureViewOf(labelled, { sections: [`${BINDINGS}/0/label`] }).notRead![0]
+    expect(label.reason).toMatch(/one value of 130002 characters/) /* the label and its two quotes */
+    expect(figureViewOf(labelled, { sections: ['/nowhere'] }).notRead![0].reason).toMatch(/no section/)
+  })
+
+  it('a section left out and not read is not changed; a new entry beside it may be added', () => {
+    const view = figureViewOf(labelled, { parts: ['shelf-2'] })
+    const relabel = applyFigureProposal(labelled, [{ kind: 'remove-binding', id: 'seat' }] as never)
+    expect(unreadSectionEdits(labelled, relabel, view)).toEqual([expect.stringMatching(/^UNREAD_SECTION: .*\/document\/capabilities\/bindings\/0/)])
+    const added = applyFigureProposal(labelled, [
+      { kind: 'add-binding', id: 'grip', label: 'Grip', role: 'grip', part: 'shelf-1', face: 'top', accepts: ['box'], capacity: 1 }
+    ] as never)
+    expect(unreadSectionEdits(labelled, added, view)).toEqual([])
+    const read = figureViewOf(labelled, { parts: ['shelf-2'], sections: [`${BINDINGS}/0/accepts`, `${BINDINGS}/0/capacity`] })
+    const widened = structuredClone(labelled) as any
+    widened.document.capabilities.bindings[0].capacity = 2
+    expect(unreadSectionEdits(labelled, widened, read)).toEqual([])
+    widened.document.capabilities.bindings[0].role = 'grip'
+    expect(unreadSectionEdits(labelled, widened, read)).toHaveLength(1)
+  })
+
+  it('a figure of many long-named parts still gets an outline inside the budget, saying how many it could not list', () => {
+    const many = structuredClone(under) as any
+    const look = many.appearance[0]
+    many.appearance = Array.from({ length: 3_000 }, (_, i) => ({ ...look, target: `part-with-a-rather-long-name-${'x'.repeat(40)}-${i}` }))
+    const view = figureViewOf(many)
+    expect(JSON.stringify(view).length).toBeLessThanOrEqual(FIGURE_CONTEXT_BUDGET)
+    expect(view.outline!.partsNotListed).toBeGreaterThan(0)
+    expect(view.outline!.parts.length + view.outline!.partsNotListed!).toBe(3_000)
+  })
+})
+
+describe('a proposal changes only what it was shown', () => {
+  let shown: ReturnType<typeof figureViewOf>
+  beforeAll(() => {
+    shown = figureViewOf(over, { parts: ['shelf-2'] })
+  })
+
+  it('changing a part not shown is refused, naming the step and the part', () => {
+    const reasons = unreadPartEdits(over, [{ kind: 'set-material', target: 'shelf-5', material: { token: 'palette.primary' } }] as never, shown)
+    expect(reasons).toEqual([expect.stringMatching(/^UNREAD_PART: steps\[0\] \(set-material\) changes "shelf-5"/)])
+  })
+
+  it('a joint is its moving part’s: refastening or removing it changes that part', () => {
+    const set = { kind: 'set-joint', joint: { id: 'shelf-5', type: 'fixed', body0: { part: 'shelf-2', face: 'top' }, body1: { part: 'shelf-5', face: 'bottom' }, origin: {} } }
+    const remove = { kind: 'remove-joint', id: 'shelf-5' }
+    expect(unreadPartEdits(over, [set, remove] as never, shown)).toHaveLength(2)
+  })
+
+  /*
+    Audit D4-R1: the part a step changes is the field the kernel reads for its kind. `set-material` reads `target`; a
+    `part` beside it named a part that was read, and the unread one was recoloured.
+  */
+  it('a field the kernel does not read for the kind does not stand in for the one it does', () => {
+    const decoys = { part: 'shelf-2', target: 'shelf-2', id: 'shelf-2' }
+    const steps = [
+      { ...decoys, kind: 'set-material', target: 'shelf-5', material: { token: 'palette.primary' } },
+      { ...decoys, kind: 'attach', part: 'shelf-5', face: 'bottom', to: { part: 'shelf-2', face: 'top' } },
+      { ...decoys, kind: 'remove-joint', joint: 'shelf-2', id: 'shelf-5' },
+      { ...decoys, kind: 'set-joint', joint: { id: 'shelf-2', type: 'fixed', body0: { part: 'shelf-2', face: 'top' }, body1: { part: 'shelf-5', face: 'bottom' }, origin: {} } }
+    ]
+    const reasons = unreadPartEdits(over, steps as never, shown)
+    expect(reasons).toHaveLength(steps.length)
+    reasons.forEach((reason, i) => expect(reason.startsWith(`UNREAD_PART: steps[${i}] (${steps[i].kind}) changes "shelf-5"`)).toBe(true))
+  })
+
+  it('every kind the grammar teaches is judged; a kind the judge does not know is refused, not let through', () => {
+    for (const kind of FIGURE_PROPOSAL_KINDS) expect(unreadPartEdits(over, [{ kind }] as never, shown).join()).not.toMatch(/UNKNOWN_STEP/)
+    expect(unreadPartEdits(over, [{ kind: 'recolour-anything', target: 'shelf-5' }] as never, shown)).toEqual([expect.stringMatching(/^UNKNOWN_STEP: steps\[0\]/)])
+  })
+
+  it('a shown part may change, a new part may be fastened to any part, the figure as a whole may change', () => {
+    const steps = [
+      { kind: 'set-material', target: 'shelf-2', material: { token: 'palette.primary' } },
+      { kind: 'add-part', part: { id: 'lamp', kind: 'sphere', dimensions: { radiusX: 40, radiusY: 40, radiusZ: 40 } } },
+      { kind: 'attach', part: 'lamp', face: 'bottom', to: { part: 'shelf-9', face: 'top' } },
+      { kind: 'link-dimension', part: 'lamp', axis: 'x', source: { of: 'part', part: 'shelf-7', axis: 'x' }, times: 0.1 },
+      { kind: 'fit-room', placement: 'floor' }
+    ]
+    expect(unreadPartEdits(over, steps as never, shown)).toEqual([])
+  })
+
+  it('the judge refuses it before applying; without a shown set (whole source) it does not ask', () => {
+    const answer = { steps: [{ kind: 'set-material', target: 'shelf-5', material: { token: 'palette.primary' } }] }
+    expect(judgeFigureAnswer(over, answer, true, shown).reasons[0]).toMatch(/^UNREAD_PART/)
+    const decoy = { steps: [{ kind: 'set-material', part: 'shelf-2', target: 'shelf-5', material: { token: 'palette.primary' } }] }
+    expect(judgeFigureAnswer(over, decoy, true, shown).reasons[0]).toMatch(/^UNREAD_PART/)
+    expect(judgeFigureAnswer(over, answer, true).source).toBeDefined()
+  })
+})
+
+function stubClient(answers: unknown[]): AIClient & { sent: any[][] } {
+  const client = {
+    id: 'stub',
+    sent: [] as any[][],
+    async chat() {
+      return ''
+    },
+    async generateJSON(messages: any[]) {
+      client.sent.push(JSON.parse(JSON.stringify(messages)))
+      return answers[client.sent.length - 1]
+    }
+  }
+  return client as unknown as AIClient & { sent: any[][] }
+}
+
+describe('the step writer is shown the same view', () => {
+  const recolour = (part: string) => ({ steps: [{ kind: 'set-material', target: part, material: { token: 'palette.primary' } }] })
+
+  it('just under: the whole source, and any part may change', async () => {
+    const client = stubClient([recolour('shelf-5')])
+    const result = await proposeFigureSteps({ client, prompt: 'recolour shelf 5', base: under })
+    expect(client.sent[0][0].content).toContain(serializeFigureAsset(under))
+    expect(result.attempts).toBe(1)
+  })
+
+  it('just over: the outline and the parts asked for, never the whole; the prompt fits the budget', async () => {
+    const client = stubClient([recolour('shelf-2')])
+    const result = await proposeFigureSteps({ client, prompt: 'recolour shelf 2', base: over, read: { parts: ['shelf-2'] } })
+    const task = client.sent[0][0].content as string
+    expect(task).not.toContain(serializeFigureAsset(over))
+    expect(task).toContain('"shelf-2.shape"')
+    expect(task).not.toContain('"shelf-5.shape"')
+    expect(task).toMatch(/Parts shown in full: shelf-2\./)
+    expect(task.length).toBeLessThan(FIGURE_CONTEXT_BUDGET + 2_000)
+    /* Judged on the full draft: the recoloured shelf is in the figure the steps make, with every other one. */
+    expect(partsOf(result.source)).toEqual(partsOf(over))
+  })
+
+  it('the selected part is shown too: “this part” is one the writer has read', async () => {
+    const client = stubClient([recolour('shelf-4')])
+    await proposeFigureSteps({ client, prompt: 'recolour this', base: over, focus: { selection: { part: 'shelf-4' } } })
+    expect(client.sent[0][0].content).toContain('"shelf-4.shape"')
+  })
+
+  it('a step on an unread part goes back to the writer as the reason; three times and the outer model is told to read it', async () => {
+    const client = stubClient([recolour('shelf-5'), recolour('shelf-5'), recolour('shelf-5')])
+    const failed = await proposeFigureSteps({ client, prompt: 'recolour shelf 5', base: over, read: { parts: ['shelf-2'] } }).catch(e => e)
+    expect(failed).toBeInstanceOf(ProposeFigureFailure)
+    expect(failed.reasons[0]).toMatch(/UNREAD_PART: steps\[0\] \(set-material\) changes "shelf-5".*getFigureSource.*parts/)
+    expect(client.sent[1].at(-1).content).toMatch(/UNREAD_PART/)
+  })
+
+  it('the audit’s mixed step (part read, target not) is refused on the real path, and nothing is recoloured', async () => {
+    const mixed = { steps: [{ kind: 'set-material', part: 'shelf-0', target: 'shelf-5', material: { token: 'palette.accent' }, palette: { 'palette.accent': '#ff0000' } }] }
+    const client = stubClient([mixed, mixed, mixed])
+    const failed = await proposeFigureSteps({ client, prompt: 'recolour', base: over, read: { parts: ['shelf-0'] } }).catch(e => e)
+    expect(failed).toBeInstanceOf(ProposeFigureFailure)
+    expect(failed.reasons[0]).toMatch(/UNREAD_PART: steps\[0\] \(set-material\) changes "shelf-5"/)
+  })
+
+  it('a step whose effect reaches a section the writer was not shown goes back as the reason', async () => {
+    const client = stubClient([{ steps: [{ kind: 'remove-binding', id: 'seat' }] }, { steps: [{ kind: 'set-material', target: 'shelf-2', material: { token: 'palette.primary' } }] }])
+    const result = await proposeFigureSteps({ client, prompt: 'tidy', base: labelled, read: { parts: ['shelf-2'] } })
+    expect(client.sent[1].at(-1).content).toMatch(/UNREAD_SECTION/)
+    expect(result.attempts).toBe(2)
+    expect((client.sent[0][0].content as string).length).toBeLessThan(FIGURE_CONTEXT_BUDGET + 2_000)
+  })
+
+  it('parts that are not there, or too many to show, fail before the writer is asked', async () => {
+    const client = stubClient([])
+    const failed = await proposeFigureSteps({ client, prompt: 'x', base: over, read: { parts: ['ghost'] } }).catch(e => e)
+    expect(failed).toBeInstanceOf(ProposeFigureFailure)
+    expect(failed.reasons.join('\n')).toMatch(/ghost.*not a part/)
+    expect(client.sent).toHaveLength(0)
+  })
+})