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,802 @@
1
+ // Whether an attempt passed, decided by code and a top-tier critic, never by
2
+ // the role saying so (studio diagnosis 2026-10-19: the model was never the
3
+ // cause, the missing bar for done was). Tool checks run first, in the
4
+ // board's order (build and runtime ahead of anything that looks at the
5
+ // preview), every one even after a failure so the next attempt hears
6
+ // all of them; when one failed the critic is not called (it is a top-tier
7
+ // call), and the next attempt gets the failures. When all passed and the
8
+ // task has critic criteria, the critic judges the shots against the
9
+ // reference, the brief and the best attempt so far (pairwise, which holds
10
+ // steadier than an absolute score), and returns structured scores and ranked
11
+ // changes. Pixel metrics never pass an attempt on their own: they only stop
12
+ // a pass (a gross mismatch) and tell stagnation from progress.
13
+ //
14
+ // Each check answers { id, kind, ok, text, evidence: { images, numbers } };
15
+ // its pictures are saved under the production's shots/ and travel as paths.
16
+
17
+ import { createRequire } from 'node:module'
18
+ import fs from 'node:fs'
19
+ import fsp from 'node:fs/promises'
20
+ import path from 'node:path'
21
+ import { TRIANGLE_BUDGETS } from '../../schema/dist/index.js'
22
+ import { ledgerProblems, readLedgerState } from '../assets/ledger.mjs'
23
+ import { CONFIDENT } from '../reference/facts.mjs'
24
+ import { runDef } from '../tools/index.mjs'
25
+ import { playParams } from '../tools/eyes.mjs'
26
+ import { DONE, PREVIEW_KINDS, isDirectorFile, matches, placementsOf, relPath } from './board.mjs'
27
+ import { CompareMetrics, CriticReport, GROSS_FLAGS, normalizeCheck, parseWith } from './contracts.mjs'
28
+ import { methodProblem } from './methods.mjs'
29
+ import { subjectCrops } from './reading.mjs'
30
+ import { PLACEMENTS_SEAM, placementsProbe, stubsLeft } from './seams.mjs'
31
+ import { ownedMarkers } from './taskGate.mjs'
32
+
33
+ const require = createRequire(import.meta.url)
34
+
35
+ /** What each check kind runs and when it passes, for PLAN and for the roles. */
36
+ export const CHECK_CATALOGUE = [
37
+ ['build', '{ id, kind: "build" }', 'nw_check: the game compiles, mounts and runs'],
38
+ ['runtime', '{ id, kind: "runtime" }', 'nw_status twice a second apart: no runtime, material or file errors, and the frame counter moved'],
39
+ ['view', '{ id, kind: "view", cameras: ["player", ...] }', 'nw_view at the named brief cameras: every shot came back and the preview is not frozen'],
40
+ ['compare', '{ id, kind: "compare", camera: "reference" }', "nw_compare at the camera against the reference: no gross flag of the task's own (palette and value far are an artist's, structure and detail far a builder's) that it raised or worsened against the game before it; its pictures and numbers go to the critic (with no reference picture it passes, and the critic judges against the brief)"],
41
+ ['cameras', '{ id, kind: "cameras" }', 'every brief camera is a shot in the blockout\'s report and was shot; the reference camera\'s horizon is within 0.08 of the reference\'s'],
42
+ ['placements', '{ id, kind: "placements" }', 'every placement the blockout declares stands in the running game through place() of src/placements/index.ts (the blockout gets it by default)'],
43
+ ['play', '{ id, kind: "play", steps: [{ goto: "<a placement id or kind in the game>" }, { keys: ["<the key the game reads>"], seconds: 1 }], expect: [{ code: "<an nw_eval expression>", op: "truthy" }] }', 'nw_play with the steps (every goto reached), then each expect read with nw_eval holds'],
44
+ ['eval', '{ id, kind: "eval", code: "<an nw_eval expression>", expect: [{ code: "", op: ">=", value: <the number the brief asks for> }] }', 'nw_eval of code: the one expect holds (op ==, >=, <=, between [lo, hi], truthy)'],
45
+ ['perf', '{ id, kind: "perf" }', 'a 10 s walk: draw calls and triangles within the brief\'s performance tier; on this machine at least 55 fps and no frame over 50 ms'],
46
+ ['asset', '{ id, kind: "asset", path: "assets/<asset>.glb", class: "<its class>", size: { height: <the brief\'s metres> }, hero: false }', 'its ledger entry: made the way its task\'s method says, triangles within the class, size within 5%, measured by nw_blender when made, and at least 3 rounds for a hero (the rubric numbers go to the critic as evidence, judged against this request\'s brief and criteria, never as a pass mark)'],
47
+ ['module', '{ id, kind: "module", path: "src/look/<module>.ts", exports: ["<material code name>"] }', 'the module bundles alone (three, the SDK external) and exports every name'],
48
+ ['palette', '{ id, kind: "palette", files: ["src/look/**"] }', 'at most 2 colour literals in the files off the brief\'s palette and material colours'],
49
+ ['audio', '{ id, kind: "audio", events: ["<brief sound event id>"] }', 'every event renders offline within level, length and click bounds'],
50
+ ['ledger', '{ id, kind: "ledger" }', 'asset_ledger shows no problem for the task\'s files'],
51
+ ['markers', '{ id, kind: "markers" }', 'no DBG or DEBUG marker in the task\'s files (always on)'],
52
+ ['ownership', '{ id, kind: "ownership" }', 'everything the attempt wrote is inside what the task owns (always on)'],
53
+ ]
54
+ export const catalogueText = () => CHECK_CATALOGUE.map(([kind, shape, passes]) => `- ${kind}: ${shape}. Passes when ${passes}.`).join('\n')
55
+
56
+ export { PREVIEW_KINDS }
57
+
58
+ const firstLine = (t) => String(t ?? 'no reason given').split('\n').find((l) => l.trim()) ?? 'no reason given'
59
+ const round2 = (n) => Math.round(n * 100) / 100
60
+ const extOf = (mime) => (mime === 'image/png' ? 'png' : 'jpg')
61
+ const deepEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b)
62
+
63
+ // ---------------------------------------------------------------- whose a pixel flag is
64
+
65
+ /** Whose work each gross flag measures: the look and the materials make the
66
+ * palette and the values; the forms and the framing make the structure and
67
+ * the detail. */
68
+ export const FLAG_OWNERS = { 'palette-far': 'artist', 'value-far': 'artist', 'structure-far': 'builder', 'detail-far': 'builder' }
69
+ /** What each flag measures, larger the further from the reference, and how
70
+ * much it may move between two renders of the same game and still be the
71
+ * same. */
72
+ const FAR = {
73
+ 'palette-far': { of: (m) => Number(m.colour?.paletteDeltaE) || 0, still: 1 },
74
+ 'value-far': { of: (m) => Math.abs(Number(m.colour?.deltaMeanL) || 0), still: 1 },
75
+ 'structure-far': { of: (m) => -(Number(m.structure?.correlation) || 0), still: 0.02 },
76
+ 'detail-far': { of: (m) => Math.abs(Math.log2(Number(m.structure?.edgeRatio) || 1)), still: 0.07 },
77
+ }
78
+ /** Whether a flag is about the task's own work (the final gate's is everything). */
79
+ export const ownsFlag = (task, flag) => task?.id === 'final' || FLAG_OWNERS[flag] === task?.role
80
+
81
+ /**
82
+ * The gross flags a task answers for: those about its own work that it
83
+ * raised, or made worse, against the game before it (`before`: the same
84
+ * camera measured with the task's work taken out; null when that was not
85
+ * measured, and every flag of its own counts). A flag about another role's
86
+ * work is that role's to fix: evidence for the critic and a note to its
87
+ * owner, never the task's failure (post-mortem gap 3).
88
+ */
89
+ export function chargedFlags(task, metrics, before = null) {
90
+ const gross = (metrics?.flags ?? []).filter((f) => GROSS_FLAGS.includes(f))
91
+ return gross.filter((f) => ownsFlag(task, f) && (!before || !(before.flags ?? []).includes(f) || FAR[f].of(metrics) > FAR[f].of(before) + FAR[f].still))
92
+ }
93
+
94
+ /** Whether a value read off the game holds. */
95
+ export function holds(op, got, want) {
96
+ if (op === 'truthy') return !!got
97
+ if (op === '==') return deepEqual(got, want)
98
+ if (op === '>=') return Number(got) >= Number(want)
99
+ if (op === '<=') return Number(got) <= Number(want)
100
+ if (op === 'between') return Array.isArray(want) && Number(got) >= Number(want[0]) && Number(got) <= Number(want[1])
101
+ return false
102
+ }
103
+
104
+ /** CompareMetrics from nw_compare's answer: its `metrics` field, else the
105
+ * JSON after "metrics:" in its text. */
106
+ export function metricsOf(result) {
107
+ const raw = result?.metrics ?? (() => {
108
+ const m = /metrics:\s*(\{[\s\S]*\})/.exec(String(result?.text ?? ''))
109
+ try {
110
+ return m ? JSON.parse(m[1]) : null
111
+ } catch {
112
+ return null
113
+ }
114
+ })()
115
+ const parsed = raw ? parseWith(CompareMetrics, raw) : null
116
+ return parsed?.ok ? parsed.value : null
117
+ }
118
+
119
+ /** A modeller's asset path as nw_blender names its render folder. */
120
+ const stemOf = (rel) => relPath(rel).replace(/^assets\//, '').replace(/\.glb$/i, '').replace(/\//g, '_').replace(/[^A-Za-z0-9._-]/g, '_')
121
+
122
+ /**
123
+ * @param {object} env
124
+ * projectRoot, store, rpc (through the rpc mutex), byName (ToolDefs),
125
+ * roleChecks, critic ({ criticSpec, passes, CRITIC_SCHEMA }), decide
126
+ * (sessions.decide), router, lanes ({ preview: mutex }), laneOf(task),
127
+ * prod() (brief, vision, facts, cameras, board, reference, placed,
128
+ * briefChanges: what the director changed in the brief), ctxFor(task, round),
129
+ * sleep, now, log, stopped() (the production was stopped: no check
130
+ * starts after it), and measureBefore(task, round, measure, tag) (the
131
+ * director's: the game with the task's own work taken out, measured by
132
+ * `measure`, its pictures saved as `tag`, and put back; null when it
133
+ * cannot be).
134
+ */
135
+ export function createGate(env) {
136
+ const { projectRoot, store, rpc, byName, roleChecks = {}, critic, decide, router, lanes, laneOf, prod, ctxFor, sleep, now = Date.now, log, stopped = () => false, measureBefore = null } = env
137
+
138
+ /** Saves a picture under shots/ and answers its project-relative path. */
139
+ async function save(name, image) {
140
+ if (!image?.data) return null
141
+ const rel = `shots/${name}.${extOf(image.mime)}`
142
+ await store.writeBytes(rel, Buffer.from(image.data, 'base64'))
143
+ return store.rel(rel)
144
+ }
145
+
146
+ /** A brief camera as an nw_view shot: the blockout's (or, in a blockout's
147
+ * own task_check, the ones it is about to report), or for the plain views
148
+ * their own camera. A brief camera's aspect (the reference's is the
149
+ * picture's, set by code) is the shot's, whatever the shot says. */
150
+ function shotOf(id, given = null) {
151
+ const cam = (given ?? []).find((c) => c?.id === id && c.shot && typeof c.shot.view === 'string') ?? (prod().cameras ?? []).find((c) => c.id === id)
152
+ const aspect = (prod().brief?.cameras ?? []).find((c) => c.id === id)?.aspect
153
+ if (cam?.shot && typeof cam.shot === 'object' && typeof cam.shot.view === 'string') return aspect ? { ...cam.shot, aspect } : cam.shot
154
+ if (id === 'player' || id === 'overview') return { view: id }
155
+ return null
156
+ }
157
+
158
+ async function view(ids, tag, given = null) {
159
+ const shots = ids.map((id) => ({ id, shot: shotOf(id, given) }))
160
+ const missing = shots.filter((s) => !s.shot).map((s) => s.id)
161
+ const asked = shots.filter((s) => s.shot)
162
+ if (asked.length === 0) return { ok: false, text: `No camera to shoot: ${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} not a shot yet.`, pictures: [], missing }
163
+ // The player camera is the visitor's arrival. A playtest leaves the game
164
+ // where it ended (and a build of unchanged files does not start it
165
+ // again), so a short fresh start comes first: otherwise the critic would
166
+ // judge wherever the last walk stopped.
167
+ if (asked.some((s) => s.shot.view === 'player') && !stopped()) {
168
+ const fresh = playParams({ steps: [{ keys: [], seconds: 0.5 }], frames: 0 })
169
+ if (fresh.ok) await rpc('play', fresh.params, 30_000).catch(() => null)
170
+ }
171
+ const r = await rpc('view', { shots: asked.map((s) => s.shot) }, 15_000 + 3_000 * asked.length)
172
+ if (!r?.ok || !Array.isArray(r.shots)) return { ok: false, text: `No pictures: ${r?.error ?? 'the preview did not answer.'}`, pictures: [], missing }
173
+ const pictures = []
174
+ const lost = []
175
+ for (let i = 0; i < asked.length; i++) {
176
+ const s = r.shots[i]
177
+ if (!s?.ok || !s.image?.data) lost.push(`${asked[i].id}: ${s?.error ?? 'nothing came back'}`)
178
+ else pictures.push({ camera: asked[i].id, image: { data: s.image.data, mime: s.image.mime ?? 'image/jpeg' }, path: await save(`${tag}-${asked[i].id}`, s.image), frame: s.frame })
179
+ }
180
+ const frozen = r.frozen ? `The preview is frozen (no frame for ${(r.frozen.msSinceLast / 1000).toFixed(1)} s).` : null
181
+ const ok = lost.length === 0 && missing.length === 0 && !frozen
182
+ const text = ok ? `${pictures.length} shot${pictures.length === 1 ? '' : 's'}: ${pictures.map((p) => p.camera).join(', ')}.` : [frozen, lost.length ? `Missing: ${lost.join('; ')}.` : null, missing.length ? `Not a shot yet: ${missing.join(', ')}.` : null].filter(Boolean).join(' ')
183
+ return { ok, text, pictures, missing }
184
+ }
185
+
186
+ /** nw_compare at a camera, through its ToolDef; `shot` stands for the
187
+ * camera's when the production does not have it yet. */
188
+ async function compare(task, round, camera, tag, shot = null) {
189
+ const def = byName.get('nw_compare')
190
+ const p = prod()
191
+ if (!def) return { ok: false, text: 'nw_compare is not in this build, so nothing could be compared.', metrics: null, pictures: [] }
192
+ // A request without a picture has nothing to be close to: the critic
193
+ // judges the shots against the brief alone.
194
+ if (!p.reference) return { ok: true, text: 'No reference picture: nothing to compare; the critic judges against the brief.', metrics: null, pictures: [] }
195
+ const args = { reference: p.reference.rel, camera: shot ?? camera, ...(p.reference.crop ? { crop: p.reference.crop } : {}) }
196
+ const result = await runDef(def, args, ctxFor(task, round))
197
+ if (result.isError) return { ok: false, text: firstLine(result.text), metrics: null, pictures: [] }
198
+ const metrics = metricsOf(result)
199
+ const pictures = []
200
+ for (const [i, image] of (result.images ?? []).entries()) {
201
+ pictures.push({ camera: i === 0 ? `${camera}-side` : camera, image, path: await save(`${tag}-${camera}${i === 0 ? '-side' : ''}`, image) })
202
+ }
203
+ if (!metrics) return { ok: false, text: 'nw_compare gave no metrics.', metrics: null, pictures }
204
+ const gross = metrics.flags.filter((f) => GROSS_FLAGS.includes(f))
205
+ return {
206
+ ok: gross.length === 0,
207
+ text: gross.length ? `Far from the reference at ${camera}: ${gross.join(', ')} (distance ${round2(metrics.distance)}).` : `Close enough to judge at ${camera} (distance ${round2(metrics.distance)}).`,
208
+ metrics,
209
+ pictures,
210
+ }
211
+ }
212
+
213
+ async function status() {
214
+ const r = await rpc('status', {}, 10_000)
215
+ return r && typeof r === 'object' ? r : {}
216
+ }
217
+
218
+ /**
219
+ * A compare check's verdict: only a gross flag the task answers for fails
220
+ * it (chargedFlags). With `attribute` (the director's gate), a flag of the
221
+ * task's own is measured against the game with the task's work taken
222
+ * out, so a flag that was there before it and is no worse is not its;
223
+ * task_check, inside the session, counts every flag of its own.
224
+ */
225
+ async function compareVerdict(task, round, check, tag, attribute) {
226
+ const r = await compare(task, round, check.camera, tag)
227
+ if (!r.metrics) return { ...r, charged: [], others: [] }
228
+ const gross = r.metrics.flags.filter((f) => GROSS_FLAGS.includes(f))
229
+ const own = gross.filter((f) => ownsFlag(task, f))
230
+ let before = null
231
+ if (attribute && own.length && typeof measureBefore === 'function' && !stopped()) {
232
+ before = await measureBefore(task, round, () => compare(task, round, check.camera, `${tag}-before`).then((x) => x.metrics), `${tag}-before`).catch(() => null)
233
+ }
234
+ const charged = chargedFlags(task, r.metrics, before)
235
+ const others = gross.filter((f) => !ownsFlag(task, f)).map((flag) => ({ flag, owner: FLAG_OWNERS[flag] }))
236
+ const was = own.filter((f) => !charged.includes(f))
237
+ const d = `distance ${round2(r.metrics.distance)}`
238
+ const notes = [
239
+ others.length ? `${others.map((o) => o.flag).join(', ')} ${others.length === 1 ? 'is' : 'are'} about ${[...new Set(others.map((o) => `the ${o.owner}'s work`))].join(' and ')}, not this task's: evidence for the critic and a note to its owner.` : '',
240
+ was.length ? `${was.join(', ')} ${was.length === 1 ? 'was' : 'were'} there before this task and ${was.length === 1 ? 'is' : 'are'} no worse.` : '',
241
+ ].filter(Boolean)
242
+ const text = charged.length ? `Far from the reference at ${check.camera}: ${charged.join(', ')} (${d}).${!attribute && own.length ? ' The gate measures the game without your work too, so a flag that was there before and is no worse is not yours.' : ''}` : `Close enough to judge at ${check.camera} (${d}).`
243
+ return { ...r, ok: charged.length === 0, text: [text, ...notes].join(' '), charged, others, before }
244
+ }
245
+
246
+ /** One check of a task. */
247
+ async function runOne(task, round, raw, { writes, tag, cameras = null, attribute = false }) {
248
+ const check = normalizeCheck(raw)
249
+ const base = { id: check.id, kind: check.kind }
250
+ const done = (ok, text, extra = {}) => ({ ...base, ok, text, evidence: { images: (extra.pictures ?? []).map((p) => p.path).filter(Boolean), ...(extra.numbers ? { numbers: extra.numbers } : {}) }, pictures: extra.pictures ?? [], metrics: extra.metrics ?? null, ...(extra.charged ? { charged: extra.charged, others: extra.others } : {}) })
251
+ const owns = (task.owns ?? []).map(relPath)
252
+ const p = prod()
253
+ switch (check.kind) {
254
+ case 'build': {
255
+ const r = await rpc('build', {}, 120_000)
256
+ if (!r?.ok) return done(false, `The build failed: ${firstLine(r?.error)}`)
257
+ if (r.ran === false) return done(false, `It compiles but has not run: ${firstLine(r.note ?? 'the preview held it')}`)
258
+ return done(true, 'It compiles, mounts and runs.')
259
+ }
260
+ case 'runtime': {
261
+ const a = await status()
262
+ await sleep(1000)
263
+ const b = await status()
264
+ const errors = b.runtime?.errors ?? []
265
+ const live = b.live
266
+ if (!live) return done(false, `No live numbers: ${b.liveError ?? 'the preview did not answer'}.`)
267
+ const materials = live.materials?.errors ?? []
268
+ const files = live.assets ?? []
269
+ const moved = Number(live.frame?.frame) > Number(a.live?.frame?.frame)
270
+ const bad = [
271
+ errors.length ? `runtime errors: ${errors.slice(0, 3).map(firstLine).join('; ')}` : null,
272
+ materials.length ? `materials that failed: ${materials.slice(0, 3).join('; ')}` : null,
273
+ files.length ? `files that failed: ${files.slice(0, 3).map((f) => f.path ?? f).join(', ')}` : null,
274
+ moved ? null : 'the frame counter did not move',
275
+ ].filter(Boolean)
276
+ return done(bad.length === 0, bad.length ? `It does not run clean: ${bad.join('; ')}.` : `It runs clean at ${round2(Number(live.frame?.fps) || 0)} fps.`, { numbers: { fps: live.frame?.fps ?? null, frame: live.frame?.frame ?? null } })
277
+ }
278
+ case 'view': {
279
+ const r = await view(check.cameras ?? [], tag, cameras)
280
+ return done(r.ok, r.text, { pictures: r.pictures })
281
+ }
282
+ case 'compare': {
283
+ const r = await compareVerdict(task, round, check, tag, attribute)
284
+ const numbers = r.metrics ? { distance: r.metrics.distance, flags: r.metrics.flags, ...(r.charged.length !== r.metrics.flags.filter((f) => GROSS_FLAGS.includes(f)).length ? { charged: r.charged } : {}), ...(r.before ? { before: { distance: r.before.distance, flags: r.before.flags } } : {}) } : undefined
285
+ return done(r.ok, r.text, { pictures: r.pictures, metrics: r.metrics, numbers, charged: r.charged, others: r.others })
286
+ }
287
+ case 'cameras': {
288
+ const ids = (p.brief?.cameras ?? []).map((c) => c.id)
289
+ const r = await view(ids, tag, cameras)
290
+ let text = r.text
291
+ let ok = r.ok
292
+ const refCam = (p.brief?.cameras ?? []).find((c) => c.purpose === 'reference')
293
+ const horizon = p.facts?.horizon
294
+ if (ok && refCam && horizon && horizon.y !== null && horizon.confidence >= CONFIDENT && byName.get('nw_compare')) {
295
+ const c = await compare(task, round, refCam.id, `${tag}-horizon`, shotOf(refCam.id, cameras))
296
+ const delta = c.metrics?.structure?.horizonDelta
297
+ if (typeof delta === 'number' && Math.abs(delta) > 0.08) {
298
+ ok = false
299
+ text += ` The ${refCam.id} camera's horizon is ${round2(Math.abs(delta))} of the frame from the reference's (at most 0.08).`
300
+ }
301
+ }
302
+ return done(ok, text, { pictures: r.pictures })
303
+ }
304
+ case 'placements': {
305
+ // The blockout's stand-ins, each through the seam's place(), so the
306
+ // director can put a made model in at its placement.
307
+ const ids = placementsOf(p.board).map((x) => x.id)
308
+ if (ids.length === 0) return done(true, 'The board declares no placements.')
309
+ const v = await rpc('eval', { code: placementsProbe(ids), timeoutMs: 2000 }, 12_000)
310
+ if (!v?.ok) return done(false, `nw_eval failed: ${firstLine(v?.error)}`)
311
+ if (v.value === true) return done(true, `Every placement stands through place() of ${PLACEMENTS_SEAM}: ${ids.join(', ')}.`)
312
+ const missing = Array.isArray(v.value?.missing) ? v.value.missing : ids
313
+ return done(false, `Not added through place() of ${PLACEMENTS_SEAM}: ${missing.join(', ')}. Add the stand-in of each with place(ctx, world, '<placement id>', standIn, opts) where the code calls world.add now.`)
314
+ }
315
+ case 'play': {
316
+ const params = playParams({ steps: check.steps ?? [], frames: 2 })
317
+ if (!params.ok) return done(false, `The steps are not a playtest: ${params.error}`)
318
+ const total = params.params.steps.reduce((s, x) => s + x.seconds, 0)
319
+ const r = await rpc('play', params.params, (total + 45) * 1000)
320
+ if (!r?.ok) return done(false, `The playtest did not run: ${firstLine(r?.error)}`)
321
+ if (r.skipped) return done(false, `The playtest did not run: ${firstLine(r.note)}`)
322
+ const walks = (r.goto ?? []).filter((w) => w.outcome !== 'reached' && w.outcome !== 'gone')
323
+ const misses = []
324
+ for (const e of check.expect ?? []) {
325
+ const v = await rpc('eval', { code: e.code, timeoutMs: 2000 }, 12_000)
326
+ if (!v?.ok) misses.push(`${e.code}: ${firstLine(v?.error)}`)
327
+ else if (!holds(e.op, v.value, e.value)) misses.push(`${e.code} is ${JSON.stringify(v.value)}, not ${e.op} ${JSON.stringify(e.value ?? '')}`.trim())
328
+ }
329
+ const pictures = []
330
+ for (const [i, f] of (r.frames ?? []).entries()) if (f.image) pictures.push({ camera: `play${i + 1}`, image: f.image, path: await save(`${tag}-${check.id}-${i + 1}`, f.image) })
331
+ const bad = [...walks.map((w) => `walk to ${w.target}: ${w.outcome}`), ...misses]
332
+ return done(bad.length === 0, bad.length ? `The playtest failed: ${bad.join('; ')}.` : `The playtest passed (${(check.expect ?? []).length} expects).`, { pictures, numbers: { fps: r.fps?.avg ?? null } })
333
+ }
334
+ case 'eval': {
335
+ const e = check.expect?.[0]
336
+ const v = await rpc('eval', { code: check.code, timeoutMs: 2000 }, 12_000)
337
+ if (!v?.ok) return done(false, `nw_eval failed: ${firstLine(v?.error)}`)
338
+ const ok = e ? holds(e.op, v.value, e.value) : !!v.value
339
+ return done(ok, ok ? `${check.code} holds.` : `${check.code} is ${JSON.stringify(v.value)}, not ${e?.op ?? 'truthy'} ${JSON.stringify(e?.value ?? '')}.`)
340
+ }
341
+ case 'perf': {
342
+ const params = playParams({ steps: [{ keys: ['KeyW'], seconds: 10, look: { yaw: 60 } }], frames: 0 })
343
+ const r = await rpc('play', params.params, 60_000)
344
+ if (!r?.ok || r.skipped) return done(false, `The walk did not run: ${firstLine(r?.error ?? r?.note)}`)
345
+ const info = await rpc('eval', { code: 'const r = renderer.info.render; return { drawCalls: r.drawCalls ?? r.calls ?? 0, triangles: r.triangles ?? 0 }', timeoutMs: 2000 }, 12_000)
346
+ const tier = p.brief?.performance ?? { drawCalls: 150, triangles: 500_000 }
347
+ const calls = Number(info?.value?.drawCalls)
348
+ const tris = Number(info?.value?.triangles)
349
+ const bad = []
350
+ if (!info?.ok) bad.push(`the renderer's numbers could not be read (${firstLine(info?.error)})`)
351
+ else {
352
+ if (calls > tier.drawCalls) bad.push(`${calls} draw calls, over the ${tier.drawCalls} of the ${tier.tier ?? 'low'} tier`)
353
+ if (tris > tier.triangles) bad.push(`${tris} triangles, over the ${tier.triangles}`)
354
+ }
355
+ // A playtest starts a fresh game, whose first frames build its
356
+ // materials: the frame rate after its first second is the one held to
357
+ // the proxy (a page from before reports only the whole run's).
358
+ const fps = r.fpsSteady ?? r.fps
359
+ if (Number(fps?.avg) < 55) bad.push(`${round2(Number(fps?.avg))} fps on average here (at least 55)`)
360
+ if (Number(fps?.longestFrameMs) > 50) bad.push(`a ${Math.round(fps.longestFrameMs)} ms frame (at most 50)`)
361
+ return done(bad.length === 0, bad.length ? `Too heavy: ${bad.join('; ')}.` : `Within the ${tier.tier ?? 'low'} tier: ${calls} draw calls, ${tris} triangles, ${round2(Number(fps?.avg))} fps.`, { numbers: { drawCalls: calls, triangles: tris, fps: fps?.avg ?? null, longestFrameMs: fps?.longestFrameMs ?? null, startLongestFrameMs: r.fps?.longestFrameMs ?? null } })
362
+ }
363
+ case 'asset':
364
+ return done(...(await assetCheck(check, tag, task)))
365
+ case 'module': {
366
+ let esbuild
367
+ try {
368
+ esbuild = require('esbuild')
369
+ } catch {
370
+ return done(false, 'esbuild is not there, so the module could not be bundled.')
371
+ }
372
+ try {
373
+ const r = await esbuild.build({
374
+ entryPoints: [path.join(projectRoot, check.path)],
375
+ bundle: true,
376
+ write: false,
377
+ format: 'esm',
378
+ platform: 'browser',
379
+ metafile: true,
380
+ logLevel: 'silent',
381
+ external: ['three', 'three/*', '@nowhere/sdk'],
382
+ })
383
+ const out = Object.values(r.metafile.outputs)[0]
384
+ const missing = (check.exports ?? []).filter((n) => !(out?.exports ?? []).includes(n))
385
+ return done(missing.length === 0, missing.length ? `${check.path} builds but does not export ${missing.join(', ')}.` : `${check.path} builds alone and exports ${(check.exports ?? []).join(', ')}.`)
386
+ } catch (err) {
387
+ return done(false, `${check.path} does not build alone: ${firstLine(err?.errors?.[0]?.text ?? err?.message)}`)
388
+ }
389
+ }
390
+ case 'palette':
391
+ case 'audio': {
392
+ const fn = roleChecks[check.kind]
393
+ if (typeof fn !== 'function') return done(false, `The ${check.kind} check is not in this build.`)
394
+ try {
395
+ const r = await fn(check, ctxFor(task, round))
396
+ return done(r?.ok === true, String(r?.text ?? (r?.ok ? 'It passed.' : 'It failed.')), { numbers: r?.evidence?.numbers })
397
+ } catch (err) {
398
+ return done(false, `The ${check.kind} check could not run: ${firstLine(err?.message ?? err)}`)
399
+ }
400
+ }
401
+ case 'ledger': {
402
+ const problems = (await ledgerProblems(projectRoot).catch(() => [])).filter((x) => !x.path || owns.some((g) => matches(g, x.path)))
403
+ return done(problems.length === 0, problems.length ? `The asset ledger has problems: ${problems.slice(0, 4).map((x) => x.message).join(' ')}` : 'The asset ledger has no problem with these files.')
404
+ }
405
+ case 'markers': {
406
+ const left = await ownedMarkers(projectRoot, owns)
407
+ return done(left.length === 0, left.length ? `Debug code is left at ${left.slice(0, 6).map((m) => `${m.file}:${m.line}`).join(', ')}.` : 'No debug markers.')
408
+ }
409
+ case 'ownership': {
410
+ const outside = [...(writes ?? [])].filter((rel) => isDirectorFile(rel) || !owns.some((g) => matches(g, rel)))
411
+ return done(outside.length === 0, outside.length ? `It wrote outside what the task owns: ${outside.join(', ')}.` : 'Everything it wrote is its own.')
412
+ }
413
+ case 'seams': {
414
+ const left = await stubsLeft(projectRoot)
415
+ const standing = placementsOf(p.board).filter((x) => !p.placed?.[x.id]).map((x) => x.id)
416
+ const named = left.map((rel) => (rel === PLACEMENTS_SEAM && standing.length ? `${rel} (stand-ins at ${standing.join(', ')})` : rel))
417
+ return done(left.length === 0, left.length ? `Still a placeholder: ${named.join(', ')}.` : 'Every seam is its module.')
418
+ }
419
+ case 'coverage': {
420
+ // A kept task's work is in the game, below the critic's bar: it
421
+ // covers what it was for, and the outcome says it was kept.
422
+ const inGame = (p.board?.tasks ?? []).filter((t) => DONE.has(t.status))
423
+ const covered = new Set(inGame.flatMap((t) => t.covers ?? []))
424
+ const want = [...(p.brief?.requestElements ?? []).map((e) => e.id), ...(p.vision?.moments ?? []).map((m) => m.id)]
425
+ const missing = want.filter((id) => !covered.has(id))
426
+ return done(missing.length === 0, missing.length ? `Not covered by a task whose work is in the game: ${missing.join(', ')}.` : `Every request element and moment is covered (${want.length}).`)
427
+ }
428
+ default:
429
+ return done(false, `The check kind "${check.kind}" is not one the gate knows.`)
430
+ }
431
+ }
432
+
433
+ /** The asset check: the ledger entry nw_blender or asset_import wrote, the
434
+ * rounds it took, that it was made the way its task's method says, and
435
+ * the newest contact sheets as evidence, with the pictures it was made
436
+ * from (the reference's crop, the views generated for it). */
437
+ async function assetCheck(check, tag, task = null) {
438
+ const rel = relPath(check.path)
439
+ const { lock } = await readLedgerState(projectRoot)
440
+ const entry = lock.files?.[rel]
441
+ if (!entry) return [false, `${rel} is not in assets.lock.json: it was never exported or imported.`]
442
+ if (!fs.existsSync(path.join(projectRoot, rel))) return [false, `${rel} is in the ledger but not on disk.`]
443
+ const meta = entry.meta ?? {}
444
+ const bad = []
445
+ const madeOtherwise = methodProblem(task?.method ?? null, rel, entry, lock)
446
+ if (madeOtherwise) bad.push(madeOtherwise)
447
+ const budget = TRIANGLE_BUDGETS[check.class] ?? TRIANGLE_BUDGETS.prop
448
+ if (Number.isFinite(meta.triangles) && meta.triangles > budget) bad.push(`${meta.triangles} triangles, over the ${budget} of a ${check.class}`)
449
+ const size = meta.size_m ?? null
450
+ for (const k of ['height', 'width', 'depth']) {
451
+ const want = Number(check.size?.[k])
452
+ if (!(want > 0)) continue
453
+ const got = Number(size?.[k])
454
+ if (!(got > 0)) bad.push(`its ${k} is not known`)
455
+ else if (Math.abs(got - want) / want > 0.05) bad.push(`${k} ${round2(got)} m, not ${want} m (within 5%)`)
456
+ }
457
+ // The rubric measures (colours, razor edges, outline, triangles); it does
458
+ // not pass or fail. One colour is right for a one-colour brief and razor
459
+ // edges for a faceted one, so the numbers go to the critic as evidence
460
+ // and the hard checks stay the class budget, the size and the rounds.
461
+ if (entry.origin === 'made' && !meta.rubric) bad.push('not measured yet (render it with nw_blender)')
462
+ let rounds = null
463
+ try {
464
+ rounds = JSON.parse(await fsp.readFile(path.join(projectRoot, '.nowhere', 'renders', `${stemOf(rel)}.rounds.json`), 'utf8')).round ?? null
465
+ } catch {
466
+ rounds = null
467
+ }
468
+ if (check.hero && entry.origin === 'made' && !(rounds >= 3)) bad.push(`${rounds ?? 0} rounds; a hero takes at least 3`)
469
+ const pictures = []
470
+ const dir = path.join(projectRoot, '.nowhere', 'renders', stemOf(rel))
471
+ try {
472
+ const latest = (await fsp.readdir(dir)).filter((n) => /^\d{8}-\d{6}/.test(n)).sort().at(-1)
473
+ if (latest) {
474
+ for (const name of (await fsp.readdir(path.join(dir, latest))).filter((n) => /(color|colour|clay).*\.(jpe?g|png)$/i.test(n)).sort()) {
475
+ const bytes = await fsp.readFile(path.join(dir, latest, name))
476
+ const image = { data: bytes.toString('base64'), mime: /\.png$/i.test(name) ? 'image/png' : 'image/jpeg' }
477
+ pictures.push({ camera: /clay/i.test(name) ? 'clay' : 'colour', image, path: await save(`${tag}-${/clay/i.test(name) ? 'clay' : 'colour'}`, image) })
478
+ }
479
+ }
480
+ } catch {
481
+ // no renders: an imported asset, or one never rendered
482
+ }
483
+ // What it was made from, seen beside it.
484
+ const inputs = (Array.isArray(meta.provenance?.inputs) ? meta.provenance.inputs : []).slice(0, 2)
485
+ for (const [k, i] of inputs.entries()) {
486
+ try {
487
+ const bytes = await fsp.readFile(path.join(projectRoot, i.path))
488
+ const image = { data: bytes.toString('base64'), mime: /\.png$/i.test(i.path) ? 'image/png' : 'image/jpeg' }
489
+ const what = i.subject ? `the reference's crop of ${i.subject}` : i.vendor ? `a picture ${i.vendor} made for it` : i.path
490
+ pictures.push({ camera: `input-${k + 1}`, input: what, image, path: await save(`${tag}-input-${k + 1}`, image) })
491
+ } catch {
492
+ // a picture that is gone is named in the numbers
493
+ }
494
+ }
495
+ const numbers = { triangles: meta.triangles ?? null, rounds, size: size ?? null, rubric: meta.rubric ?? null, ...(inputs.length ? { madeFrom: inputs.map((i) => i.path) } : {}), ...(meta.cleanup ? { cleanup: meta.cleanup } : {}) }
496
+ return [bad.length === 0, bad.length ? `${rel}: ${bad.join('; ')}.` : `${rel} is within its class and size${rounds ? `, ${rounds} rounds` : ''}.`, { pictures, numbers }]
497
+ }
498
+
499
+ /**
500
+ * The task's tool checks, in the board's order, but build and runtime
501
+ * first when any check looks at the preview: the view, play and perf
502
+ * kinds judge whatever was mounted last, so the game is built from the
503
+ * files as they are before anything looks at it. The preview kinds wait
504
+ * for the preview lane unless the task's own lane is the preview (its
505
+ * worker holds it already). After a Stop no check starts: those left
506
+ * answer stopped. `attribute` (the director's gate, not task_check)
507
+ * measures a compare flag of the task's own against the game before it.
508
+ */
509
+ async function runChecks(task, round, { writes = [], tag = `${task.id}-r${round}`, checks: given = task.accept?.checks ?? [], holdsPreview = laneOf(task) === 'preview', cameras = null, attribute = false } = {}) {
510
+ const kindOf = (c) => normalizeCheck(c)?.kind
511
+ const looks = given.some((c) => PREVIEW_KINDS.has(kindOf(c)) && !['build', 'runtime'].includes(kindOf(c)))
512
+ const checks = looks ? [...given.filter((c) => kindOf(c) === 'build'), ...given.filter((c) => kindOf(c) === 'runtime'), ...given.filter((c) => !['build', 'runtime'].includes(kindOf(c)))] : given
513
+ const out = []
514
+ for (const c of checks) {
515
+ const kind = kindOf(c)
516
+ if (stopped()) {
517
+ out.push({ id: c.id, kind, ok: false, text: 'stopped', evidence: { inline: [] }, pictures: [], metrics: null })
518
+ continue
519
+ }
520
+ const go = () => runOne(task, round, c, { writes, tag, cameras, attribute })
521
+ let r
522
+ try {
523
+ r = PREVIEW_KINDS.has(kind) && !holdsPreview ? await lanes.preview.run(go) : await go()
524
+ } catch (err) {
525
+ r = { id: c.id, kind, ok: false, text: `The check could not run: ${firstLine(err?.message ?? err)}`, evidence: {}, pictures: [], metrics: null }
526
+ }
527
+ // task_check's answer carries the pictures inline.
528
+ r.evidence.inline = (r.pictures ?? []).slice(0, 4).map((p) => p.image)
529
+ out.push(r)
530
+ }
531
+ return out
532
+ }
533
+
534
+ /** Reads a saved picture back for the critic. */
535
+ async function pictureAt(rel) {
536
+ if (!rel) return null
537
+ try {
538
+ const bytes = await fsp.readFile(path.join(projectRoot, rel))
539
+ return { data: bytes.toString('base64'), mime: /\.png$/i.test(rel) ? 'image/png' : 'image/jpeg' }
540
+ } catch {
541
+ return null
542
+ }
543
+ }
544
+
545
+ /** Whether the critic of a task is stuck: its pairwise calls flip, or it
546
+ * says "same" twice while the pixels moved by more than 0.05. */
547
+ function stuckOf(history) {
548
+ const gates = history.map((a) => a.gate).filter((g) => g?.critic)
549
+ if (gates.length < 2) return false
550
+ const [a, b] = gates.slice(-2)
551
+ if (a.critic.pairwise === 'better' && b.critic.pairwise === 'worse') return true
552
+ if (a.critic.pairwise === 'same' && b.critic.pairwise === 'same' && a.metrics && b.metrics && Math.abs(a.metrics.distance - b.metrics.distance) > 0.05) return true
553
+ return false
554
+ }
555
+
556
+ /** The best attempt so far: tool checks passed, the critic's highest overall, then the smaller pixel distance. */
557
+ function bestOf(history) {
558
+ const judged = history.filter((a) => a.gate && a.gate.checks.every((c) => c.ok) && a.gate.critic)
559
+ if (judged.length === 0) return null
560
+ return judged.reduce((best, a) => {
561
+ const d = (x) => x.gate.metrics?.distance ?? Infinity
562
+ if (a.gate.critic.overall > best.gate.critic.overall) return a
563
+ if (a.gate.critic.overall === best.gate.critic.overall && d(a) < d(best)) return a
564
+ return best
565
+ })
566
+ }
567
+
568
+ /** The reference's crops of the subjects a judgement names (the criteria's,
569
+ * or for the whole game its subjects in the game), at most `most`. */
570
+ const crops = new Map()
571
+ async function subjectsFor(ids, most) {
572
+ const p = prod()
573
+ const subjects = p.brief?.subjects ?? []
574
+ const want = [...new Set(ids)].filter((id) => subjects.some((s) => s.id === id)).slice(0, most)
575
+ if (!p.reference?.image || !want.length) return []
576
+ const out = []
577
+ for (const id of want) {
578
+ const s = subjects.find((x) => x.id === id)
579
+ const key = `${id}:${JSON.stringify(s.box)}`
580
+ if (!crops.has(key)) crops.set(key, (await subjectCrops(p.reference.image, subjects, [id], p.reference.crop ?? null).catch(() => []))[0] ?? null)
581
+ if (crops.get(key)) out.push(crops.get(key))
582
+ }
583
+ return out
584
+ }
585
+
586
+ /**
587
+ * The critic on one attempt (or on the whole game when task is the final
588
+ * gate's). Returns { report } or { error }.
589
+ */
590
+ async function critique({ task, round, scope, shots, sideBySide, best, metrics, flags, criteria, history = [], inputs = [] }) {
591
+ const p = prod()
592
+ if (typeof critic?.criticSpec !== 'function') return { error: 'The critic is not in this build.' }
593
+ const key = scope === 'final' ? `critic:final:r${round}` : `critic:${task.id}:r${round}`
594
+ const named = scope === 'final' ? (p.brief?.subjects ?? []).filter((s) => s.kind !== 'atmosphere').map((s) => s.id) : criteria.map((c) => c.subject).filter(Boolean)
595
+ const subjects = await subjectsFor(named, scope === 'final' ? 4 : 2)
596
+ const input = {
597
+ scope,
598
+ key,
599
+ task: { id: task.id, role: task.role, title: task.title, goal: task.goal, covers: task.covers ?? [] },
600
+ round,
601
+ reference: p.reference?.image ?? null,
602
+ shots: shots.slice(0, scope === 'final' ? 8 : 4),
603
+ sideBySide: sideBySide ?? null,
604
+ best: best ?? null,
605
+ brief: JSON.stringify(p.brief ?? {}, null, 1),
606
+ pillars: p.vision?.pillars ?? [],
607
+ moments: (p.vision?.moments ?? []).filter((m) => scope === 'final' || (task.covers ?? []).includes(m.id)),
608
+ criteria,
609
+ metrics: metrics ?? null,
610
+ flags: flags ?? [],
611
+ locale: p.locale ?? 'en',
612
+ ...(subjects.length ? { subjects } : {}),
613
+ ...(inputs.length ? { inputs: inputs.slice(0, 2) } : {}),
614
+ ...(p.briefChanges?.length ? { briefChanges: p.briefChanges.slice(-8) } : {}),
615
+ }
616
+ let spec
617
+ try {
618
+ spec = critic.criticSpec(input)
619
+ } catch (err) {
620
+ return { error: `The critic's prompt could not be built: ${firstLine(err?.message ?? err)}` }
621
+ }
622
+ const pick = router.decision('critic', { stuck: stuckOf(history) })
623
+ const r = await decide({ key, role: 'critic', task: scope === 'final' ? null : task.id, systemPrompt: spec.systemPrompt, userText: spec.userText, images: spec.images ?? [], schema: CriticReport, jsonSchema: spec.schema ?? critic.CRITIC_SCHEMA, pick, timeoutMs: (env.limits?.decisionMinutes ?? 15) * 60_000 })
624
+ if (!r.ok) return { error: `The critic did not answer: ${r.errors.join('; ')}`, pick, stopped: r.stopped }
625
+ return { report: r.value, pick }
626
+ }
627
+
628
+ /** The shots the critic sees for a task: the contact sheets for a
629
+ * modeller, else the views at its cameras, criteria cameras first. */
630
+ function criticShots(task, checks) {
631
+ const all = checks.flatMap((c) => (c.pictures ?? []).map((p) => ({ ...p, kind: c.kind })))
632
+ if (task.role === 'modeller') return all.filter((p) => p.kind === 'asset' && !p.input).map(({ camera, image }) => ({ camera, image }))
633
+ const wanted = new Set((task.accept?.critic ?? []).map((c) => c.camera).filter(Boolean))
634
+ const views = all.filter((p) => (p.kind === 'view' || p.kind === 'cameras' || p.kind === 'compare') && !String(p.camera).endsWith('-side'))
635
+ return [...views.filter((p) => wanted.has(p.camera)), ...views.filter((p) => !wanted.has(p.camera))].map(({ camera, image }) => ({ camera, image }))
636
+ }
637
+
638
+ /** The progress of an attempt against the one before it, for the router. */
639
+ function progressOf({ prev, failedNow, critic: report, metrics }) {
640
+ if (!prev) return 'first'
641
+ const failedBefore = prev.checks.filter((c) => !c.ok).length + (prev.noReport ? 1 : 0)
642
+ if (!report) return failedNow < failedBefore ? 'better' : failedNow > failedBefore ? 'worse' : 'same'
643
+ // A first judgement after a measured fix of the tool checks is progress.
644
+ if (report.pairwise === 'first') return failedNow < failedBefore ? 'better' : 'same'
645
+ if (report.pairwise === 'better' && failedNow <= failedBefore) return 'better'
646
+ if (report.pairwise === 'worse') return 'worse'
647
+ if (report.pairwise === 'same') {
648
+ const stagnant = env.policy?.rules?.stagnantDistance ?? 0.02
649
+ if (metrics && prev.metrics) return Math.abs(metrics.distance - prev.metrics.distance) < stagnant ? 'stagnant' : 'same'
650
+ if (!metrics && prev.critic?.pairwise === 'same') return 'stagnant'
651
+ }
652
+ return 'same'
653
+ }
654
+
655
+ /**
656
+ * The gate of one attempt: its tool checks, then the critic, then pass,
657
+ * progress and best. `attempt` is the attempt just run; `history` the
658
+ * task's earlier attempts (with their gates).
659
+ */
660
+ async function judge(task, attempt, history = []) {
661
+ const t0 = now()
662
+ const round = attempt.round
663
+ const checks = await runChecks(task, round, { writes: attempt.writes, attribute: true })
664
+ const failedTools = checks.filter((c) => !c.ok)
665
+ const noReport = !attempt.report
666
+ const compared = checks.find((c) => c.kind === 'compare' && c.metrics)
667
+ const metrics = compared?.metrics ?? null
668
+ const flags = metrics?.flags ?? []
669
+ // The flags this task answers for decide its pass; the others are
670
+ // another role's, which the critic sees named as theirs.
671
+ const charged = compared?.charged ?? flags
672
+ const outOfScope = compared?.others ?? []
673
+ const flagWords = flags.map((f) => (charged.includes(f) ? f : outOfScope.some((o) => o.flag === f) ? `${f} (the ${FLAG_OWNERS[f]}'s work, not this task's)` : `${f} (there before this task, no worse)`))
674
+ let report = null
675
+ let criticError = null
676
+ let pass = failedTools.length === 0 && !noReport
677
+ const criteria = task.accept?.critic ?? []
678
+ if (task.role === 'qa') {
679
+ const qa = attempt.report
680
+ const ran = new Set((qa?.results ?? []).map((r) => r.script))
681
+ const missing = (qa?.scripts ?? []).filter((s) => !ran.has(s.id)).map((s) => s.id)
682
+ if (qa && missing.length) checks.push({ id: 'qa-results', kind: 'qa', ok: false, text: `No result for ${missing.join(', ')}.`, evidence: {}, pictures: [] })
683
+ pass = pass && !!qa && missing.length === 0 && (qa.scripts ?? []).length > 0
684
+ } else if (pass && criteria.length > 0) {
685
+ const prevBest = bestOf(history)
686
+ const bestShot = prevBest ? await pictureAt(bestPicturePath(prevBest, task)) : null
687
+ const shots = criticShots(task, checks)
688
+ const sideBySide = compared?.pictures?.find((p) => String(p.camera).endsWith('-side'))?.image ?? null
689
+ const inputs = checks.flatMap((c) => (c.pictures ?? []).filter((p) => p.input).map((p) => ({ what: p.input, image: p.image })))
690
+ const r = await critique({ task, round, scope: 'task', shots, sideBySide, best: bestShot, metrics, flags: flagWords, criteria, history, inputs })
691
+ if (r.report) {
692
+ report = r.report
693
+ let ok = false
694
+ try {
695
+ ok = critic.passes(report, metrics ? { ...metrics, flags: charged } : null, task) === true
696
+ } catch (err) {
697
+ log(`[director] the critic's pass rule failed: ${err?.message ?? err}`)
698
+ }
699
+ pass = ok
700
+ } else {
701
+ criticError = r.error
702
+ pass = false
703
+ }
704
+ }
705
+ const prev = history.at(-1)?.gate ?? null
706
+ const progress = progressOf({ prev, failedNow: failedTools.length + (noReport ? 1 : 0), critic: report, metrics })
707
+ const bestBefore = bestOf(history)
708
+ const isBest = !!report && failedTools.length === 0 && (!bestBefore || report.overall > bestBefore.gate.critic.overall || (report.overall === bestBefore.gate.critic.overall && (metrics?.distance ?? Infinity) < (bestBefore.gate.metrics?.distance ?? Infinity)))
709
+ // Worse than the best so far, or it broke a tool check the best passed:
710
+ // the next attempt starts from the best.
711
+ const broke = !!bestBefore && failedTools.some((c) => bestBefore.gate.checks.some((b) => b.id === c.id && b.ok))
712
+ const restore = broke || (!!bestBefore && !!report && (report.pairwise === 'worse' || report.overall <= bestBefore.gate.critic.overall - 1))
713
+ return {
714
+ task: task.id,
715
+ round,
716
+ checks: checks.map(({ pictures, metrics: _m, evidence, charged: _c, others: _o, ...c }) => ({ ...c, evidence: { ...(evidence.images?.length ? { images: evidence.images } : {}), ...(evidence.numbers ? { numbers: evidence.numbers } : {}) } })),
717
+ metrics,
718
+ critic: report,
719
+ flags,
720
+ ...(charged.length !== flags.filter((f) => GROSS_FLAGS.includes(f)).length ? { charged } : {}),
721
+ ...(outOfScope.length ? { outOfScope } : {}),
722
+ pass,
723
+ progress,
724
+ best: isBest,
725
+ usd: 0,
726
+ ms: now() - t0,
727
+ ...(noReport ? { noReport: true, reportError: attempt.failure ?? 'no report' } : {}),
728
+ ...(criticError ? { criticError } : {}),
729
+ ...(restore ? { restore: true } : {}),
730
+ pictures: checks.flatMap((c) => (c.pictures ?? []).filter((p) => p.path).map((p) => ({ camera: p.camera, path: p.path, kind: c.kind }))),
731
+ }
732
+ }
733
+
734
+ /** The picture of an attempt the pairwise call compares against. */
735
+ function bestPicturePath(attempt, task) {
736
+ const pics = attempt.gate?.pictures ?? []
737
+ if (task.role === 'modeller') return pics.find((p) => p.camera === 'colour')?.path ?? pics[0]?.path ?? null
738
+ const cam = (task.accept?.critic ?? []).find((c) => c.camera)?.camera
739
+ return (cam && pics.find((p) => p.camera === cam)?.path) ?? pics.find((p) => p.kind === 'compare' && !String(p.camera).endsWith('-side'))?.path ?? pics.find((p) => p.kind === 'view' || p.kind === 'cameras')?.path ?? null
740
+ }
741
+
742
+ /**
743
+ * The final gate on the whole game: build, runtime, every brief camera,
744
+ * each moment's camera, perf, the seams, coverage, QA's word, then the
745
+ * whole-scene critic with every brief camera and the reference (unless
746
+ * critic is false: the creator declined more spend, and only the free
747
+ * tool checks run).
748
+ */
749
+ async function final(round, { qa, critic: judged = true }) {
750
+ const p = prod()
751
+ const task = { id: 'final', role: 'builder', title: 'The whole game', goal: 'Everything the brief and the vision ask for, seen from every camera.', covers: [], owns: [], accept: { checks: [], critic: [] } }
752
+ const checks = [
753
+ { id: 'build', kind: 'build' },
754
+ { id: 'runtime', kind: 'runtime' },
755
+ { id: 'cameras', kind: 'cameras' },
756
+ { id: 'moments', kind: 'view', cameras: [...new Set((p.vision?.moments ?? []).map((m) => m.camera))] },
757
+ { id: 'perf', kind: 'perf' },
758
+ { id: 'seams', kind: 'seams' },
759
+ { id: 'coverage', kind: 'coverage' },
760
+ ]
761
+ // The final gate holds the preview the whole time: nothing else runs.
762
+ const results = await lanes.preview.run(() => runChecks(task, round, { tag: `final-r${round}`, checks, holdsPreview: true }))
763
+ if (qa) results.push({ id: 'qa', kind: 'qa', ok: qa.ok, text: qa.text, evidence: {}, pictures: [] })
764
+ const failed = results.filter((c) => !c.ok)
765
+ const shots = results.filter((c) => c.kind === 'cameras' || c.kind === 'view').flatMap((c) => c.pictures ?? []).map(({ camera, image }) => ({ camera, image }))
766
+ const seen = new Set()
767
+ const unique = shots.filter((s) => !seen.has(s.camera) && seen.add(s.camera))
768
+ let report = null
769
+ let criticError = null
770
+ if (unique.length > 0 && judged && !stopped()) {
771
+ const r = await critique({ task, round, scope: 'final', shots: unique, sideBySide: null, best: null, metrics: null, flags: [], criteria: (p.vision?.moments ?? []).map((m) => ({ id: m.id, text: m.acceptance, camera: m.camera })) })
772
+ if (r.report) report = r.report
773
+ else criticError = r.error
774
+ }
775
+ let criticOk = false
776
+ if (report) {
777
+ try {
778
+ criticOk = critic.passes(report, null, task) === true
779
+ } catch {
780
+ criticOk = false
781
+ }
782
+ }
783
+ return {
784
+ task: 'final',
785
+ round,
786
+ checks: results.map(({ pictures, metrics: _m, evidence, ...c }) => ({ ...c, evidence: { ...(evidence.images?.length ? { images: evidence.images } : {}), ...(evidence.numbers ? { numbers: evidence.numbers } : {}) } })),
787
+ metrics: null,
788
+ critic: report,
789
+ flags: [],
790
+ pass: failed.length === 0 && criticOk,
791
+ tools: failed.length === 0,
792
+ progress: 'first',
793
+ best: false,
794
+ usd: 0,
795
+ ms: 0,
796
+ ...(criticError ? { criticError } : {}),
797
+ pictures: results.flatMap((c) => (c.pictures ?? []).filter((x) => x.path).map((x) => ({ camera: x.camera, path: x.path, kind: c.kind }))),
798
+ }
799
+ }
800
+
801
+ return { runChecks, judge, final, bestOf, stuckOf, progressOf, critique, compare }
802
+ }