oda-engine 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/README.md +151 -2
  2. package/bin/nowhere.mjs +352 -0
  3. package/lib/account.mjs +57 -0
  4. package/lib/agentModules.mjs +57 -0
  5. package/lib/devServer.mjs +351 -0
  6. package/lib/headless.mjs +231 -0
  7. package/lib/headlessPreview.mjs +212 -0
  8. package/lib/keys.mjs +517 -0
  9. package/lib/make.mjs +855 -0
  10. package/lib/mcp.mjs +537 -0
  11. package/lib/open.mjs +22 -0
  12. package/lib/preview.mjs +87 -0
  13. package/lib/previewRpc.mjs +134 -0
  14. package/lib/project.mjs +359 -0
  15. package/lib/publishFlow.mjs +131 -0
  16. package/lib/resources.mjs +50 -0
  17. package/lib/rules.mjs +60 -0
  18. package/lib/scaffold.mjs +42 -0
  19. package/lib/setup.mjs +59 -0
  20. package/lib/tools.mjs +668 -0
  21. package/package.json +51 -4
  22. package/template/game.config.json +9 -0
  23. package/template/scene.json +4 -0
  24. package/template/src/main.ts +11 -0
  25. package/vendor/DOCS.md +447 -0
  26. package/vendor/agent/appRun.mjs +520 -0
  27. package/vendor/agent/assets/brief.mjs +242 -0
  28. package/vendor/agent/assets/collider.mjs +531 -0
  29. package/vendor/agent/assets/environments/index.mjs +12 -0
  30. package/vendor/agent/assets/environments/worldlabs.mjs +161 -0
  31. package/vendor/agent/assets/fetch.mjs +168 -0
  32. package/vendor/agent/assets/footprint.mjs +13 -0
  33. package/vendor/agent/assets/gltf.mjs +547 -0
  34. package/vendor/agent/assets/hdr.mjs +269 -0
  35. package/vendor/agent/assets/imageOps.mjs +171 -0
  36. package/vendor/agent/assets/images/codex.mjs +307 -0
  37. package/vendor/agent/assets/images/fal.mjs +75 -0
  38. package/vendor/agent/assets/images/gemini.mjs +84 -0
  39. package/vendor/agent/assets/images/index.mjs +25 -0
  40. package/vendor/agent/assets/images/openai.mjs +75 -0
  41. package/vendor/agent/assets/images/stability.mjs +71 -0
  42. package/vendor/agent/assets/images/views.mjs +31 -0
  43. package/vendor/agent/assets/import.mjs +1352 -0
  44. package/vendor/agent/assets/inspect.mjs +465 -0
  45. package/vendor/agent/assets/jobs.mjs +196 -0
  46. package/vendor/agent/assets/ktx2.mjs +290 -0
  47. package/vendor/agent/assets/ledger.mjs +466 -0
  48. package/vendor/agent/assets/net.mjs +254 -0
  49. package/vendor/agent/assets/prices.json +39 -0
  50. package/vendor/agent/assets/providers/fal.mjs +115 -0
  51. package/vendor/agent/assets/providers/index.mjs +22 -0
  52. package/vendor/agent/assets/providers/meshy.mjs +119 -0
  53. package/vendor/agent/assets/providers/tripo.mjs +188 -0
  54. package/vendor/agent/assets/sources/ambientcg.mjs +129 -0
  55. package/vendor/agent/assets/sources/index.mjs +23 -0
  56. package/vendor/agent/assets/sources/polyhaven.mjs +237 -0
  57. package/vendor/agent/assets/sources/polypizza.mjs +121 -0
  58. package/vendor/agent/assets/splat.mjs +631 -0
  59. package/vendor/agent/assets/targets.mjs +122 -0
  60. package/vendor/agent/assets/tile.mjs +261 -0
  61. package/vendor/agent/assets/unzip.mjs +180 -0
  62. package/vendor/agent/blender/cleanup.py +360 -0
  63. package/vendor/agent/blender/convert.py +167 -0
  64. package/vendor/agent/blender/find.mjs +192 -0
  65. package/vendor/agent/blender/nw_export.py +104 -0
  66. package/vendor/agent/blender/nw_rubric.py +426 -0
  67. package/vendor/agent/blender/run.mjs +193 -0
  68. package/vendor/agent/blender/runner.py +252 -0
  69. package/vendor/agent/blender/sheet.py +743 -0
  70. package/vendor/agent/depth.mjs +134 -0
  71. package/vendor/agent/director/board.mjs +451 -0
  72. package/vendor/agent/director/contracts.mjs +663 -0
  73. package/vendor/agent/director/director.mjs +2365 -0
  74. package/vendor/agent/director/estimate.mjs +200 -0
  75. package/vendor/agent/director/gate.mjs +802 -0
  76. package/vendor/agent/director/limits.json +16 -0
  77. package/vendor/agent/director/methods.mjs +457 -0
  78. package/vendor/agent/director/policy.json +33 -0
  79. package/vendor/agent/director/prompts.mjs +244 -0
  80. package/vendor/agent/director/reading.mjs +341 -0
  81. package/vendor/agent/director/router.mjs +184 -0
  82. package/vendor/agent/director/seams.mjs +243 -0
  83. package/vendor/agent/director/session.mjs +643 -0
  84. package/vendor/agent/director/store.mjs +119 -0
  85. package/vendor/agent/director/taskGate.mjs +110 -0
  86. package/vendor/agent/director/teamLedger.mjs +118 -0
  87. package/vendor/agent/director/triage.mjs +63 -0
  88. package/vendor/agent/downloads.cjs +363 -0
  89. package/vendor/agent/flow.mjs +78 -0
  90. package/vendor/agent/guard.mjs +613 -0
  91. package/vendor/agent/host.mjs +1736 -0
  92. package/vendor/agent/language.mjs +58 -0
  93. package/vendor/agent/ledger.mjs +360 -0
  94. package/vendor/agent/locale.cjs +186 -0
  95. package/vendor/agent/loop/capacity.mjs +74 -0
  96. package/vendor/agent/loop/compose.mjs +127 -0
  97. package/vendor/agent/loop/gate.mjs +205 -0
  98. package/vendor/agent/loop/judge.mjs +189 -0
  99. package/vendor/agent/loop/levels.mjs +273 -0
  100. package/vendor/agent/loop/state.mjs +358 -0
  101. package/vendor/agent/notes.cjs +278 -0
  102. package/vendor/agent/pace.mjs +258 -0
  103. package/vendor/agent/panels.mjs +431 -0
  104. package/vendor/agent/prompt.mjs +342 -0
  105. package/vendor/agent/reference/board.mjs +410 -0
  106. package/vendor/agent/reference/compose.mjs +364 -0
  107. package/vendor/agent/reference/decode.mjs +56 -0
  108. package/vendor/agent/reference/facts.mjs +1874 -0
  109. package/vendor/agent/reference/png.mjs +107 -0
  110. package/vendor/agent/reference/records.mjs +63 -0
  111. package/vendor/agent/reference/web.mjs +252 -0
  112. package/vendor/agent/roles/artist.mjs +69 -0
  113. package/vendor/agent/roles/builder.mjs +79 -0
  114. package/vendor/agent/roles/checks.mjs +223 -0
  115. package/vendor/agent/roles/common.mjs +188 -0
  116. package/vendor/agent/roles/critic.mjs +171 -0
  117. package/vendor/agent/roles/index.mjs +39 -0
  118. package/vendor/agent/roles/modeller.mjs +142 -0
  119. package/vendor/agent/roles/qa.mjs +58 -0
  120. package/vendor/agent/roles/rubrics.mjs +79 -0
  121. package/vendor/agent/roles/sound.mjs +69 -0
  122. package/vendor/agent/rounds.cjs +333 -0
  123. package/vendor/agent/shared.mjs +284 -0
  124. package/vendor/agent/stopGate.mjs +574 -0
  125. package/vendor/agent/subagents.mjs +129 -0
  126. package/vendor/agent/tools/assets.mjs +499 -0
  127. package/vendor/agent/tools/blender.mjs +754 -0
  128. package/vendor/agent/tools/cards.mjs +479 -0
  129. package/vendor/agent/tools/choices.mjs +479 -0
  130. package/vendor/agent/tools/compose.mjs +74 -0
  131. package/vendor/agent/tools/environment.mjs +488 -0
  132. package/vendor/agent/tools/eyes.mjs +733 -0
  133. package/vendor/agent/tools/generate.mjs +338 -0
  134. package/vendor/agent/tools/guide.mjs +46 -0
  135. package/vendor/agent/tools/harness.mjs +193 -0
  136. package/vendor/agent/tools/image.mjs +643 -0
  137. package/vendor/agent/tools/index.mjs +162 -0
  138. package/vendor/agent/tools/look.mjs +578 -0
  139. package/vendor/agent/tools/loop.mjs +858 -0
  140. package/vendor/agent/tools/others.mjs +123 -0
  141. package/vendor/agent/tools/pictures.mjs +535 -0
  142. package/vendor/agent/tools/reference.mjs +366 -0
  143. package/vendor/agent/transcripts.mjs +118 -0
  144. package/vendor/agent-loop.mjs +602 -0
  145. package/vendor/agent-plugin/.claude-plugin/plugin.json +5 -0
  146. package/vendor/agent-plugin/skills/art-direction/SKILL.md +82 -0
  147. package/vendor/agent-plugin/skills/asset-legality/SKILL.md +101 -0
  148. package/vendor/agent-plugin/skills/asset-sources/SKILL.md +111 -0
  149. package/vendor/agent-plugin/skills/blender-modeling/SKILL.md +97 -0
  150. package/vendor/agent-plugin/skills/look-dev/SKILL.md +104 -0
  151. package/vendor/agent-plugin/skills/playtesting/SKILL.md +74 -0
  152. package/vendor/agent-plugin/skills/reference-loop/SKILL.md +102 -0
  153. package/vendor/agent-plugin/skills/sound-design/SKILL.md +60 -0
  154. package/vendor/agent-plugin/skills/style/SKILL.md +35 -0
  155. package/vendor/agent-plugin/skills/tsl-r185/SKILL.md +107 -0
  156. package/vendor/auth.cjs +570 -0
  157. package/vendor/build.cjs +953 -0
  158. package/vendor/catalog.json +455 -0
  159. package/vendor/connectors.cjs +688 -0
  160. package/vendor/eyes.mjs +733 -0
  161. package/vendor/gameExports.json +1390 -0
  162. package/vendor/git.cjs +222 -0
  163. package/vendor/models.json +57 -0
  164. package/vendor/publish.cjs +1018 -0
  165. package/vendor/refBoard.cjs +301 -0
  166. package/vendor/schema/dist/assets.d.ts +335 -0
  167. package/vendor/schema/dist/assets.js +439 -0
  168. package/vendor/schema/dist/brief.d.ts +357 -0
  169. package/vendor/schema/dist/brief.js +302 -0
  170. package/vendor/schema/dist/common.d.ts +9 -0
  171. package/vendor/schema/dist/common.js +13 -0
  172. package/vendor/schema/dist/config.d.ts +406 -0
  173. package/vendor/schema/dist/config.js +355 -0
  174. package/vendor/schema/dist/contract.d.ts +599 -0
  175. package/vendor/schema/dist/contract.js +1146 -0
  176. package/vendor/schema/dist/index.d.ts +14 -0
  177. package/vendor/schema/dist/index.js +21 -0
  178. package/vendor/schema/dist/look.d.ts +463 -0
  179. package/vendor/schema/dist/look.js +681 -0
  180. package/vendor/schema/dist/lookStats.d.ts +230 -0
  181. package/vendor/schema/dist/lookStats.js +768 -0
  182. package/vendor/schema/dist/pilot.d.ts +32 -0
  183. package/vendor/schema/dist/pilot.js +44 -0
  184. package/vendor/schema/dist/publish.d.ts +214 -0
  185. package/vendor/schema/dist/publish.js +291 -0
  186. package/vendor/schema/dist/scene.d.ts +75 -0
  187. package/vendor/schema/dist/scene.js +120 -0
  188. package/vendor/schema/dist/skyLight.d.ts +141 -0
  189. package/vendor/schema/dist/skyLight.js +436 -0
  190. package/vendor/schema/dist/style.d.ts +131 -0
  191. package/vendor/schema/dist/style.js +155 -0
  192. package/vendor/schema/package.json +1 -0
  193. package/vendor/selectionPrompt.mjs +51 -0
  194. package/vendor/useTools.mjs +195 -0
  195. package/vendor/userMessage.mjs +26 -0
  196. package/web-dist/assets/GaussianSplatUtils-CptQkDVX.js +1 -0
  197. package/web-dist/assets/KTX2Loader-C53LJqss.js +2 -0
  198. package/web-dist/assets/SPZLoader-BQ3tjaTv.js +1 -0
  199. package/web-dist/assets/gaussianSplat-_9tcWegB.js +1 -0
  200. package/web-dist/assets/index-Baka-ZO7.js +693 -0
  201. package/web-dist/assets/index-CcjyyQco.css +1 -0
  202. package/web-dist/assets/meshopt_decoder.module-BvwdjiD3.js +1 -0
  203. package/web-dist/assets/zstddec.module-CfFeQW7d.js +1 -0
  204. package/web-dist/index.html +34 -0
@@ -0,0 +1,242 @@
1
+ // The project's space brief (brief.json) as the asset tools read it: what
2
+ // they hold a texture to (its texel density), which libraries this space
3
+ // draws from, and the record of what was picked from them. The schema and
4
+ // its rules are @nowhere/schema's (brief.ts); this file adds the disk.
5
+ //
6
+ // Every function here answers rather than throws: a brief that is missing or
7
+ // broken never stops an import, it only means there is nothing to compare with.
8
+
9
+ import { randomBytes } from 'node:crypto'
10
+ import fsp from 'node:fs/promises'
11
+ import path from 'node:path'
12
+ import { BRIEF_FILE, STYLE_FILE, styleAdvice, validateBrief, validateStyle } from '../../schema/dist/index.js'
13
+
14
+ /**
15
+ * { status: 'absent' } | { status: 'invalid', findings, error } |
16
+ * { status: 'ok', brief, raw }. `error` is the first finding as a sentence.
17
+ */
18
+ export async function readBrief(projectRoot) {
19
+ let text
20
+ try {
21
+ text = await fsp.readFile(path.join(projectRoot, BRIEF_FILE), 'utf8')
22
+ } catch (err) {
23
+ if (err?.code === 'ENOENT') return { status: 'absent' }
24
+ return { status: 'invalid', findings: [], error: `${BRIEF_FILE} could not be read (${err?.code ?? err?.message})` }
25
+ }
26
+ let raw
27
+ try {
28
+ raw = JSON.parse(text)
29
+ } catch (err) {
30
+ return { status: 'invalid', findings: [], error: `${BRIEF_FILE} is not valid JSON (${err.message})` }
31
+ }
32
+ const checked = validateBrief(raw)
33
+ if (!checked.ok) {
34
+ const first = checked.findings[0]
35
+ return { status: 'invalid', findings: checked.findings, error: first ? `${first.path}: ${first.message}` : `${BRIEF_FILE} does not pass its schema` }
36
+ }
37
+ return { status: 'ok', brief: checked.brief, raw }
38
+ }
39
+
40
+ /**
41
+ * lookAdvice's lines as this space's brief reads them: a sky of none is no
42
+ * warning when the brief itself picks none (an interior whose references
43
+ * show no sky), so nw_status, nw_check and the stop gate never send the
44
+ * agent off to set a sky against its own brief.
45
+ */
46
+ export async function adviceUnderBrief(projectRoot, lines) {
47
+ const none = (l) => /^sky is none\b/.test(String(l))
48
+ let out = lines
49
+ if (lines.some(none)) {
50
+ const r = await readBrief(projectRoot)
51
+ if (r.status === 'ok' && r.brief.light.sky.kind === 'none') out = lines.filter((l) => !none(l))
52
+ }
53
+ // Where the look draws otherwise than style.json says.
54
+ const st = await readStyle(projectRoot)
55
+ if (st.status === 'ok') {
56
+ try {
57
+ out = [...out, ...styleAdvice(st.style, JSON.parse(await fsp.readFile(path.join(projectRoot, 'game.config.json'), 'utf8')))]
58
+ } catch {
59
+ // a config that cannot be read is the build's to say
60
+ }
61
+ }
62
+ return out
63
+ }
64
+
65
+ /** style.json as { status: 'absent' | 'invalid' | 'ok', style?, findings, error? }. */
66
+ export async function readStyle(projectRoot) {
67
+ let text
68
+ try {
69
+ text = await fsp.readFile(path.join(projectRoot, STYLE_FILE), 'utf8')
70
+ } catch (err) {
71
+ if (err?.code === 'ENOENT') return { status: 'absent', findings: [] }
72
+ return { status: 'invalid', findings: [], error: `${STYLE_FILE} could not be read (${err?.code ?? err?.message})` }
73
+ }
74
+ let raw
75
+ try {
76
+ raw = JSON.parse(text)
77
+ } catch (err) {
78
+ return { status: 'invalid', findings: [], error: `${STYLE_FILE} is not valid JSON (${err.message})` }
79
+ }
80
+ const checked = validateStyle(raw)
81
+ if (!checked.ok) {
82
+ const first = checked.findings[0]
83
+ return { status: 'invalid', findings: checked.findings, error: first ? `${first.path}: ${first.message}` : `${STYLE_FILE} does not pass its schema` }
84
+ }
85
+ return { status: 'ok', style: checked.style, findings: [] }
86
+ }
87
+
88
+ const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
89
+
90
+ /** The lines nw_check adds for the brief: none without one, the findings
91
+ * for a broken one (a failure), a summary for a good one. */
92
+ export async function briefCheck(projectRoot) {
93
+ const st = await readStyle(projectRoot)
94
+ const styleLines =
95
+ st.status === 'ok'
96
+ ? [`${STYLE_FILE} passes its schema: ${st.style.medium}${st.style.look ? `, drawn with ${Object.keys(st.style.look).join(', ') || 'no technique'}` : ', drawn by the light and materials alone'}.`]
97
+ : []
98
+ if (st.status === 'invalid') {
99
+ const found = st.findings.length ? st.findings.slice(0, 8).map((f) => `- ${f.path}: ${f.message}`) : [`- ${st.error}`]
100
+ return { ok: false, lines: [`${STYLE_FILE} does not pass its schema (nw_schema kind "style" has the shape):`, ...found] }
101
+ }
102
+ const b0 = await briefCheckAlone(projectRoot)
103
+ return { ok: b0.ok, lines: [...styleLines, ...b0.lines] }
104
+ }
105
+
106
+ async function briefCheckAlone(projectRoot) {
107
+ const r = await readBrief(projectRoot)
108
+ if (r.status === 'absent') return { ok: true, lines: [] }
109
+ if (r.status === 'invalid') {
110
+ const found = r.findings.length ? r.findings.slice(0, 8).map((f) => `- ${f.path}: ${f.message}`) : [`- ${r.error}`]
111
+ return { ok: false, lines: [`${BRIEF_FILE} does not pass its schema (nw_schema kind "brief" has the shape):`, ...found] }
112
+ }
113
+ const b = r.brief
114
+ return {
115
+ ok: true,
116
+ lines: [`${BRIEF_FILE} passes its schema: ${count(b.references.length, 'reference')}, ${count(b.materials.length, 'material')}, ${count(b.heroViews.length, 'hero view')}, its files up to ${b.budget.assetsMb} MB.`],
117
+ }
118
+ }
119
+
120
+ /**
121
+ * Adds what was imported from a library to the brief's sources.picked, so
122
+ * the space keeps to one family of sources and the brief says where each
123
+ * file came from. Only into a brief that passes its schema and already names
124
+ * its libraries; anything else is left as it is. Answers a sentence or null.
125
+ */
126
+ export async function recordPick(projectRoot, pick) {
127
+ const r = await readBrief(projectRoot)
128
+ if (r.status !== 'ok' || !r.raw.sources) return null
129
+ const raw = r.raw
130
+ const picked = Array.isArray(raw.sources.picked) ? raw.sources.picked.filter((p) => p?.as !== pick.as) : []
131
+ picked.push(pick)
132
+ raw.sources.picked = picked
133
+ if (!validateBrief(raw).ok) return null
134
+ const abs = path.join(projectRoot, BRIEF_FILE)
135
+ const temp = `${abs}.${process.pid}.${randomBytes(3).toString('hex')}.part`
136
+ try {
137
+ await fsp.writeFile(temp, `${JSON.stringify(raw, null, 2)}\n`)
138
+ await fsp.rename(temp, abs)
139
+ } catch {
140
+ await fsp.rm(temp, { force: true }).catch(() => {})
141
+ return null
142
+ }
143
+ const provider = pick.id.slice(0, pick.id.indexOf(':'))
144
+ const outside = !raw.sources.libraries.includes(provider)
145
+ return `Recorded in ${BRIEF_FILE}'s sources as ${pick.id}.${outside ? ` The brief names ${raw.sources.libraries.join(', ')} as this space's libraries, not ${provider}: say why in brief.md, or pick from them.` : ''}`
146
+ }
147
+
148
+ /**
149
+ * Cites the pictures the creator picked for the brief (nw_ask_pictures) in
150
+ * its references, as the board shows a citation: each with the next free id
151
+ * (R1, R2...), its path on the board, where it came from when that was the
152
+ * web, what the space takes from it and nw_reference's numbers under the
153
+ * brief's names. A picture the brief already cites keeps its id and its
154
+ * words. Only into a brief that passes its schema, and only when it still
155
+ * passes with them; otherwise nothing is written and the references are
156
+ * answered for the agent to write into brief.json itself.
157
+ *
158
+ * picks: [{ path, url?, what, measured? }]
159
+ * Answers { status: 'written' | 'unchanged' | 'absent' | 'invalid', refs, error? },
160
+ * refs being every pick as the brief cites it (or would).
161
+ */
162
+ export async function recordReferences(projectRoot, picks) {
163
+ const r = await readBrief(projectRoot)
164
+ const existing = r.status === 'ok' ? r.raw.references : []
165
+ const taken = new Map(existing.filter((x) => typeof x?.path === 'string').map((x) => [x.path, x]))
166
+ let next = Math.max(0, ...existing.map((x) => Number(/^R(\d+)$/.exec(String(x?.id))?.[1]) || 0)) + 1
167
+ const refs = []
168
+ const added = []
169
+ for (const p of picks) {
170
+ const cited = taken.get(p.path)
171
+ if (cited) {
172
+ refs.push({ id: cited.id, path: cited.path, what: cited.what, ...(cited.url ? { url: cited.url } : {}), already: true })
173
+ continue
174
+ }
175
+ const ref = {
176
+ id: `R${next++}`,
177
+ path: p.path,
178
+ ...(p.url ? { url: p.url } : {}),
179
+ what: String(p.what ?? '').trim().slice(0, 400) || 'Picked by the creator for the brief.',
180
+ ...(p.origin === 'target' || p.origin === 'attached' ? { origin: p.origin } : {}),
181
+ ...(p.measured && Object.keys(p.measured).length ? { measured: p.measured } : {}),
182
+ }
183
+ refs.push(ref)
184
+ added.push(ref)
185
+ }
186
+ if (r.status !== 'ok') return { status: r.status, refs, ...(r.error ? { error: r.error } : {}) }
187
+ if (!added.length) return { status: 'unchanged', refs }
188
+ const raw = { ...r.raw, references: [...existing, ...added] }
189
+ const checked = validateBrief(raw)
190
+ if (!checked.ok) {
191
+ const first = checked.findings[0]
192
+ return { status: 'invalid', refs, error: first ? `${first.path}: ${first.message}` : `${BRIEF_FILE} would not pass its schema` }
193
+ }
194
+ const abs = path.join(projectRoot, BRIEF_FILE)
195
+ const temp = `${abs}.${process.pid}.${randomBytes(3).toString('hex')}.part`
196
+ try {
197
+ await fsp.writeFile(temp, `${JSON.stringify(raw, null, 2)}\n`)
198
+ await fsp.rename(temp, abs)
199
+ } catch (err) {
200
+ await fsp.rm(temp, { force: true }).catch(() => {})
201
+ return { status: 'invalid', refs, error: `${BRIEF_FILE} could not be written (${err?.code ?? err?.message})` }
202
+ }
203
+ return { status: 'written', refs }
204
+ }
205
+
206
+ /**
207
+ * The reference loop's numbers written into brief.json (REFERENCE_LOOP.md
208
+ * 2.1, 2.3, 2.5): the speed level's time and rounds beside the files'
209
+ * weight in budget, the bar, and the judge's score after each round.
210
+ * Answers { status: 'written' | 'unchanged' | 'absent' | 'invalid', error? }:
211
+ * a brief not written yet takes them when it is (the tools' answers give
212
+ * them), and a broken one is left as it is.
213
+ */
214
+ export async function recordLoop(projectRoot, { budget = null, bar = null, scoreHistory = null } = {}) {
215
+ const r = await readBrief(projectRoot)
216
+ if (r.status !== 'ok') return { status: r.status, ...(r.error ? { error: r.error } : {}) }
217
+ const raw = { ...r.raw }
218
+ if (budget) {
219
+ // The loop's own keys are replaced whole: a level kicked off later must
220
+ // not keep an earlier step's quality or least rounds beside it.
221
+ const { level: _level, quality: _quality, minRounds: _minRounds, timeFloorMin: _floor, timeCapMin: _cap, roundCap: _rounds, usdEstimate: _usd, ...kept } = raw.budget ?? {}
222
+ raw.budget = { ...kept, ...budget }
223
+ }
224
+ if (bar) raw.bar = { ...bar }
225
+ if (Array.isArray(scoreHistory)) raw.scoreHistory = scoreHistory.map((v) => Math.round(v * 10) / 10)
226
+ if (JSON.stringify(raw) === JSON.stringify(r.raw)) return { status: 'unchanged' }
227
+ const checked = validateBrief(raw)
228
+ if (!checked.ok) {
229
+ const first = checked.findings[0]
230
+ return { status: 'invalid', error: first ? `${first.path}: ${first.message}` : `${BRIEF_FILE} would not pass its schema` }
231
+ }
232
+ const abs = path.join(projectRoot, BRIEF_FILE)
233
+ const temp = `${abs}.${process.pid}.${randomBytes(3).toString('hex')}.part`
234
+ try {
235
+ await fsp.writeFile(temp, `${JSON.stringify(raw, null, 2)}\n`)
236
+ await fsp.rename(temp, abs)
237
+ } catch (err) {
238
+ await fsp.rm(temp, { force: true }).catch(() => {})
239
+ return { status: 'invalid', error: `${BRIEF_FILE} could not be written (${err?.code ?? err?.message})` }
240
+ }
241
+ return { status: 'written' }
242
+ }