@jam-overture/loom 0.1.0 → 0.2.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 (290) hide show
  1. package/README.md +3 -1
  2. package/dist/application/application.d.ts +109 -0
  3. package/dist/application/application.js +97 -0
  4. package/dist/application/memory.d.ts +20 -0
  5. package/dist/application/memory.js +79 -0
  6. package/dist/application/store.d.ts +101 -0
  7. package/dist/application/store.js +25 -0
  8. package/dist/audience/audience.d.ts +36 -0
  9. package/dist/audience/audience.js +41 -0
  10. package/dist/cli/templates.js +19 -0
  11. package/dist/data/plan.js +0 -0
  12. package/dist/data/resolution.d.ts +23 -1
  13. package/dist/data/resolve.d.ts +30 -3
  14. package/dist/data/resolve.js +11 -3
  15. package/dist/ids.d.ts +10 -0
  16. package/dist/ids.js +11 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.js +1 -0
  19. package/dist/patch.d.ts +54 -0
  20. package/dist/patch.js +44 -0
  21. package/dist/project/closing.d.ts +51 -0
  22. package/dist/project/closing.js +53 -0
  23. package/dist/project/memory.d.ts +20 -0
  24. package/dist/project/memory.js +97 -0
  25. package/dist/project/project.d.ts +90 -0
  26. package/dist/project/project.js +91 -0
  27. package/dist/project/store.d.ts +135 -0
  28. package/dist/project/store.js +41 -0
  29. package/dist/registered.d.ts +64 -0
  30. package/dist/registered.js +118 -0
  31. package/dist/render/behaviour-adjust.d.ts +11 -19
  32. package/dist/render/behaviour-adjust.js +75 -21
  33. package/dist/render/behaviour-present.d.ts +8 -0
  34. package/dist/render/behaviour-present.js +57 -6
  35. package/dist/render/behaviour.d.ts +98 -17
  36. package/dist/render/behaviour.js +91 -26
  37. package/dist/render/control-name.d.ts +68 -0
  38. package/dist/render/control-name.js +37 -0
  39. package/dist/render/diagnostics.d.ts +72 -0
  40. package/dist/render/diagnostics.js +7 -0
  41. package/dist/render/index.d.ts +2 -0
  42. package/dist/render/index.js +2 -0
  43. package/dist/render/reads.d.ts +11 -0
  44. package/dist/render/reads.js +12 -1
  45. package/dist/render/render.js +102 -7
  46. package/dist/render/slots.d.ts +52 -0
  47. package/dist/render/slots.js +24 -0
  48. package/dist/render/theme.d.ts +54 -1
  49. package/dist/render/theme.js +23 -1
  50. package/dist/render/unshown.d.ts +152 -0
  51. package/dist/render/unshown.js +80 -0
  52. package/dist/runtime/analysis.d.ts +94 -9
  53. package/dist/runtime/analysis.js +54 -9
  54. package/dist/runtime/assessment.d.ts +36 -2
  55. package/dist/runtime/assessment.js +27 -2
  56. package/dist/runtime/checks.d.ts +148 -0
  57. package/dist/runtime/checks.js +112 -0
  58. package/dist/runtime/disposition.d.ts +96 -0
  59. package/dist/runtime/disposition.js +46 -0
  60. package/dist/runtime/gate.js +22 -0
  61. package/dist/runtime/index.d.ts +3 -0
  62. package/dist/runtime/index.js +3 -0
  63. package/dist/runtime/irreversibility.d.ts +64 -0
  64. package/dist/runtime/irreversibility.js +45 -0
  65. package/dist/runtime/pipeline.d.ts +43 -0
  66. package/dist/runtime/pipeline.js +10 -2
  67. package/dist/runtime/policy-change.d.ts +93 -0
  68. package/dist/runtime/policy-change.js +299 -0
  69. package/dist/runtime/policy-log.d.ts +406 -0
  70. package/dist/runtime/policy-log.js +285 -0
  71. package/dist/runtime/reversibility.d.ts +11 -9
  72. package/dist/runtime/stakes.d.ts +129 -1
  73. package/dist/runtime/stakes.js +240 -26
  74. package/dist/runtime/vocabulary.d.ts +164 -7
  75. package/dist/runtime/vocabulary.js +181 -8
  76. package/dist/sdk/audit.d.ts +174 -3
  77. package/dist/sdk/audit.js +176 -17
  78. package/dist/sdk/catalogue.d.ts +9 -1
  79. package/dist/sdk/conformance.d.ts +37 -3
  80. package/dist/sdk/conformance.js +25 -4
  81. package/dist/sdk/definition.d.ts +65 -0
  82. package/dist/sdk/definition.js +22 -0
  83. package/dist/sdk/registry.d.ts +29 -2
  84. package/dist/sdk/registry.js +63 -1
  85. package/dist/signals/action-change.d.ts +507 -0
  86. package/dist/signals/action-change.js +265 -0
  87. package/dist/signals/action.d.ts +331 -0
  88. package/dist/signals/action.js +182 -0
  89. package/dist/signals/applied-window.contract.d.ts +23 -0
  90. package/dist/signals/applied-window.contract.js +160 -0
  91. package/dist/signals/arriving.d.ts +210 -0
  92. package/dist/signals/arriving.js +133 -0
  93. package/dist/signals/audiences.d.ts +528 -0
  94. package/dist/signals/audiences.js +255 -0
  95. package/dist/signals/broadcast.d.ts +8 -2
  96. package/dist/signals/broadcast.js +58 -8
  97. package/dist/signals/change.d.ts +378 -0
  98. package/dist/signals/change.js +327 -0
  99. package/dist/signals/collect.d.ts +41 -0
  100. package/dist/signals/collect.js +88 -7
  101. package/dist/signals/copy-change.d.ts +553 -0
  102. package/dist/signals/copy-change.js +377 -0
  103. package/dist/signals/copy.d.ts +337 -0
  104. package/dist/signals/copy.js +211 -0
  105. package/dist/signals/counters.d.ts +46 -0
  106. package/dist/signals/counters.js +102 -0
  107. package/dist/signals/deliver.d.ts +23 -4
  108. package/dist/signals/deliver.js +34 -6
  109. package/dist/signals/deployment-change.d.ts +371 -0
  110. package/dist/signals/deployment-change.js +268 -0
  111. package/dist/signals/deployment.d.ts +265 -0
  112. package/dist/signals/deployment.js +152 -0
  113. package/dist/signals/door.d.ts +92 -0
  114. package/dist/signals/door.js +53 -0
  115. package/dist/signals/fold.d.ts +10 -0
  116. package/dist/signals/fold.js +5 -1
  117. package/dist/signals/form-action.d.ts +302 -0
  118. package/dist/signals/form-action.js +169 -0
  119. package/dist/signals/form-copy.d.ts +523 -0
  120. package/dist/signals/form-copy.js +346 -0
  121. package/dist/signals/forms.d.ts +247 -0
  122. package/dist/signals/forms.js +147 -0
  123. package/dist/signals/funnel-change.d.ts +548 -0
  124. package/dist/signals/funnel-change.js +361 -0
  125. package/dist/signals/funnel.d.ts +532 -0
  126. package/dist/signals/funnel.js +216 -0
  127. package/dist/signals/health.d.ts +497 -0
  128. package/dist/signals/health.js +361 -0
  129. package/dist/signals/index.d.ts +41 -0
  130. package/dist/signals/index.js +41 -0
  131. package/dist/signals/ingest.d.ts +56 -1
  132. package/dist/signals/ingest.js +91 -1
  133. package/dist/signals/journal.d.ts +11 -0
  134. package/dist/signals/kinds.d.ts +8 -6
  135. package/dist/signals/kinds.js +14 -6
  136. package/dist/signals/library-action.d.ts +430 -0
  137. package/dist/signals/library-action.js +336 -0
  138. package/dist/signals/library-change.d.ts +477 -0
  139. package/dist/signals/library-change.js +335 -0
  140. package/dist/signals/library-copy-change.d.ts +498 -0
  141. package/dist/signals/library-copy-change.js +476 -0
  142. package/dist/signals/library-pace.d.ts +319 -0
  143. package/dist/signals/library-pace.js +305 -0
  144. package/dist/signals/library-reach-change.d.ts +636 -0
  145. package/dist/signals/library-reach-change.js +534 -0
  146. package/dist/signals/library-reach.d.ts +377 -0
  147. package/dist/signals/library-reach.js +227 -0
  148. package/dist/signals/library-word-reach-change.d.ts +567 -0
  149. package/dist/signals/library-word-reach-change.js +568 -0
  150. package/dist/signals/library.d.ts +306 -0
  151. package/dist/signals/library.js +178 -0
  152. package/dist/signals/memory.d.ts +9 -0
  153. package/dist/signals/memory.js +105 -14
  154. package/dist/signals/migrate.d.ts +17 -2
  155. package/dist/signals/migrate.js +122 -5
  156. package/dist/signals/notice.d.ts +334 -0
  157. package/dist/signals/notice.js +228 -0
  158. package/dist/signals/pace-change.d.ts +501 -0
  159. package/dist/signals/pace-change.js +310 -0
  160. package/dist/signals/pace.d.ts +296 -0
  161. package/dist/signals/pace.js +291 -0
  162. package/dist/signals/page-views.d.ts +365 -0
  163. package/dist/signals/page-views.js +218 -0
  164. package/dist/signals/parts.d.ts +344 -0
  165. package/dist/signals/parts.js +273 -0
  166. package/dist/signals/postgres.d.ts +16 -2
  167. package/dist/signals/postgres.js +390 -87
  168. package/dist/signals/progress.d.ts +212 -0
  169. package/dist/signals/progress.js +150 -0
  170. package/dist/signals/ratios.d.ts +108 -0
  171. package/dist/signals/ratios.js +40 -0
  172. package/dist/signals/reach.d.ts +309 -0
  173. package/dist/signals/reach.js +93 -0
  174. package/dist/signals/readable.d.ts +34 -0
  175. package/dist/signals/readable.js +34 -0
  176. package/dist/signals/readership.d.ts +381 -0
  177. package/dist/signals/readership.js +308 -0
  178. package/dist/signals/region-pages.d.ts +173 -0
  179. package/dist/signals/region-pages.js +62 -0
  180. package/dist/signals/region.d.ts +287 -0
  181. package/dist/signals/region.js +198 -0
  182. package/dist/signals/retention.d.ts +141 -0
  183. package/dist/signals/retention.js +58 -0
  184. package/dist/signals/rollup.d.ts +67 -3
  185. package/dist/signals/rollup.js +0 -0
  186. package/dist/signals/schema.d.ts +432 -1
  187. package/dist/signals/schema.js +157 -3
  188. package/dist/signals/signal.d.ts +237 -11
  189. package/dist/signals/signal.js +70 -10
  190. package/dist/signals/silence-census.d.ts +205 -0
  191. package/dist/signals/silence-census.js +87 -0
  192. package/dist/signals/silences.d.ts +848 -0
  193. package/dist/signals/silences.js +753 -0
  194. package/dist/signals/tally.d.ts +140 -11
  195. package/dist/signals/window-figures.d.ts +148 -0
  196. package/dist/signals/window-figures.js +42 -0
  197. package/dist/signals/window.d.ts +866 -0
  198. package/dist/signals/window.js +693 -0
  199. package/dist/signals/words.d.ts +24 -0
  200. package/dist/signals/words.js +24 -0
  201. package/dist/store/index.d.ts +19 -0
  202. package/dist/store/index.js +19 -0
  203. package/dist/store/memory.d.ts +2 -1
  204. package/dist/store/memory.js +48 -12
  205. package/dist/store/migrate.d.ts +80 -0
  206. package/dist/store/migrate.js +259 -7
  207. package/dist/store/postgres-applications.d.ts +4 -0
  208. package/dist/store/postgres-applications.js +197 -0
  209. package/dist/store/postgres-holds.d.ts +10 -1
  210. package/dist/store/postgres-holds.js +116 -101
  211. package/dist/store/postgres-policy-log.d.ts +14 -0
  212. package/dist/store/postgres-policy-log.js +240 -0
  213. package/dist/store/postgres-projects.d.ts +4 -0
  214. package/dist/store/postgres-projects.js +217 -0
  215. package/dist/store/postgres.d.ts +16 -1
  216. package/dist/store/postgres.js +59 -9
  217. package/dist/store/replay.d.ts +102 -1
  218. package/dist/store/replay.js +190 -19
  219. package/dist/store/reseed.d.ts +238 -0
  220. package/dist/store/reseed.js +308 -0
  221. package/dist/store/schema.d.ts +450 -2
  222. package/dist/store/schema.js +141 -5
  223. package/dist/store/store.d.ts +29 -6
  224. package/dist/submit/resolve.js +2 -1
  225. package/dist/telemetry/calibration.d.ts +25 -0
  226. package/dist/telemetry/calibration.js +27 -1
  227. package/dist/telemetry/event.d.ts +391 -33
  228. package/dist/telemetry/event.js +84 -20
  229. package/dist/telemetry/index.d.ts +1 -0
  230. package/dist/telemetry/index.js +1 -0
  231. package/dist/telemetry/journal.d.ts +72 -3
  232. package/dist/telemetry/journal.js +9 -0
  233. package/dist/telemetry/lookup.d.ts +27 -0
  234. package/dist/telemetry/lookup.js +18 -0
  235. package/dist/telemetry/memory.js +23 -0
  236. package/dist/telemetry/migrate.js +22 -1
  237. package/dist/telemetry/postgres.d.ts +10 -1
  238. package/dist/telemetry/postgres.js +172 -90
  239. package/dist/telemetry/remeasure.d.ts +78 -0
  240. package/dist/telemetry/remeasure.js +83 -0
  241. package/dist/telemetry/retention.d.ts +2 -2
  242. package/dist/telemetry/schema.d.ts +17 -0
  243. package/dist/telemetry/schema.js +27 -1
  244. package/dist/telemetry/sink.d.ts +2 -2
  245. package/dist/testing/application-contract.d.ts +14 -0
  246. package/dist/testing/application-contract.js +270 -0
  247. package/dist/testing/contracts.d.ts +12 -7
  248. package/dist/testing/contracts.js +12 -7
  249. package/dist/testing/definitions.d.ts +78 -0
  250. package/dist/testing/definitions.js +134 -9
  251. package/dist/testing/doubles.d.ts +103 -0
  252. package/dist/testing/doubles.js +143 -0
  253. package/dist/testing/index.d.ts +2 -2
  254. package/dist/testing/index.js +2 -2
  255. package/dist/testing/journal-contract.js +140 -2
  256. package/dist/testing/model-contract.d.ts +110 -0
  257. package/dist/testing/model-contract.js +150 -0
  258. package/dist/testing/policy-log-contract.d.ts +26 -0
  259. package/dist/testing/policy-log-contract.js +344 -0
  260. package/dist/testing/project-contract.d.ts +14 -0
  261. package/dist/testing/project-contract.js +266 -0
  262. package/dist/testing/reader-signal-contract.d.ts +27 -2
  263. package/dist/testing/reader-signal-contract.js +475 -5
  264. package/dist/testing/store-contract.d.ts +7 -1
  265. package/dist/testing/store-contract.js +84 -3
  266. package/dist/theme/apply.d.ts +20 -1
  267. package/dist/theme/apply.js +5 -3
  268. package/dist/theme/derive.d.ts +22 -0
  269. package/dist/theme/derive.js +54 -1
  270. package/dist/theme/library.js +1 -1
  271. package/dist/theme/measure.d.ts +34 -0
  272. package/dist/theme/measure.js +30 -1
  273. package/dist/theme/palettes.js +7 -7
  274. package/dist/theme/ramp.d.ts +64 -0
  275. package/dist/theme/ramp.js +114 -0
  276. package/dist/theme/registry.d.ts +9 -0
  277. package/dist/theme/registry.js +11 -1
  278. package/dist/theme/separation.d.ts +97 -3
  279. package/dist/theme/separation.js +75 -0
  280. package/dist/tree/compare.d.ts +9 -0
  281. package/dist/tree/compare.js +18 -0
  282. package/dist/write/computed.d.ts +60 -0
  283. package/dist/write/computed.js +61 -0
  284. package/dist/write/held.d.ts +59 -0
  285. package/dist/write/index.d.ts +5 -2
  286. package/dist/write/index.js +5 -2
  287. package/dist/write/reseed.d.ts +151 -0
  288. package/dist/write/reseed.js +184 -0
  289. package/dist/write/revert.js +2 -16
  290. package/package.json +98 -19
@@ -1,10 +1,17 @@
1
+ import { type SourceEntry } from "../data/adapter.js";
1
2
  import type { ModelClient, ModelClientError, ModelCompletion, ModelRequest } from "../interpretation/client.js";
2
3
  import type { IdFactory, IntentId, TreeId } from "../ids.js";
3
4
  import { type Result } from "../result.js";
5
+ import type { ChangeAnalysis } from "../runtime/analysis.js";
6
+ import type { ChangeAssessment } from "../runtime/assessment.js";
7
+ import { type WriteCheck } from "../runtime/checks.js";
4
8
  import type { Clock, EventSink, RuntimeEventEnvelope } from "../runtime/events.js";
5
9
  import type { EditIntent, IntentOrigin } from "../runtime/intent.js";
6
10
  import type { ChangeInterpreter, ChangeRepairer, InterpretationError, RepairRequest } from "../runtime/interpreter.js";
7
11
  import type { AuthorKind, ProposedChange } from "../runtime/proposal.js";
12
+ import type { IrreversibilityReason } from "../runtime/reversibility.js";
13
+ import type { StakeFactor } from "../runtime/stakes.js";
14
+ import { type EndpointEntry } from "../submit/endpoint.js";
8
15
  import type { TreeDelta } from "../tree/delta.js";
9
16
  /**
10
17
  * Test doubles for the impure seams this file owns — the interpreter and its
@@ -91,4 +98,100 @@ export type ProposalDraft = {
91
98
  readonly confidence?: number;
92
99
  };
93
100
  export declare const buildProposal: (idFactory: IdFactory, draft: ProposalDraft) => ProposedChange;
101
+ /**
102
+ * What a hanging seam double reports, beside the entry a registry takes.
103
+ *
104
+ * The `abortedWith` half is the reason these are published rather than written
105
+ * out per surface: reaching a ceiling is observable in the seam's own
106
+ * vocabulary, but the *abort* the runtime sends afterwards is not observable
107
+ * anywhere except from inside the adapter, and it is the half a hand-written
108
+ * double leaves out (0140).
109
+ */
110
+ export type HangingSeam<TEntry> = {
111
+ readonly entry: TEntry;
112
+ /** Whether the runtime's ceiling aborted the call, and what it said (0140). */
113
+ readonly abortedWith: () => string | undefined;
114
+ };
115
+ /**
116
+ * A source that never answers — the sibling of `hangingModelClient` at the data
117
+ * seam, published for the same reason.
118
+ *
119
+ * Every surface that renders a bound region has an "it did not come back" state
120
+ * to show, and a promise that is never resolved is the only honest imitation of
121
+ * an integration nobody is going to answer. Use it with a small `ceilingMs`;
122
+ * the default is ten seconds and a test that waits it out is a test nobody runs.
123
+ *
124
+ * Its params schema accepts anything, because a double whose whole job is to
125
+ * not answer must never be the thing that refuses first: a binding written
126
+ * against the real source it stands in for has to reach the adapter unchanged.
127
+ */
128
+ export declare const hangingSource: (id: string, description: string) => HangingSeam<SourceEntry>;
129
+ /**
130
+ * An endpoint that never says where a form posts — the same double at the
131
+ * submission seam.
132
+ *
133
+ * A form's target is resolved while the page is being served, so this is the
134
+ * state a token store having a very bad afternoon puts a page into, and the one
135
+ * a ceiling exists to bound (0140).
136
+ */
137
+ export declare const hangingEndpoint: (id: string, description: string) => HangingSeam<EndpointEntry>;
138
+ /**
139
+ * Every fact an analysis states, measuring nothing.
140
+ *
141
+ * The whole of why `buildAssessment` exists is in this one declaration: a field
142
+ * added to `ChangeAnalysis` stops it compiling, here, in the lane that added
143
+ * the field. A surface's fixture that spelled the record out itself would
144
+ * instead keep compiling and start lying — ten of nineteen fields, the gap cast
145
+ * away, and the failure arriving later in whichever test is the next to narrow
146
+ * one of the nine it left out.
147
+ */
148
+ export declare const NOTHING_MEASURED: ChangeAnalysis;
149
+ /**
150
+ * The facts a test wants to be true of a judged change. Everything else is
151
+ * absent, empty or zero.
152
+ *
153
+ * What is *not* here is the point. A level, a reversible flag, a retained count
154
+ * and an inverse delta are all computed below from what this draft says,
155
+ * because each of the four is something the runtime derives and none is
156
+ * something a caller may contradict. The Gate's level is the highest of its
157
+ * factors; a change is reversible exactly when nothing says otherwise; the
158
+ * inverse retains what a removal destroyed. A draft that could set them
159
+ * independently could describe an assessment no run of Loom will ever produce,
160
+ * which is the one thing a published double must not let a test assert against.
161
+ */
162
+ export type AssessmentDraft = {
163
+ /** The change being judged. Its delta decides what the inverse is written against. */
164
+ readonly proposal: ProposedChange;
165
+ /** What the delta does. The fields left out measure zero. */
166
+ readonly analysis?: Partial<ChangeAnalysis>;
167
+ /** The rules the Gate raised, in the order it raised them. */
168
+ readonly factors?: readonly StakeFactor[];
169
+ /** Why the change cannot be taken back. Empty means it can. */
170
+ readonly irreversibilityReasons?: readonly IrreversibilityReason[];
171
+ /**
172
+ * Which of the write path's optional checks were in place. Empty by default,
173
+ * which is what a double has wired: the real seams need a registry, and a
174
+ * fixture claiming a check it never performed would put a reader's confidence
175
+ * in the wrong place.
176
+ */
177
+ readonly wiredChecks?: readonly WriteCheck[];
178
+ };
179
+ /**
180
+ * A complete `ChangeAssessment` from the handful of facts a test cares about.
181
+ *
182
+ * The third double of its kind and the first that had to be asked for. A
183
+ * surface needing one of these had two options and both are bad: run
184
+ * `assessChange` against a real tree, which means owning a tree and a registry
185
+ * to get at a number; or write the record out as a literal and cast the gap
186
+ * away, which is what three fixtures across two lanes did until a field was
187
+ * added underneath them.
188
+ *
189
+ * It is not `assessChange` and does not pretend to be. The real one measures a
190
+ * delta against a tree, so reaching a particular factor through it means
191
+ * crafting a delta that raises exactly that rule — which is the right test for
192
+ * the Gate and the wrong one for a screen that only needs a critical change to
193
+ * draw. This builds the record directly and keeps the three invariants that
194
+ * make the record coherent.
195
+ */
196
+ export declare const buildAssessment: (idFactory: IdFactory, draft: AssessmentDraft) => ChangeAssessment;
94
197
  //# sourceMappingURL=doubles.d.ts.map
@@ -1,4 +1,9 @@
1
+ import { z } from "zod";
2
+ import { defineSource } from "../data/adapter.js";
1
3
  import { ok } from "../result.js";
4
+ import { canonicalChecksOf } from "../runtime/checks.js";
5
+ import { highestStake } from "../runtime/stake-level.js";
6
+ import { defineEndpoint } from "../submit/endpoint.js";
2
7
  /**
3
8
  * Test doubles for the impure seams this file owns — the interpreter and its
4
9
  * repairer, the clock, and the event sink. The runtime's other two seams are
@@ -138,4 +143,142 @@ export const buildProposal = (idFactory, draft) => ({
138
143
  interpretedAt: FIXED_INSTANT,
139
144
  },
140
145
  });
146
+ /**
147
+ * Records what an abort said, in the one shape all three seams hand it over in.
148
+ */
149
+ const abortRecorder = () => {
150
+ let aborted;
151
+ return {
152
+ read: () => aborted,
153
+ listen: (signal) => {
154
+ signal?.addEventListener("abort", () => {
155
+ const { reason } = signal;
156
+ aborted = reason instanceof Error ? reason.message : "unnamed";
157
+ });
158
+ },
159
+ };
160
+ };
161
+ /**
162
+ * A source that never answers — the sibling of `hangingModelClient` at the data
163
+ * seam, published for the same reason.
164
+ *
165
+ * Every surface that renders a bound region has an "it did not come back" state
166
+ * to show, and a promise that is never resolved is the only honest imitation of
167
+ * an integration nobody is going to answer. Use it with a small `ceilingMs`;
168
+ * the default is ten seconds and a test that waits it out is a test nobody runs.
169
+ *
170
+ * Its params schema accepts anything, because a double whose whole job is to
171
+ * not answer must never be the thing that refuses first: a binding written
172
+ * against the real source it stands in for has to reach the adapter unchanged.
173
+ */
174
+ export const hangingSource = (id, description) => {
175
+ const abort = abortRecorder();
176
+ return {
177
+ entry: defineSource({
178
+ id,
179
+ description,
180
+ params: z.object({}).passthrough(),
181
+ answers: z.custom(),
182
+ adapter: {
183
+ fetch: ({ signal }) => new Promise(() => {
184
+ abort.listen(signal);
185
+ }),
186
+ },
187
+ }),
188
+ abortedWith: abort.read,
189
+ };
190
+ };
191
+ /**
192
+ * An endpoint that never says where a form posts — the same double at the
193
+ * submission seam.
194
+ *
195
+ * A form's target is resolved while the page is being served, so this is the
196
+ * state a token store having a very bad afternoon puts a page into, and the one
197
+ * a ceiling exists to bound (0140).
198
+ */
199
+ export const hangingEndpoint = (id, description) => {
200
+ const abort = abortRecorder();
201
+ return {
202
+ entry: defineEndpoint({
203
+ id,
204
+ description,
205
+ endpoint: {
206
+ target: ({ signal }) => new Promise(() => {
207
+ abort.listen(signal);
208
+ }),
209
+ },
210
+ }),
211
+ abortedWith: abort.read,
212
+ };
213
+ };
214
+ /**
215
+ * Every fact an analysis states, measuring nothing.
216
+ *
217
+ * The whole of why `buildAssessment` exists is in this one declaration: a field
218
+ * added to `ChangeAnalysis` stops it compiling, here, in the lane that added
219
+ * the field. A surface's fixture that spelled the record out itself would
220
+ * instead keep compiling and start lying — ten of nineteen fields, the gap cast
221
+ * away, and the failure arriving later in whichever test is the next to narrow
222
+ * one of the nine it left out.
223
+ */
224
+ export const NOTHING_MEASURED = {
225
+ operationCount: 0,
226
+ insertedNodeCount: 0,
227
+ removedNodeCount: 0,
228
+ movedNodeCount: 0,
229
+ configuredNodeCount: 0,
230
+ relocatedNodeCount: 0,
231
+ affectedNodeIds: [],
232
+ touchedPrimitiveTypes: [],
233
+ relocatedPrimitiveTypes: [],
234
+ removedPrimitiveTypes: [],
235
+ configuredPropKeys: [],
236
+ nestedTargets: [],
237
+ unknownPrimitives: [],
238
+ invalidProps: [],
239
+ unreadBindings: [],
240
+ unplacedSlots: [],
241
+ redirectedSubmissions: [],
242
+ repointedBindings: [],
243
+ shallowestAffectedDepth: 0,
244
+ };
245
+ /**
246
+ * A complete `ChangeAssessment` from the handful of facts a test cares about.
247
+ *
248
+ * The third double of its kind and the first that had to be asked for. A
249
+ * surface needing one of these had two options and both are bad: run
250
+ * `assessChange` against a real tree, which means owning a tree and a registry
251
+ * to get at a number; or write the record out as a literal and cast the gap
252
+ * away, which is what three fixtures across two lanes did until a field was
253
+ * added underneath them.
254
+ *
255
+ * It is not `assessChange` and does not pretend to be. The real one measures a
256
+ * delta against a tree, so reaching a particular factor through it means
257
+ * crafting a delta that raises exactly that rule — which is the right test for
258
+ * the Gate and the wrong one for a screen that only needs a critical change to
259
+ * draw. This builds the record directly and keeps the three invariants that
260
+ * make the record coherent.
261
+ */
262
+ export const buildAssessment = (idFactory, draft) => {
263
+ const analysis = { ...NOTHING_MEASURED, ...draft.analysis };
264
+ const factors = draft.factors ?? [];
265
+ const reasons = draft.irreversibilityReasons ?? [];
266
+ return {
267
+ proposal: draft.proposal,
268
+ analysis,
269
+ stakes: { level: highestStake(factors.map((factor) => factor.level)), factors },
270
+ reversibility: {
271
+ reversible: reasons.length === 0,
272
+ inverse: {
273
+ deltaId: idFactory.deltaId(),
274
+ treeId: draft.proposal.delta.treeId,
275
+ baseRevision: draft.proposal.delta.baseRevision + 1,
276
+ operations: [],
277
+ },
278
+ retainedNodeCount: analysis.removedNodeCount,
279
+ reasons,
280
+ },
281
+ wiredChecks: canonicalChecksOf(draft.wiredChecks ?? []),
282
+ };
283
+ };
141
284
  //# sourceMappingURL=doubles.js.map
@@ -31,8 +31,8 @@
31
31
  * a browser, which is the property the course's in-page runner needs and the
32
32
  * one `surface.test.ts` holds.
33
33
  */
34
- export { cardDefinition, footerDefinition, headerDefinition, pageDefinition, registryOf, testDefinitions, testRegistry, } from "./definitions.js";
35
- export { buildIntent, buildProposal, collectingEventSink, failingEventSink, fixedClock, FIXED_INSTANT, hangingModelClient, scriptedInterpreter, scriptedModelClient, scriptedRepairer, type CollectingEventSink, type HangingModelClient, type IntentDraft, type ProposalDraft, type RecordingInterpreter, type RecordingModelClient, type RecordingRepairer, } from "./doubles.js";
34
+ export { brokenUnshownDefinition, cardDefinition, footerDefinition, headerDefinition, pageDefinition, registryOf, testDefinitions, testRegistry, UNSHOWN_BREAKAGES, type UnshownBreakage, } from "./definitions.js";
35
+ export { buildAssessment, buildIntent, buildProposal, collectingEventSink, failingEventSink, fixedClock, FIXED_INSTANT, hangingEndpoint, hangingModelClient, hangingSource, NOTHING_MEASURED, scriptedInterpreter, scriptedModelClient, scriptedRepairer, type AssessmentDraft, type CollectingEventSink, type HangingModelClient, type HangingSeam, type IntentDraft, type ProposalDraft, type RecordingInterpreter, type RecordingModelClient, type RecordingRepairer, } from "./doubles.js";
36
36
  export { harnessWith, proposalScript, removalDelta, type EpisodeHarness, } from "./episode-harness.js";
37
37
  export { memoryFileSystem, type MemoryFileSystem, type MemoryFileSystemOptions, } from "./filesystem.js";
38
38
  export { formTree, sampleTree, type FormTree, type SampleTree } from "./fixtures.js";
@@ -31,8 +31,8 @@
31
31
  * a browser, which is the property the course's in-page runner needs and the
32
32
  * one `surface.test.ts` holds.
33
33
  */
34
- export { cardDefinition, footerDefinition, headerDefinition, pageDefinition, registryOf, testDefinitions, testRegistry, } from "./definitions.js";
35
- export { buildIntent, buildProposal, collectingEventSink, failingEventSink, fixedClock, FIXED_INSTANT, hangingModelClient, scriptedInterpreter, scriptedModelClient, scriptedRepairer, } from "./doubles.js";
34
+ export { brokenUnshownDefinition, cardDefinition, footerDefinition, headerDefinition, pageDefinition, registryOf, testDefinitions, testRegistry, UNSHOWN_BREAKAGES, } from "./definitions.js";
35
+ export { buildAssessment, buildIntent, buildProposal, collectingEventSink, failingEventSink, fixedClock, FIXED_INSTANT, hangingEndpoint, hangingModelClient, hangingSource, NOTHING_MEASURED, scriptedInterpreter, scriptedModelClient, scriptedRepairer, } from "./doubles.js";
36
36
  export { harnessWith, proposalScript, removalDelta, } from "./episode-harness.js";
37
37
  export { memoryFileSystem, } from "./filesystem.js";
38
38
  export { formTree, sampleTree } from "./fixtures.js";
@@ -1,9 +1,9 @@
1
1
  import { describe, expect, it } from "vitest";
2
2
  import { sequentialIdFactory, treeIdSchema } from "../ids.js";
3
- import { recordOf } from "../telemetry/index.js";
3
+ import { MAX_ASSESSMENT_LOOKUP, recordOf, } from "../telemetry/index.js";
4
4
  import { buildElement } from "../tree/builders.js";
5
5
  import { createTree } from "../tree/tree.js";
6
- import { buildIntent, buildProposal, FIXED_INSTANT } from "./doubles.js";
6
+ import { buildAssessment, buildIntent, buildProposal, FIXED_INSTANT } from "./doubles.js";
7
7
  /**
8
8
  * One suite, run against every `TelemetryJournal`.
9
9
  *
@@ -60,6 +60,32 @@ const recordsFor = (treeId, count) => Array.from({ length: count }, (_, index) =
60
60
  },
61
61
  }));
62
62
  const typesOf = (records) => records.map((record) => record.event.type);
63
+ /**
64
+ * One `change-assessed` record, narrowed the way a host's would be.
65
+ *
66
+ * Through `buildAssessment` and `recordOf` rather than written out as a literal,
67
+ * so the suite is asserting against a record a real run of Loom could produce —
68
+ * the rule the 3 October fixture entry was filed about.
69
+ */
70
+ const assessedRecord = (treeId, namespace, options = {}) => {
71
+ const ids = sequentialIdFactory(namespace);
72
+ const proposal = buildProposal(ids, {
73
+ intentId: ids.intentId(),
74
+ delta: { deltaId: ids.deltaId(), treeId, baseRevision: 0, operations: [] },
75
+ });
76
+ const assessment = buildAssessment(ids, {
77
+ proposal,
78
+ analysis: { removedNodeCount: options.removedNodeCount ?? 0 },
79
+ });
80
+ return {
81
+ record: recordOf({
82
+ treeId,
83
+ occurredAt: FIXED_INSTANT,
84
+ event: { type: "change-assessed", assessment },
85
+ }),
86
+ proposalId: proposal.proposalId,
87
+ };
88
+ };
63
89
  export const describeTelemetryJournalContract = (name, makeJournal) => {
64
90
  const freshJournal = async () => await makeJournal();
65
91
  describe(`${name} — TelemetryJournal contract`, () => {
@@ -181,6 +207,118 @@ export const describeTelemetryJournalContract = (name, makeJournal) => {
181
207
  expect(past).toEqual({ ok: true, value: { records: [], older: null, newer: null } });
182
208
  });
183
209
  });
210
+ /**
211
+ * The join, not a page.
212
+ *
213
+ * A revision log holds a `proposalId` and no judgment (0016, 0225), so the
214
+ * only way a screen can say *undoing this will not undo everything* is to
215
+ * ask the journal about the proposals it is already holding. What a journal
216
+ * owes is that both implementations answer the same way about an id it has
217
+ * never heard of, about an id narrated twice, and about more ids than one
218
+ * lookup reaches.
219
+ */
220
+ describe("looking an assessment up by proposal", () => {
221
+ it("answers about the proposals it was asked about and no others", async () => {
222
+ const journal = await freshJournal();
223
+ const treeId = treeIdSchema.parse("t_lookup");
224
+ const wanted = assessedRecord(treeId, "want", { removedNodeCount: 3 });
225
+ const other = assessedRecord(treeId, "other");
226
+ await journal.record([wanted.record, other.record]);
227
+ const found = await journal.assessments({ proposalIds: [wanted.proposalId] });
228
+ expect(found.ok && [...found.value.assessments.keys()]).toEqual([wanted.proposalId]);
229
+ expect(found.ok && found.value.assessments.get(wanted.proposalId)?.removedNodeCount).toBe(3);
230
+ expect(found.ok && found.value.unasked).toEqual([]);
231
+ });
232
+ /** The same reason there is no `not-found`: a journal claims nothing exists. */
233
+ it("leaves a proposal it has never heard of out of the map rather than failing", async () => {
234
+ const journal = await freshJournal();
235
+ const treeId = treeIdSchema.parse("t_absentlookup");
236
+ const known = assessedRecord(treeId, "known");
237
+ const stranger = assessedRecord(treeId, "stranger");
238
+ await journal.record([known.record]);
239
+ const found = await journal.assessments({
240
+ proposalIds: [known.proposalId, stranger.proposalId],
241
+ });
242
+ expect(found.ok && found.value.assessments.has(known.proposalId)).toBe(true);
243
+ expect(found.ok && found.value.assessments.has(stranger.proposalId)).toBe(false);
244
+ expect(found.ok && found.value.unasked).toEqual([]);
245
+ });
246
+ it("asks nothing and answers emptily for an empty lookup", async () => {
247
+ const journal = await freshJournal();
248
+ expect(await journal.assessments({ proposalIds: [] })).toEqual({
249
+ ok: true,
250
+ value: { assessments: new Map(), unasked: [] },
251
+ });
252
+ });
253
+ /**
254
+ * A journal is append-only, so a proposal narrated twice is a history
255
+ * rather than a fault — and the later record is the one that describes
256
+ * what the Gate last read.
257
+ */
258
+ it("answers with the latest assessment when a proposal was narrated twice", async () => {
259
+ const journal = await freshJournal();
260
+ const treeId = treeIdSchema.parse("t_twice");
261
+ const first = assessedRecord(treeId, "twice", { removedNodeCount: 1 });
262
+ const second = assessedRecord(treeId, "twice", { removedNodeCount: 9 });
263
+ await journal.record([first.record, second.record]);
264
+ const found = await journal.assessments({ proposalIds: [first.proposalId] });
265
+ expect(first.proposalId).toEqual(second.proposalId);
266
+ expect(found.ok && found.value.assessments.get(first.proposalId)?.removedNodeCount).toBe(9);
267
+ });
268
+ it("counts a repeated id once rather than spending the lookup on it", async () => {
269
+ const journal = await freshJournal();
270
+ const treeId = treeIdSchema.parse("t_repeat");
271
+ const one = assessedRecord(treeId, "repeat");
272
+ await journal.record([one.record]);
273
+ const found = await journal.assessments({
274
+ proposalIds: Array.from({ length: MAX_ASSESSMENT_LOOKUP + 1 }, () => one.proposalId),
275
+ });
276
+ expect(found.ok && found.value.assessments.size).toBe(1);
277
+ expect(found.ok && found.value.unasked).toEqual([]);
278
+ });
279
+ /**
280
+ * Every read in Loom is bounded. What this pins is that going over the
281
+ * bound is *said* rather than silently dropped: on the screen this exists
282
+ * for, "nothing was recorded" and "nobody looked" would otherwise be the
283
+ * same blank.
284
+ */
285
+ it("names the ids beyond the cap instead of dropping them", async () => {
286
+ const journal = await freshJournal();
287
+ const treeId = treeIdSchema.parse("t_cap");
288
+ const asked = Array.from({ length: MAX_ASSESSMENT_LOOKUP + 2 }, (_, index) => assessedRecord(treeId, `cap${index}`).proposalId);
289
+ const found = await journal.assessments({ proposalIds: asked });
290
+ expect(found.ok && found.value.unasked).toEqual(asked.slice(MAX_ASSESSMENT_LOOKUP));
291
+ });
292
+ it("keeps trees apart when a lookup names one", async () => {
293
+ const journal = await freshJournal();
294
+ const mine = treeIdSchema.parse("t_minelookup");
295
+ const yours = treeIdSchema.parse("t_yourslookup");
296
+ const ours = assessedRecord(yours, "ours");
297
+ await journal.record([ours.record]);
298
+ const wrongTree = await journal.assessments({
299
+ proposalIds: [ours.proposalId],
300
+ treeId: mine,
301
+ });
302
+ const rightTree = await journal.assessments({
303
+ proposalIds: [ours.proposalId],
304
+ treeId: yours,
305
+ });
306
+ expect(wrongTree.ok && wrongTree.value.assessments.size).toBe(0);
307
+ expect(rightTree.ok && rightTree.value.assessments.size).toBe(1);
308
+ });
309
+ /** A record a prune has forgotten is a record nothing can join against. */
310
+ it("stops answering about a proposal whose record was forgotten", async () => {
311
+ const journal = await freshJournal();
312
+ const treeId = treeIdSchema.parse("t_forgotten");
313
+ const gone = assessedRecord(treeId, "gone");
314
+ await journal.record([gone.record]);
315
+ const page = await journal.read();
316
+ const last = page.ok ? page.value.records.at(-1) : undefined;
317
+ await journal.forget({ before: (last?.seq ?? 0) + 1 });
318
+ const found = await journal.assessments({ proposalIds: [gone.proposalId] });
319
+ expect(found.ok && found.value.assessments.size).toBe(0);
320
+ });
321
+ });
184
322
  /**
185
323
  * The destructive half. Every rule about *what* may go lives in
186
324
  * `retention.ts`; what a journal owes is that a position means the same
@@ -0,0 +1,110 @@
1
+ import type { ModelClient } from "../interpretation/client.js";
2
+ import type { ModelRequest } from "../interpretation/client.js";
3
+ /**
4
+ * One suite, run against every `ModelClient`.
5
+ *
6
+ * `ModelClient` is the seam a host is likeliest to implement — 0005 made the
7
+ * vendor adapter opt-in precisely so a host could bring its own — and it is the
8
+ * only published seam that had no suite. The three stores and the journal each
9
+ * got one as soon as there were two implementations; this one has had exactly
10
+ * one implementation since day 37, so the promises it makes have been held by
11
+ * `anthropic.test.ts` and by nothing a host can run.
12
+ *
13
+ * **The promises are not in the type, and they are not obvious.** `complete`
14
+ * returns `Promise<Result<…>>` on paper whatever an implementation does with a
15
+ * socket that closes; what the runtime needs is narrower, and all of it is
16
+ * invisible to the compiler:
17
+ *
18
+ * - The five error codes name *who must act*, not what went wrong. A key the
19
+ * service rejects and a rate limit are both "it did not answer"; one needs an
20
+ * operator and the other needs a wait, and an implementation that collapses
21
+ * them tells a host to stop trying something that would have worked. They
22
+ * were one code until day 37, and the merge was a lie downstream could not
23
+ * detect.
24
+ * - The reply text crosses **unchanged**. Parsing, validating and deciding what
25
+ * a bad answer means live above this seam (0005), so an adapter that trims,
26
+ * unwraps a fence or parses on the way through has moved a decision below the
27
+ * line and taken it away from the tests that cover it.
28
+ * - Nothing throws. The interpreter reads a `Result`; a rejected promise from
29
+ * this call is an exception on a path that has no handler.
30
+ *
31
+ * ## What a host supplies
32
+ *
33
+ * Not a client — a **situation**, answered for every member of `ModelSituation`.
34
+ * A suite that took one client could check that a success is a success and
35
+ * nothing else, because nobody can make a real service return a 402 on demand.
36
+ * So the host wires each situation to whatever their vendor does in it, the
37
+ * same way `anthropic.test.ts` stubs `messages.create`, and this suite says
38
+ * what the answer has to be.
39
+ *
40
+ * It is a record keyed by every situation rather than a list of the ones a host
41
+ * felt like covering, and `everyMemberOf` makes that a compile-time fact: a
42
+ * situation added here stops every host's call compiling until they have
43
+ * answered it. A list would have gone quietly out of date on the first one.
44
+ */
45
+ /**
46
+ * What happened, in terms every vendor has rather than one vendor's.
47
+ *
48
+ * Each member is a thing that demonstrably occurs on a real service and that an
49
+ * adapter has to turn into one of the five codes. The HTTP statuses are grouped
50
+ * by the answer they require rather than listed, because the question this suite
51
+ * asks is never "is 402 handled" — it is "does this implementation know that
52
+ * only an operator can clear a 402".
53
+ */
54
+ export type ModelSituation =
55
+ /** The service answered, with this text, served by this model. */
56
+ "answers"
57
+ /** The service answered, and there was nothing in the reply that was text. */
58
+ | "answers-without-text"
59
+ /** The answer stopped at the output ceiling, mid-sentence. */
60
+ | "truncates"
61
+ /** The model declined to answer this content. */
62
+ | "refuses"
63
+ /** A credential, entitlement or billing problem: 401, 402, 403. */
64
+ | "refuses-the-caller"
65
+ /** The request itself is wrong and would fail again unchanged: 400, 404, 413, 422. */
66
+ | "refuses-the-request"
67
+ /** Busy now, fine later: 408, 409, 429, 500, 503. */
68
+ | "asks-for-later"
69
+ /** No response at all — a closed socket, a DNS failure, a TLS error. */
70
+ | "never-answers";
71
+ export declare const MODEL_SITUATIONS: readonly ModelSituation[];
72
+ /**
73
+ * The text this suite sends through, and the model it says served it.
74
+ *
75
+ * **Deliberately dirty, and that is the whole value of it.** A real reply
76
+ * sometimes arrives wrapped in a code fence with whitespace around it, and an
77
+ * adapter is *not* allowed to clean that up: what a malformed answer means is
78
+ * the interpreter's decision and is covered by the interpreter's own tests
79
+ * (0005). An adapter that trims has moved that decision below the seam, where
80
+ * nothing watches it.
81
+ *
82
+ * This was found by breaking it. The first version of this constant was the
83
+ * bare reply, and an adapter mutated to `text.trim().replace(/^```json/, "")`
84
+ * passed all twenty-five cases — because a no-op on clean input is
85
+ * indistinguishable from doing nothing. The fence and the newlines are what
86
+ * make the assertion an assertion.
87
+ *
88
+ * `INSERT_NOTE_REPLY` inside it rather than a lorem string, so an adapter that
89
+ * parses and re-serialises produces valid JSON that still fails the comparison.
90
+ */
91
+ export declare const CONTRACT_REPLY: string;
92
+ export declare const CONTRACT_SERVED_BY = "a-model-that-served-it";
93
+ /**
94
+ * A client wired to behave as one situation does, or a statement that this
95
+ * vendor has no such situation.
96
+ *
97
+ * `"not-expressible"` is a claim, not a skip, and the difference is the whole
98
+ * reason it is spelled out. A vendor with no distinct refusal signal reports a
99
+ * declined answer some other way, and an adapter that invented a `refused` for
100
+ * it would be worse than one that said so. What the suite then checks is the
101
+ * honest remainder: that the situation really cannot be produced is the host's
102
+ * word, and the suite holds them to using one of the five codes for whatever
103
+ * they *do* produce instead.
104
+ */
105
+ export type ModelSituationClient = (() => ModelClient | Promise<ModelClient>) | "not-expressible";
106
+ export type ModelClientContract = Readonly<Record<ModelSituation, ModelSituationClient>>;
107
+ /** The request every case sends. Fixed, because none of these turn on its content. */
108
+ export declare const contractRequest: () => ModelRequest;
109
+ export declare const describeModelClientContract: (name: string, contract: ModelClientContract) => void;
110
+ //# sourceMappingURL=model-contract.d.ts.map