@seriousgaming/sdk-tools 1.10.0 → 1.12.0

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 (219) hide show
  1. package/dist/agent/guidance.md +35 -23
  2. package/dist/{cli-F2D4GGUA.js → cli-2BKEIIA3.js} +66 -0
  3. package/dist/{cli-NQSL2CIH.js → cli-2QGTDHRX.js} +21 -21
  4. package/dist/{cli-33MZSPPK.js → cli-2SDG3SZ7.js} +21 -21
  5. package/dist/{cli-CLO7HKEQ.js → cli-2VXP34R5.js} +5 -3
  6. package/dist/{cli-P3NUTOPK.js → cli-2W4B6PD5.js} +1 -1
  7. package/dist/{cli-SOO6SEIS.js → cli-2X7DKSXN.js} +28 -25
  8. package/dist/{cli-LNEZ6KDW.js → cli-2ZP4N7HK.js} +19 -19
  9. package/dist/{cli-5O7XENQY.js → cli-3GJYZH4C.js} +5 -5
  10. package/dist/{cli-NAZTYKZT.js → cli-3GO3M2MX.js} +30 -14
  11. package/dist/{cli-YZJBFKRI.js → cli-3LDLUNME.js} +17 -17
  12. package/dist/{cli-J42N4PJG.js → cli-3WY6L2WP.js} +31 -29
  13. package/dist/{cli-WG7MAOCS.js → cli-44MBABRD.js} +25 -25
  14. package/dist/{cli-MGZYQDCH.js → cli-4IO7MKLR.js} +20 -20
  15. package/dist/{cli-HNDFANQG.js → cli-4U2PY7W3.js} +1 -1
  16. package/dist/{cli-4JNF3O5N.js → cli-4WI4LTBI.js} +2 -2
  17. package/dist/{cli-OTBCA54D.js → cli-55EIGGZK.js} +1 -1
  18. package/dist/{cli-5TKPT3CY.js → cli-5AQV6FTL.js} +18 -18
  19. package/dist/{cli-KNXY43YV.js → cli-5CW7BEU7.js} +3 -3
  20. package/dist/{cli-5V4N4BR4.js → cli-5JUVHNZF.js} +12 -12
  21. package/dist/{cli-F3YJKP6D.js → cli-5KERL6HV.js} +9 -4
  22. package/dist/{cli-HN442ZVK.js → cli-5KSA24NQ.js} +24 -24
  23. package/dist/{cli-5VZBFMCK.js → cli-5PIFO3EN.js} +8 -0
  24. package/dist/{cli-IQBY7Z7Q.js → cli-5QN2Z43X.js} +20 -20
  25. package/dist/cli-5XSPAA5X.js +69 -0
  26. package/dist/{cli-QW7VXL2V.js → cli-62KAYGXO.js} +20 -20
  27. package/dist/{cli-TDLIPYKT.js → cli-6IMV5ZZU.js} +26 -26
  28. package/dist/{cli-UULZSQBV.js → cli-6KWCIAN2.js} +764 -66
  29. package/dist/{cli-2ANX6E3A.js → cli-6NWETIX5.js} +20 -20
  30. package/dist/{cli-EXUPHPDJ.js → cli-774W3MN5.js} +26 -26
  31. package/dist/cli-7BUD3VAD.js +16 -0
  32. package/dist/{cli-7NUFHMGE.js → cli-7KEP57S7.js} +12 -12
  33. package/dist/{cli-6CYAOUYT.js → cli-7OYFJMA6.js} +18 -18
  34. package/dist/{cli-ILHHJR2S.js → cli-7ZNEDQ3G.js} +20 -20
  35. package/dist/{cli-5RRPUL6V.js → cli-AFK6OUID.js} +12 -12
  36. package/dist/{cli-A3AJQZEN.js → cli-AIYQFWXN.js} +25 -25
  37. package/dist/{cli-B5DWKRZ4.js → cli-ARAAEWIQ.js} +2 -2
  38. package/dist/cli-AVQYV3N4.js +36 -0
  39. package/dist/{cli-35GV2F6R.js → cli-B54Z6CXH.js} +16 -16
  40. package/dist/{cli-467VRXGP.js → cli-B5TC4MEL.js} +5 -5
  41. package/dist/{cli-5Z4D3F6Y.js → cli-BCXGOLU3.js} +3 -3
  42. package/dist/{cli-G2GLW5Z4.js → cli-BHAODVTZ.js} +1 -1
  43. package/dist/{cli-XR3O2YTV.js → cli-BPS2JG74.js} +20 -20
  44. package/dist/{cli-W3RG2MRI.js → cli-BVO55SR2.js} +2 -2
  45. package/dist/{cli-PYAST3G5.js → cli-CFH3JZP5.js} +21 -21
  46. package/dist/{cli-VZVHS5AP.js → cli-CTK2OIK6.js} +20 -20
  47. package/dist/{cli-ATWJCB2G.js → cli-CW5MV4VX.js} +4 -4
  48. package/dist/{cli-TCQJL2GY.js → cli-D5VOSJZ7.js} +1 -1
  49. package/dist/{cli-KIZTASLL.js → cli-DAEPMK7A.js} +5 -5
  50. package/dist/{cli-44CM2AH2.js → cli-DAHR7PKB.js} +1 -1
  51. package/dist/{cli-XW3JLRSA.js → cli-DWDSBTYL.js} +1 -1
  52. package/dist/cli-DYSDPGXW.js +95 -0
  53. package/dist/{cli-GRSQRFRG.js → cli-DZCLRZXJ.js} +9 -2
  54. package/dist/{cli-RSF5R3HC.js → cli-EJ47IE45.js} +28 -25
  55. package/dist/{cli-QDBYFITU.js → cli-EK4OSJHA.js} +2 -2
  56. package/dist/{cli-GO64NABP.js → cli-FCJHNXDA.js} +1 -1
  57. package/dist/{cli-ZNQBF4Z3.js → cli-FNESSE3L.js} +1 -1
  58. package/dist/{cli-MUOLHQNL.js → cli-FTLH4WCE.js} +17 -17
  59. package/dist/{cli-JHLWBRXB.js → cli-FYV77YS2.js} +18 -18
  60. package/dist/cli-GMJX6Q4Q.js +36 -0
  61. package/dist/{cli-7JUNA74L.js → cli-GRBVNGDW.js} +1 -1
  62. package/dist/{cli-XKAIDYIE.js → cli-HAFCFY77.js} +33 -19
  63. package/dist/{cli-OXLOGXT3.js → cli-HCJLYI24.js} +3 -3
  64. package/dist/{cli-HHRP6FP6.js → cli-HCXS5EXU.js} +25 -25
  65. package/dist/cli-HEUNNHDH.js +36 -0
  66. package/dist/{cli-36GABN2A.js → cli-HNUTIWDZ.js} +19 -19
  67. package/dist/{cli-JXQLHJO2.js → cli-HXT25ETJ.js} +244 -243
  68. package/dist/{cli-5EH4WTH4.js → cli-IGEL7UJQ.js} +5 -5
  69. package/dist/{cli-JMNPMDXH.js → cli-IO32YA5N.js} +26 -26
  70. package/dist/cli-IPTGZDBB.js +36 -0
  71. package/dist/{cli-L54SXUK6.js → cli-J25TYFKB.js} +19 -19
  72. package/dist/{cli-CQ4ZR3ZQ.js → cli-J7XYMEMX.js} +20 -20
  73. package/dist/{cli-5DWR7RPQ.js → cli-JC5OJRID.js} +2 -2
  74. package/dist/{cli-25SJZI7N.js → cli-JD563OF4.js} +126 -27
  75. package/dist/{cli-JAVMRERQ.js → cli-JRJF2WHU.js} +20 -20
  76. package/dist/{cli-UQC46YSV.js → cli-JTFLIMIG.js} +3 -3
  77. package/dist/{cli-2AH6D32V.js → cli-K2BSJ2PK.js} +2 -2
  78. package/dist/{cli-XB5PI2XT.js → cli-K4QTYMN2.js} +25 -25
  79. package/dist/{cli-5SHG2M7E.js → cli-KFJDD4C4.js} +20 -20
  80. package/dist/{cli-WW54THXN.js → cli-KVQ2JPVD.js} +1 -1
  81. package/dist/{cli-O5WYATAI.js → cli-L6AHMW2Z.js} +4 -2
  82. package/dist/{cli-IKSLPAZN.js → cli-LCYUBCVY.js} +4 -4
  83. package/dist/{cli-HGCOEL5T.js → cli-LEWSCDH5.js} +4 -4
  84. package/dist/{cli-HNG6PZW2.js → cli-LI6G7GND.js} +27 -27
  85. package/dist/{cli-2AVPNSAX.js → cli-LU2GCWIU.js} +21 -21
  86. package/dist/{cli-UEQMK4WX.js → cli-M3Z2KOEB.js} +1 -1
  87. package/dist/{cli-226ZJ72R.js → cli-M6E3E3I2.js} +170 -3
  88. package/dist/{cli-OXU6TTEN.js → cli-MCRPA4Z6.js} +20 -20
  89. package/dist/{cli-BQ36DV5C.js → cli-MI2DEDMA.js} +3 -3
  90. package/dist/{cli-6O7YCK2M.js → cli-MITZ6SE7.js} +3 -3
  91. package/dist/{cli-VALLLE6Y.js → cli-MTIYD3BX.js} +26 -26
  92. package/dist/{cli-5M6KDNVX.js → cli-MTZUJGBK.js} +2 -2
  93. package/dist/{cli-GSOV26O5.js → cli-NCLMUXLC.js} +14 -14
  94. package/dist/{cli-Z3DITVBE.js → cli-NLS3DKWH.js} +26 -26
  95. package/dist/{cli-AH6AMAIB.js → cli-NMDGS7IE.js} +1 -1
  96. package/dist/cli-O3DJO2CS.js +30 -0
  97. package/dist/{cli-BC67QHD5.js → cli-O47D5BFN.js} +2 -2
  98. package/dist/{cli-MDVC5ZNM.js → cli-OBRZ36VP.js} +14 -14
  99. package/dist/{cli-267QJ2DS.js → cli-OMG4E53H.js} +20 -20
  100. package/dist/{cli-C32Q5E5I.js → cli-P6V3NSU4.js} +1 -1
  101. package/dist/{cli-PBSLPO6G.js → cli-PAMQMTHK.js} +21 -21
  102. package/dist/{cli-RUEPTOWG.js → cli-PKTHOCT3.js} +26 -26
  103. package/dist/{cli-PTXOKO2Y.js → cli-QK7QAP5H.js} +18 -18
  104. package/dist/cli-QQ432JEN.js +36 -0
  105. package/dist/{cli-YFLQ7XOO.js → cli-QVNDPTBU.js} +20 -20
  106. package/dist/{cli-KJA6GLZI.js → cli-R2DFD6ZZ.js} +15 -15
  107. package/dist/{cli-6BLVI2JM.js → cli-RMVJMOWU.js} +111 -7
  108. package/dist/{cli-M6AZFIMV.js → cli-RQISHMJF.js} +88 -23
  109. package/dist/{cli-X64BNBQH.js → cli-RVZH462G.js} +585 -8
  110. package/dist/{cli-LLJQI2QP.js → cli-SEEOQVUL.js} +12 -12
  111. package/dist/{cli-QTCTWYCM.js → cli-SO354HPI.js} +3 -3
  112. package/dist/{cli-URCHZDTS.js → cli-T76HDH7F.js} +90 -5
  113. package/dist/{cli-ZJW6HQ6N.js → cli-TIS7DWRR.js} +7 -7
  114. package/dist/{cli-WOFYI7HZ.js → cli-TY3B6XS7.js} +21 -21
  115. package/dist/{cli-4FJL3KQZ.js → cli-UKEZJFIT.js} +2 -2
  116. package/dist/cli-VQAMW4RF.js +95 -0
  117. package/dist/{cli-4A7RWFNO.js → cli-W4LMRVZT.js} +78 -47
  118. package/dist/cli-W7I5KGIB.js +84 -0
  119. package/dist/{cli-B3EFE7ZF.js → cli-WXGJFA4F.js} +1 -1
  120. package/dist/{cli-IPTHJT3J.js → cli-XCG33I77.js} +28 -25
  121. package/dist/{cli-WLSACMYA.js → cli-YHLSG5HB.js} +30 -28
  122. package/dist/cli-YNH5DTHY.js +36 -0
  123. package/dist/cli-YPMJWPDA.js +69 -0
  124. package/dist/{cli-PXQYY6KM.js → cli-YSXIR7EM.js} +0 -0
  125. package/dist/cli-ZPFWO4VW.js +85 -0
  126. package/dist/cli.js +53 -53
  127. package/dist/client/index.d.ts +1 -1
  128. package/dist/client/test-session.d.ts +44 -6
  129. package/dist/client.js +1934 -286
  130. package/dist/core/assessment-moves.d.ts +32 -0
  131. package/dist/core/assessment-reports.d.ts +38 -0
  132. package/dist/core/assessment-settings.d.ts +15 -0
  133. package/dist/core/benchmark-samples.d.ts +28 -0
  134. package/dist/core/session-host.d.ts +4 -0
  135. package/dist/core/session-roster.d.ts +6 -0
  136. package/dist/core/session-timers.d.ts +40 -0
  137. package/dist/core/session.d.ts +14 -1
  138. package/dist/core/tick-timer.d.ts +18 -0
  139. package/dist/dev/console/assets/{index-Ch6HHb2T.js → index-zd--5H1f.js} +26 -26
  140. package/dist/dev/console/index.html +1 -1
  141. package/dist/dev/shell.d.ts +8 -0
  142. package/dist/dev/view/commands.d.ts +3 -1
  143. package/dist/docs/api/index.md +4 -2
  144. package/dist/docs/api/sdk-commands.md +29 -0
  145. package/dist/docs/api/sdk-e2e.md +30 -0
  146. package/dist/docs/api/sdk-projection.md +5 -0
  147. package/dist/docs/api/sdk-tools-client.md +68 -6
  148. package/dist/docs/api/sdk-tools-vite.md +21 -0
  149. package/dist/docs/api/sdk-ui.md +7 -0
  150. package/dist/docs/api/sdk.md +834 -19
  151. package/dist/docs/changelog.md +67 -0
  152. package/dist/docs/cli-error-codes.md +5 -1
  153. package/dist/docs/cli-reference.md +76 -2
  154. package/dist/docs/concepts/index.md +2 -0
  155. package/dist/docs/concepts/terminology.md +12 -0
  156. package/dist/docs/guides/assessments.md +248 -0
  157. package/dist/docs/guides/benchmarks.md +241 -0
  158. package/dist/docs/guides/endpoints.md +1 -1
  159. package/dist/docs/guides/engine-testing.md +49 -14
  160. package/dist/docs/guides/engine.md +10 -2
  161. package/dist/docs/guides/index.md +2 -0
  162. package/dist/docs/guides/presentation.md +11 -9
  163. package/dist/docs/guides/session-hooks.md +24 -22
  164. package/dist/docs/guides/testing.md +3 -8
  165. package/dist/docs/guides/tick-controller.md +22 -1
  166. package/dist/docs/guides/ui.md +24 -0
  167. package/dist/docs/guides/upgrading.md +36 -0
  168. package/dist/docs/page-index.md +18 -13
  169. package/dist/docs/recipes/create-assessment.md +124 -0
  170. package/dist/docs/recipes/create-benchmark.md +115 -0
  171. package/dist/docs/recipes/create-game.md +1 -1
  172. package/dist/docs/recipes/fix-duplicate-packages.md +8 -19
  173. package/dist/docs/recipes/index.md +2 -0
  174. package/dist/execution/context-composition.d.ts +39 -4
  175. package/dist/execution/engine-state.d.ts +13 -0
  176. package/dist/execution/executor.d.ts +16 -0
  177. package/dist/execution/logic-result.d.ts +13 -2
  178. package/dist/help-examples.d.ts +12 -0
  179. package/dist/host/adapter.d.ts +24 -1
  180. package/dist/host/protocol.d.ts +115 -1
  181. package/dist/host.js +29 -1
  182. package/dist/oxlint/logic.json +184 -0
  183. package/dist/playwright.js +1928 -280
  184. package/dist/runtime/index.d.ts +3 -1
  185. package/dist/runtime/manifest-version.d.ts +1 -1
  186. package/dist/runtime.js +298 -16
  187. package/dist/schema.json +189 -0
  188. package/dist/templates/package/README.md.liquid +1 -0
  189. package/dist/templates/package/claude/rules/workflow-create-engine.md +1 -1
  190. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  191. package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
  192. package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +2 -2
  193. package/dist/templates/package/claude/settings.json.template +1 -0
  194. package/dist/templates/package/oxfmtrc.json.template +8 -1
  195. package/dist/templates/package/oxlintrc.json.template +1 -180
  196. package/dist/templates/package/package.json.liquid +1 -0
  197. package/dist/templates/package/vite.config.ts.liquid +2 -8
  198. package/dist/templates/package/vitest.config.ts.liquid +2 -8
  199. package/dist/templates/starter-game/package.json +2 -1
  200. package/dist/templates/starter-game/testing/engine/game.engine.test.ts +62 -37
  201. package/dist/templates/starter-game/vite.config.ts +2 -8
  202. package/dist/templates/starter-game/vitest.config.ts +4 -3
  203. package/dist/templating/resource-metadata.d.ts +1 -1
  204. package/dist/utils/error-codes.d.ts +9 -1
  205. package/dist/utils/resource-scan.d.ts +5 -0
  206. package/dist/validation/assessment-validation.d.ts +34 -0
  207. package/dist/validation/benchmark-validation.d.ts +20 -0
  208. package/dist/validation/schema-validation.d.ts +4 -0
  209. package/dist/vite/index.d.ts +30 -0
  210. package/dist/vite.js +12 -0
  211. package/package.json +12 -4
  212. package/dist/cli-27Z5T52R.js +0 -30
  213. package/dist/cli-5XE4OMFL.js +0 -36
  214. package/dist/cli-BB6CU4ZC.js +0 -36
  215. package/dist/cli-FGP6YYM7.js +0 -36
  216. package/dist/cli-I3ZAZYWP.js +0 -36
  217. package/dist/cli-RFAPPYXK.js +0 -36
  218. package/dist/cli-WZNIW6ZO.js +0 -16
  219. package/dist/cli-XEEOJGBL.js +0 -36
@@ -6,6 +6,64 @@ Every export of `@seriousgaming/sdk`, with the declaration it is published with.
6
6
 
7
7
  ## Functions
8
8
 
9
+ ### applyBenchmarkWrite
10
+
11
+ Fold a valid write over the current record: one level deep, `null` removing a field, `tags` replaced whole. Returns `undefined` when the write removes the record, or leaves it with nothing in it.
12
+
13
+ ```ts
14
+ function applyBenchmarkWrite(
15
+ current: Record<string, unknown> | undefined,
16
+ write: Record<string, unknown> | null
17
+ ): Record<string, unknown> | undefined;
18
+ ```
19
+
20
+ ### assessmentBandOf
21
+
22
+ The band a score falls in: the last band, in declared order, whose `from` is at or below it. Null for a score below every band, or with no bands. Read in declared order rather than sorted, so a session's overrides that leave the thresholds out of order still give one answer everywhere.
23
+
24
+ ```ts
25
+ function assessmentBandOf(
26
+ score: number,
27
+ bands: readonly ResolvedAssessmentBand[]
28
+ ): ResolvedAssessmentBand | null;
29
+ ```
30
+
31
+ ### benchmarkFilters
32
+
33
+ The filters a query tries, in order: `where` as a list, a single filter as a list of one, and `[{}]` when omitted. Throws on a malformed filter, so a surface finds out from its own call rather than from an empty answer.
34
+
35
+ ```ts
36
+ function benchmarkFilters(query: BenchmarkQuery | undefined): BenchmarkFilter[];
37
+ ```
38
+
39
+ ### benchmarkWriteProblem
40
+
41
+ Check one benchmark write against its definition.
42
+
43
+ ```ts
44
+ function benchmarkWriteProblem(
45
+ definition: Pick<BenchmarkDefinition, 'fields' | 'tags'>,
46
+ write: unknown
47
+ ): string | null;
48
+ ```
49
+
50
+ ### buildAssessmentReport
51
+
52
+ Build one assessment's report.
53
+
54
+ ```ts
55
+ function buildAssessmentReport(input: {
56
+ definition: AssessmentDefinition;
57
+ bands: readonly ResolvedAssessmentBand[];
58
+ teams: readonly AssessmentReportTeam[];
59
+ participants: readonly {
60
+ id: string;
61
+ teamId: string;
62
+ }[];
63
+ audience: AssessmentAudience;
64
+ }): AssessmentReport;
65
+ ```
66
+
9
67
  ### decodeUtf8
10
68
 
11
69
  Decode a UTF-8 byte sequence to a string.
@@ -30,6 +88,25 @@ Encode a string to its UTF-8 byte sequence.
30
88
  function encodeUtf8(input: string): Uint8Array;
31
89
  ```
32
90
 
91
+ ### foldAssessmentWrite
92
+
93
+ Fold one assessment's write over its current records, or say what is wrong with it.
94
+
95
+ ```ts
96
+ function foldAssessmentWrite(
97
+ definition: Pick<AssessmentDefinition, 'level' | 'min' | 'max'>,
98
+ current: unknown,
99
+ write: unknown,
100
+ participantIds: ReadonlySet<string>
101
+ ):
102
+ | {
103
+ next: unknown;
104
+ }
105
+ | {
106
+ problem: string;
107
+ };
108
+ ```
109
+
33
110
  ### getText
34
111
 
35
112
  Helper for the common case where a caller just wants the assistant's text. Returns the concatenation of every `text` block in the response; `toolUse` blocks are skipped.
@@ -94,6 +171,25 @@ Read a setting path back into its settings identifier and keys, or `undefined` w
94
171
  function parseSettingPath(path: string): ParsedSettingPath | undefined;
95
172
  ```
96
173
 
174
+ ### resolveAssessmentBands
175
+
176
+ An assessment's bands in the order it declares them, with the thresholds and passes in force: the bundle's, under whatever the resolved `assessments` settings say for it.
177
+
178
+ ```ts
179
+ function resolveAssessmentBands(
180
+ definition: Pick<AssessmentDefinition, 'bands'>,
181
+ settings?: Record<string, AssessmentBandSetting>
182
+ ): ResolvedAssessmentBand[];
183
+ ```
184
+
185
+ ### resolveBenchmarkLevel
186
+
187
+ A benchmark's level, defaulted.
188
+
189
+ ```ts
190
+ function resolveBenchmarkLevel(definition: Pick<BenchmarkDefinition, 'level'>): 'team' | 'session';
191
+ ```
192
+
97
193
  ### scheduledTick
98
194
 
99
195
  Convenience builder that creates a `TickControllerResult` for scheduled (absolute-time) ticking.
@@ -167,6 +263,73 @@ class UndeclaredApiUseError extends Error {
167
263
 
168
264
  ## Constants
169
265
 
266
+ ### ASSESSMENT_FEEDBACK_MAX_LENGTH
267
+
268
+ The longest feedback line a result may carry.
269
+
270
+ ```ts
271
+ const ASSESSMENT_FEEDBACK_MAX_LENGTH = 500;
272
+ ```
273
+
274
+ ### ASSESSMENTS_FEATURE
275
+
276
+ The feature name a game lists in `requires` when it declares an assessment, so a runtime that cannot hold results refuses the package rather than failing the first tick that returns them.
277
+
278
+ ```ts
279
+ const ASSESSMENTS_FEATURE = 'assessments';
280
+ ```
281
+
282
+ ### ASSESSMENTS_SETTINGS
283
+
284
+ The identifier of the built-in settings resource that holds every assessment's band thresholds, so a scenario or a session can move them as it overrides any other setting.
285
+
286
+ ```ts
287
+ const ASSESSMENTS_SETTINGS = 'assessments';
288
+ ```
289
+
290
+ ### BENCHMARK_RESERVED_FIELDS
291
+
292
+ Field names the SDK owns on every benchmark record. A bundle may not declare them, so an author's field can never be mistaken for one.
293
+
294
+ ```ts
295
+ const BENCHMARK_RESERVED_FIELDS: readonly [
296
+ "tags",
297
+ "excluded"
298
+ ];
299
+ ```
300
+
301
+ ### BENCHMARK_TAG_VALUE_PATTERN
302
+
303
+ What a tag's value may contain. Short and restricted, so a value can name a difficulty or a team count but never carry a team name, a participant's email or a sentence out of the session.
304
+
305
+ ```ts
306
+ const BENCHMARK_TAG_VALUE_PATTERN: RegExp;
307
+ ```
308
+
309
+ ### BENCHMARKS_FEATURE
310
+
311
+ The feature name a game lists in `requires` when it declares a benchmark, so a runtime that cannot record benchmarks refuses the package rather than failing the first tick that returns them.
312
+
313
+ ```ts
314
+ const BENCHMARKS_FEATURE = 'benchmarks';
315
+ ```
316
+
317
+ ### MAX_ASSESSMENTS_PER_GAME
318
+
319
+ The most assessments a game may declare.
320
+
321
+ ```ts
322
+ const MAX_ASSESSMENTS_PER_GAME = 20;
323
+ ```
324
+
325
+ ### MAX_BENCHMARKS_PER_GAME
326
+
327
+ The most benchmarks a game may declare.
328
+
329
+ ```ts
330
+ const MAX_BENCHMARKS_PER_GAME = 20;
331
+ ```
332
+
170
333
  ### SCENARIO_GATE_READ_LIMIT_BYTES
171
334
 
172
335
  The largest file, in bytes, a `Scenario` gate's `readAsset` reads: 10 MB (10,485,760 bytes), the same in every runtime, so a gate gives the same answer at build and on save. A read of a larger file rejects with `ScenarioAssetTooLargeError` before any of it is read.
@@ -182,20 +345,127 @@ const SCENARIO_GATE_READ_LIMIT_BYTES: number;
182
345
  The session's shared store, as an aggregate function sees it: one value per shared-scope capability the engine declared, whatever the number of teams.
183
346
 
184
347
  ```ts
185
- interface AggregateFunctionShared<TSharedContext, TSharedState = never> {
348
+ interface AggregateFunctionShared<
349
+ TSharedContext,
350
+ TSharedState = never,
351
+ TSessionBenchmarks = never,
352
+ > {
186
353
  context: TSharedContext;
187
354
  state?: TSharedState;
355
+ benchmarks?: Partial<TSessionBenchmarks>;
188
356
  }
189
357
  ```
190
358
 
191
359
  ### AggregateFunctionTeam
192
360
 
193
361
  ```ts
194
- interface AggregateFunctionTeam<TTeamContext, TTeamState = never> {
362
+ interface AggregateFunctionTeam<
363
+ TTeamContext,
364
+ TTeamState = never,
365
+ TTeamBenchmarks = never,
366
+ TTeamAssessments = never,
367
+ > {
195
368
  teamId: string;
196
369
  index: number;
197
370
  context: TTeamContext;
198
371
  state?: TTeamState;
372
+ benchmarks?: Partial<TTeamBenchmarks>;
373
+ assessments?: Partial<TTeamAssessments>;
374
+ }
375
+ ```
376
+
377
+ ### AssessmentBand
378
+
379
+ One band of an assessment's scores, such as 'developing' or 'expert': every score from `from` up to the next band's `from`
380
+
381
+ ```ts
382
+ interface AssessmentBand {
383
+ id: string;
384
+ from: number;
385
+ passing?: boolean;
386
+ description?: string;
387
+ }
388
+ ```
389
+
390
+ ### AssessmentBandSetting
391
+
392
+ One band's override, as the built-in `assessments` settings hold it: the values a scenario or a session set, over the bundle's.
393
+
394
+ ```ts
395
+ interface AssessmentBandSetting {
396
+ from?: number;
397
+ passing?: boolean;
398
+ }
399
+ ```
400
+
401
+ ### AssessmentDefinition
402
+
403
+ Definition of an assessment: one measure the engine scores for each participant, or for each team, which a runtime may report to a learning management system. The score is the game's; the runtime places it in a band and decides pass or fail from the band
404
+
405
+ ```ts
406
+ interface AssessmentDefinition {
407
+ identifier: string;
408
+ description?: string;
409
+ level: 'participant' | 'team';
410
+ min: number;
411
+ max: number;
412
+ bands?: AssessmentBand[];
413
+ }
414
+ ```
415
+
416
+ ### AssessmentRecord
417
+
418
+ One result as the engine reads and writes it: the score, an optional line of feedback for the learner, and whether the game has marked it final.
419
+
420
+ ```ts
421
+ interface AssessmentRecord {
422
+ score: number;
423
+ feedback?: string;
424
+ final?: boolean;
425
+ }
426
+ ```
427
+
428
+ ### AssessmentReport
429
+
430
+ What `getAssessment` resolves to: one assessment's results the caller may see.
431
+
432
+ ```ts
433
+ interface AssessmentReport {
434
+ identifier: string;
435
+ level: AssessmentLevel;
436
+ min: number;
437
+ max: number;
438
+ bands: ResolvedAssessmentBand[];
439
+ results: AssessmentResult[];
440
+ }
441
+ ```
442
+
443
+ ### AssessmentReportTeam
444
+
445
+ One team, as a report is built from it.
446
+
447
+ ```ts
448
+ interface AssessmentReportTeam {
449
+ teamId: string;
450
+ records: unknown;
451
+ complete: boolean;
452
+ }
453
+ ```
454
+
455
+ ### AssessmentResult
456
+
457
+ One result, as a surface reads it and a runtime reports it.
458
+
459
+ ```ts
460
+ interface AssessmentResult {
461
+ teamId: string;
462
+ participantId?: string;
463
+ score: number;
464
+ scaled: number;
465
+ band: string | null;
466
+ passed: boolean | null;
467
+ feedback?: string;
468
+ final: boolean;
199
469
  }
200
470
  ```
201
471
 
@@ -210,6 +480,50 @@ interface AssetDescription {
210
480
  }
211
481
  ```
212
482
 
483
+ ### BenchmarkDefinition
484
+
485
+ Definition of a benchmark: outcomes and decisions the engine records for each team (or the session), which a runtime pools anonymously across sessions so a user interface can compare a team with everyone who has played
486
+
487
+ ```ts
488
+ interface BenchmarkDefinition {
489
+ identifier: string;
490
+ revision: number;
491
+ level?: 'team' | 'session';
492
+ tags?:
493
+ | []
494
+ | [string]
495
+ | [string, string]
496
+ | [string, string, string]
497
+ | [string, string, string, string]
498
+ | [string, string, string, string, string];
499
+ fields: {
500
+ [k: string]: BenchmarkField;
501
+ };
502
+ }
503
+ ```
504
+
505
+ ### BenchmarkQuery
506
+
507
+ Which records to pool.
508
+
509
+ ```ts
510
+ interface BenchmarkQuery {
511
+ where?: BenchmarkFilter | BenchmarkFilter[];
512
+ }
513
+ ```
514
+
515
+ ### BenchmarkStatistics
516
+
517
+ What `getBenchmark` resolves to when there are statistics to show.
518
+
519
+ ```ts
520
+ interface BenchmarkStatistics {
521
+ scope: BenchmarkScope;
522
+ matched: BenchmarkFilter;
523
+ fields: Record<string, BenchmarkFieldStatistics>;
524
+ }
525
+ ```
526
+
213
527
  ### CapabilityDefinition
214
528
 
215
529
  Definition of a capability
@@ -225,6 +539,18 @@ interface CapabilityDefinition {
225
539
  }
226
540
  ```
227
541
 
542
+ ### ChoiceBenchmarkStatistics
543
+
544
+ Statistics for a field with declared options.
545
+
546
+ ```ts
547
+ interface ChoiceBenchmarkStatistics {
548
+ kind: 'choice';
549
+ count: number;
550
+ options: Record<string, number>;
551
+ }
552
+ ```
553
+
228
554
  ### EndpointBaseArgs
229
555
 
230
556
  The arguments every team- or session-scoped endpoint receives.
@@ -404,6 +730,8 @@ interface EngineDefinition {
404
730
  writes?: string[];
405
731
  uses?: ApiUse[];
406
732
  settings?: string[];
733
+ benchmarks?: string[];
734
+ assessments?: string[];
407
735
  aggregate?: boolean;
408
736
  }
409
737
  ```
@@ -418,8 +746,12 @@ interface EngineFunctionArgs<
418
746
  TSettings = unknown,
419
747
  TCallbacks = SignatureCallbacks,
420
748
  TState = never,
749
+ TBenchmarks = never,
750
+ TAssessments = never,
421
751
  > extends LogicFunctionArgs<TContext, TSettings, TCallbacks> {
422
752
  state?: TState;
753
+ benchmarks?: Partial<TBenchmarks>;
754
+ assessments?: Partial<TAssessments>;
423
755
  }
424
756
  ```
425
757
 
@@ -428,8 +760,15 @@ interface EngineFunctionArgs<
428
760
  What the engine's `Init` and `Run` return: the capabilities they write and, optionally, the engine's private memory.
429
761
 
430
762
  ```ts
431
- interface EngineResult<TContext, TState = never> extends LogicResult<TContext> {
763
+ interface EngineResult<
764
+ TContext,
765
+ TState = never,
766
+ TBenchmarks = never,
767
+ TAssessments = never,
768
+ > extends LogicResult<TContext> {
432
769
  state?: TState;
770
+ benchmarks?: BenchmarkWritesOf<TBenchmarks>;
771
+ assessments?: AssessmentWritesOf<TAssessments>;
433
772
  }
434
773
  ```
435
774
 
@@ -747,6 +1086,25 @@ interface LogicResult<TContext> {
747
1086
  }
748
1087
  ```
749
1088
 
1089
+ ### NumericBenchmarkStatistics
1090
+
1091
+ Statistics for a numeric field. Only `count` is always present: a runtime may hold back any other figure until enough results back it, `min` and `max` most of all, since each is one team's real result.
1092
+
1093
+ ```ts
1094
+ interface NumericBenchmarkStatistics {
1095
+ kind: 'number';
1096
+ count: number;
1097
+ mean?: number;
1098
+ min?: number;
1099
+ max?: number;
1100
+ p10?: number;
1101
+ p25?: number;
1102
+ p50?: number;
1103
+ p75?: number;
1104
+ p90?: number;
1105
+ }
1106
+ ```
1107
+
750
1108
  ### PackageDefinition
751
1109
 
752
1110
  Definition of a package
@@ -870,6 +1228,18 @@ interface RequestTickFunctionArgs<TContext, TSettings> {
870
1228
  }
871
1229
  ```
872
1230
 
1231
+ ### ResolvedAssessmentBand
1232
+
1233
+ One band, with the threshold and pass in force for a session.
1234
+
1235
+ ```ts
1236
+ interface ResolvedAssessmentBand {
1237
+ id: string;
1238
+ from: number;
1239
+ passing: boolean;
1240
+ }
1241
+ ```
1242
+
873
1243
  ### ResolvedPackageManifest
874
1244
 
875
1245
  Every resource a package holds: the shape the loader builds from disk and the shape the build writes to seriousgaming.json. A game holds one of nine kinds, each in its own field; everything a package may hold more than one of is an array.
@@ -892,6 +1262,8 @@ interface ResolvedPackageManifest {
892
1262
  tick_controller?: SDKTickController;
893
1263
  guide?: SDKFacilitatorGuide;
894
1264
  capabilities?: SDKCapability[];
1265
+ benchmarks?: SDKBenchmark[];
1266
+ assessments?: SDKAssessment[];
895
1267
  settings?: SDKSettings[];
896
1268
  scenarios?: SDKScenario[];
897
1269
  hooks?: SDKHook[];
@@ -910,9 +1282,12 @@ interface RunAggregateFunctionArgs<
910
1282
  TCallbacks = SignatureCallbacks,
911
1283
  TTeamState = never,
912
1284
  TSharedState = never,
1285
+ TTeamBenchmarks = never,
1286
+ TSessionBenchmarks = never,
1287
+ TTeamAssessments = never,
913
1288
  > {
914
- shared: AggregateFunctionShared<TSharedContext, TSharedState>;
915
- teams: AggregateFunctionTeam<TTeamContext, TTeamState>[];
1289
+ shared: AggregateFunctionShared<TSharedContext, TSharedState, TSessionBenchmarks>;
1290
+ teams: AggregateFunctionTeam<TTeamContext, TTeamState, TTeamBenchmarks, TTeamAssessments>[];
916
1291
  settings: TSettings;
917
1292
  meta: RunMeta;
918
1293
  participants: readonly Readonly<Participant>[];
@@ -930,9 +1305,12 @@ interface RunAggregateResult<
930
1305
  TSharedContext,
931
1306
  TTeamState = never,
932
1307
  TSharedState = never,
1308
+ TTeamBenchmarks = never,
1309
+ TSessionBenchmarks = never,
1310
+ TTeamAssessments = never,
933
1311
  > {
934
- shared: EngineResult<Partial<TSharedContext>, TSharedState>;
935
- teams: EngineResult<TTeamContext, TTeamState>[];
1312
+ shared: EngineResult<Partial<TSharedContext>, TSharedState, TSessionBenchmarks>;
1313
+ teams: EngineResult<TTeamContext, TTeamState, TTeamBenchmarks, TTeamAssessments>[];
936
1314
  }
937
1315
  ```
938
1316
 
@@ -946,9 +1324,12 @@ interface RunAggregateTickResult<
946
1324
  TSharedContext,
947
1325
  TTeamState = never,
948
1326
  TSharedState = never,
1327
+ TTeamBenchmarks = never,
1328
+ TSessionBenchmarks = never,
1329
+ TTeamAssessments = never,
949
1330
  > {
950
- shared: RunResult<Partial<TSharedContext>, TSharedState>;
951
- teams: RunResult<TTeamContext, TTeamState>[];
1331
+ shared: RunResult<Partial<TSharedContext>, TSharedState, TSessionBenchmarks>;
1332
+ teams: RunResult<TTeamContext, TTeamState, TTeamBenchmarks, TTeamAssessments>[];
952
1333
  }
953
1334
  ```
954
1335
 
@@ -967,7 +1348,12 @@ interface RunMeta extends LogicMeta {
967
1348
  What the engine's `Run` returns: an `EngineResult`, plus whether the game is now over for this team.
968
1349
 
969
1350
  ```ts
970
- interface RunResult<TContext, TState = never> extends EngineResult<TContext, TState> {
1351
+ interface RunResult<
1352
+ TContext,
1353
+ TState = never,
1354
+ TBenchmarks = never,
1355
+ TAssessments = never,
1356
+ > extends EngineResult<TContext, TState, TBenchmarks, TAssessments> {
971
1357
  complete?: boolean;
972
1358
  }
973
1359
  ```
@@ -1109,6 +1495,12 @@ interface Schema {
1109
1495
  SDKPackage?: SDKPackage;
1110
1496
  SDKEngine?: SDKEngine;
1111
1497
  SDKCapability?: SDKCapability;
1498
+ BenchmarkField?: BenchmarkField;
1499
+ BenchmarkDefinition?: BenchmarkDefinition;
1500
+ SDKBenchmark?: SDKBenchmark;
1501
+ AssessmentBand?: AssessmentBand;
1502
+ AssessmentDefinition?: AssessmentDefinition;
1503
+ SDKAssessment?: SDKAssessment;
1112
1504
  SDKScenario?: SDKScenario;
1113
1505
  SDKUserInterface?: SDKUserInterface;
1114
1506
  SDKSetup?: SDKSetup;
@@ -1130,6 +1522,26 @@ interface Schema {
1130
1522
  }
1131
1523
  ```
1132
1524
 
1525
+ ### SDKAssessment
1526
+
1527
+ Bundle containing an assessment definition
1528
+
1529
+ ```ts
1530
+ interface SDKAssessment {
1531
+ definition: AssessmentDefinition;
1532
+ }
1533
+ ```
1534
+
1535
+ ### SDKBenchmark
1536
+
1537
+ Bundle containing a benchmark definition
1538
+
1539
+ ```ts
1540
+ interface SDKBenchmark {
1541
+ definition: BenchmarkDefinition;
1542
+ }
1543
+ ```
1544
+
1133
1545
  ### SDKCapability
1134
1546
 
1135
1547
  Bundle containing a capability definition
@@ -1359,6 +1771,11 @@ interface SessionUserInterfaceCallbacks {
1359
1771
  getPastState: <T = Record<string, unknown>>(
1360
1772
  query: PastStateQuery<T>
1361
1773
  ) => Promise<PastStateEntry<T>[]>;
1774
+ getBenchmark: (
1775
+ identifier: string,
1776
+ query?: BenchmarkQuery
1777
+ ) => Promise<BenchmarkStatistics | null>;
1778
+ getAssessment: (identifier: string) => Promise<AssessmentReport>;
1362
1779
  requestTick: (teamId?: string) => Promise<void>;
1363
1780
  pauseTimer: (teamId?: string) => Promise<void>;
1364
1781
  resumeTimer: (teamId?: string) => Promise<void>;
@@ -1553,6 +1970,8 @@ interface TimerState {
1553
1970
  pausedMs: number;
1554
1971
  extendedMs: number;
1555
1972
  scheduleStartedAt: number | null;
1973
+ dormant?: boolean;
1974
+ dormantAt?: number | null;
1556
1975
  }
1557
1976
  ```
1558
1977
 
@@ -1571,6 +1990,11 @@ interface UserInterfaceCallbacks {
1571
1990
  getPastState: <T = Record<string, unknown>>(
1572
1991
  query: PastStateQuery<T>
1573
1992
  ) => Promise<PastStateEntry<T>[]>;
1993
+ getBenchmark: (
1994
+ identifier: string,
1995
+ query?: BenchmarkQuery
1996
+ ) => Promise<BenchmarkStatistics | null>;
1997
+ getAssessment: (identifier: string) => Promise<AssessmentReport>;
1574
1998
  getAllTeamsParticipants: () => Promise<Participant[]>;
1575
1999
  endpoints: Record<string, (request: unknown) => Promise<unknown>>;
1576
2000
  setThemePreference: (preference: ThemePreference) => void;
@@ -1658,6 +2082,341 @@ Runtime callback API (a service) a logic-bearing resource is permitted to invoke
1658
2082
  type ApiUse = 'generateText' | 'extractText' | 'generateSpeech' | 'writeBlob';
1659
2083
  ```
1660
2084
 
2085
+ ### AssessmentAudience
2086
+
2087
+ Which results a report holds: everyone's, one team's, or one participant's own.
2088
+
2089
+ ```ts
2090
+ type AssessmentAudience =
2091
+ | {
2092
+ kind: 'all';
2093
+ }
2094
+ | {
2095
+ kind: 'team';
2096
+ teamId: string;
2097
+ }
2098
+ | {
2099
+ kind: 'participant';
2100
+ teamId: string;
2101
+ participantId: string;
2102
+ };
2103
+ ```
2104
+
2105
+ ### AssessmentLevel
2106
+
2107
+ Whether an assessment is scored once per participant or once per team.
2108
+
2109
+ ```ts
2110
+ type AssessmentLevel = 'participant' | 'team';
2111
+ ```
2112
+
2113
+ ### AssessmentRecordWrite
2114
+
2115
+ A write to one result. A patch over the current record: a field set to `null` is removed. `null` in place of the whole write removes the result. A result always has a score, so the first write must carry one.
2116
+
2117
+ ```ts
2118
+ type AssessmentRecordWrite = {
2119
+ score?: number;
2120
+ feedback?: string | null;
2121
+ final?: boolean | null;
2122
+ } | null;
2123
+ ```
2124
+
2125
+ ### AssessmentSettings
2126
+
2127
+ The built-in `assessments` settings as they resolve: each assessment's bands, by band id, with their threshold and pass.
2128
+
2129
+ ```ts
2130
+ type AssessmentSettings = Record<string, Record<string, AssessmentBandSetting>>;
2131
+ ```
2132
+
2133
+ ### AssessmentWrite
2134
+
2135
+ The write for one assessment: a record write for a team-level assessment, or record writes by participant id for a participant-level one, where `null` in place of the whole write removes every result.
2136
+
2137
+ ```ts
2138
+ type AssessmentWrite<TRecords> = TRecords extends {
2139
+ score: unknown;
2140
+ }
2141
+ ? AssessmentRecordWrite
2142
+ : {
2143
+ [participantId: string]: AssessmentRecordWrite;
2144
+ } | null;
2145
+ ```
2146
+
2147
+ ### AssessmentWrites
2148
+
2149
+ The writes an engine result carries under `assessments`, by identifier.
2150
+
2151
+ ```ts
2152
+ type AssessmentWrites<TAssessments> = {
2153
+ [K in keyof TAssessments]?: AssessmentWrite<TAssessments[K]>;
2154
+ };
2155
+ ```
2156
+
2157
+ ### BenchmarkField
2158
+
2159
+ One field of a benchmark: a number, pooled as a distribution, or one of a short declared list of options, pooled as a count per option
2160
+
2161
+ ```ts
2162
+ type BenchmarkField =
2163
+ | {
2164
+ type: 'number';
2165
+ description?: string;
2166
+ }
2167
+ | {
2168
+ enum:
2169
+ | [string]
2170
+ | [string, string]
2171
+ | [string, string, string]
2172
+ | [string, string, string, string]
2173
+ | [string, string, string, string, string]
2174
+ | [string, string, string, string, string, string]
2175
+ | [string, string, string, string, string, string, string]
2176
+ | [string, string, string, string, string, string, string, string]
2177
+ | [string, string, string, string, string, string, string, string, string]
2178
+ | [string, string, string, string, string, string, string, string, string, string]
2179
+ | [
2180
+ string,
2181
+ string,
2182
+ string,
2183
+ string,
2184
+ string,
2185
+ string,
2186
+ string,
2187
+ string,
2188
+ string,
2189
+ string,
2190
+ string,
2191
+ ]
2192
+ | [
2193
+ string,
2194
+ string,
2195
+ string,
2196
+ string,
2197
+ string,
2198
+ string,
2199
+ string,
2200
+ string,
2201
+ string,
2202
+ string,
2203
+ string,
2204
+ string,
2205
+ ]
2206
+ | [
2207
+ string,
2208
+ string,
2209
+ string,
2210
+ string,
2211
+ string,
2212
+ string,
2213
+ string,
2214
+ string,
2215
+ string,
2216
+ string,
2217
+ string,
2218
+ string,
2219
+ string,
2220
+ ]
2221
+ | [
2222
+ string,
2223
+ string,
2224
+ string,
2225
+ string,
2226
+ string,
2227
+ string,
2228
+ string,
2229
+ string,
2230
+ string,
2231
+ string,
2232
+ string,
2233
+ string,
2234
+ string,
2235
+ string,
2236
+ ]
2237
+ | [
2238
+ string,
2239
+ string,
2240
+ string,
2241
+ string,
2242
+ string,
2243
+ string,
2244
+ string,
2245
+ string,
2246
+ string,
2247
+ string,
2248
+ string,
2249
+ string,
2250
+ string,
2251
+ string,
2252
+ string,
2253
+ ]
2254
+ | [
2255
+ string,
2256
+ string,
2257
+ string,
2258
+ string,
2259
+ string,
2260
+ string,
2261
+ string,
2262
+ string,
2263
+ string,
2264
+ string,
2265
+ string,
2266
+ string,
2267
+ string,
2268
+ string,
2269
+ string,
2270
+ string,
2271
+ ]
2272
+ | [
2273
+ string,
2274
+ string,
2275
+ string,
2276
+ string,
2277
+ string,
2278
+ string,
2279
+ string,
2280
+ string,
2281
+ string,
2282
+ string,
2283
+ string,
2284
+ string,
2285
+ string,
2286
+ string,
2287
+ string,
2288
+ string,
2289
+ string,
2290
+ ]
2291
+ | [
2292
+ string,
2293
+ string,
2294
+ string,
2295
+ string,
2296
+ string,
2297
+ string,
2298
+ string,
2299
+ string,
2300
+ string,
2301
+ string,
2302
+ string,
2303
+ string,
2304
+ string,
2305
+ string,
2306
+ string,
2307
+ string,
2308
+ string,
2309
+ string,
2310
+ ]
2311
+ | [
2312
+ string,
2313
+ string,
2314
+ string,
2315
+ string,
2316
+ string,
2317
+ string,
2318
+ string,
2319
+ string,
2320
+ string,
2321
+ string,
2322
+ string,
2323
+ string,
2324
+ string,
2325
+ string,
2326
+ string,
2327
+ string,
2328
+ string,
2329
+ string,
2330
+ string,
2331
+ ]
2332
+ | [
2333
+ string,
2334
+ string,
2335
+ string,
2336
+ string,
2337
+ string,
2338
+ string,
2339
+ string,
2340
+ string,
2341
+ string,
2342
+ string,
2343
+ string,
2344
+ string,
2345
+ string,
2346
+ string,
2347
+ string,
2348
+ string,
2349
+ string,
2350
+ string,
2351
+ string,
2352
+ string,
2353
+ ];
2354
+ description?: string;
2355
+ };
2356
+ ```
2357
+
2358
+ ### BenchmarkFieldStatistics
2359
+
2360
+ ```ts
2361
+ type BenchmarkFieldStatistics = NumericBenchmarkStatistics | ChoiceBenchmarkStatistics;
2362
+ ```
2363
+
2364
+ ### BenchmarkFilter
2365
+
2366
+ A filter on tag values. `{}` matches every record.
2367
+
2368
+ ```ts
2369
+ type BenchmarkFilter = Record<string, string>;
2370
+ ```
2371
+
2372
+ ### BenchmarkRecord
2373
+
2374
+ One benchmark record as the engine reads and writes it: the declared fields, the tags it is grouped by, and whether it is withdrawn. Every field is optional, because a record may be filled in round by round.
2375
+
2376
+ ```ts
2377
+ type BenchmarkRecord<
2378
+ TFields extends Record<string, unknown> = Record<string, number | string>,
2379
+ TTags extends string = string,
2380
+ > = {
2381
+ [K in keyof TFields]?: TFields[K];
2382
+ } & {
2383
+ tags?: {
2384
+ [K in TTags]?: string;
2385
+ };
2386
+ excluded?: boolean;
2387
+ };
2388
+ ```
2389
+
2390
+ ### BenchmarkScope
2391
+
2392
+ Whose results were pooled, for a user interface to say so. The runtime decides it; the game only shows it.
2393
+
2394
+ ```ts
2395
+ type BenchmarkScope = 'organisation' | 'global';
2396
+ ```
2397
+
2398
+ ### BenchmarkWrite
2399
+
2400
+ A write to one benchmark, as an engine returns it under `benchmarks`. It is a patch, merged one level deep over the current record: a field set to `null` is removed, and `tags` replaces the record's tags whole. `null` in place of the whole write removes the record.
2401
+
2402
+ ```ts
2403
+ type BenchmarkWrite<TRecord> =
2404
+ | {
2405
+ [K in keyof TRecord]?: TRecord[K] | null;
2406
+ }
2407
+ | null;
2408
+ ```
2409
+
2410
+ ### BenchmarkWrites
2411
+
2412
+ The writes an engine result carries under `benchmarks`, by identifier.
2413
+
2414
+ ```ts
2415
+ type BenchmarkWrites<TBenchmarks> = {
2416
+ [K in keyof TBenchmarks]?: BenchmarkWrite<TBenchmarks[K]>;
2417
+ };
2418
+ ```
2419
+
1661
2420
  ### ContentBlock
1662
2421
 
1663
2422
  A content block inside an LLM message or response.
@@ -2063,6 +2822,9 @@ type InitAggregateFunction<
2063
2822
  TCallbacks = SignatureCallbacks,
2064
2823
  TTeamState = never,
2065
2824
  TSharedState = never,
2825
+ TTeamBenchmarks = never,
2826
+ TSessionBenchmarks = never,
2827
+ TTeamAssessments = never,
2066
2828
  > = (
2067
2829
  args: RunAggregateFunctionArgs<
2068
2830
  TTeamContext,
@@ -2070,9 +2832,22 @@ type InitAggregateFunction<
2070
2832
  TSettings,
2071
2833
  TCallbacks,
2072
2834
  TTeamState,
2073
- TSharedState
2835
+ TSharedState,
2836
+ TTeamBenchmarks,
2837
+ TSessionBenchmarks,
2838
+ TTeamAssessments
2074
2839
  >
2075
- ) => Promise<RunAggregateResult<TTeamContext, TSharedContext, TTeamState, TSharedState>>;
2840
+ ) => Promise<
2841
+ RunAggregateResult<
2842
+ TTeamContext,
2843
+ TSharedContext,
2844
+ TTeamState,
2845
+ TSharedState,
2846
+ TTeamBenchmarks,
2847
+ TSessionBenchmarks,
2848
+ TTeamAssessments
2849
+ >
2850
+ >;
2076
2851
  ```
2077
2852
 
2078
2853
  ### InitializationFunction
@@ -2083,9 +2858,11 @@ type InitializationFunction<
2083
2858
  TSettings = unknown,
2084
2859
  TCallbacks = SignatureCallbacks,
2085
2860
  TState = never,
2861
+ TBenchmarks = never,
2862
+ TAssessments = never,
2086
2863
  > = (
2087
- args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>
2088
- ) => Promise<EngineResult<TContext, TState>>;
2864
+ args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState, TBenchmarks, TAssessments>
2865
+ ) => Promise<EngineResult<TContext, TState, TBenchmarks, TAssessments>>;
2089
2866
  ```
2090
2867
 
2091
2868
  ### LLMGenerateFunction
@@ -2121,6 +2898,14 @@ type LogicCallbacks<Uses extends ApiUse = never> = Required<Pick<SignatureCallba
2121
2898
  UngatedSignatureCallbacks;
2122
2899
  ```
2123
2900
 
2901
+ ### ParticipantAssessmentRecords
2902
+
2903
+ A participant-level assessment's records, by participant id.
2904
+
2905
+ ```ts
2906
+ type ParticipantAssessmentRecords = Record<string, AssessmentRecord>;
2907
+ ```
2908
+
2124
2909
  ### RequestTickFunction
2125
2910
 
2126
2911
  A validator's `RequestTick` export: the gate on a participant's request for the next tick. Only a player surface's request reaches it; the facilitator's ticks, the timer's and every system-trusted caller's pass straight through.
@@ -2141,6 +2926,9 @@ type RunAggregateFunction<
2141
2926
  TCallbacks = SignatureCallbacks,
2142
2927
  TTeamState = never,
2143
2928
  TSharedState = never,
2929
+ TTeamBenchmarks = never,
2930
+ TSessionBenchmarks = never,
2931
+ TTeamAssessments = never,
2144
2932
  > = (
2145
2933
  args: RunAggregateFunctionArgs<
2146
2934
  TTeamContext,
@@ -2148,9 +2936,22 @@ type RunAggregateFunction<
2148
2936
  TSettings,
2149
2937
  TCallbacks,
2150
2938
  TTeamState,
2151
- TSharedState
2939
+ TSharedState,
2940
+ TTeamBenchmarks,
2941
+ TSessionBenchmarks,
2942
+ TTeamAssessments
2943
+ >
2944
+ ) => Promise<
2945
+ RunAggregateTickResult<
2946
+ TTeamContext,
2947
+ TSharedContext,
2948
+ TTeamState,
2949
+ TSharedState,
2950
+ TTeamBenchmarks,
2951
+ TSessionBenchmarks,
2952
+ TTeamAssessments
2152
2953
  >
2153
- ) => Promise<RunAggregateTickResult<TTeamContext, TSharedContext, TTeamState, TSharedState>>;
2954
+ >;
2154
2955
  ```
2155
2956
 
2156
2957
  ### RunFunction
@@ -2161,9 +2962,11 @@ type RunFunction<
2161
2962
  TSettings = unknown,
2162
2963
  TCallbacks = SignatureCallbacks,
2163
2964
  TState = never,
2965
+ TBenchmarks = never,
2966
+ TAssessments = never,
2164
2967
  > = (
2165
- args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>
2166
- ) => Promise<RunResult<TContext, TState>>;
2968
+ args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState, TBenchmarks, TAssessments>
2969
+ ) => Promise<RunResult<TContext, TState, TBenchmarks, TAssessments>>;
2167
2970
  ```
2168
2971
 
2169
2972
  ### RunKind
@@ -2215,7 +3018,19 @@ type StepFunction<
2215
3018
  TSettings = unknown,
2216
3019
  TCallbacks = SignatureCallbacks,
2217
3020
  TState = unknown,
2218
- > = (args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>) => Promise<TContext>;
3021
+ TBenchmarks = unknown,
3022
+ TAssessments = unknown,
3023
+ > = (
3024
+ args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState, TBenchmarks, TAssessments>
3025
+ ) => Promise<TContext>;
3026
+ ```
3027
+
3028
+ ### TeamAssessmentRecord
3029
+
3030
+ A team-level assessment's record: one result for the whole team.
3031
+
3032
+ ```ts
3033
+ type TeamAssessmentRecord = AssessmentRecord;
2219
3034
  ```
2220
3035
 
2221
3036
  ### ThemePreference