@jam-overture/loom 0.2.0 → 0.3.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 (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -0,0 +1,354 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { audienceIdSchema } from "../audience/audience.js";
3
+ import { treeIdSchema } from "../ids.js";
4
+ import { treeDeltaSchema } from "../tree/delta.js";
5
+ /**
6
+ * One suite, run against every `AudienceOverlayStore`.
7
+ *
8
+ * `memoryAudienceOverlayStore` calls itself the reference implementation; this
9
+ * is what makes that claim checkable rather than aspirational, on the terms
10
+ * `store-contract.ts`, `policy-log-contract.ts` and `project-contract.ts`
11
+ * already set. The alternative — each store asserted against its own
12
+ * expectations — is how two stores that disagree both stay green.
13
+ *
14
+ * What is checked here is what the type cannot say: that the rules are a log
15
+ * rather than a column, that their order survives a round trip, that a save
16
+ * with nothing in it does not append, that two editors racing cannot both
17
+ * commit, that a form is replaced rather than accumulated, and that a
18
+ * withdrawn form stops being served without ceasing to exist (0403).
19
+ */
20
+ export const CONTRACT_TREE = treeIdSchema.parse("t_overlaycontract");
21
+ export const audienceNamed = (name) => audienceIdSchema.parse(`aud_${name}`);
22
+ export const ruleFor = (audienceId, key, value) => ({
23
+ audienceId,
24
+ clauses: [{ key, anyOf: [value] }],
25
+ });
26
+ /**
27
+ * A delta that is well-formed and is never applied by this suite — what is
28
+ * under test is custody, not composition, which `compose.test.ts` covers
29
+ * against the tree it belongs to.
30
+ */
31
+ export const formDelta = (over = {}) => treeDeltaSchema.parse({
32
+ deltaId: "d_contract",
33
+ treeId: CONTRACT_TREE,
34
+ baseRevision: 3,
35
+ operations: [{ op: "remove", nodeId: "n_footer" }],
36
+ ...over,
37
+ });
38
+ const EU = audienceNamed("eu");
39
+ const UK = audienceNamed("uk");
40
+ const recording = (rules, over = {}) => ({
41
+ rules,
42
+ actor: "person:ana",
43
+ recordedAt: "2026-11-10T09:00:00.000Z",
44
+ ...over,
45
+ });
46
+ const authoring = (audienceId, delta = formDelta()) => ({
47
+ audienceId,
48
+ delta,
49
+ actor: "person:ana",
50
+ authoredAt: "2026-11-10T09:00:00.000Z",
51
+ });
52
+ /** A different person at a later hour than `authoring`, so an overwritten author would show. */
53
+ const withdrawing = (audienceId, over = {}) => ({
54
+ audienceId,
55
+ actor: "person:ben",
56
+ withdrawnAt: "2026-11-11T09:00:00.000Z",
57
+ ...over,
58
+ });
59
+ export const describeAudienceOverlayStoreContract = (name, make) => {
60
+ describe(`${name} — the audience overlay contract`, () => {
61
+ it("answers an empty overlay for a page nobody has written rules for, rather than not-found", async () => {
62
+ const store = await make();
63
+ expect(await store.overlay(CONTRACT_TREE)).toEqual({
64
+ ok: true,
65
+ value: { rules: [], forms: [] },
66
+ });
67
+ expect(await store.rules(CONTRACT_TREE)).toEqual({ ok: true, value: undefined });
68
+ });
69
+ it("reads back the rules it recorded, as revision 1", async () => {
70
+ const store = await make();
71
+ const rules = [ruleFor(EU, "region", "eu")];
72
+ const recorded = await store.recordRules(CONTRACT_TREE, recording(rules));
73
+ expect(recorded.ok && recorded.value.outcome).toBe("recorded");
74
+ expect(recorded.ok && recorded.value.revision.revision).toBe(1);
75
+ expect(recorded.ok && recorded.value.revision.actor).toBe("person:ana");
76
+ const read = await store.rules(CONTRACT_TREE);
77
+ expect(read.ok && read.value?.rules).toEqual(rules);
78
+ });
79
+ /**
80
+ * The property the whole table exists for. The order is the precedence — the
81
+ * last matching rule wins a contested node — so a store that round-trips
82
+ * the same rules in another order has changed what the deployment serves
83
+ * without anybody editing anything (0359).
84
+ */
85
+ it("keeps the rule order, which is the precedence", async () => {
86
+ const store = await make();
87
+ const general = ruleFor(EU, "region", "eu");
88
+ const specific = ruleFor(UK, "country", "gb");
89
+ await store.recordRules(CONTRACT_TREE, recording([general, specific]));
90
+ const read = await store.overlay(CONTRACT_TREE);
91
+ expect(read.ok && read.value.rules.map((rule) => rule.audienceId)).toEqual([EU, UK]);
92
+ });
93
+ it("appends rather than overwriting, so who changed who sees what is a record", async () => {
94
+ const store = await make();
95
+ await store.recordRules(CONTRACT_TREE, recording([ruleFor(EU, "region", "eu")]));
96
+ const second = await store.recordRules(CONTRACT_TREE, recording([ruleFor(EU, "region", "eu"), ruleFor(UK, "country", "gb")], {
97
+ actor: "person:ben",
98
+ recordedAt: "2026-11-10T10:00:00.000Z",
99
+ }));
100
+ expect(second.ok && second.value.revision.revision).toBe(2);
101
+ expect(second.ok && second.value.revision.actor).toBe("person:ben");
102
+ });
103
+ /**
104
+ * The read that makes the log a record. A store that overwrote instead of
105
+ * appending would pass every other assertion here: the revision numbers
106
+ * come off the head either way.
107
+ */
108
+ it("keeps every edit, newest first, so who changed who sees what can be read back", async () => {
109
+ const store = await make();
110
+ await store.recordRules(CONTRACT_TREE, recording([ruleFor(EU, "region", "eu")]));
111
+ await store.recordRules(CONTRACT_TREE, recording([ruleFor(UK, "country", "gb")], {
112
+ actor: "person:ben",
113
+ recordedAt: "2026-11-10T10:00:00.000Z",
114
+ }));
115
+ const history = await store.history(CONTRACT_TREE);
116
+ expect(history.ok && history.value.map((edit) => [edit.revision, edit.actor])).toEqual([
117
+ [2, "person:ben"],
118
+ [1, "person:ana"],
119
+ ]);
120
+ });
121
+ it("answers an empty history for a page nobody has written rules for", async () => {
122
+ const store = await make();
123
+ expect(await store.history(CONTRACT_TREE)).toEqual({ ok: true, value: [] });
124
+ });
125
+ it("bounds the history it hands back, whether a caller names a large limit or none", async () => {
126
+ const store = await make();
127
+ for (const index of [0, 1, 2]) {
128
+ await store.recordRules(CONTRACT_TREE, recording([ruleFor(EU, "region", `eu${index}`)], {
129
+ recordedAt: `2026-11-10T0${index}:00:00.000Z`,
130
+ }));
131
+ }
132
+ const asked = await store.history(CONTRACT_TREE, { limit: 2 });
133
+ const flooded = await store.history(CONTRACT_TREE, { limit: 10_000 });
134
+ expect(asked.ok && asked.value).toHaveLength(2);
135
+ expect(flooded.ok && flooded.value).toHaveLength(3);
136
+ });
137
+ it("does not record an unchanged save in the history", async () => {
138
+ const store = await make();
139
+ const rules = [ruleFor(EU, "region", "eu")];
140
+ await store.recordRules(CONTRACT_TREE, recording(rules));
141
+ await store.recordRules(CONTRACT_TREE, recording(rules, { actor: "person:ben" }));
142
+ const history = await store.history(CONTRACT_TREE);
143
+ expect(history.ok && history.value).toHaveLength(1);
144
+ });
145
+ it("treats the same rules in the same order as unchanged, so a screen that saves on blur writes nothing", async () => {
146
+ const store = await make();
147
+ const rules = [ruleFor(EU, "region", "eu")];
148
+ await store.recordRules(CONTRACT_TREE, recording(rules));
149
+ const again = await store.recordRules(CONTRACT_TREE, recording(rules, { actor: "person:ben", recordedAt: "2026-11-10T11:00:00.000Z" }));
150
+ expect(again.ok && again.value.outcome).toBe("unchanged");
151
+ expect(again.ok && again.value.revision.revision).toBe(1);
152
+ expect(again.ok && again.value.revision.actor).toBe("person:ana");
153
+ });
154
+ /** A reorder is an edit, because the order is the thing that decides. */
155
+ it("treats the same rules in another order as an edit", async () => {
156
+ const store = await make();
157
+ const general = ruleFor(EU, "region", "eu");
158
+ const specific = ruleFor(UK, "country", "gb");
159
+ await store.recordRules(CONTRACT_TREE, recording([general, specific]));
160
+ const flipped = await store.recordRules(CONTRACT_TREE, recording([specific, general]));
161
+ expect(flipped.ok && flipped.value.outcome).toBe("recorded");
162
+ expect(flipped.ok && flipped.value.revision.revision).toBe(2);
163
+ });
164
+ it("refuses an edit of a revision that is no longer the current one", async () => {
165
+ const store = await make();
166
+ await store.recordRules(CONTRACT_TREE, recording([ruleFor(EU, "region", "eu")]));
167
+ const lost = await store.recordRules(CONTRACT_TREE, recording([ruleFor(UK, "country", "gb")], { expectedRevision: 0 }));
168
+ expect(lost).toEqual({
169
+ ok: false,
170
+ error: { code: "out-of-date", treeId: CONTRACT_TREE, expected: 0, current: 1 },
171
+ });
172
+ const read = await store.rules(CONTRACT_TREE);
173
+ expect(read.ok && read.value?.rules[0]?.audienceId).toBe(EU);
174
+ });
175
+ it("records an empty list, because a page served to everybody the same way is a decision somebody made", async () => {
176
+ const store = await make();
177
+ await store.recordRules(CONTRACT_TREE, recording([ruleFor(EU, "region", "eu")]));
178
+ const cleared = await store.recordRules(CONTRACT_TREE, recording([]));
179
+ expect(cleared.ok && cleared.value.revision.revision).toBe(2);
180
+ const read = await store.overlay(CONTRACT_TREE);
181
+ expect(read.ok && read.value.rules).toEqual([]);
182
+ });
183
+ it("refuses an actor nobody is named by and a stamp that is not an instant", async () => {
184
+ const store = await make();
185
+ const unattributed = await store.recordRules(CONTRACT_TREE, recording([], { actor: "" }));
186
+ const unstamped = await store.recordRules(CONTRACT_TREE, recording([], { recordedAt: "yesterday" }));
187
+ expect(unattributed.ok).toBe(false);
188
+ expect(unstamped.ok).toBe(false);
189
+ expect(await store.rules(CONTRACT_TREE)).toEqual({ ok: true, value: undefined });
190
+ });
191
+ it("reads back a form under the audience that earned it", async () => {
192
+ const store = await make();
193
+ expect(await store.setForm(CONTRACT_TREE, authoring(EU))).toEqual({
194
+ ok: true,
195
+ value: {
196
+ treeId: CONTRACT_TREE,
197
+ audienceId: EU,
198
+ delta: formDelta(),
199
+ actor: "person:ana",
200
+ authoredAt: "2026-11-10T09:00:00.000Z",
201
+ },
202
+ });
203
+ const read = await store.overlay(CONTRACT_TREE);
204
+ expect(read.ok && read.value.forms).toEqual([{ audienceId: EU, delta: formDelta() }]);
205
+ });
206
+ it("replaces an audience's form rather than keeping both, which is what rebasing one is", async () => {
207
+ const store = await make();
208
+ await store.setForm(CONTRACT_TREE, authoring(EU));
209
+ const rebased = formDelta({ baseRevision: 4 });
210
+ await store.setForm(CONTRACT_TREE, authoring(EU, rebased));
211
+ const read = await store.overlay(CONTRACT_TREE);
212
+ expect(read.ok && read.value.forms).toEqual([{ audienceId: EU, delta: rebased }]);
213
+ });
214
+ it("keeps two audiences' forms apart", async () => {
215
+ const store = await make();
216
+ await store.setForm(CONTRACT_TREE, authoring(EU));
217
+ await store.setForm(CONTRACT_TREE, authoring(UK, formDelta({ baseRevision: 5 })));
218
+ const read = await store.overlay(CONTRACT_TREE);
219
+ expect(read.ok && read.value.forms.map((form) => form.audienceId)).toEqual([EU, UK]);
220
+ });
221
+ /**
222
+ * The reading a moved base makes necessary — *a base edit stales every
223
+ * audience delta* — without the deltas, which is the whole reason the
224
+ * listing is a separate read (0359).
225
+ */
226
+ it("lists a form's base revision without handing over its delta", async () => {
227
+ const store = await make();
228
+ await store.setForm(CONTRACT_TREE, authoring(EU, formDelta({ baseRevision: 7 })));
229
+ expect(await store.forms(CONTRACT_TREE)).toEqual({
230
+ ok: true,
231
+ value: [
232
+ {
233
+ audienceId: EU,
234
+ baseRevision: 7,
235
+ actor: "person:ana",
236
+ authoredAt: "2026-11-10T09:00:00.000Z",
237
+ withdrawn: undefined,
238
+ },
239
+ ],
240
+ });
241
+ });
242
+ it("refuses a form carrying a delta for another page, which could never be served", async () => {
243
+ const store = await make();
244
+ const elsewhere = treeIdSchema.parse("t_elsewhere");
245
+ const refused = await store.setForm(CONTRACT_TREE, authoring(EU, formDelta({ treeId: elsewhere })));
246
+ expect(refused).toEqual({
247
+ ok: false,
248
+ error: { code: "tree-mismatch", treeId: CONTRACT_TREE, delta: elsewhere },
249
+ });
250
+ const read = await store.overlay(CONTRACT_TREE);
251
+ expect(read.ok && read.value.forms).toEqual([]);
252
+ });
253
+ /**
254
+ * The act a withdrawal exists for (0403), and the one assertion in this
255
+ * file that is about what a **reader** is served rather than about custody:
256
+ * a segment whose form has been withdrawn composes to the base, because the
257
+ * render path is handed no form for it at all.
258
+ */
259
+ it("stops serving a withdrawn form, which is how a segment's last change is undone", async () => {
260
+ const store = await make();
261
+ await store.setForm(CONTRACT_TREE, authoring(EU));
262
+ const withdrawn = await store.withdrawForm(CONTRACT_TREE, withdrawing(EU));
263
+ expect(withdrawn.ok && withdrawn.value?.withdrawn).toEqual({
264
+ actor: "person:ben",
265
+ at: "2026-11-11T09:00:00.000Z",
266
+ });
267
+ const read = await store.overlay(CONTRACT_TREE);
268
+ expect(read.ok && read.value.forms).toEqual([]);
269
+ });
270
+ /**
271
+ * The no-delete rule, kept (0376). A withdrawal that deleted the row would
272
+ * pass the assertion above and fail this one, which is the difference that
273
+ * matters: *we stopped serving this* and *we threw the work away* are two
274
+ * acts, and only the first one happened.
275
+ */
276
+ it("keeps a withdrawn form's delta and its author, so the work is there when it is wanted", async () => {
277
+ const store = await make();
278
+ await store.setForm(CONTRACT_TREE, authoring(EU, formDelta({ baseRevision: 7 })));
279
+ await store.withdrawForm(CONTRACT_TREE, withdrawing(EU));
280
+ expect(await store.forms(CONTRACT_TREE)).toEqual({
281
+ ok: true,
282
+ value: [
283
+ {
284
+ audienceId: EU,
285
+ baseRevision: 7,
286
+ actor: "person:ana",
287
+ authoredAt: "2026-11-10T09:00:00.000Z",
288
+ withdrawn: { actor: "person:ben", at: "2026-11-11T09:00:00.000Z" },
289
+ },
290
+ ],
291
+ });
292
+ });
293
+ it("puts a withdrawn form back into service when it is written again", async () => {
294
+ const store = await make();
295
+ await store.setForm(CONTRACT_TREE, authoring(EU));
296
+ await store.withdrawForm(CONTRACT_TREE, withdrawing(EU));
297
+ const again = await store.setForm(CONTRACT_TREE, authoring(EU));
298
+ expect(again.ok && again.value.withdrawn).toBeUndefined();
299
+ const read = await store.overlay(CONTRACT_TREE);
300
+ expect(read.ok && read.value.forms.map((form) => form.audienceId)).toEqual([EU]);
301
+ const listed = await store.forms(CONTRACT_TREE);
302
+ expect(listed.ok && listed.value[0]?.withdrawn).toBeUndefined();
303
+ });
304
+ /**
305
+ * Not an error, because the caller undoing a change wants that segment
306
+ * served the base and a page with no form for it is already in that state.
307
+ * `undefined` rather than a row is how a caller tells the two apart.
308
+ */
309
+ it("answers nothing, and not an error, for a form the page does not have", async () => {
310
+ const store = await make();
311
+ expect(await store.withdrawForm(CONTRACT_TREE, withdrawing(EU))).toEqual({
312
+ ok: true,
313
+ value: undefined,
314
+ });
315
+ });
316
+ it("restamps a form that is already withdrawn rather than refusing", async () => {
317
+ const store = await make();
318
+ await store.setForm(CONTRACT_TREE, authoring(EU));
319
+ await store.withdrawForm(CONTRACT_TREE, withdrawing(EU));
320
+ const again = await store.withdrawForm(CONTRACT_TREE, withdrawing(EU, { actor: "person:cat", withdrawnAt: "2026-11-12T09:00:00.000Z" }));
321
+ expect(again.ok && again.value?.withdrawn).toEqual({
322
+ actor: "person:cat",
323
+ at: "2026-11-12T09:00:00.000Z",
324
+ });
325
+ });
326
+ it("withdraws one audience's form and leaves the other's being served", async () => {
327
+ const store = await make();
328
+ await store.setForm(CONTRACT_TREE, authoring(EU));
329
+ await store.setForm(CONTRACT_TREE, authoring(UK));
330
+ await store.withdrawForm(CONTRACT_TREE, withdrawing(EU));
331
+ const read = await store.overlay(CONTRACT_TREE);
332
+ expect(read.ok && read.value.forms.map((form) => form.audienceId)).toEqual([UK]);
333
+ const listed = await store.forms(CONTRACT_TREE);
334
+ expect(listed.ok && listed.value.map((form) => form.audienceId)).toEqual([EU, UK]);
335
+ });
336
+ it("withdraws under one page without touching another's form for the same audience", async () => {
337
+ const store = await make();
338
+ const other = treeIdSchema.parse("t_otherpage");
339
+ await store.setForm(CONTRACT_TREE, authoring(EU));
340
+ await store.setForm(other, authoring(EU, formDelta({ treeId: other })));
341
+ await store.withdrawForm(CONTRACT_TREE, withdrawing(EU));
342
+ const read = await store.overlay(other);
343
+ expect(read.ok && read.value.forms.map((form) => form.audienceId)).toEqual([EU]);
344
+ });
345
+ it("keeps one page's rules and forms out of another's", async () => {
346
+ const store = await make();
347
+ const other = treeIdSchema.parse("t_otherpage");
348
+ await store.recordRules(CONTRACT_TREE, recording([ruleFor(EU, "region", "eu")]));
349
+ await store.setForm(CONTRACT_TREE, authoring(EU));
350
+ expect(await store.overlay(other)).toEqual({ ok: true, value: { rules: [], forms: [] } });
351
+ });
352
+ });
353
+ };
354
+ //# sourceMappingURL=audience-overlay-contract.js.map
@@ -30,6 +30,7 @@
30
30
  * reason — it asks a live Postgres about a table, so it needs `drizzle-orm`,
31
31
  * which the Postgres suites already do.
32
32
  */
33
+ export { audienceNamed, CONTRACT_TREE, describeAudienceOverlayStoreContract, formDelta, ruleFor, } from "./audience-overlay-contract.js";
33
34
  export { describeHoldStoreContract, heldProposalFixture } from "./hold-contract.js";
34
35
  export { CONTRACT_REPLY, CONTRACT_SERVED_BY, contractRequest, describeModelClientContract, MODEL_SITUATIONS, type ModelClientContract, type ModelSituation, type ModelSituationClient, } from "./model-contract.js";
35
36
  export { describeTelemetryJournalContract, sampleEpisode } from "./journal-contract.js";
@@ -30,6 +30,7 @@
30
30
  * reason — it asks a live Postgres about a table, so it needs `drizzle-orm`,
31
31
  * which the Postgres suites already do.
32
32
  */
33
+ export { audienceNamed, CONTRACT_TREE, describeAudienceOverlayStoreContract, formDelta, ruleFor, } from "./audience-overlay-contract.js";
33
34
  export { describeHoldStoreContract, heldProposalFixture } from "./hold-contract.js";
34
35
  export { CONTRACT_REPLY, CONTRACT_SERVED_BY, contractRequest, describeModelClientContract, MODEL_SITUATIONS, } from "./model-contract.js";
35
36
  export { describeTelemetryJournalContract, sampleEpisode } from "./journal-contract.js";
@@ -1,6 +1,6 @@
1
1
  import { describe, expect, it } from "vitest";
2
2
  import { sequentialIdFactory, treeIdSchema } from "../ids.js";
3
- import { MAX_ASSESSMENT_LOOKUP, recordOf, } from "../telemetry/index.js";
3
+ import { describeTelemetryWindowFault, MAX_ASSESSMENT_LOOKUP, MAX_TELEMETRY_LIMIT, recordOf, telemetryWindow, } from "../telemetry/index.js";
4
4
  import { buildElement } from "../tree/builders.js";
5
5
  import { createTree } from "../tree/tree.js";
6
6
  import { buildAssessment, buildIntent, buildProposal, FIXED_INSTANT } from "./doubles.js";
@@ -103,7 +103,7 @@ export const describeTelemetryJournalContract = (name, makeJournal) => {
103
103
  const journal = await freshJournal();
104
104
  expect(await journal.read({ treeId: treeIdSchema.parse("t_absent") })).toEqual({
105
105
  ok: true,
106
- value: { records: [], older: null, newer: null },
106
+ value: { records: [], older: null, newer: null, span: null },
107
107
  });
108
108
  });
109
109
  it("accepts an empty batch", async () => {
@@ -111,7 +111,7 @@ export const describeTelemetryJournalContract = (name, makeJournal) => {
111
111
  expect(await journal.record([])).toEqual({ ok: true, value: undefined });
112
112
  expect(await journal.read()).toEqual({
113
113
  ok: true,
114
- value: { records: [], older: null, newer: null },
114
+ value: { records: [], older: null, newer: null, span: null },
115
115
  });
116
116
  });
117
117
  it("survives the round trip with the proposal intact", async () => {
@@ -204,7 +204,7 @@ export const describeTelemetryJournalContract = (name, makeJournal) => {
204
204
  const all = await journal.read();
205
205
  const last = all.ok ? all.value.records.at(-1) : undefined;
206
206
  const past = await journal.read({ cursor: String(last?.seq ?? 0) });
207
- expect(past).toEqual({ ok: true, value: { records: [], older: null, newer: null } });
207
+ expect(past).toEqual({ ok: true, value: { records: [], older: null, newer: null, span: null } });
208
208
  });
209
209
  });
210
210
  /**
@@ -406,7 +406,7 @@ export const describeTelemetryJournalContract = (name, makeJournal) => {
406
406
  });
407
407
  expect(await journal.read()).toEqual({
408
408
  ok: true,
409
- value: { records: [], older: null, newer: null },
409
+ value: { records: [], older: null, newer: null, span: null },
410
410
  });
411
411
  });
412
412
  it("accepts a position an empty journal has nothing below", async () => {
@@ -486,6 +486,159 @@ export const describeTelemetryJournalContract = (name, makeJournal) => {
486
486
  expect(page.ok && page.value.records).toHaveLength(2);
487
487
  });
488
488
  });
489
+ /**
490
+ * The read a person actually asks for, and the one a journal paged by
491
+ * arrival could not answer.
492
+ *
493
+ * Every bound here is taken off the journal's own stamps rather than off the
494
+ * clock in this process. A journal in memory stamps from a clock it was
495
+ * handed; a journal in Postgres stamps from `now()` on the database server,
496
+ * whose reading of the hour is its own. A suite that composed a bound
497
+ * locally would be asserting that two machines agree about the time, which
498
+ * is the one thing a `recordedAt` exists because they do not.
499
+ */
500
+ describe("asking for a stretch of time", () => {
501
+ const spanOrThrow = async (journal) => {
502
+ const page = await journal.read({ limit: MAX_TELEMETRY_LIMIT });
503
+ if (!page.ok)
504
+ throw new Error("the journal could not be read");
505
+ if (page.value.span === null)
506
+ throw new Error("the journal reported no span to bound by");
507
+ return page.value.span;
508
+ };
509
+ const windowOrThrow = (request) => {
510
+ const built = telemetryWindow(request);
511
+ if (!built.ok)
512
+ throw new Error(describeTelemetryWindowFault(built.error));
513
+ return built.value;
514
+ };
515
+ /** One millisecond past a stamp, which is the smallest exclusive upper bound that holds it. */
516
+ const justAfter = (stamp) => new Date(Date.parse(stamp) + 1).toISOString();
517
+ it("reports the stretch a page covers, and reports nothing for a page with no records", async () => {
518
+ const journal = await freshJournal();
519
+ expect(await journal.read()).toMatchObject({ ok: true, value: { span: null } });
520
+ await journal.record(sampleEpisode("span"));
521
+ const page = await journal.read();
522
+ if (!page.ok)
523
+ throw new Error("the journal could not be read");
524
+ const span = page.value.span;
525
+ expect(span).not.toBeNull();
526
+ expect(page.value.records.every((record) => Date.parse(record.recordedAt) >= Date.parse(span?.from ?? "") &&
527
+ Date.parse(record.recordedAt) <= Date.parse(span?.to ?? ""))).toBe(true);
528
+ });
529
+ it("holds every record when the window spans the journal's own ends", async () => {
530
+ const journal = await freshJournal();
531
+ const episode = sampleEpisode("whole");
532
+ await journal.record(episode);
533
+ const span = await spanOrThrow(journal);
534
+ const page = await journal.read({
535
+ window: windowOrThrow({ since: span.from, until: justAfter(span.to) }),
536
+ });
537
+ expect(page.ok && typesOf(page.value.records)).toEqual(typesOf(episode));
538
+ });
539
+ /**
540
+ * `since` is inclusive and `until` is not, which is what lets two
541
+ * consecutive windows tile. The two assertions are the two ends of that
542
+ * one claim: the earliest stamp is in a window that begins on it, and out
543
+ * of a window that ends on it.
544
+ */
545
+ it("includes a record on its since and excludes one on its until", async () => {
546
+ const journal = await freshJournal();
547
+ await journal.record(sampleEpisode("ends"));
548
+ const span = await spanOrThrow(journal);
549
+ const from = await journal.read({ window: windowOrThrow({ since: span.from }) });
550
+ const upTo = await journal.read({ window: windowOrThrow({ until: span.from }) });
551
+ expect(from.ok && from.value.records.length).toBeGreaterThan(0);
552
+ expect(upTo.ok && upTo.value.records).toEqual([]);
553
+ expect(upTo.ok && upTo.value.span).toBeNull();
554
+ });
555
+ /**
556
+ * The property the half-open shape exists for: a boundary cuts the
557
+ * journal in two and loses nothing and counts nothing twice. An
558
+ * implementation that made `until` inclusive passes every other test here
559
+ * and fails this one, because the record stamped exactly on the boundary
560
+ * turns up on both sides.
561
+ */
562
+ it("tiles: a boundary splits the journal with nothing lost and nothing counted twice", async () => {
563
+ const journal = await freshJournal();
564
+ await journal.record(sampleEpisode("tilea"));
565
+ await journal.record(sampleEpisode("tileb"));
566
+ const span = await spanOrThrow(journal);
567
+ const everything = await journal.read({ limit: MAX_TELEMETRY_LIMIT });
568
+ const before = await journal.read({
569
+ window: windowOrThrow({ until: span.to }),
570
+ limit: MAX_TELEMETRY_LIMIT,
571
+ });
572
+ const after = await journal.read({
573
+ window: windowOrThrow({ since: span.to }),
574
+ limit: MAX_TELEMETRY_LIMIT,
575
+ });
576
+ const seqsIn = (page) => page.ok ? page.value.records.map((record) => record.seq) : [];
577
+ const split = [...seqsIn(before), ...seqsIn(after)].sort((a, b) => a - b);
578
+ expect(split).toEqual(seqsIn(everything));
579
+ expect(new Set(split).size).toBe(split.length);
580
+ });
581
+ /**
582
+ * A window is measured against `recordedAt` and never against
583
+ * `occurredAt`, and this is the test that can tell. Every record in the
584
+ * fixture carries an `occurredAt` months in the past, so a window bounded
585
+ * at the journal's own stamps holds them all — and an implementation that
586
+ * bounded on what the host said would answer with nothing at all.
587
+ */
588
+ it("measures the window against when it learned of a record, not against what the host said", async () => {
589
+ const journal = await freshJournal();
590
+ const episode = sampleEpisode("stamped");
591
+ await journal.record(episode);
592
+ const span = await spanOrThrow(journal);
593
+ const page = await journal.read({ window: windowOrThrow({ since: span.from }) });
594
+ expect(page.ok && page.value.records).toHaveLength(episode.length);
595
+ expect(page.ok && page.value.records.every((record) => record.occurredAt === FIXED_INSTANT)).toBe(true);
596
+ expect(Date.parse(span.from)).toBeGreaterThan(Date.parse(FIXED_INSTANT));
597
+ });
598
+ it("reads a window nothing landed in as an empty page rather than an error", async () => {
599
+ const journal = await freshJournal();
600
+ await journal.record(sampleEpisode("after"));
601
+ const span = await spanOrThrow(journal);
602
+ expect(await journal.read({ window: windowOrThrow({ since: justAfter(span.to) }) })).toEqual({ ok: true, value: { records: [], older: null, newer: null, span: null } });
603
+ });
604
+ /**
605
+ * The cursors a windowed page names stay inside the window. A `beyond`
606
+ * probe that ignored the bound would hand back a cursor pointing at a
607
+ * record the window excludes, and a reader paging to the end of *last
608
+ * week* would walk out of it without being told.
609
+ */
610
+ it("pages within the window and never out of it", async () => {
611
+ const journal = await freshJournal();
612
+ const treeId = treeIdSchema.parse("t_windowpage");
613
+ await journal.record(recordsFor(treeId, 5));
614
+ const span = await spanOrThrow(journal);
615
+ const bounded = windowOrThrow({ since: span.from, until: justAfter(span.to) });
616
+ const collected = [];
617
+ let cursor;
618
+ do {
619
+ const page = await journal.read({ window: bounded, limit: 2, ...(cursor ? { cursor } : {}) });
620
+ if (!page.ok)
621
+ throw new Error("the journal could not be read");
622
+ collected.push(...page.value.records.map((record) => record.seq));
623
+ cursor = page.value.newer;
624
+ } while (cursor);
625
+ expect(collected).toHaveLength(5);
626
+ expect(new Set(collected).size).toBe(5);
627
+ });
628
+ it("narrows by tree and by window together", async () => {
629
+ const journal = await freshJournal();
630
+ const mine = treeIdSchema.parse("t_wmine");
631
+ const yours = treeIdSchema.parse("t_wyours");
632
+ await journal.record([...recordsFor(mine, 2), ...recordsFor(yours, 3)]);
633
+ const span = await spanOrThrow(journal);
634
+ const page = await journal.read({
635
+ treeId: yours,
636
+ window: windowOrThrow({ since: span.from, until: justAfter(span.to) }),
637
+ });
638
+ expect(page.ok && page.value.records).toHaveLength(3);
639
+ expect(page.ok && page.value.records.every((record) => record.treeId === yours)).toBe(true);
640
+ });
641
+ });
489
642
  });
490
643
  };
491
644
  //# sourceMappingURL=journal-contract.js.map
@@ -83,20 +83,25 @@ export type TextPairing = {
83
83
  };
84
84
  export declare const PALETTE_TEXT_PAIRINGS: readonly TextPairing[];
85
85
  /**
86
- * The colour as three 0–255 channels, or nothing when it is a form this cannot
87
- * measure.
88
- *
89
- * `colourSchema` accepts more than hex — `rgb()`, `hsl()`, a named colour, and
90
- * eight-digit hex with an alpha. Only three- and six-digit hex are measured
91
- * here, and the rest answer `undefined` rather than a guess:
92
- *
93
- * - a named colour needs the CSS colour table, which is 148 entries of vocabulary
94
- * this module would then own
95
- * - `hsl()` and modern `rgb()` syntax are a parser, and a parser that is subtly
96
- * wrong reports a passing ratio for a failing pair, which is worse than
97
- * reporting nothing
98
- * - an alpha composites against whatever is behind it, so its contrast is not a
99
- * property of the two slots at all
86
+ * A colour's three 0–255 channels, unrounded, or nothing when the form cannot
87
+ * be measured.
88
+ *
89
+ * `colourSchema` accepts four shapes: hex of three to eight digits, `rgb()`,
90
+ * `hsl()`, and a bare word naming a CSS colour. Of those, **every form whose
91
+ * channels are arithmetic is read here**, and two are declined (0365):
92
+ *
93
+ * - **a named colour is vocabulary, not arithmetic.** It needs the CSS colour
94
+ * table — 148 entries this module would then own and keep — and no amount of
95
+ * care with the other forms supplies it.
96
+ * - **an alpha below 1 composites against whatever is behind it**, so its
97
+ * contrast is not a property of the two slots at all. A *fully opaque* alpha
98
+ * is a different case and is read: `#111827ff` composites to exactly
99
+ * `#111827`, so declining it reported nothing about a colour that was never
100
+ * in doubt.
101
+ *
102
+ * Channels are left unrounded. A browser quantises `hsl()` to eight bits per
103
+ * channel on its way into a pixel; nothing here draws anything, so rounding to
104
+ * match it would discard precision to imitate a step this never takes.
100
105
  *
101
106
  * Answering "I could not measure this" is the same move `not-probeable` makes in
102
107
  * the conformance probe: a check that cannot answer says so, rather than passing.